Русский ▾ Topics ▾ Latest version ▾ git-credential last updated in 2.46.0

НАЗВАНИЕ

git-credential — получение и хранение учётных данных пользователя

ОБЗОР

'git credential' (fill|approve|reject|capability)

ОПИСАНИЕ

Git имеет внутренний интерфейс для хранения и получения учётных данных от системно-зависимых помощников, а также для запроса у пользователя имён пользователей и паролей. Команда git-credential предоставляет этот интерфейс сценариям, которые могут захотеть получить, сохранить или запросить учётные данные так же, как Git. Дизайн этого интерфейса, доступного для сценариев, моделирует внутренний C API; дополнительные сведения о концепциях см. в credential.h.

git-credential принимает параметр «действие» в командной строке (один из fill, approve или reject) и читает описание учётных данных из stdin (см. ФОРМАТ ВВОДА/ВЫВОДА).

Если действие — fill, git-credential попытается добавить атрибуты «username» и «password» к описанию, читая файлы конфигурации, обращаясь к любым настроенным помощникам учётных данных или запрашивая у пользователя. Затем атрибуты имени пользователя и пароля описания учётных данных выводятся в stdout вместе с уже предоставленными атрибутами.

Если действие — approve, git-credential отправит описание любым настроенным помощникам учётных данных, которые могут сохранить учётные данные для последующего использования.

Если действие — reject, git-credential отправит описание любым настроенным помощникам учётных данных, которые могут удалить любые сохранённые учётные данные, соответствующие описанию.

Если действие — capability, git-credential объявит о любых возможностях, которые он поддерживает, в стандартный вывод.

Если действие — approve или reject, вывод не должен производиться.

ТИПИЧНОЕ ИСПОЛЬЗОВАНИЕ GIT CREDENTIAL

Приложение, использующее git-credential, обычно будет использовать git credential в соответствии со следующими шагами:

  1. Создать описание учётных данных на основе контекста.

    Например, если нам нужен пароль для https://example.com/foo.git, мы можем создать следующее описание учётных данных (не забудьте о пустой строке в конце; она сообщает git credential, что приложение закончило передавать всю имеющуюся у него информацию):

    protocol=https
host=example.com
path=foo.git

  2. Попросить git-credential предоставить нам имя пользователя и пароль для этого описания. Это делается путём запуска git credential fill, передавая описание из шага (1) в его стандартный ввод. Полное описание учётных данных (включая сами учётные данные, т.е. логин и пароль) будет выведено в стандартный вывод, например:

    protocol=https
host=example.com
username=bob
password=secr3t

    В большинстве случаев это означает, что атрибуты, указанные во входных данных, будут повторены в выводе, но Git также может изменить описание учётных данных, например, удалив атрибут path, когда протоколом является HTTP(s), а credential.useHttpPath имеет значение false.

    Если git credential знал о пароле, этот шаг мог не включать фактический ввод этого пароля пользователем (пользователь мог ввести пароль для разблокировки связки ключей вместо этого, или взаимодействие с пользователем не выполнялось, если связка ключей уже была разблокирована) перед тем, как он вернул password=secr3t.

  3. Использовать учётные данные (например, получить доступ к URL с именем пользователя и паролем из шага (2)) и проверить, приняты ли они.

  4. Сообщить об успехе или неудаче пароля. Если учётные данные позволили успешно завершить операцию, их можно пометить действием "approve", чтобы сообщить git credential повторно использовать их при следующем вызове. Если учётные данные были отклонены во время операции, используйте действие "reject", чтобы git credential запросил новый пароль при следующем вызове. В любом случае, git credential должен быть передан с описанием учётных данных, полученным из шага (2) (которое также содержит поля, предоставленные в шаге (1)).

ФОРМАТ ВВОДА/ВЫВОДА

