Pivit

Pivit هي أداة سطر أوامر لإدارة شهادات x509 المخزنة على البطاقات الذكية التي تدعم تطبيق PIV (Yubikey)، واستخدام تلك الشهادات لتوقيع البيانات والتحقق منها.

وهي متوافقة تمامًا مع الطريقة التي يستدعي بها سطر أوامر git البرامج الخارجية لتوقيع عمليات الالتزام والوسوم والتحقق منها.

التثبيت

Brew

brew install pivit

التثبيت عبر Go

go install github.com/cashapp/pivit/cmd/pivit@latest

الاستخدام

لإعداد git لاستخدام pivit في توقيع التواقيع والتحقق منها، نفّذ الأوامر التالية:

git config --(local|global) gpg.format x509
git config --(local|global) gpg.x509.program pivit

إعادة تعيين PIV في Yubikey وتهيئته

pivit --reset

يُعيد تعيين تطبيق PIV في Yubikey وينشئ رقم PIN جديدًا للوصول إليه.

إنشاء شهادة

pivit --generate [--p256] [--self-sign | --no-csr] [--assume-yes] [--pin-policy] [--touch-policy]

ينشئ زوج مفاتيح جديدًا في فتحة مصادقة البطاقة في Yubikey.
سينشئ هذا الأمر أيضًا شهادة x509 للمفتاح المُنشأ ويخزّنها، وهي موقّعة من Yubico.

إذا تم توفير الخيار --p256، فسيتم إنشاء زوج المفاتيح باستخدام المنحنى الإهليلجي P-256.
وإلا، فسيتم استخدام المنحنى P-384.

أضف العلامة --self-sign لإنشاء شهادة موقّعة ذاتيًا؛
تُوقَّع الشهادة بالمفتاح المُنشأ حديثًا.
سيُطلب منك تأكيد رغبتك فعلًا في الحصول على شهادة موقّعة ذاتيًا، ثم سيُطلب منك رقم PIN، ثم لمس Yubikey.
سيحتوي المخرج على 3 كتل CERTIFICATE بدلًا من CERTIFICATE_REQUEST في النهاية (مثال على المخرج أدناه).
هذا الخيار مفيد لأغراض الاختبار في الغالب.
يمكن استخدام العلامة --assume-yes مع الخيار --self-sign لتعطيل مطالبة n/y.

أضف العلامة --no-csr لتخطّي طباعة طلب توقيع الشهادة. في هذه الحالة، لن يُطلب منك لمس Yubikey.
هذا الخيار مفيد إذا لم تكن بحاجة إلى أن يكون المفتاح المُنشأ جزءًا من بنية PKI قائمة.
لا يزال بإمكانك التحقق من شهادة المفتاح باستخدام شهادة Yubico هنا.

تتحكم العلامة --pin-policy في وقت المطالبة برقم PIN عند الوصول إلى المفتاح المُنشأ.
عيّنها إلى إحدى القيم never أو once أو always (الافتراضي هو never).

تتحكم العلامة --touch-policy في وقت مطالبتك بلمس العتاد فعليًا عند الوصول إلى المفتاح المُنشأ.
عيّنها إلى إحدى القيم never أو cached أو always (الافتراضي هو always).

سيبدو مخرج الأمر كما يلي:

Printing Yubikey device attestation certificate:
----- BEGIN CERTIFICATE -----
...
----- END CERTIFICATE -----
Printing generated key certificate:
----- BEGIN CERTIFICATE -----
...
----- END CERTIFICATE -----
Printing certificate signing request:
----- BEGIN CERTIFICATE REQUEST -----
...
----- END CERTIFICATE REQUEST-----

إن CERTIFICATE REQUEST في النهاية موقّع بالمفتاح الخاص المُنشأ حديثًا، ويمكن استخدامه لإصدار شهادة موقّعة من جهة تصديق (CA).

إذا اخترت إصدار واستخدام شهادة خاصة بك، فمن المهم أيضًا التحقق من أن:

• شهادة إثبات هوية الجهاز موقّعة من Yubico.
• شهادة المفتاح موقّعة من شهادة إثبات هوية الجهاز.
• المفتاح العام في طلب توقيع الشهادة هو نفسه المفتاح العام في شهادة المفتاح.

معلمات طلب الشهادة

يتيح Pivit تعيين سمات مختلفة في CSR عبر متغيرات البيئة.

سيتم تعيين خيارات الشهادة التالية على النحو التالي:

