git-credential

Имя

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

Синтаксис

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

Описание

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

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

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

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

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

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

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

Типичное использование git-credential

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

Сгенерируйте описание учетных данных на основе контекста.

Например, если нам нужен пароль для https://example.com/foo.git, мы можем сгенерировать следующее описание учетных данных (не забудьте о пустой строке в конце; она сообщает git credential о том, что приложение завершило предоставление всей имеющейся информации):
```
protocol=https
host=example.com
path=foo.git
```
Попросите 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.
Используйте учетные данные (например, получите доступ к URL с именем пользователя и паролем из шага (2)) и посмотрите, приняты ли они.
Отчет о успехе или неудаче пароля. Если учетные данные позволили успешно завершить операцию, пометьте их действием «одобрить», чтобы сообщить git credential о повторном использовании. Если учетные данные были отклонены во время операции, используйте действие «отклонить», чтобы git credential запросил новый пароль при следующей вызове. В любом случае git credential должно быть передано описание учетных данных, полученное из шага (2) (которое также содержит поля, предоставленные на шаге (1)).

Формат ввода/вывода

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

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

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

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

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

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

protocol

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

host

Удаленный хост-имя для сетевых учетных данных. Это включает номер порта, если он был указан (например, "example.com:8088").

path

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

username

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

password

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

password_expiry_utc

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

oauth_refresh_token

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

url

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

Обратите внимание, что указание протокола является обязательным, и если URL не указывает хост-имя (например, "cert:///path/to/file"), учетные данные будут содержать атрибут хост-имя, значение которого — пустая строка.

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

authtype

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

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

credential

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

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

ephemeral

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

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

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

state[]

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

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

continue

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

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

wwwauth[]

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

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

capability[]

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

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

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

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

Формат ввода/вывода возможностей

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

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

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

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/git-credential