git credential читает и/или записывает (в зависимости от используемого действия) информацию об учётных данных в своём стандартном вводе/выводе. Эта информация может соответствовать либо ключам, для которых git credential получит информацию для входа (например, host, protocol, path), либо фактическим данным учётных данных, которые необходимо получить (username/password).

Учётные данные разделены на набор именованных атрибутов, по одному атрибуту на строку. Каждый атрибут задаётся парой ключ-значение, разделённой знаком = (равно), за которым следует новая строка.

Ключ может содержать любые байты, кроме =, новой строки или NUL. Значение может содержать любые байты, кроме новой строки или NUL. Строка, включая конечную новую строку, не должна превышать 65535 байт, чтобы позволить реализациям эффективно выполнять анализ.

Атрибуты с ключами, заканчивающимися квадратными скобками [] в стиле C, могут иметь несколько значений. Каждый экземпляр многозначного атрибута формирует упорядоченный список значений — порядок повторяющихся атрибутов определяет порядок значений. Пустой многозначный атрибут (key[]=\n) служит для очистки всех предыдущих записей и сброса списка.

Во всех случаях все байты обрабатываются как есть (т.е. нет кавычек, и нельзя передать значение с новой строкой или NUL внутри). Список атрибутов завершается пустой строкой или концом файла.

Git понимает следующие атрибуты:

protocol

Протокол, по которому будут использоваться учётные данные (например, https).

host

Имя внешнего хоста для сетевых учётных данных. Включает номер порта, если он был указан (например, "example.com:8088").

path

Путь, с которым будут использоваться учётные данные. Например, для доступа к внешнему репозиторию https это будет путь к репозиторию на сервере.

username

Имя пользователя учётных данных, если оно у нас уже есть (например, из URL, конфигурации, пользователя или из ранее запущенного помощника).

password

Пароль учётных данных, если мы просим его сохранить.

password_expiry_utc

Сгенерированные пароли, такие как токен доступа OAuth, могут иметь дату истечения срока действия. При чтении учётных данных от помощников git credential fill игнорирует просроченные пароли. Представляется как время Unix UTC, секунды с 1970 года.

oauth_refresh_token

Токен обновления OAuth может сопровождать пароль, который является токеном доступа OAuth. Помощники должны обращаться с этим атрибутом как с конфиденциальным, как с атрибутом пароля. Сам Git не имеет специального поведения для этого атрибута.

url

