GPG-CARD(1) دستورهای کاربری GPG-CARD(1)

gpg-card - ابزار مدیریت و پیکربندی کارتهای هوشمند (Smart Cards) در GnuPG

gpg-card [ گزینهها ] [ دستور [ آرگومانها... ] ]

دستور gpg-card یک ابزار تعاملی و خط فرمانی برای مدیریت، پیکربندی کلیدها و اعمال تنظیمات بر روی کارتهای هوشمند OpenPGP و توکنهای امنیتی است. این ابزار مجموعه‌ای گسترده‌تر از امکانات gpg --card-edit را فراهم می‌کند و می‌توان آن را یک رابط پیشانه (Frontend) برای scdaemon در نظر گرفت؛ دیمنی که توسط gpg-agent برای رسیدگی به کارت‌های هوشمند اجرا می‌شود.

اگر gpg-card بدون هیچ دستوری اجرا شود، حالت تعاملی (Interactive) فعال می‌شود.

اگر gpg-card همراه با یک یا چند دستور فراخوانی شود، همان دستورهای موجود در حالت تعاملی از طریق خط فرمان اجرا می‌شوند. این دستورها باید با دو خط تیره (--) از یکدیگر جدا شوند. اگر یک خط تیره دوگانه یا نویسه ویژه‌ای از پوسته بخشی از دستور باشد، کل آن دستور باید درون علامت نقل‌قول قرار گیرد. چنانچه یکی از این دستورها با خطا مواجه شود، اجرای دستورهای باقی‌مانده متوقف خواهد شد مگر اینکه آن دستور با یک خط تیره تکی پیشوند شده باشد.

فهرست دستورها با استفاده از دستور help در دسترس است و توضیح مختصری از هر دستور با دستور help CMD چاپ می‌شود. برای توضیحات کامل به بخش «دستورها (COMMANDS)» مراجعه کنید.

برای دستورالعمل‌های مربوط به کارت‌های خاص یا برنامه‌های کاربردی کارت، بخش‌های «نکات» را ببینید.

دستور gpg-card دستورهای زیر را که هر یک گزینه‌های مخصوص به خود را دارند درک می‌کند. شبه‌گزینه ‘--’ می‌تواند برای جدا کردن گزینه‌های دستور از آرگومان‌ها استفاده شود؛ اگر این شبه‌گزینه در خط فرمان به کار رود، کل دستور همراه با گزینه‌ها و آرگومان‌ها باید درون نقل‌قول قرار گیرد تا با ‘--’ که در خط فرمان برای جداسازی دستورها استفاده می‌شود اشتباه نشود. توجه داشته باشید که با قرار دادن پیشوند «help» قبل از هر دستور، راهنمای کوتاه برخطی برای آن در دسترس است. تکمیل خودکار دستورها (Tab Completion) در حالت تعاملی نیز پشتیبانی می‌شود.

احراز هویت در کارت. انجام یک احراز هویت متقابل (Mutual Authentication) یا از طریق خواندن کلید از file یا با دریافت آن از خط فرمان به عنوان key. بدون گزینه --raw انتظار می‌رود کلید به صورت هگزادسیمال کدگذاری شده باشد. برای نصب یک کلید مدیریتی جدید از گزینه --setkey استفاده می‌شود؛ این کار نیازمند احراز هویت قبلی با کلید قدیمی است. این دستور در کارت‌های PIV استفاده می‌شود.
تغییر شماره اثرانگشت مرجع صدور گواهی (CA Fingerprint) به شماره N در کارت OpenPGP. مقدار N باید در بازه ۱ تا ۳ باشد. گزینه --clear اثرانگشت CA مشخص‌شده با N یا تمام آن‌ها را (در صورتی که N برابر ۰ باشد یا داده نشود) پاک می‌کند.
بازنشانی کامل (Reset کارخانه‌ای) برخی از کارت‌های OpenPGP و PIV. این دستور تمام داده‌ها و کلیدها را حذف کرده و PINها را به مقادیر پیش‌فرض آن‌ها بازمی‌گرداند. نگران نباشید، پیش از ادامه عملیات باید آن را تأیید کنید.
بازیابی کلید با استفاده از شیء داده‌ای URL کارت OpenPGP، یا در صورت موجود نبودن آن، با استفاده از اثرانگشت ذخیره‌شده.
تغییر وضعیت پرچم forcesig در یک کارت OpenPGP.
ایجاد یک کلید جدید بر روی کارت. از گزینه --force برای رونویسی بر روی یک کلید موجود استفاده کنید. از «help» برای algo استفاده کنید تا فهرستی از الگوریتم‌های شناخته‌شده نمایش داده شود. برای کارت‌های OpenPGP می‌توان چند الگوریتم تعیین کرد. توجه داشته باشید که تولید کلید OpenPGP به صورت تعاملی انجام می‌شود مگر آنکه --algo یا keyref مشخص شده باشند.
آماده‌سازی قابلیت KDF (تابع مشتق کلید) کارت OpenPGP برای این کارت.
تغییر اطلاعات زبان برای کارت. این اطلاعات می‌تواند توسط برنامه‌ها برای خوش‌آمدگویی شخصی‌سازی‌شده استفاده شود. تا ۴ شناسه زبان دورقمی می‌تواند به عنوان اولویت وارد شود. گزینه --clear تمام شناسه‌ها را حذف می‌کند. گنوپی‌جی (GnuPG) از این اطلاعات استفاده نمی‌کند.
LIST [--cards] [--apps] [--info] [--no-key-lookup] [n] [app]
این دستور تمام اطلاعات کارت فعلی را خوانده و آن‌ها را در قالبی خوانا برای انسان نمایش می‌دهد. بخش اول اطلاعات عمومی موجود برای تمام کارت‌ها را نشان می‌دهد. بخش بعدی اطلاعات مربوط به کلیدها را نمایش می‌دهد که به کارت و برنامه کاربردی واقعی بستگی دارند.