• سيتم تعيين Subject.CommonName إلى قيمة متغير البيئة PIVIT_EMAIL.
• سيتم تعيين Subject.Organization إلى قيمة متغير البيئة PIVIT_ORG.
• سيتم تعيين Subject.OrganizationalUnit إلى قيمة متغير البيئة PIVIT_ORG_UNIT.

بالإضافة إلى ذلك، ستُضمَّن الأسماء البديلة للموضوع (SANs) التالية في طلب الشهادة:

• عناوين البريد الإلكتروني: ستتضمن PIVIT_EMAIL
• عناوين URI: ستتضمن جميع عناوين URL المحددة في متغير البيئة PIVIT_CERT_URIS (تُفصل عناوين URI بمسافة)

دعم فتحات PIV

تدعم وحدة PIV فتحات متعددة يمكن تخزين المفاتيح والشهادات فيها.
الفتحات المتاحة - 9a و9c و9d و9e.

• 9e هي فتحة "مصادقة البطاقة".
  وهي الفتحة الوحيدة التي لا تتطلب رقم PIN للوصول إلى المفتاح الخاص عند التوقيع بها، مما يقلل الاحتكاك في الاستخدام.
• 9a هي فتحة "المصادقة". تُستخدم لإجراءات مثل تسجيل الدخول إلى النظام.
• 9c هي فتحة "التوقيع الرقمي". تُستخدم لتوقيع المستندات، أو توقيع الملفات والبرامج التنفيذية.
• 9d هي فتحة "إدارة المفاتيح". تُستخدم لأشياء مثل تشفير رسائل البريد الإلكتروني أو الملفات بغرض السرية.

لمزيد من المعلومات

يتيح pivit اختيار فتحة باستخدام العلامة -w.
لكل أمر، إذا لم يتم تحديد فتحة، تُستخدم 9e افتراضيًا.
على سبيل المثال:

• إنشاء الشهادة

  root@kitploit:~

  pivit --generate [-w slot]
  

• التوقيع

  root@kitploit:~

  pivit -s -u userid [-w slot]
  

• طباعة شهادة

  root@kitploit:~

  pivit --print [-w slot]
  

تحديد Yubikey عبر الرقم التسلسلي

افتراضيًا، يتوقع pivit وجود Yubikey واحد موصول. إذا كان النظام يحتوي على عدة قارئات بطاقات أو عدة Yubikeys، أو ببساطة للتأكد من أن pivit يتواصل مع Yubikey المقصود، حدد الرقم التسلسلي عبر متغير البيئة PIVIT_YK_SERIAL.

مثال:

PIVIT_YK_SERIAL=13078292 pivit --print

يمكن استخدام هذا مع أي أمر.

استيراد شهادة إلى Yubikey

pivit --import [--first-pem] [file]

يستورد شهادة من file.
من المتوقع أن يحتوي اسم الملف المعطى على شهادة x509 متسلسلة مشفرة ككتلة PEM.

يتطلب هذا الإجراء إدخال رقم PIN الخاص بـ Yubikey.

أضف --first-pem لاستيراد أول كتلة PEM من file، متجاهلاً البقية. هذا مفيد إذا كنت تستخدم جهة تصديق (CA) توفر شهاداتها الصادرة كسلسلة أو حزمة، مع وضع شهادة الكيان النهائي أولًا (هذه هي الاتفاقية المتبعة).

طباعة معلومات الشهادة

pivit --print

يطبع الشهادة المخزنة في فتحة مصادقة البطاقة في Yubikey، بالإضافة إلى بصمتها.
على سبيل المثال:

> pivit --print
bad126c47dc90e90e0c7ec90ec682b1717e52757
-----BEGIN CERTIFICATE-----
MIICczCCAVugAwIBAgIRANATKTxzlHOJgMdV30XRz5kwDQYJKoZIhvcNAQELBQAw
ITEfMB0GA1UEAwwWWXViaWNvIFBJViBBdHRlc3RhdGlvbjAgFw0xNjAzMTQwMDAw
MDBaGA8yMDUyMDQxNzAwMDAwMFowJTEjMCEGA1UEAwwaWXViaUtleSBQSVYgQXR0
ZXN0YXRpb24gOWUwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAT1l76Mvo6dJ4CwX2QQ
HImYRWbxLqt1kCVsn0PUn20DYtSKLuq8kCnMAn+kdneqjtaaBmWuPJH+g7LMyI18
QDQp2w+qSOf9ZWrOupMAGM8EpWXNTSNKoE50JhKXFbudBByjTjBMMBEGCisGAQQB
gsQKAwMEAwUBAjAUBgorBgEEAYLECgMHBAYCBACDq1IwEAYKKwYBBAGCxAoDCAQC
AQIwDwYKKwYBBAGCxAoDCQQBBDANBgkqhkiG9w0BAQsFAAOCAQEAGSmu0PUMDfEb
PkmkJ/rKYvpOKhbmpryjXuZ7ENJ3jGq3foyLSN+aBbd3M1im2ejC6/upthcp1N5M
Mg2SN6MBRS4crtt43DVHepBPt2W07vW8h4uFosJX29HdhK0dP+RnBGDdWYo0nq7y
7q1Y1c0BI7oGnaORL0DzSDtdxAJAphjspWsWNCIP2DTWQPhLTg4DqmYd/ahygVsZ
IE64QvJDQC72Dfyad6tIajmtPncqPt857H0hEJv2X58iOoJA/wAeuId4or859cJU
GTDbN7Ke4LWXRbs7StJTgefmNgWmKjm1Q2qs80WGShyQ6OrxALejd8jivtcTwsDz
WvzdmHCOmg==
-----END CERTIFICATE-----

يتم حساب بصمة الشهادة عن طريق إجراء مجموع اختباري SHA1 على وحدات البايت الخام للشهادة ثم ترميز المجموع الاختباري كسلسلة سداسية عشرية.

استخدم بصمة الشهادة لإخبار git بالشهادة التي يجب استخدامها عند توقيع عمليات الالتزام والوسوم:

FINGERPRINT=`pivit --print | head -1`
git config --(local|global) user.signingkey $FINGERPRINT

التوقيع

pivit -s [-a] [-b] [-u userid] [--status-fd=[num]] [-t url] [file]

• -a (--armor) - ما إذا كان يجب تغليف التوقيع بترميز ASCII لجعله قابلًا للطباعة.
• -b (--detach-sign) - إنشاء توقيع منفصل.
• -u (--local-user) - إما عنوان بريد إلكتروني أو بصمة مفتاح مشفرة كسلسلة سداسية عشرية.
  يحدد هذا المعرّف الشهادة التي سيتم استخدامها. إذا تم توفير عنوان بريد إلكتروني، فابحث عن شهادة تحتوي على العنوان المعطى.
  إذا تم توفير بصمة مفتاح، فابحث عن شهادة تطابق مجموع SHA1 الاختباري الخاص بها السلسلة السداسية العشرية المعطاة.
• --status-fd - واصف ملف لإرسال رسائل الحالة إليه. 1 هو stdout، و2 هو stderr.
  أي قيمة 0 أو أقل تعني عدم كتابة أي رسائل حالة.
• -t (--timestamp-authority) - عنوان URL لسلطة الطوابع الزمنية RFC3161 لاستخدامها في ختم الوقت.
• file - مسار الملف الذي سيتم توقيعه. إذا لم يتم تحديد اسم ملف، فاستخدم stdin.

سيؤدي هذا الأمر إلى جعل Yubikey يومض وسيتم حظره حتى يتم لمسه.

عند إعداد git لتوقيع عمليات الالتزام والوسوم، سيستخدم المعاملات الثابتة التالية -sbau [user.signingkey] --status-fd=1.
يتم أخذ user.signingkey من إعدادات git المحلية/العامة.

ملاحظة: صُمم Pivit لدعم توقيع عمليات الالتزام في git.
لكن إذا كان المفتاح المستخدم قد أُنشئ باستخدام --pin-policy=always فقد لا يكون مدعومًا بالكامل.
حاليًا، يطلب Pivit رقم PIN فقط عبر سطر الأوامر. إذا كنت تستخدم عملاء git بواجهات رسومية مثل GitKraken أو SourceTree فمن المحتمل أن تفوتك هذه المطالبة.

التحقق من التوقيع

pivit --verify [file ...]

يتحقق من البيانات الموقعة المحددة في وسيطات الملف (الملفات).

إذا لم يتم تحديد أي ملفات، فاقرأ من stdin.
إذا تم تحديد مسار ملف واحد أو لم يتم تحديد أي مسار، فافترض أن التوقيع مرفق بالبيانات الموقعة.

بخلاف ذلك، افترض أن الملف الأول يحتوي على التوقيع، والملف الثاني يحتوي على البيانات الموقعة.
حدد - للإشارة إلى أنه يجب قراءة البيانات الموقعة من stdin.