.Dd $Mdocdate: Jun 3 2020$
.Dt EFIKEYGEN 1
.Os Linux
.Sh "نام (NAME)"
.Nm efikeygen
.Nd ابزاری برای تولید کلیدهای امضای ایمیج PE برای UEFI Secure Boot
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm efikeygen
.Bk -words
.Ao
.Fl C |
.Fl k |
.Fl m
.Ac
.Ek
.Bk -words
.Ao
.Cm Fl S |
.Cm Fl Fl signer Ar nickname
.Ac
.Ek
.Cm Fl n Ar nickname
.Cm Fl c Ar common_name
.Op Fl u Ar url
.Op Fl s Ar serial
.Op Fl d Ar directory
.Op Fl t Ar token
.Ek
.Sh "توضیحات (DESCRIPTION)"
دستور
.Nm
یک ابزار خط فرمانی برای تولید کلیدها و گواهی‌ها جهت استفاده با pesign است. این‌ها گواهی‌های استاندارد X.509 هستند و می‌توان آن‌ها را با هر ابزار ساخت گواهی دیگری نیز تولید کرد.
.Nm
گواهی‌ها را با گزینه‌های مناسب برای کلیدی که جهت امضای ایمیج PE در UEFI Secure Boot به کار می‌رود تولید می‌کند.

.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag
.It Fl C | Fl Fl ca
ایجاد یک گواهی CA
.It Fl k | Fl Fl kernel
ایجاد یک گواهی امضای هسته (kernel)
.Pp
نباید برای گواهی‌های CA استفاده شود
.It Fl m | Fl Fl module
ایجاد یک گواهی امضای ماژول
.Pp
نباید برای گواهی‌های CA استفاده شود
.It Fl S | Fl Fl self-sign
ایجاد یک گواهی خودامضا
.It Fl Fl signer Ar nickname
استفاده از گواهی NSS ارجاع داده‌شده توسط
.Ar nickname
به‌عنوان گواهی صادرکننده
.It Fl n Ar nickname | Fl nickname Ar nickname
تنظیم نام مستعار گواهی جدید در پایگاه‌داده NSS به
.Ar nickname
.It Fl c Ar common_name | Fl Fl common-name Ar common_name
نام عمومی (Common Name) استاندارد X.509 برای گواهی تولیدشده. این مقدار باید در ساختار نحوی rfc2253 باشد، مانند:\p
.Qq CN=John Doe,OU=editing,O=New York Times,L=New York,ST=NY,C=US
.It Fl u Ar url | Fl Fl url Ar url
نشانی اینترنتی (URL) برای دریافت اطلاعات مربوط به این گواهی و اشیاء امضاشده با آن.
.It Fl s Ar serial | Fl Fl serial Ar serial
شماره سریال برای استفاده با این کلید. یک گواهی با صادرکننده و شماره سریالش شناخته می‌شود، بنابراین بهتر است هرگز این مقدار برای یک صادرکننده یکسان دوباره استفاده نشود. به‌طور پیش‌فرض، این مقدار به‌صورت تصادفی تولید می‌شود. استفاده از این گزینه برای بازنویسی آن توصیه نمی‌شود.
.It Fl d Ar directory | Fl Fl dbdir Ar directory
دایرکتوری پایگاه‌داده کلید NSS\p
.Po
پیش‌فرض:
.Pa /etc/pki/pesign
.Pc
.It Fl t Ar token | Fl Fl token Ar token
نام توکن NSS جهت استفاده\p
.Po
پیش‌فرض:
.Pa pkcs11:token=NSS%20Certificate%20DB
.Pc
.El.Sh "مثال‌ها (EXAMPLES)"
.Ss YubiKey


در اینجا نحوه ایجاد هم گواهی و جفت‌کلید CA و هم گواهی و جفت‌کلید امضای
هسته، و وارد کردن آن‌ها به دستگاه‌های PIV متعلق به yubikey آمده است:

تولید کلیدها:

.Bd -literal -offset 1 -compact
# ساخت یک کلید CA جدید
host:~$ \fBefikeygen -C -n my-ca -S \e
        -c "CN=CA Person,OU=My Org's CA,O=My Org" \e
        -u https://myorg.example.com/ca/\fR