با تعیین n، کارت n-ام انتخاب و فهرست می‌شود؛ اگر app نیز داده شده باشد، آن برنامه کاربردی انتخاب می‌گردد. برای انتخاب یک app روی کارت فعلی، از «-» برای n استفاده کنید. به جای n می‌توان از شماره سریال کارت نیز استفاده کرد.

گزینه --cards شماره سریال‌های کارت‌های در دسترس را فهرست می‌کند. گزینه --apps تمام برنامه‌های کاربردی کارت را فهرست می‌کند. گزینه --info یک کارت را انتخاب کرده و شماره سریال آن را چاپ می‌کند. گزینه --no-key-lookup از فهرست کردن کلیدهای منطبق OpenPGP یا X.509 جلوگیری می‌کند.

تنظیم شیء داده‌ای ورود (Login) برای کارت‌های OpenPGP. اگر file داده شود، داده‌ها از آن فایل خوانده می‌شوند. این قابلیت اجازه می‌دهد تا داده‌های باینری در فیلد ورود ذخیره شوند. گزینه --clear شیء داده‌ای ورود را حذف می‌کند.
تنظیم فیلد نام در یک کارت OpenPGP. با گزینه --clear نام ذخیره‌شده از روی کارت پاک می‌شود.
تغییر یا رفع انسداد PINها. توجه داشته باشید که در حالت تعاملی و بدون تعیین pinref منویی برای برخی کارت‌ها نمایش داده می‌شود. در حالت غیرتعاملی و بدون pinref، مقدار پیش‌فرض برای این کارت‌ها استفاده می‌شود. گزینه --reset با کارت‌های TCOS برای بازنشانی PIN با استفاده از PUK یا برعکس استفاده می‌شود؛ گزینه --nullpin برای این کارت‌ها جهت تنظیم PIN اولیه به کار می‌رود.
تغییر شیء داده‌ای خصوصی n در یک کارت OpenPGP. مقدار n باید در بازه ۱ تا ۴ باشد. اگر file داده شود، داده‌ها از آن فایل خوانده می‌شوند. گزینه --clear داده‌ها را پاک می‌کند.
توقف پردازش و خروج از gpg-card.
خواندن گواهی برای کلید certref و ذخیره آن در file. با گزینه --openpgp یک بلوک کلید OpenPGP محصور در یک نوع محتوای اختصاصی CMS (با شناسه OID=1.3.6.1.4.1.11591.2.3.1) مورد انتظار است و در file استخراج می‌شود. توجه داشته باشید که برای کارت‌های فعلی OpenPGP یک گواهی ممکن است تنها در certref با مقدار «OPENPGP.3» موجود باشد.
ارسال یک دستور بازنشانی (Reset) به دیمن کارت.
تغییر اطلاعات عنوان/احترام برای کارت. این اطلاعات می‌تواند توسط برنامه‌ها برای خوش‌آمدگویی شخصی‌سازی‌شده استفاده شود. گزینه --clear این شیء داده‌ای را حذف می‌کند. گنوپی‌جی از این اطلاعات استفاده نمی‌کند.
تغییر پرچم تعامل کاربر (User Interaction Flag). این پرچم مشخص می‌کند که آیا دکمه تأیید روی توکن باید استفاده شود یا خیر. مقدار N باید در بازه ۱ تا ۳ باشد. مقدار «permanent» مانند «on» است با این تفاوت که پرچم پس از تنظیم دیگر قابل تغییر نیست.
رفع انسداد PIN با استفاده از PUK یا کد بازنشانی (Reset Code). توجه داشته باشید که کارت‌های OpenPGP پیش از نگارش ۲ نمی‌توانند از این دستور استفاده کنند؛ به جای آن می‌توان از دستور PASSWD برای تنظیم PIN جدید استفاده کرد.
تنظیم شیء داده‌ای URL در یک کارت OpenPGP. این شیء داده‌ای می‌تواند توسط گزینه --fetch دستور gpg برای بازیابی کلید عمومی کامل استفاده شود. گزینه --clear محتوای آن شیء داده‌ای را حذف می‌کند.
بررسی و اعتبارسنجی PIN مشخص‌شده با chvid یا PIN پیش‌فرض.
نوشتن یک گواهی بر روی کارت تحت شناسه certref. گزینه --clear گواهی را از روی کارت حذف می‌کند. گزینه --openpgp یک بلوک کلید OpenPGP را انتظار دارد و آن را درون یک کانتینر CMS ذخیره می‌کند؛ بلوک کلید از file یا مستقیماً از کلید OpenPGP مشخص‌شده با اثرانگشت fpr دریافت می‌شود.
نوشتن یک شیء کلید خصوصی مشخص‌شده با keygrip بر روی کارت تحت شناسه keyref. گزینه --force امکان رونویسی روی یک کلید موجود را فراهم می‌کند.
چاپ فهرستی از کلیدهای شناسایی‌شده بر روی تمامی کارت‌های متصل. با گزینه --ondisk تنها کلیدهای کارت هوشمندی که یک کپی روی دیسک دارند فهرست می‌شوند. با گزینه --delete-clear-copy کپی‌های کلیدهای کارت هوشمند ذخیره‌شده بر روی دیسک که بدون هیچ‌گونه حفاظتی هستند حذف خواهند شد. با گزینه --delete-protected-copy کپی‌های محافظت‌شده با گذرواژه کلیدهای کارت هوشمند ذخیره‌شده بر روی دیسک حذف خواهند شد.