Когда этот специальный атрибут читается git credential, значение анализируется как URL и обрабатывается так, как если бы были прочитаны его составные части (например, url=https://example.com будет вести себя так, как если бы были предоставлены protocol=https и host=example.com). Это может помочь вызывающим сторонам избежать самостоятельного анализа URL-адресов.

Обратите внимание, что указание протокола является обязательным, и если URL не указывает имя хоста (например, "cert:///путь/к/файлу"), учётные данные будут содержать атрибут hostname, значение которого является пустой строкой.

Компоненты, отсутствующие в URL (например, в приведённом выше примере нет имени пользователя), будут оставлены неустановленными.

authtype

Указывает, что должна использоваться данная схема аутентификации. Общие значения для HTTP и HTTPS включают basic, bearer и digest, хотя последний небезопасен и не должен использоваться. Если используется credential, это может быть установлено в произвольную строку, подходящую для данного протокола (обычно HTTP).

Это значение не должно отправляться, если соответствующая возможность (см. ниже) не предоставлена на входе.

credential

Предварительно закодированные учётные данные, подходящие для данного протокола (обычно HTTP). Если этот ключ отправлен, authtype является обязательным, а username и password не используются. Для HTTP Git объединяет значение authtype и это значение с одним пробелом для определения заголовка Authorization.

Это значение не должно отправляться, если соответствующая возможность (см. ниже) не предоставлена на входе.

ephemeral

Это логическое значение указывает, если true, что значение в поле credential не должно сохраняться помощником учётных данных, поскольку его полезность ограничена во времени. Например, значение credential для HTTP Digest вычисляется с использованием одноразового числа, и повторное его использование не приведёт к успешной аутентификации. Это также может использоваться для ситуаций с кратковременными (например, 24-часовыми) учётными данными. Значение по умолчанию — false.

Помощник учётных данных всё равно будет вызван с store или erase, чтобы он мог определить, была ли операция успешной.

Это значение не должно отправляться, если соответствующая возможность (см. ниже) не предоставлена на входе.

state[]

Это значение предоставляет непрозрачное состояние, которое будет передано обратно этому помощнику, если он будет вызван снова. Каждый другой помощник учётных данных может указать это один раз. Значение должно включать префикс, уникальный для помощника учётных данных, и должно игнорировать значения, не соответствующие его префиксу.

Это значение не должно отправляться, если соответствующая возможность (см. ниже) не предоставлена на входе.

continue

Это логическое значение, которое, если оно включено, указывает, что эта аутентификация является неокончательной частью многоэтапного шага аутентификации. Это распространено в таких протоколах, как NTLM и Kerberos, где требуются два раунда аутентификации клиента, и установка этого флага позволяет помощнику учётных данных реализовать многоэтапный шаг аутентификации. Этот флаг должен отправляться только в том случае, если требуется дальнейший этап; то есть если ожидается ещё один раунд аутентификации.

Это значение не должно отправляться, если соответствующая возможность (см. ниже) не предоставлена на входе. Этот атрибут является однонаправленным от помощника учётных данных для передачи информации Git (или другим программам, вызывающим git credential).

wwwauth[]

Когда Git получает HTTP-ответ, содержащий один или несколько заголовков аутентификации WWW-Authenticate, Git передаст их помощникам учётных данных.

Каждое значение заголовка WWW-Authenticate передаётся как многозначный атрибут wwwauth[], где порядок атрибутов соответствует порядку их появления в HTTP-ответе. Этот атрибут является однонаправленным от Git для передачи дополнительной информации помощникам учётных данных.

capability[]

Это сигнализирует о том, что Git или помощник, в зависимости от ситуации, поддерживает данную возможность. Это можно использовать для предоставления лучших, более конкретных данных в рамках протокола. Директива capability[] должна предшествовать любому значению, зависящему от неё, и эти директивы должны быть первым элементом, объявленным в протоколе.

В настоящее время поддерживаются две возможности. Первая — authtype, которая указывает, что значения authtype, credential и ephemeral понимаются. Вторая — state, которая указывает, что значения state[] и continue понимаются.

Необязательно использовать дополнительные функции только потому, что возможность поддерживается, но они не должны предоставляться без возможности.

Нераспознанные атрибуты и возможности молча отбрасываются.

ФОРМАТ ВВОДА/ВЫВОДА ВОЗМОЖНОСТЕЙ

Для git credential capability формат немного отличается. Сначала делается объявление version 0, чтобы указать текущую версию протокола, а затем каждая возможность объявляется строкой типа capability authtype. Помощники учётных данных также могут реализовать этот формат, снова с аргументом capability. В будущем могут быть добавлены дополнительные строки; вызывающие стороны должны игнорировать строки, которые они не понимают.

Поскольку это новая часть протокола помощника учётных данных, более старые версии Git, а также некоторые помощники учётных данных могут не поддерживать его. Если получен ненулевой статус выхода или если первая строка не начинается со слова version и пробела, вызывающие стороны должны предполагать, что никакие возможности не поддерживаются.

Цель этого формата — однозначно отличить его от вывода учётных данных. Можно использовать очень простых помощников учётных данных (например, встроенные сценарии оболочки), которые всегда создают идентичный вывод. Использование отдельного формата позволяет пользователям продолжать использовать этот синтаксис, не беспокоясь о правильной реализации объявлений возможностей или случайном запутывании вызывающих сторон, запрашивающих возможности.

GIT

Является частью пакета git[1]