# ساخت یک کلید امضای هسته
host:~$ \fBefikeygen -n my-signer --signer my-ca -k \e
        -c "CN=Secure Boot Signer,OU=My Org's CA,O=My Org" \e
        -u https://myorg.example.com/ca/\fR
.Ed

ذخیره CA روی یک yubikey:

.Bd -literal -offset 1 -compact
# ذخیره آن در یک بسته PKCS-12\p
host:~$ \fBpk12util -d /etc/pki/pesign -o myca.pk12 -n my-ca\fR\p
Enter password for PKCS12 file: \fB<یک گذرواژه اینجا وارد کنید>\fR\p
Re-enter password: \fB<دوباره آن را اینجا وارد کنید>\fR\p
pk12util: PKCS12 EXPORT SUCCESSFUL

# وارد کردن کلید به yubikey
host:~$ \fByubico-piv-tool -s 9c -a import-key -K PKCS12 \e
        -c -i myca.pk12\fR\p
Enter PEM pass phrase: \fB<همان گذرواژه را اینجا وارد کنید>\fR\p
Successfully imported a new private key.\p

# وارد کردن گواهی به yubikey\p
host:~$ \fByubico-piv-tool -s 9c -a import-certificate \e
        -K PKCS12 -i myca.pk12\fR
Enter PEM pass phrase: \fB<همان گذرواژه را اینجا وارد کنید>\fR\p
Successfully imported a new certificate.\p

# حذف گواهی CA از پایگاه‌داده NSS\p
host:~$ \fBcertutil -d /etc/pki/pesign -D -n my-ca\fR\p
.Ed

اکنون yubikeyها را جابه‌جا کرده و امضاکننده هسته را روی دستگاه دیگری وارد کنید:

.Bd -literal -offset 1 -compact
# ذخیره آن در یک بسته PKCS-12\p
host:~$ \fBpk12util -d /etc/pki/pesign -o mysigner.pk12 -n my-signer\fR\p
Enter password for PKCS12 file: \fB<یک گذرواژه اینجا وارد کنید>\fR\p
Re-enter password: \fB<دوباره آن را اینجا وارد کنید>\fR\p
pk12util: PKCS12 EXPORT SUCCESSFUL\p

# وارد کردن کلید به yubikey\p
host:~$ \fByubico-piv-tool -s 9c -a import-key -K PKCS12 \e\p
        -i mysigner.pk12\fR\p
Enter PEM pass phrase: \fB<همان گذرواژه را اینجا وارد کنید>\fR\p
Successfully imported a new private key.\p

# وارد کردن گواهی به yubikey\p
host:~$ \fByubico-piv-tool -s 9c -a import-certificate \e\p
        -K PKCS12 -i mysigner.pk12\fR\p
Enter PEM pass phrase: \fB<همان گذرواژه را اینجا وارد کنید>\fR\p
Successfully imported a new certificate.\p

# حذف امضاکننده هسته از پایگاه‌داده NSS\p
host:~$ \fBcertutil -d /etc/pki/pesign -D -n my-signer\fR
.Ed

پس از انجام این کار، برای امضای فایل‌های باینری آماده‌اید:

.Bd -literal -offset 1 -compact
# در هر یک از این اعلان‌ها، باید PIN مربوط به\p
# Yubikey را وارد کنید. این موضوع و این انتخاب عجیب نام‌ها به این\p
# خاطر است که PKCS-11 افتضاح است. متاسفم.\p
host:~$ \fBpesign -s -t 'Secure Boot Signer' \e\p
        -c "Certificate for Digital Signature" \e\p
        -i shimx64.efi -o shimx64.signed.efi\fR\p
Enter Password or Pin for "Secure Boot Signer": \fB<PIN را اینجا وارد کنید>\fR\p
Enter passphrase for private key: \fB<دوباره آن را اینجا وارد کنید>\fR\p
Enter passphrase for private key: \fB<دوباره آن را اینجا وارد کنید>\fR\p
.Ed

اکنون صحت عملکرد آن را بررسی کنید:

.Bd -literal -offset 1 -compact
host:~$ \fBpesign -i shimx64.signed.efi -l\fR\p
---------------------------------------------\p
certificate address is 0x7fbbae061468\p
Content was not encrypted.\p
Content is detached; signature cannot be verified.\p
The signer's common name is Secure Boot Signer\p
No signer email address.\p
Signing time: Wed May 15, 2019\p
There were certs or crls included.\p
---------------------------------------------\p
.Ed