این دستور کلیدهای سایه (Shadow Keys) ناموجود را ایجاد می‌کند. گزینه‌های حذف، وضعیت کلیدها را پیش از حذف آن‌ها چاپ می‌کنند.

قالب خروجی به این صورت است:

یک رشته هگزادسیمال حاوی شماره سریال کارت.
نوع برنامه کاربردی کارت را مشخص می‌کند؛ برای مثال «OpenPGP» یا «PIV».
یک رشته هگزادسیمال که یک کلید را شناسایی می‌کند.
اسلات برنامه‌ای که کلید در آن بر روی کارت ذخیره شده است؛ برای مثال «OpenPGP.1».
وضعیت کلید. متداول‌ترین مقدار «shadowed» برای کلیدی است که تنها کلید عمومی آن همراه با شماره سریال کارت بر روی دیسک ذخیره شده است. مقدار «clear» نشان می‌دهد که یک نسخه از کلید کارت به صورت محافظت‌نشده روی دیسک ذخیره شده است. مقدار «protected» نشان می‌دهد که یک نسخه از کلید کارت روی دیسک ذخیره شده اما با گذرواژه محافظت می‌شود. مقدار «error» نیز ممکن است در صورت بروز مشکل در خواندن اطلاعات از کارت نمایش داده شود.
دستورهای گوناگون مربوط به توکن‌های Yubikey که cmd می‌تواند یکی از موارد زیر باشد:
فهرست کردن برنامه‌های کاربردی پشتیبانی‌شده و فعال Yubikey.
فعال یا غیرفعال کردن برنامه‌های کاربردی مشخص‌شده یا تمام آن‌ها بر روی رابط داده‌شده.

پشتیبانی از کارت‌های OpenPGP در gpg-card هنوز کامل نیست. برای ویژگی‌های ناموجود، لطفاً همچنان از gpg --card-edit استفاده کنید.

گنوپی‌جی از کارت‌های PIV (سرنام «Personal Identity Verification» طبق استاندارد NIST Special Publication 800-73-4) پشتیبانی می‌کند. این بخش نحوه مقداردهی اولیه (شخصی‌سازی) یک توکن تازه Yubikey دارای برنامه کاربردی PIV را شرح می‌دهد (نیازمند Yubikey-5). فرض ما بر این است که اطلاعات اعتباری هنوز تغییر نکرده‌اند و بدین شرح هستند:

این یک کلید ۲۴ بایتی است که با رشته هگزادسیمال زیر توصیف می‌شود:
010203040506070801020304050607080102030405060708.
این رشته 123456 است.
این رشته 12345678 است.

