українська мова ▾ 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 (див. INPUT/OUTPUT FORMAT).

Якщо дія — fill, git-credential спробує додати атрибути "username" та "password" до опису, зчитуючи конфігураційні файли, зв’язуючись із будь-якими помічниками з налаштованих облікових даних або запитуючи користувача. Атрибути імені користувача та пароля з опису облікових даних потім виводяться на stdout разом із уже наданими атрибутами.

Якщо дія — approve, git-credential надішле опис будь-яким налаштованим помічникам облікових даних, які можуть зберігати облікові дані для подальшого використання.

Якщо дія — reject, git-credential надішле опис будь-яким налаштованим помічникам облікових даних, що може видалити будь-які збережені облікові дані, що відповідають опису.

Якщо дією є capability, git-credential оголосить про будь-які підтримувані можливості на стандартний вивід.

Якщо дія — схвалити або відхилити, жодних виводів не повинно бути.

ТИПОВЕ ВИКОРИСТАННЯ ОБЛІКОВИХ ДОСВІДЧЕНЬ GIT

Застосунок, що використовує 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. Повідомити про успішне або невдале введення пароля. Якщо облікові дані дозволили успішно завершити операцію, їх можна позначити дією "схвалити", щоб git credential повторно використав їх під час наступного виклику. Якщо облікові дані були відхилені під час операції, скористайтеся дією "відхилити", щоб git credential запитував новий пароль під час наступного виклику. У будь-якому випадку, git credential слід передати з описом облікових даних, отриманим на кроці (2) (який також містить поля, надані на кроці (1)).

ФОРМАТ ВВЕДЕННЯ/ВИВЕДЕННЯ

git credential зчитує та/або записує (залежно від використаної дії) інформацію про облікові дані у свій стандартний ввід/вивід. Ця інформація може відповідати або ключам, для яких git credential отримуватиме інформацію для входу (наприклад, хост, протокол, шлях), або фактичним даним облікових даних, які потрібно отримати (ім’я користувача/пароль).

Облікові дані розділені на набір іменованих атрибутів, по одному атрибуту на рядок. Кожен атрибут визначається парою ключ-значення, розділеними знаком = (дорівнює), за яким йде символ нового рядка.

Ключ може містити будь-які байти, окрім =, символу нового рядка або 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. Помічники повинні розглядати цей атрибут як конфіденційний, як і атрибут password. Сам Git не має спеціальної поведінки для цього атрибута.

url

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

Зверніть увагу, що вказівка протоколу є обов’язковою, і якщо URL-адреса не вказує ім’я хоста (наприклад, «cert:///шлях/до/файлу»), облікові дані міститимуть атрибут імені хоста, значенням якого є порожній рядок.

Компоненти, яких бракує в URL-адресі (наприклад, у наведеному вище прикладі немає імені користувача), залишаться невстановленими.

authtype

Це вказує на те, що слід використовувати відповідну схему автентифікації. Загальні значення для HTTP та HTTPS включають basic, bearer та digest, хоча останній є небезпечним і не повинен використовуватися. Якщо використовується credential, його можна встановити на довільний рядок, що підходить для відповідного протоколу (зазвичай HTTP).

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

credential

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

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

ephemeral

Це логічне значення вказує, якщо воно має значення true (істина), що значення в полі credential не повинно зберігатися помічником облікових даних, оскільки його корисність обмежена в часі. Наприклад, значення credential HTTP Digest обчислюється за допомогою nonce, і його повторне використання не призведе до успішної автентифікації. Це також може використовуватися для ситуацій з обліковими даними короткої тривалості (наприклад, 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]