هورا!.Ss OpenSC (کارت هوشمند)
در اینجا نحوه ایجاد هم گواهی و جفت‌کلید CA و هم گواهی و جفت‌کلید امضای هسته، و سپس وارد کردن (import) آن‌ها به دستگاه‌های کارت هوشمند CardOS پشتیبانی‌شده توسط OpenSC آورده شده است:

در صورت تمایل، کارت را قالب‌بندی کرده و داده‌های PKCS15 آن را مقداردهی اولیه کنید:

.Bd -literal -offset 1 -compact
# قالب‌بندی کارت\p
host:~$ \fBcardos-tool -f\fR\p
Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00\p
card in administrative state, ok\p

# مقداردهی اولیه داده‌های PKCS15 کارت، تنظیم PIN افسر امنیت (Security Officer) و کد بازگشایی.\p
host:~$ \fBpkcs15-init -CT --so-pin $SOPIN --so-puk $SOPUK\fR\p
Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00\p

# مقداردهی اولیه PIN و کد بازگشایی کاربر، و برچسب‌گذاری توکن\p
host:~$ \fBpkcs15-init -P -a 1 --pin $PIN --puk $PUK \e\p
        --so-pin $SOPIN --so-puk $SOPUK \e\p
        --label "myorg-sb-ca"\fR\p
Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00\p
.Ed

تولید کلیدها و گواهی‌ها:

.Bd -literal -offset 1 -compact
# ایجاد یک کلید و گواهی CA جدید\p
host:~$ \fBefikeygen -C -n my-ca -S \e\p
        -c "CN=My Org's Secure Boot CA,OU=My Org's CA,O=My Org" \e\p
        -u https://myorg.example.com/ca\fR

# ایجاد کلید و گواهی امضای هسته\p
host:~$ \fBefikeygen -n my-signer --signer my-ca -k \e\p
        -c "CN=My Org's SB Signer,OU=My Org's CA,O=My Org"\e\p
        -u https://myorg.example.com/ca\fR
.Ed

انتقال آن‌ها به کارت هوشمند

.Bd -literal -offset 1 -compact
# ذخیره کلید و گواهی CA در یک بسته PKCS-12\p
host:~$ \fBpk12util -d /etc/pki/pesign -o my-ca.p12 -n my-ca\fB\p
Enter password for PKCS12 file: \fB<یک گذرواژه در اینجا وارد کنید>\fR\p
Re-enter password: \fB<آن را دوباره در اینجا وارد کنید>\fR\p
pk12util: PKCS12 EXPORT SUCCESSFUL

# وارد کردن بسته PKCS-12 به درون کارت\p
host:~$ \fBpkcs15-init --store-private-key my-ca.p12 \e\p
        --format pkcs12 --auth-id 01 \e\p
        --pin $PIN --so-pin $SOPIN --so-puk $SOPUK\fR\p
Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00\p
Importing 1 certificates:\p
   0: /CN=My Org's Secure Boot CA\p

# فهرست کردن محتویات:\p
host:~$ \fBpkcs11-tool --module opensc-pkcs11.so -l --pin $PIN -O\fR\p
Using slot 1 with a present token (0x1)\p
Private Key Object; RSA\p
  label:      Private Key\p
  ID:         de61fac87e0315352e7b9a487377ace2f6354d9b\p
  Usage:      sign\p
Certificate Object, type = X.509 cert\p
  label:      /CN=My Org's Secure Boot CA\p
  ID:         de61fac87e0315352e7b9a487377ace2f6354d9b\p
Public Key Object; RSA 2048 bits\p
  label:      /CN=My Org's Secure Boot CA\p
  ID:         de61fac87e0315352e7b9a487377ace2f6354d9b\p
  Usage:      encrypt, verify