برای چگونگی تغییر این مقادیر پیش‌فرض، بخش مثال‌ها را ببینید. برای استفاده در محیط‌های عملیاتی، بسیار مهم است که از مقادیر امنی برای آن‌ها استفاده شود. توجه داشته باشید که کلید احراز هویت (Authentication Key) از طریق کادر معمول Pinentry پرسیده نمی‌شود، بلکه باید به صورت دستی وارد شود یا از یک فایل خوانده شود. استفاده از یک دستگاه اختصاصی و امن برای شخصی‌سازی توکن‌ها به شدت پیشنهاد می‌شود.

برای مشاهده محتویات کارت، می‌توان دستور list را صادر کرد. در ادامه از حالت تعاملی استفاده خواهیم کرد (رشته gpg/card> اعلان خط فرمان است). یک خروجی نمونه برای یک کارت تازه به این صورت است:

gpg/card> list
Reader ...........: 1050:0407:X:0
Card type ........: yubikey
Card firmware ....: 5.1.2
Serial number ....: D2760001240102010006090746250000
Application type .: OpenPGP
Version ..........: 2.1
[...]

همان‌طور که از سطر «Application type» مشخص است، GnuPG برنامه کاربردی OpenPGP توکن Yubikey را انتخاب کرده است. دلیل این امر آن است که GnuPG بالاترین اولویت را به برنامه OpenPGP اختصاص می‌دهد. برای استفاده از برنامه کاربردی PIV در Yubikey چند روش وجود دارد:

در Yubikey نگارش ۵ یا بالاتر، برنامه OpenPGP روی Yubikey را می‌توان غیرفعال کرد:

gpg/card> yubikey disable all opgp
gpg/card> yubikey list
Application  USB    NFC
-----------------------
OTP          yes    yes
U2F          yes    yes
OPGP         no     no
PIV          yes    no
OATH         yes    yes
FIDO2        yes    yes
gpg/card> reset

دستور reset لازم است تا سیستم GnuPG کارت را دوباره بخواند. توجه داشته باشید که برنامه‌های غیرفعال‌شده تمام داده‌های خود را حفظ می‌کنند و در هر زمانی می‌توان دوباره آن‌ها را فعال کرد (از ‘help yubikey’ استفاده کنید).

گزینه دیگر، که برای تمامی نسخه‌های Yubikey کار می‌کند، غیرفعال کردن پشتیبانی از کارت‌های OpenPGP در scdaemon است. این کار با افزودن سطر زیر انجام می‌شود:

disable-application openpgp

به فایل ‘~/.gnupg/scdaemon.conf’ و راه‌اندازی مجدد scdaemon، خواه با بستن فرایند یا با استفاده از ‘gpgconf --kill scdaemon’. در نهایت، ترتیب پیش‌فرضی که برنامه‌های کارت توسط scdaemon آزمایش می‌شوند قابل تغییر است. به عنوان مثال، برای اولویت دادن به PIV نسبت به OpenPGP کافی است سطر زیر اضافه شود:

application-priority piv

به فایل ‘~/.gnupg/scdaemon.conf’ و راه‌اندازی مجدد scdaemon. این تنظیم تنها بر روی توکن‌هایی که هم از PIV و هم از OpenPGP پشتیبانی می‌کنند اثر می‌گذارد، اما مانع استفاده از توکن‌های ویژه OpenPGP نمی‌شود.

با به کار بردن یکی از این روش‌ها، دستور list در gpg-card این خروجی را نشان می‌دهد:

gpg/card> list
Reader ...........: 1050:0407:X:0
Card type ........: yubikey
Card firmware ....: 5.1.2
Serial number ....: FF020001008A77C1
Application type .: PIV
Version ..........: 1.0
Displayed s/n ....: yk-9074625
PIN usage policy .: app-pin
PIN retry counter : - 3 -
PIV authentication: [none]
      keyref .....: PIV.9A
Card authenticat. : [none]
      keyref .....: PIV.9E
Digital signature : [none]
      keyref .....: PIV.9C
Key management ...: [none]
      keyref .....: PIV.9D

در صورتی که چند توکن به رایانه متصل باشند، gpg-card تنها یکی را نشان می‌دهد. برای نمایش توکنی دیگر، می‌توان شماره توکن (0, 1, 2, ...) را به عنوان آرگومان به دستور list داد. دستور ‘list --cards’ فهرستی از تمامی توکن‌های متصل را چاپ می‌کند.

توجه داشته باشید که «Displayed s/n» بر روی خود توکن چاپ شده و همچنین در کادرهای Pinentry هنگام درخواست PIN نشان داده می‌شود. چهار اسلات کلید استاندارد همیشه نمایش داده می‌شوند؛ در صورتی که اسلات‌های کلید دیگری نیز مقداردهی شده باشند، آن‌ها نیز نشان داده خواهند شد. کلید PIV authentication (ارجاع داخلی PIV.9A) برای احراز هویت کارت و دارنده کارت استفاده می‌شود. استفاده از کلید خصوصی مربوطه با Application PIN محافظت می‌شود که تنها یک‌بار باید وارد شود و پس از آن کلید تا زمان بازنشانی کارت یا خارج شدن آن از کارت‌خوان یا درگاه USB قابل استفاده خواهد بود. گنوپی‌جی از این کلید به همراه پشتیبانی از Secure Shell (SSH) استفاده می‌کند. کلید Card authentication (PIV.9E) با نام CAK نیز شناخته می‌شود و برای پشتیبانی از برنامه‌های دسترسی فیزیکی به کار می‌رود. این کلید خصوصی توسط PIN محافظت نمی‌شود و بنابراین بلافاصله قابل استفاده است. کلید Digital signature (PIV.9C) برای امضای دیجیتال اسناد استفاده می‌شود. استفاده از کلید خصوصی مربوطه با Application PIN محافظت می‌شود که باید برای هر عملیات امضا وارد شود. کلید Key management (PIV.9D) برای رمزنگاری استفاده می‌شود. استفاده از کلید خصوصی مربوطه با Application PIN محافظت می‌شود که تنها یک‌بار لازم است وارد شود تا عملیات رمزگشایی تا زمان بازنشانی کارت یا جدا شدن آن از کارت‌خوان یا درگاه USB امکان‌پذیر باشد.

اکنون سه کلید از چهار کلید را تولید می‌کنیم. توجه داشته باشید که GnuPG در حال حاضر از کلید Card authentication استفاده نمی‌کند؛ با این حال، آن کلید طبق استاندارد PIV الزامی است و بنابراین ما نیز آن را ایجاد می‌کنیم. ایجاد کلید نیازمند احراز هویت در کارت است. این کار می‌تواند در خط فرمان انجام شود (که کلید را آشکار می‌سازد):

gpg/card> auth 010203040506070801020304050607080102030405060708

یا با خواندن کلید از یک فایل. آن فایل باید شامل یک سطر پایان‌یافته با LF حاوی کلید کدگذاری‌شده هگزادسیمال (همانند بالا) باشد:

gpg/card> auth < myauth.key

همانند همیشه ‘help auth’ راهنمای این دستور را نمایش می‌دهد. اگر از یک کلید نامنطبق استفاده شود، پیام خطا چاپ خواهد شد. احراز هویت تا زمان بازنشانی کارت یا تا زمان خارج کردن کارت از کارت‌خوان یا درگاه USB معتبر است. توجه داشته باشید که در حالت غیرتعاملی نماد ‘<’ باید کوت شود تا پوسته آن را به عنوان نماد ریدایرکت خود تفسیر نکند.

در اینجا دستورهای واقعی برای ایجاد کلیدها آورده شده است:

gpg/card> generate --algo=nistp384 PIV.9A
PIV card no. yk-9074625 detected
gpg/card> generate --algo=nistp256 PIV.9E
PIV card no. yk-9074625 detected
gpg/card> generate --algo=rsa2048 PIV.9C
PIV card no. yk-9074625 detected

اگر قبلاً کلیدی برای یکی از اسلات‌ها ایجاد شده باشد، خطایی چاپ می‌شود؛ برای ایجاد کلید جدید در هر صورت، می‌توان از گزینه ‘--force’ استفاده کرد. توجه داشته باشید که تنها کلیدهای خصوصی و عمومی ایجاد شده‌اند و هیچ گواهی در اسلات‌های کلید ذخیره نشده است. در حقیقت، GnuPG از روش غیراستاندارد خود برای ذخیره تنها کلید عمومی به جای گواهی استفاده می‌کند. سایر برنامه‌ها تا زمانی که از gpgsm یا ابزار دیگری برای ساخت و ذخیره گواهی‌های مربوطه استفاده نشود، قادر به استفاده از این کلیدها نخواهند بود. بیایید ببینیم دستور list اکنون چه چیزی را نمایش می‌دهد:

gpg/card> list
Reader ...........: 1050:0407:X:0
Card type ........: yubikey
Card firmware ....: 5.1.2
Serial number ....: FF020001008A77C1
Application type .: PIV
Version ..........: 1.0
Displayed s/n ....: yk-9074625
PIN usage policy .: app-pin
PIN retry counter : - 3 -
PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E
      keyref .....: PIV.9A  (auth)
      algorithm ..: nistp384
Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C
      keyref .....: PIV.9E  (auth)
      algorithm ..: nistp256
Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED
      keyref .....: PIV.9C  (sign,cert)
      algorithm ..: rsa2048
Key management ...: [none]
      keyref .....: PIV.9D