# بررسی و اطمینان از اینکه nss می‌تواند کارت را ببیند\p
host:~$ \fBmodutil -dbdir /etc/pki/pesign/ -list\fR\p
Listing of PKCS #11 Modules\p
-----------------------------------------------------------\p
  1. NSS Internal PKCS #11 Module\p
     slots: 2 slots attached\p
    status: loaded\p

     slot: NSS Internal Cryptographic Services\p
    token: NSS Generic Crypto Services\p

     slot: NSS User Private Key and Certificate Services\p
    token: NSS Certificate DB\p

  2. opensc-pkcs11\p
    library name: /usr/lib64/pkcs11/opensc-pkcs11.so\p
     slots: 2 slots attached\p
    status: loaded\p

     slot: Virtual hotplug slot\p
    token:\p

     slot: Generic Smart Card Reader Interface [Smart Card Read...\p
    token: OpenSC Card (myorg-sb-ca)\p
-----------------------------------------------------------\p

# بررسی و اطمینان از اینکه NSS می‌تواند گواهی را ببیند:\p
host:~$ \fBcertutil -d /etc/pki/pesign -L \e\p
        -h "OpenSC Card (myorg-sb-ca)"\fR\p
Certificate Nickname                             Trust Attributes\p
                                                 SSL,S/MIME,JAR/XPI\p

Enter Password or Pin for "OpenSC Card (myorg-sb-ca)": \fB<PIN را در اینجا وارد کنید>\fR\p
OpenSC Card (myorg-sb-ca):/CN=My Org's Secure Boot CA    u,u,u\p

# حذف CA از پایگاه‌داده NSS\p
host:~$ \fBcertutil -d /etc/pki/pesign -D -n my-ca\fR\p
.Ed

به یاد داشته باشید که کارت‌ها را جابه‌جا کرده و همین مراحل را برای امضاکننده (signer) نیز انجام دهید، درست مانند مثال YubiKey؛ سپس یک فایل باینری را با کلید امضا روی یک کارت هوشمند امضا کرده و درستی عملکرد آن را تأیید کنید:

.Bd -literal -offset 1 -compact
# امضای فایل باینری. در هر یک از این اعلان‌ها، باید PIN\p
# کارت هوشمند را وارد کنید. این مورد و این انتخاب عجیب\p
# نام‌ها به خاطر نامناسب بودن PKCS-11 است. پوزش می‌خواهم.\p
host:~$ \fBpesign -s -t "OpenSC Card(myorg-sb-signer)" \e\p
        -c "OpenSC Card (myorg-sb-signer):/CN=My Org's SB Signer"\e\p
        -i shimx64.efi -o shimx64.signed.efi\fR\p
Enter Password or Pin for "My Org's SB Signer": \fB<PIN را در اینجا وارد کنید>\fR\p
Enter passphrase for private key: \fB<PIN را در اینجا وارد کنید>\fR\p
Enter passphrase for private key: \fB<PIN را در اینجا وارد کنید>\fR\p

# تأیید اینکه کار کرده است:\p
host:~$ \fBpesign -i shimx64.signed.efi -l\fR\p
---------------------------------------------\p
certificate address is 0x7fbbae061468\p
Content was not encrypted.\p
Content is detached; signature cannot be verified.\p
The signer's common name is My Org's SB Signer\p
No signer email address.\p
Signing time: Wed Jun 2, 2020\p
There were certs or crls included.\p
---------------------------------------------\p
.Ed

بسیار عالی!.Sh "استانداردها (STANDARDS)"
.Rs
.%A B. Kaliski
.%R RFC 2315
.%B PKCS #7: Cryptographic Message Syntax v1.5
.%I Internet Engineering Task Force
.%D مارس ۱۹۹۸
.%U https://tools.ietf.org/html/rfc2315\ \&
.Re

.Rs
.%A K. Moriarty
.%A M. Nystr\[u00F6]m
.%A S. Parkinson
.%A A. Rusch
.%A M. Scott
.%R RFC 7292
.%B PKCS #12: Personal Information Exchange Syntax v1.1
.%I Internet Engineering Task Force
.%D ژوئیه ۲۰۱۴
.%U https://tools.ietf.org/html/rfc7292\ \&
.Re

.Rs
.%A PKCS11 Technical Committee
.%B PKCS#11: Cryptographic Token Interface Standard
.%I OASIS
.%U https://www.cryptsoft.com/pkcs11doc
.Re
.Sh "همچنین ببینید (SEE ALSO)"
.Xr certutil 1 ,
.Xr modutil 1 ,
.Xr opensc-tool 1 ,
.Xr pesign 1 ,
.Xr pk12util 1 ,
.Xr pkcs15-init 1 ,
.Xr yubico-piv-tool 1 ,
.Sh "نویسندگان (AUTHORS)"
.An Peter Jones