اطلاعات اصلی برای هر کلید keygrip است، یک رشته هگزادسیمال ۴۰ بایتی که کلید را شناسایی می‌کند. این keygrip یک شناسه منحصر‌به‌فرد برای پارامترهای مشخص یک کلید است. این مقدار توسط gpg-agent و سایر بخش‌های GnuPG برای مرتبط ساختن یک کلید خصوصی با قالب گواهی خاص پروتکل مربوطه (X.509، OpenPGP یا SecureShell) استفاده می‌شود. در زیر keygrip ارجاع کلید به همراه قابلیت‌های استفاده از کلید نمایش داده می‌شوند. در پایان الگوریتم در قالبی که توسط gpg استفاده می‌شود چاپ می‌گردد. در این مرحله اطلاعات دیگری نمایش داده نمی‌شود زیرا برای این کلیدهای جدید gpg قادر به یافتن گواهی‌های منطبق نخواهد بود.

اگرچه می‌توانستیم کلید Key management را نیز با دستور generate بسازیم، اما آن کلید را خارج از کارت ایجاد می‌کنیم تا یک نسخه پشتیبان وجود داشته باشد. برای دستیابی به این منظور، کلید باید با gpg یا gpgsm ایجاد شود یا در یکی از این ابزارها وارد (Import) گردد. در مثال ما، یک گواهی خودامضا (Self-signed) X.509 می‌سازیم (ابتدا با دستور quit از ابزار gpg-card خارج شوید):

$ gpgsm --gen-key -o encr.crt
   (1) RSA
   (2) Existing key
   (3) Existing key from card
Your selection? 1
What keysize do you want? (3072) 2048
Requested keysize is 2048 bits
Possible actions for a RSA key:
   (1) sign, encrypt
   (2) sign
   (3) encrypt
Your selection? 3
Enter the X.509 subject name: CN=Encryption key for yk-9074625,O=example,C=DE
Enter email addresses (end with an empty line):
> otto@example.net
>
Enter DNS names (optional; end with an empty line):
>
Enter URIs (optional; end with an empty line):
>
Create self-signed certificate? (y/N) y
These parameters are used:
    Key-Type: RSA
    Key-Length: 2048
    Key-Usage: encrypt
    Serial: random
    Name-DN: CN=Encryption key for yk-9074625,O=example,C=DE
    Name-Email: otto@example.net
Proceed with creation? (y/N)
Now creating self-signed certificate.  This may take a while ...
gpgsm: about to sign the certificate for key: &34798AAFE0A7565088101CC4AE31C5C8C74461CB
gpgsm: certificate created
Ready.
$ gpgsm --import encr.crt
gpgsm: certificate imported
gpgsm: total number processed: 1
gpgsm:               imported: 1

به مرحله آخر که گواهی ایجادشده را ایمپورت کرد توجه کنید. اگر به جای گواهی خودامضا یک درخواست امضای گواهی (CSR) ایجاد کرده و آن را به یک مرجع صدور گواهی (CA) ارسال می‌کردید، همین مرحله ایمپورت را با گواهی دریافت‌شده از CA انجام می‌دادید. به keygrip (که با یک علامت & پیشوند شده است) همان‌طور که هنگام ایجاد گواهی نشان داده شد توجه کنید یا با استفاده از ‘gpgsm --with-keygrip -k otto@example.net’ دوباره آن را فهرست کنید. اکنون برای انتقال کلید و گواهی به کارت، gpg-card را دوباره اجرا کرده و وارد کنید:

gpg/card> writekey PIV.9D 34798AAFE0A7565088101CC4AE31C5C8C74461CB
gpg/card> writecert PIV.9D < encr.crt

اگر یک عبارت عبور (Passphrase) برای محافظت از کلید خصوصی وارد کرده باشید، از طریق اعلان Pinentry از شما درخواست خواهد شد. در صورت موفقیت، کلید و گواهی بر روی کارت نوشته شده‌اند و دستور list نمایش می‌دهد:

[...]
Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB
      keyref .....: PIV.9D  (encr)
      algorithm ..: rsa2048
      used for ...: X.509
        user id ..: CN=Encryption key for yk-9074625,O=example,C=DE
        user id ..: <otto@example.net>

در صورتی که از همان کلید (مشخص‌شده با keygrip) برای چندین گواهی استفاده شده باشد، چند بخش «used for» را مشاهده خواهید کرد. با این کار کلید رمزنگاری اکنون کاملاً کاربردی است و می‌تواند برای رمزگشایی پیام‌های رمزگذاری‌شده برای این گواهی استفاده شود. دقت کنید: کلید اصلی همچنان بر روی دیسک ذخیره است و باید به یک رسانه پشتیبان انتقال یابد. این کار را می‌توان به سادگی با کپی کردن فایل ‘34798AAFE0A7565088101CC4AE31C5C8C74461CB.key’ از پوشه ‘~/.gnupg/private-keys-v1.d/’ به رسانه پشتیبان و حذف فایل در محل اصلی آن انجام داد.

مثال پایانی، ایجاد یک گواهی خودامضا برای امضاهای دیجیتال است. با quit یا فشردن کلیدهای Control-D از gpg-card خارج شده و از gpgsm استفاده کنید:

$ gpgsm --learn
$ gpgsm --gen-key -o sign.crt
Please select what kind of key you want:
   (1) RSA
   (2) Existing key
   (3) Existing key from card
Your selection? 3
Serial number of the card: FF020001008A77C1
Available keys:
   (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384
   (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256
   (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048
   (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048
Your selection? 3
Possible actions for a RSA key:
   (1) sign, encrypt
   (2) sign
   (3) encrypt
Your selection? 2
Enter the X.509 subject name: CN=Signing key for yk-9074625,O=example,C=DE
Enter email addresses (end with an empty line):
> otto@example.net
>
Enter DNS names (optional; end with an empty line):
>
Enter URIs (optional; end with an empty line):
>
Create self-signed certificate? (y/N)
These parameters are used:
    Key-Type: card:PIV.9C
    Key-Length: 1024
    Key-Usage: sign
    Serial: random
    Name-DN: CN=Signing key for yk-9074625,O=example,C=DE
    Name-Email: otto@example.net
Proceed with creation? (y/N) y
Now creating self-signed certificate.  This may take a while ...
gpgsm: about to sign the certificate for key: &32A6C6FAFCB8421878608AAB452D5470DD3223ED
gpgsm: certificate created
Ready.
$ gpgsm --import sign.crt
gpgsm: certificate imported
gpgsm: total number processed: 1
gpgsm:               imported: 1

استفاده از ‘gpgsm --learn’ در حال حاضر لازم است تا gpg-agent بداند چه کلیدهایی بر روی کارت موجود هستند. نیاز به این دستور در نهایت برطرف خواهد شد. دستورهای باقی‌مانده مشابه ایجاد کلید روی دیسک هستند. با این وجود، در اینجا کلید «Digital signature» را انتخاب می‌کنیم. در طول فرایند ایجاد، Application PIN کارت از شما درخواست خواهد شد. گام پایانی، نوشتن گواهی بر روی کارت با استفاده از gpg-card است:

gpg/card> writecert PIV.9C < sign.crt

با اجرای دوباره list، کارت کاملاً مقداردهی‌شده را مشاهده خواهیم کرد:

Reader ...........: 1050:0407:X:0
Card type ........: yubikey
Card firmware ....: 5.1.2
Serial number ....: FF020001008A77C1
Application type .: PIV
Version ..........: 1.0
Displayed s/n ....: yk-9074625
PIN usage policy .: app-pin
PIN retry counter : - [verified] -
PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E
      keyref .....: PIV.9A  (auth)
      algorithm ..: nistp384
Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C
      keyref .....: PIV.9E  (auth)
      algorithm ..: nistp256
Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED
      keyref .....: PIV.9C  (sign,cert)
      algorithm ..: rsa2048
      used for ...: X.509
        user id ..: CN=Signing key for yk-9074625,O=example,C=DE
        user id ..: <otto@example.net>
Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB
      keyref .....: PIV.9D  (encr)
      algorithm ..: rsa2048
      used for ...: X.509
        user id ..: CN=Encryption key for yk-9074625,O=example,C=DE
        user id ..: <otto@example.net>

اکنون امکان امضا کردن و رمزنگاری با استفاده از این کارت از طریق gpgsm و به کار بردن کلید «PIV authentication» با ssh وجود دارد:

$ ssh-add -l
384 SHA256:0qnJ0Y0ehWxKcx2frLfEljf6GCdlO55OZed5HqGHsaU cardno:yk-9074625 (ECDSA)

همانند معمول از ssh-add با حرف بزرگ ‘-L’ برای فهرست کردن کلید عمومی ssh استفاده کنید. برای استفاده از این گواهی‌ها با تاندربرد (Thunderbird) یا موزیلا، لطفاً برای جزئیات به راهنمای Scute مراجعه فرمایید.

اگر مایلید از همان کلیدهای PIV برای OpenPGP نیز استفاده کنید (برای مثال در یک Yubikey برای جلوگیری از جابه‌جایی میان OpenPGP و PIV)، این کار نیز امکان‌پذیر است:

$ gpgsm --learn
$ gpg --full-gen-key
Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
  (14) Existing key from card
Your selection? 14
Serial number of the card: FF020001008A77C1
Available keys:
   (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 (auth)
   (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 (auth)
   (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 (cert,sign)
   (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 (encr)
Your selection? 3
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)
Key does not expire at all
Is this correct? (y/N) y
GnuPG needs to construct a user ID to identify your key.
Real name:
Email address: otto@example.net
Comment:
You selected this USER-ID:
    "otto@example.net"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
gpg: key C3AFA9ED971BB365 marked as ultimately trusted
gpg: revocation certificate stored as '[...]D971BB365.rev'
public and secret key created and signed.
Note that this key cannot be used for encryption.  You may want to use
the command "--edit-key" to generate a subkey for this purpose.
pub   rsa2048 2019-04-04 [SC]
      7F899AE2FB73159DD68A1B20C3AFA9ED971BB365
uid                      otto@example.net

توجه داشته باشید که دو بار از شما خواسته می‌شود PIN کارت PIV خود را وارد کنید. اگر gpg را در حالت --expert اجرا کنید، گزینه تغییر پرچم‌های کاربرد کلید (Usage flags) نیز در اختیارتان قرار می‌گیرد. رونوشت ترمینال زیر نحوه افزودن زیرکلید رمزنگاری را نشان می‌دهد:

$ gpg --edit-key 7F899AE2FB73159DD68A1B20C3AFA9ED971BB365
Secret key is available.
sec  rsa2048/C3AFA9ED971BB365
     created: 2019-04-04  expires: never       usage: SC
     card-no: FF020001008A77C1
     trust: ultimate      validity: ultimate
[ultimate] (1). otto@example.net
gpg> addkey
Secret parts of primary key are stored on-card.
Please select what kind of key you want:
   (3) DSA (sign only)
   (4) RSA (sign only)
   (5) Elgamal (encrypt only)
   (6) RSA (encrypt only)
  (14) Existing key from card
Your selection? 14
Serial number of the card: FF020001008A77C1
Available keys:
   (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 (auth)
   (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 (auth)
   (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 (cert,sign)
   (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 (encr)
Your selection? 4
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)
Key does not expire at all
Is this correct? (y/N) y
Really create? (y/N) y
sec  rsa2048/C3AFA9ED971BB365
     created: 2019-04-04  expires: never       usage: SC
     card-no: FF020001008A77C1
     trust: ultimate      validity: ultimate
ssb  rsa2048/7067860A98FCE6E1
     created: 2019-04-04  expires: never       usage: E
     card-no: FF020001008A77C1
[ultimate] (1). otto@example.net
gpg> save

اکنون می‌توانید از کارت PIV خود همراه با gpg نیز استفاده کنید.

دستور gpg-card این گزینه‌ها را درک می‌کند:

این گزینه در حال حاضر هیچ تاثیری ندارد.
نوشتن رشته‌های وضعیت ویژه در توصیف‌گر فایل n. این برنامه تنها پیام‌های وضعیت SUCCESS یا FAILURE را بازمی‌گرداند که زمانی سودمند هستند که فراخواننده از رویکرد دابل‌فورک (Double fork) استفاده کرده و نمی‌تواند به سادگی کد بازگشتی فرایند را به دست آورد.
فعال کردن خروجی اطلاعاتی بیشتر.
غیرفعال کردن تقریباً تمام خروجی‌های اطلاعاتی.
چاپ نگارش برنامه و خروج.
نمایش یک صفحه راهنمای کوتاه و خروج.
عدم اجرای خودکار gpg-agent در صورتی که هنوز اجرا نشده باشد و به سرویس آن نیاز باشد. این گزینه عمدتاً در سیستم‌هایی کاربرد دارد که ارتباط با gpg-agent به سیستم‌های دیگری ریدایرکت شده است.
در حالت تعاملی، تاریخچه خط فرمان معمولاً در فایلی در زیر پوشه خانگی GnuPG ذخیره و بازیابی می‌شود. این گزینه استفاده از آن فایل را مهار می‌کند.
تعیین برنامه کارگزار جهت اجرا در صورتی که هیچ کارگزاری در حال اجرا نباشد. مقدار پیش‌فرض با اجرای gpgconf همراه با گزینه --list-dirs تعیین می‌شود.
تعیین باینری gpg غیرپیش‌فرض برای استفاده در برخی دستورها.
تعیین باینری gpgsm غیرپیش‌فرض برای استفاده در برخی دستورها.
تغییر کاربر فعلی به uid که می‌تواند یک عدد یا یک نام کاربری باشد. این گزینه را می‌توان از حساب ریشه (root) برای اجرای gpg-card برای کاربری دیگر استفاده کرد. اگر uid شناسه کاربری فعلی نباشد، یک PATH استاندارد تنظیم شده و متغیر محیطی GNUPGHOME حذف می‌گردد. برای نادیده گرفتن مورد دوم می‌توان از گزینه --homedir استفاده کرد. این گزینه تنها زمانی اثر دارد که در خط فرمان استفاده شود. این گزینه در حال حاضر در ویندوز هیچ تاثیری ندارد.

scdaemon(1)

مه ۲۰۲۵ gnupg