.TH NITROCLI 1 2021-04-24
.SH "نام (NAME)"
nitrocli \- دسترسی به دستگاه‌های Nitrokey
.SH "خلاصه دستور (SYNOPSIS)"
.B nitrocli
\fIcommand\fR
[\fIarguments\fR]
.SH "توضیحات (DESCRIPTION)"
\fBnitrocli\fR امکان دسترسی به دستگاه‌های Nitrokey را فراهم می‌کند.
این ابزار از Nitrokey Pro، Nitrokey Storage و Librem Key پشتیبانی می‌کند.
از آن می‌توان برای دسترسی به حجم رمزگذاری‌شده، مولد گذرواژهٔ یک‌بارمصرف (OTP) و گاوصندوق گذرواژه (password safe) استفاده کرد.
.SS "انتخاب دستگاه (Device selection)"
به‌طور پیش‌فرض، \fBnitrocli\fR به هر دستگاه متصل‌شدهٔ Nitrokey وصل می‌شود.
می‌توانید از گزینه‌های \fB\-\-model\fR، \fB\-\-serial-number\fR و \fB\-\-usb-path\fR
برای انتخاب دستگاه مورد نظر جهت اتصال استفاده کنید.
اگر بیش از یک دستگاه متصل‌شدهٔ Nitrokey با این فیلتر مطابقت داشته باشد، یا اگر چندین دستگاه Nitrokey متصل باشند و هیچ‌کدام از گزینه‌های فیلتر تنظیم نشده باشد، \fBnitrocli\fR با خطا متوقف می‌شود.
از دستور \fBlist\fR برای فهرست کردن تمام دستگاه‌های متصل به همراه مسیر USB، مدل و شماره سریال آن‌ها (در صورت موجود بودن) استفاده کنید.
.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-m\fR, \fB\-\-model librem\fR|\fBpro\fR|\fBstorage\fR
محدود کردن اتصالات به مدل دستگاه داده‌شده؛ بخش «انتخاب دستگاه» (Device selection) را ببینید.
.TP
\fB\-\-serial-number \fIserial-number\fR
محدود کردن اتصالات به شماره سریال داده‌شده؛ بخش «انتخاب دستگاه» (Device selection) را ببینید.
\fIserial-number\fR باید یک رشتهٔ هگزادسیمال (hex) با پیشوند اختیاری 0x باشد.
این گزینه می‌تواند چندین بار مشخص شود تا هر یک از شماره سریال‌های داده‌شده مجاز شناخته شوند.
دستگاه‌های Nitrokey Storage هرگز با این محدودیت مطابقت نخواهند داشت، چرا که شماره سریال خود را در توصیف‌گر دستگاه USB (USB device descriptor) آشکار نمی‌کنند.
.TP
\fB\-\-usb-path \fIusb-path\fR
محدود کردن اتصالات به مسیر USB داده‌شده؛ بخش «انتخاب دستگاه» (Device selection) را ببینید.
.TP
\fB\-\-no\-cache\fR
اگر این گزینه تنظیم شود، nitrocli هیچ‌یک از رازهای استعلام‌شده را با استفاده از \fBgpg\-agent\fR(1) در حافظهٔ موقت (cache) ذخیره نمی‌کند، بلکه هر بار که به آن‌ها نیاز باشد، آن‌ها را درخواست می‌کند.
توجه داشته باشید که این گزینه باعث پاک شدن رازهای ذخیره‌شده در حافظهٔ موقت نمی‌شود.
اگر رازی از قبل در حافظهٔ موقت موجود باشد نادیده گرفته می‌شود، اما در غیر این صورت دست‌نخورده باقی می‌ماند.
از دستور \fBpin clear\fR برای پاک کردن رازها از حافظهٔ موقت استفاده کنید.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
فعال‌سازی ثبت گزارش‌های (logging) اضافی و کنترل میزان جزئیات آن. گزارش‌های فعال‌شده از طریق این گزینه در جریان خطای استاندارد (stderr) نمایش داده می‌شوند. این گزینه می‌تواند چندین بار مشخص شود. یک بار درج آن، هشدارهای اضافی را نشان می‌دهد. در صورت سه بار درج، دستورهای ارسال‌شده به دستگاه نشان داده می‌شوند و با چهار بار درج، تمام ارتباطات با دستگاه قابل مشاهده خواهد بود. ارائهٔ پنج بارهٔ این گزینه بالاترین سطح جزئیات را فعال می‌کند.
.TP
\fB\-V\fR, \fB\-\-version\fR
نمایش نسخهٔ nitrocli و خروج.
.SH "دستورها (COMMANDS)"
.SS "عمومی (General)"
.TP
.B nitrocli list \fR[\fB-n\fR|\fB\-\-no-connect\fR]
فهرست کردن تمام دستگاه‌های Nitrokey متصل‌شده.
این دستور فهرستی از مسیر USB، مدل و شماره سریال تمام دستگاه‌های متصل Nitrokey را چاپ می‌کند.
برای دسترسی به شماره سریال یک دستگاه Nitrokey Storage، لازم است \fBnitrocli\fR به آن متصل شود.
برای صرف‌نظر کردن از شماره سریال دستگاه‌های Nitrokey Storage به‌جای اتصال به آن‌ها، گزینهٔ \fB\-\-no-connect\fR را تنظیم کنید.
.TP
.B nitrocli status
چاپ وضعیت دستگاه Nitrokey متصل، شامل شماره سریال دانگل، نسخهٔ سفت‌افزار (firmware) و تعداد دفعات مجاز باقیمانده برای ورود PIN. اگر دستگاه یک Nitrokey Storage باشد، اطلاعات مربوط به فضای ذخیره‌سازی از جمله شماره سریال کارت SD، میزان استفاده از کارت SD در طول این چرخهٔ روشن بودن، وضعیت رمزگذاری و وضعیت حجم‌ها (volumes) نیز چاپ می‌شود.
.TP
.B nitrocli lock
قفل کردن Nitrokey.
این دستور گاوصندوق گذرواژه را قفل می‌کند (بخش «گاوصندوق گذرواژه» (Password safe) را ببینید). در Nitrokey Storage، همچنین تمام حجم‌های فعال رمزگذاری‌شده یا مخفی را می‌بندد (بخش «فضای ذخیره‌سازی» (Storage) را ببینید).
.TP
.B nitrocli reset \fR[\fB\-\-only-aes-key\fR]
بازنشانی Nitrokey به تنظیمات کارخانه.
این دستور یک بازنشانی کارخانه‌ای روی کارت هوشمند OpenPGP انجام می‌دهد، حافظهٔ فلش را پاک می‌کند و یک کلید AES جدید می‌سازد.
کد PIN کاربر به 123456 و PIN مدیر (admin) به 12345678 بازنشانی می‌شود.

اگر گزینهٔ \fB\-\-only-aes-key\fR تنظیم شده باشد، این دستور بازنشانی کامل به تنظیمات کارخانه را انجام نمی‌دهد، بلکه تنها یک کلید AES جدید ایجاد می‌کند.
کلید AES برای نمونه جهت رمزگذاری گاوصندوق گذرواژه استفاده می‌شود.

این دستور به PIN مدیر نیاز دارد.
برای جلوگیری از فراخوانی‌های تصادفی این دستور، کاربر باید PIN را وارد کند، حتی اگر در حافظهٔ موقت ذخیره شده باشد.

.SS "فضای ذخیره‌سازی (Storage)"
دستگاه Nitrokey Storage به همراه یک فضای ذخیره‌سازی ارائه می‌شود. این فضا از یک ناحیهٔ \fIرمزگذاری‌نشده (unencrypted)\fR و یک ناحیهٔ \fIرمزگذاری‌شده (encrypted)\fR با اندازه‌های ثابت تشکیل شده است که هر یک در قالب دستگاه‌های بلوکی (block devices) در دسترس کاربر قرار می‌گیرند. ناحیهٔ رمزگذاری‌شده می‌تواند به‌صورت اختیاری با حداکثر چهار حجم \fIمخفی (hidden)\fR هم‌پوشانی (overlay) شود. به دلیل این هم‌پوشانی (که برای دستیابی به انکارپذیری موجهِ وجود حجم‌های مخفی لازم است)، مسئولیت اطمینان از این‌که داده‌های روی حجم رمزگذاری‌شده با داده‌های روی یکی از حجم‌های مخفی تداخل نداشته باشند، بر عهدهٔ کاربر است.
.TP
\fBnitrocli unencrypted set \fImode\fR
تغییر حالت خواندن-نوشتن حجم.
\fImode\fR نوع حالتی است که می‌خواهید به آن تغییر دهید: \fBread-write\fR برای خواندنی و نوشتنی کردن حجم، یا \fBread-only\fR برای ایجاد دسترسی فقط‌خواندنی.
این دستور نیازمند PIN مدیر است.

توجه داشته باشید که این دستور به سفت‌افزار نسخهٔ 0.51 یا بالاتر نیاز دارد. نسخه‌های قدیمی‌تر پشتیبانی نمی‌شوند.
.TP
\fBnitrocli encrypted open
باز کردن حجم رمزگذاری‌شده روی Nitrokey Storage.
کد PIN کاربر که برای باز کردن حجم لازم است، با استفاده از \fBpinentry\fR(1) استعلام شده و توسط \fBgpg\-agent\fR(1) در حافظهٔ موقت ذخیره می‌شود.
.TP
\fBnitrocli encrypted close
بستن حجم رمزگذاری‌شده روی Nitrokey Storage.
.TP
\fBnitrocli hidden create \fIslot\fR \fIstart\fR \fIend\fR
ایجاد یک حجم مخفی جدید در داخل حجم رمزگذاری‌شده. \fIslot\fR باید یکی از چهار شیار (slot) موجود را مشخص کند. \fIstart\fR و \fIend\fR به ترتیب موقعیت‌های آغاز و پایان حجم مخفی درون حجم رمزگذاری‌شده را بر حسب درصدی از اندازهٔ حجم رمزگذاری‌شده مشخص می‌کنند.
این دستور به یک گذرواژه نیاز دارد که بعداً برای پیدا کردن حجم مخفی جهت باز کردن استفاده می‌شود. برخلاف PIN، این گذرواژه توسط \fBgpg\-agent\fR(1) در حافظهٔ موقت ذخیره نمی‌شود.

به عنوان یک راهنما برای ایجاد حجم‌های مخفی جدید، دستور \fBstatus\fR محدوده‌ای از کارت SD را ارائه می‌دهد که در طول این چرخهٔ روشن بودن داده‌ای روی آن نوشته نشده است.
.TP
\fBnitrocli hidden open
باز کردن یک حجم مخفی. حجمی که باز می‌شود بر اساس گذرواژهٔ واردشده تعیین می‌گردد، که باید حداقل دارای شش نویسه باشد. در هر لحظه تنها یک حجم مخفی می‌تواند فعال باشد و حجم‌هایی که قبلاً باز شده‌اند به‌طور خودکار بسته خواهند شد. به‌طور مشابه، اگر حجم رمزگذاری‌شده باز باشد، بسته خواهد شد.
.TP
\fBnitrocli hidden close
بستن یک حجم مخفی.
.TP
\fBnitrocli fill \fR[\fB\-a\fR|\fB\-\-attach\fR]
پر کردن کارت SD با داده‌های تصادفی، که تمام داده‌های موجود را رونویسی (overwrite) می‌کند.
انجام این عملیات برای یک کارت SD با ظرفیت 16 گیبی‌بایت (GiB) حدود یک ساعت طول می‌کشد.
این عملیات را نمی‌توان لغو کرد، حتی اگر فرآیند \fBnitrocli\fR پیش از اتمام آن متوقف شود.

این دستور نیازمند PIN مدیر است.
برای جلوگیری از فراخوانی‌های تصادفی این دستور، کاربر باید PIN را وارد کند، حتی اگر در حافظهٔ موقت (cache) ذخیره شده باشد.

اگر گزینهٔ \fB\-\-attach\fR تنظیم شده باشد، این دستور عملیات پر کردن جدیدی را آغاز نمی‌کند.
در عوض بررسی می‌کند که آیا عملیات پر کردنی در حال حاضر روی دستگاه در حال اجرا است یا خیر و پیشرفت آن را نشان می‌دهد..SS گذرواژه‌های یک‌بارمصرف
دستگاه‌های Nitrokey Pro، Nitrokey Storage و Librem Key از تولید گذرواژه‌های
یک‌بارمصرف با استفاده از الگوریتم HOTP مطابق با RFC 4226 یا الگوریتم TOTP
مطابق با RFC 6238 پشتیبانی می‌کنند.
داده‌های مورد نیاز \(en یک نام و کلید محرمانه \(en در اسلات‌ها (slots) ذخیره می‌شوند.
در حال حاضر، دستگاه‌های Nitrokey سه اسلات HOTP و ۱۵ اسلات TOTP ارائه می‌دهند.
شماره‌گذاری اسلات‌ها برای هر الگوریتم از صفر شروع می‌شود.
.P
الگوریتم TOTP نسخه‌ای تغییریافته از الگوریتم HOTP است که از زمان فعلی نیز
استفاده می‌کند.
بنابراین، ساعت Nitrokey باید با ساعت برنامه‌ای که گذرواژهٔ یک‌بارمصرف را درخواست
می‌کند همگام باشد.
.TP
\fBnitrocli otp get \fIslot \fR[\fB\-a\fR|\fB\-\-algorithm \fIalgorithm\fR] \
\fB[\-t\fR|\fB\-\-time \fItime\fR]
تولید یک گذرواژهٔ یک‌بارمصرف.
\fIslot\fR شمارهٔ اسلاتی است که گذرواژه از آن تولید می‌شود.
\fIalgorithm\fR الگوریتم OTP مورد استفاده است.
مقادیر ممکن عبارتند از \fBhotp\fR برای الگوریتم HOTP مطابق با RFC 4226 و
\fBtotp\fR برای الگوریتم TOTP مطابق با RFC 6238 (پیش‌فرض).
به‌طور پیش‌فرض، اگر الگوریتم TOTP انتخاب شده باشد، این دستور ساعت Nitrokey را
روی ساعت سیستم تنظیم می‌کند.
اگر \fB\-\-time\fR مشخص شده باشد، در عوض روی \fItime\fR تنظیم می‌شود که باید یک
برچسب زمانی یونیکس (Unix timestamp) باشد (یعنی تعداد ثانیه‌ها از 1970-01-01 00:00:00 UTC).
این دستور ممکن است به PIN کاربر نیاز داشته باشد (بخش پیکربندی را ببینید).
.TP
\fBnitrocli otp set \fIslot name secret\fR|\fB-\fR \
\fR[\fB\-a\fR|\fB\-\-algorithm \fIalgorithm\fR] \
[\fB\-d\fR|\fB\-\-digits \fIdigits\fR] [\fB\-c\fR|\fB\-\-counter \fIcounter\fR] \
[\fB\-t\fR|\fB\-\-time-window \fItime-window\fR] \
[\fB-f\fR|\fB\-\-format ascii\fR|\fBbase32\fR|\fBhex\fR]
پیکربندی یک اسلات گذرواژهٔ یک‌بارمصرف.
\fIslot\fR شمارهٔ اسلات جهت پیکربندی است.
\fIname\fR نام اسلات است (نباید خالی باشد).
\fIsecret\fR مقدار محرمانه‌ای است که در آن اسلات ذخیره می‌شود.
اگر \fIsecret\fR روی \fB-\fR تنظیم شود، کلید محرمانه از ورودی استاندارد
خوانده می‌شود.

گزینهٔ \fB\-\-format\fR قالب کلید محرمانه را تعیین می‌کند.
اگر روی \fBascii\fR تنظیم شود، هر نویسه از کلید محرمانهٔ ارائه‌شده به عنوان کد
ASCII یک بایت تفسیر می‌شود.
اگر روی \fBbase32\fR تنظیم شود، کلید محرمانه به عنوان یک رشتهٔ base32 بر اساس
RFC 4648 تفسیر می‌شود.
اگر روی \fBhex\fR تنظیم شود، هر دو نویسه به عنوان مقدار هگزادسیمال یک بایت
تفسیر می‌شوند.
مقدار پیش‌فرض \fBbase32\fR است.

\fIalgorithm\fR الگوریتم OTP مورد استفاده است.
مقادیر ممکن عبارتند از \fBhotp\fR برای الگوریتم HOTP مطابق با RFC 4226 و
\fBtotp\fR برای الگوریتم TOTP مطابق با RFC 6238 (پیش‌فرض).
\fIdigits\fR تعداد ارقام گذرواژهٔ یک‌بارمصرف است.
مقادیر مجاز ۶ و ۸ هستند (پیش‌فرض: ۶).
\fIcounter\fR در صورت استفاده از الگوریتم HOTP، شمارندهٔ اولیه است (پیش‌فرض: ۰).
\fItime-window\fR پنجرهٔ زمانی مورد استفاده در TOTP بر حسب ثانیه است (پیش‌فرض: ۳۰).
.TP
\fBnitrocli otp clear \fIslot \fR[\fB\-a\fR|\fB\-\-algorithm \fIalgorithm\fR]
حذف نام و کلید محرمانهٔ ذخیره‌شده در یک اسلات گذرواژهٔ یک‌بارمصرف.
\fIslot\fR شمارهٔ اسلاتی است که باید پاک شود.
\fIalgorithm\fR الگوریتم OTP مورد استفاده است.
مقادیر ممکن عبارتند از \fBhotp\fR برای الگوریتم HOTP مطابق با RFC 4226 و
\fBtotp\fR برای الگوریتم TOTP مطابق با RFC 6238 (پیش‌فرض).
.TP
\fBnitrocli otp status \fR[\fB\-a\fR|\fB\-\-all\fR]
فهرست کردن تمام اسلات‌های OTP.
اگر \fB\-\-all\fR مشخص نشده باشد، اسلات‌های خالی نادیده گرفته می‌شوند.

.SS پیکربندی
دستگاه‌های Nitrokey دارای چهار تنظیم پیکربندی هستند: کلیدهای Num Lock، Caps Lock و
Scroll Lock می‌توانند به یک اسلات HOTP نگاشت شوند، و تولید OTP می‌تواند طوری
تنظیم شود که نیازمند PIN کاربر باشد.
.TP
\fBnitrocli config get\fR
چاپ پیکربندی فعلی Nitrokey.
.TP
\fBnitrocli config set \fR\
[[\fB\-n\fR|\fB\-\-num-lock \fIslot\fR] | [\fB\-N\fR|\fB\-\-no\-num-lock\fR]] \
[[\fB\-c\fR|\fB\-\-caps-lock \fIslot\fR] | [\fB\-C\fR|\fB\-\-no\-caps-lock\fR]] \
[[\fB\-s\fR|\fB\-\-scroll-lock \fIslot\fR] | [\fB\-S\fR|\fB\-\-no\-scroll-lock\fR]] \
[[\fB\-o\fR|\fB\-\-otp\-pin\fR] | [\fB\-O\fR|\fB\-\-no\-otp\-pin\fR]]
به‌روزرسانی پیکربندی Nitrokey.
این دستور نیازمند PIN مدیر (admin PIN) است.

با گزینه‌های \fB\-\-num-lock\fR، \fB\-\-caps-lock\fR و \fB\-\-scroll-lock\fR،
می‌توان اتصال‌های مربوطه را تنظیم کرد.
\fIslot\fR شمارهٔ اسلات HOTP است که کلید به آن متصل می‌شود.
اگر \fB\-\-no\-num-lock\fR، \fB\-\-no\-caps-lock\fR یا \fB\-\-no\-scroll-lock\fR
تنظیم شود، اتصال مربوطه غیرفعال می‌شود.
دو گزینهٔ متناظر با یکدیگر مانعة‌الجمع هستند.

اگر \fB\-\-otp\-pin\fR تنظیم شود، برای تولید گذرواژه‌های یک‌بارمصرف با استفاده
از دستور \fBotp get\fR به PIN کاربر نیاز خواهد بود.
اگر \fB\-\-no\-otp\-pin\fR تنظیم شود، تولید OTP می‌تواند بدون PIN انجام گیرد.
این دو گزینه مانعة‌الجمع هستند.

.SS گاوصندوق گذرواژه
دستگاه‌های Nitrokey Pro، Nitrokey Storage و Librem Key یک گاوصندوق گذرواژه
(PWS) با ۱۶ اسلات ارائه می‌دهند.
در هر یک از این اسلات‌ها می‌توانید یک نام، یک شناسهٔ ورود (login) و یک گذرواژه
ذخیره کنید.
مخزن PWS رمزگذاری نشده است، اما توسط سفت‌افزار (firmware) با PIN کاربر محافظت می‌شود.
به‌محض اینکه PWS توسط یکی از دستورهای فهرست‌شده در زیر باز شود، بدون احراز هویت
قابل دسترسی خواهد بود.
می‌توانید از دستور \fBlock\fR برای قفل کردن گاوصندوق گذرواژه استفاده کنید.
.TP
\fBnitrocli pws get \fIslot \fR[\fB\-n\fR|\fB\-\-name\fR] \
[\fB\-l\fR|\fB\-\-login\fR] \
[\fB\-p\fR|\fB\-\-password\fR] \
[\fB\-q\fR|\fB\-\-quiet\fR]
چاپ محتوای یک اسلات PWS.
\fIslot\fR شمارهٔ اسلات است.
به‌طور پیش‌فرض، این دستور نام، شناسهٔ ورود و گذرواژه را (به همین ترتیب) چاپ می‌کند.
اگر یک یا چند مورد از گزینه‌های \fB\-\-name\fR، \fB\-\-login\fR و
\fB\-\-password\fR تعیین شوند، فقط فیلدهای انتخاب‌شده چاپ می‌شوند.
ترتیب فیلدها هرگز تغییر نمی‌کند.

فیلدها همراه با یک برچسب چاپ می‌شوند.
از گزینهٔ \fB\-\-quiet\fR برای حذف برچسب‌ها و خروجی دادنِ تنها مقادیر ذخیره‌شده
در اسلات PWS استفاده کنید.
.TP
\fBnitrocli pws add \fR[\fB\-s\fR|\fB\-\-slot \fIslot\fR] \
\fIname login password\fR|\fB-\fR
افزودن یک اسلات PWS جدید.
اگر گزینهٔ \fB\-\-slot\fR تعیین شده باشد، این دستور داده‌ها را در اسلات مشخص‌شده
می‌نویسد و در صورتی که اسلات از قبل برنامه‌ریزی (پر) شده باشد، با شکست مواجه می‌شود.
اگر گزینهٔ \fB\-\-slot\fR تعیین نشده باشد، این دستور اولین اسلات خالی PWS را پیدا
کرده و محتوای آن را روی مقادیر ارائه‌شده تنظیم می‌کند.
در صورتی که تمام اسلات‌های PWS پر باشند، ناموفق خواهد بود.

اگر \fIpassword\fR روی \fB-\fR تنظیم شود، گذرواژه از ورودی استاندارد
خوانده می‌شود.
.TP
\fBnitrocli pws update \fIslot\fR \
[\fB\-n\fR|\fB\-\-name \fIname\fR] \
[\fB\-l\fR|\fB\-\-login \fIlogin\fR] \
[\fB\-p\fR|\fB\-\-password \fIpassword\fR|\fB-\fR]
به‌روزرسانی محتوای یک اسلات PWS پرشده.
\fIslot\fR شمارهٔ اسلاتی است که باید در آن نوشته شود.
این دستور تنها داده‌های ارائه‌شده با گزینه‌های \fB\-\-name\fR، \fB\-\-login\fR
و \fB\-\-password\fR را تنظیم کرده و سایر فیلدهای اسلات را بازنویسی نمی‌کند.

اگر \fIpassword\fR روی \fB-\fR تنظیم شود، گذرواژه از ورودی استاندارد
خوانده می‌شود.
.TP
\fBnitrocli pws clear \fIslot\fR
پاک کردن داده‌های ذخیره‌شده در یک اسلات PWS.
\fIslot\fR شمارهٔ اسلاتی است که باید پاک شود.
.TP
\fBnitrocli pws status \fR[\fB\-a\fR|\fB\-\-all\fR]
فهرست کردن تمام اسلات‌های PWS.
اگر \fB\-\-all\fR مشخص نشده باشد، اسلات‌های خالی نادیده گرفته می‌شوند..SS "پین‌ها (PINs)"
دستگاه‌های Nitrokey دارای دو کد PIN هستند: PIN کاربر و PIN مدیر. PIN کاربر
باید حداقل شش، و PIN مدیر حداقل هشت نویسه داشته باشد. PIN کاربر
برای دستورهایی مانند \fBotp get\fR (بسته به پیکربندی)
و برای تمام دستورهای \fBpws\fR مورد نیاز است.
PIN مدیر معمولاً برای تغییر پیکربندی دستگاه مورد نیاز است.
.P
هر PIN دارای یک شمارنده تلاش مجدد است که با هر بار ورود نادرست PIN کاهش یافته و
در صورت وارد کردن صحیح PIN بازنشانی می‌شود.
مقدار اولیه شمارنده تلاش مجدد ۳ است.
اگر شمارنده تلاش مجدد برای PIN کاربر صفر باشد، می‌توانید از
دستور \fBpin unblock\fR برای رفع مسدودی و بازنشانی PIN کاربر استفاده کنید.
اگر شمارنده تلاش مجدد برای PIN مدیر صفر باشد، باید با استفاده از
دستور \fBreset\fR یا \fBgpg\fR(1) یک بازنشانی کارخانه‌ای انجام دهید.
برای بررسی شمارنده‌های تلاش مجدد از دستور \fBstatus\fR استفاده کنید.
.TP
.B nitrocli pin clear
پاک‌سازی PINهای ذخیره‌شده در حافظه پنهان توسط دستورهای دیگر. توجه داشته باشید که PINهای
ذخیره‌شده در حافظه پنهان با دستگاه مربوط به خود مرتبط هستند و دستور \fBclear\fR تنها
PIN دستگاهِ در حال استفاده را پاک می‌کند، نه همه دستگاه‌ها را.
.TP
\fBnitrocli pin set \fItype\fR
تغییر دادن یک PIN.
\fItype\fR نوع PINی است که تغییر خواهد کرد: \fBadmin\fR برای تغییر
PIN مدیر یا \fBuser\fR برای تغییر PIN کاربر.
این دستور تنها در صورتی کار می‌کند که شمارنده تلاش مجدد برای آن نوع PIN حداقل ۱ باشد.
(برای بررسی شمارنده‌های تلاش مجدد از دستور \fBstatus\fR استفاده کنید.)
.TP
.B nitrocli pin unblock
رفع مسدودی و بازنشانی PIN کاربر.
این دستور به PIN مدیر نیاز دارد.
PIN مدیر را نمی‌توان از مسدودی خارج کرد.
این عملیات معادل گزینه unblock PIN ارائه شده توسط \fBgpg\fR(1)
(با استفاده از گزینه \fB\-\-change\-pin\fR) است.

.SS "افزونه‌ها (Extensions)"
علاوه بر دستورهای داخلی بالا، \fBnitrocli\fR از قابلیت‌های
ارائه‌شده توسط کاربر در قالب افزونه‌ها پشتیبانی می‌کند. افزونه می‌تواند هر
فایل اجرایی باشد که نام فایل آن با «nitrocli-» شروع می‌شود و از طریق جستجو
در متغیر محیطی \fBPATH\fR قابل شناسایی است. این فایل‌های اجرایی می‌توانند
به عنوان زیردستورهای معمولی فراخوانی شوند (بدون نیاز به پیشوند؛ برای مثال، یک
افزونه با نام «nitrocli-otp-cache» می‌تواند به صورت «nitrocli
otp-cache» فراخوانی شود).
.P
اطلاعات بیشتر در مورد نحوه نوشتن افزونه‌ها را می‌توان در بخش
افزونه‌ها در زیر یافت.

.SH "فایل پیکربندی (CONFIG FILE)"
دستور \fBnitrocli\fR تلاش می‌کند فایل پیکربندی را در
\fB${XDG_CONFIG_HOME}/nitrocli/config.toml\fR (یا در صورت عدم تنظیم متغیر
محیطی \fBXDG_CONFIG_HOME\fR، در \fB${HOME}/nitrocli/config.toml\fR)
بخواند.
از آن برای تنظیم مقادیر پیش‌فرض گزینه‌های فهرست‌شده در زیر استفاده می‌شود.
.P
شما همچنین می‌توانید متغیر محیطی \fBNITROCLI_\fIKEY\fR را برای بازنویسی
پیکربندی برای \fIkey\fR تنظیم کنید (بخش محیط را ببینید).
توجه داشته باشید که آرگومان‌های خط فرمان هم فایل پیکربندی و هم متغیرهای
محیطی را بازنویسی می‌کنند.
.P
مقادیر زیر را می‌توان در فایل پیکربندی تنظیم کرد:
.TP
.B model
محدود کردن اتصالات به مدل دستگاه داده‌شده (رشته، پیش‌فرض: تنظیم‌نشده،
\fB\-\-model\fR را ببینید).
.TP
.B serial_numbers
محدود کردن اتصالات به شماره سریال‌های داده‌شده (فهرستی از رشته‌ها، پیش‌فرض:
خالی، \fB\-\-serial-number\fR را ببینید).
.TP
.B usb_path
محدود کردن اتصالات به مسیر USB داده‌شده (رشته، پیش‌فرض: تنظیم‌نشده،
\fB\-\-usb-path\fR را ببینید).
.TP
.B no_cache
اگر روی true تنظیم شود، هیچ‌یک از اسرار استعلام‌شده کَش نمی‌شوند (بولی، پیش‌فرض: false،
\fB\-\-no\-cache\fR را ببینید).
.TP
.B verbosity
تنظیم سطح گزارش‌گیری (عدد صحیح، پیش‌فرض: 0، \fB\-\-verbose\fR را ببینید).
.P
فایل پیکربندی باید از قالب TOML استفاده کند، برای مثال:
    model = "pro"
    serial_numbers = ["0xf00baa", "deadbeef"]
    usb_path = "0001:0006:02"
    no_cache = false
    verbosity = 0

.SH "محیط (ENVIRONMENT)"
این برنامه به دو دسته از متغیرهای محیطی که همگی با پیشوند
«NITROCLI_» هستند، توجه می‌کند.
.SS "پیکربندی (Configuration)"
دسته اول پیکربندی اولیه برنامه را کنترل می‌کند. این متغیرها
گزینه‌های مربوطه خط فرمان و تنظیمات فایل پیکربندی را منعکس می‌کنند. آن‌ها
عبارتند از:
.TP
.B NITROCLI_MODEL
محدود کردن اتصالات به مدل دستگاه داده‌شده (رشته، پیش‌فرض: تنظیم‌نشده،
\fB\-\-model\fR را ببینید).
.TP
.B NITROCLI_SERIAL_NUMBERS
محدود کردن اتصالات به فهرست داده‌شده از شماره سریال‌ها (فهرستی از رشته‌های جداشده با
کاما، پیش‌فرض: خالی، \fB\-\-serial-number\fR را ببینید).
.TP
.B NITROCLI_USB_PATH
محدود کردن اتصالات به مسیر USB داده‌شده (رشته، پیش‌فرض: تنظیم‌نشده،
\fB\-\-usb-path\fR را ببینید).
.TP
.B NITROCLI_NO_CACHE
اگر روی true تنظیم شود، هیچ‌یک از اسرار استعلام‌شده کَش نمی‌شوند (بولی، پیش‌فرض: false،
\fB\-\-no\-cache\fR را ببینید).
.TP
.B NITROCLI_VERBOSITY
تنظیم سطح گزارش‌گیری (عدد صحیح، پیش‌فرض: 0، \fB\-\-verbose\fR را ببینید).
.SS "ورود گذرواژه و PIN (Password & PIN entry)"
دسته دوم می‌تواند برای ارائه داده‌های گذرواژه و PIN به برنامه جهت جلوگیری از
ورود تعاملی از طریق \fBpinentry\fR(1) برای عملیاتی که در غیر این صورت
آن را درخواست می‌کردند، استفاده شود. متغیرهای زیر شناسایی می‌شوند:
.TP
.B NITROCLI_ADMIN_PIN
کد PIN مدیر برای استفاده.
.TP
.B NITROCLI_USER_PIN
کد PIN کاربر برای استفاده.
.TP
.B NITROCLI_NEW_ADMIN_PIN
کد PIN جدید مدیر برای تنظیم. این متغیر تنها توسط دستور \fBpin set\fR
برای نوع \fBadmin\fR استفاده می‌شود.
.TP
.B NITROCLI_NEW_USER_PIN
کد PIN جدید کاربر برای تنظیم. این متغیر تنها توسط دستور \fBpin set\fR
برای نوع \fBuser\fR استفاده می‌شود.
.TP
.B NITROCLI_PASSWORD
گذرواژه‌ای که توسط دستورهای نیازمند آن استفاده می‌شود (مانند \fBhidden open\fR)..SH "افزونه‌ها (EXTENSIONS)"
دستور \fBnitrocli\fR از افزونه‌های ارائه‌شده توسط کاربر که فایل‌های اجرایی با نامِ آغازشونده با "nitrocli-" هستند و از طریق جست‌وجو در متغیر محیطی \fBPATH\fR قابل شناسایی می‌باشند، پشتیبانی می‌کند.

این برنامه اطلاعات پیکربندی پایه را به هر افزونه‌ای که از این طریق اجرا شود منتقل می‌کند. به‌ویژه، در صورتی که پیکربندی متناظر برنامهٔ \fBnitrocli\fR تنظیم شده باشد، هر متغیر محیطی را طبق آنچه در زیربخش پیکربندی از بخش محیط در بالا شرح داده شد تنظیم خواهد کرد. علاوه بر این، متغیرهای زیر نیز تنظیم خواهند شد:
.TP
.B NITROCLI_BINARY
مسیر مطلق به باینری \fBnitrocli\fR که افزونه از طریق آن فراخوانی شده است. این مسیر می‌تواند برای فراخوانی بازگشتی \fBnitrocli\fR جهت پیاده‌سازی عملکردهای مشخصی استفاده شود.
.TP
.B NITROCLI_RESOLVED_USB_PATH
مسیر USB دستگاهی که \fBnitrocli\fR بر اساس گزینه‌های \fB\-\-model\fR، \fB\-\-serial-number\fR و \fB\-\-usb-path\fR به آن متصل می‌شود. اگر هیچ دستگاه Nitrokey منطبقی وجود نداشته باشد، یا اگر چندین دستگاه با این گزینه‌ها تطابق داشته باشند، این متغیر محیطی تنظیم نخواهد شد.

.P
تمام متغیرهای دیگر موجود در محیط به‌صورت دست‌نخورده به افزونه منتقل خواهند شد.
.P
نسخه‌های جدیدتر برنامه این حق را برای خود محفوظ می‌دارند که متغیرهای محیطی دیگری را درون فضای نام "NITROCLI_" تنظیم کنند. بنابراین، به افزونه‌ها توصیه می‌شود متغیرهای سفارشی با این پیشوند تعریف نکنند. با این حال، "NITROCLI_EXT_" دقیقاً برای همین منظور فراهم شده است. برای جلوگیری بیشتر از تداخل میان افزونه‌ها، توصیه می‌شود پس از این پیشوند، نام افزونه (با حروف بزرگ) قرار گیرد.

.P
افزونه‌ها می‌توانند به‌صورت اختیاری داده‌های پایدار به اشکال مختلف را بخوانند یا بنویسند. مشابه با برنامهٔ اصلی، افزونه‌ها باید از «مشخصات دایرکتوری پایه‌ای XDG» (XDG Base Directory Specification) به‌عنوان راهنمایی برای محل ذخیرهٔ چنین داده‌هایی پیروی کنند. به‌طور دقیق‌تر، قراردادهای زیر باید رعایت شوند:

برای داده‌های پیکربندی، دایرکتوری \fB${XDG_CONFIG_HOME}/\fIextension/\fR دایرکتوری ترجیحی است، که در آن \fIextension\fR نام کامل افزونه، شامل پیشوند "nitrocli-" است. قالب پیکربندی توصیه‌شده TOML است. اگر تنها از یک فایل پیکربندی منفرد استفاده می‌شود، \fBconfig.toml\fR نام پیشنهادی است.

به همین ترتیب، داده‌های عادی باید در \fB${XDG_DATA_HOME}/\fIextension/\fR قرار گیرند و داده‌های حافظهٔ موقت (کَش) در \fB${XDG_CACHE_HOME}/\fIextension/\fR ذخیره شوند.

.SH "فایل‌ها (FILES)"
.TP
.B ${XDG_CONFIG_HOME}/nitrocli/config.toml
.TP
.B ${HOME}/nitrocli/config.toml
فایل پیکربندی کاربر، بخش Config file را ببینید.

.SH "مثال‌ها (EXAMPLES)"
.SS "ذخیره‌سازی (Storage)"
ایجاد یک حجم پنهان در نخستین اسلات در دسترس، با شروع از نیمی از اندازهٔ حجم رمزگذاری‌شده (یعنی ۵۰٪) و امتداد تا انتهای آن (۱۰۰٪):
    $ \fBnitrocli hidden create 0 50 100\fR

.SS "رمزهای عبور یک‌بارمصرف (One-time passwords)"
پیکربندی یک اسلات رمز عبور یک‌بارمصرف با نمایش راز در مبنای شانزده (hexadecimal):
    $ \fBnitrocli otp set 0 test\-rfc4226 3132333435363738393031323334353637383930 \-\-format hex \-\-algorithm hotp\fR
    $ \fBnitrocli otp set 1 test\-foobar 666F6F626172 \-\-format hex \-\-algorithm hotp\fR
    $ \fBnitrocli otp set 0 test\-rfc6238 3132333435363738393031323334353637383930 \-\-format hex \-\-algorithm totp \-\-digits 8\fR
.P
پیکربندی یک اسلات رمز عبور یک‌بارمصرف با نمایش راز به‌صورت ASCII:
    $ \fBnitrocli otp set 0 test\-rfc4226 12345678901234567890 \-\-format ascii \-\-algorithm hotp\fR
    $ \fBnitrocli otp set 1 test\-foobar foobar \-\-format ascii \-\-algorithm hotp\fR
    $ \fBnitrocli otp set 0 test\-rfc6238 12345678901234567890 \-\-format ascii \-\-algorithm totp \-\-digits 8\fR
.P
پیکربندی یک اسلات رمز عبور یک‌بارمصرف با نمایش راز در مبنای ۳۲ (base32):
    $ \fBnitrocli otp set 0 test\-rfc4226 gezdgnbvgy3tqojqgezdgnbvgy3tqojq \-\-algorithm hotp\fR
    $ \fBnitrocli otp set 1 test\-foobar mzxw6ytboi====== \-\-algorithm hotp\fR
    $ \fBnitrocli otp set 0 test\-rfc6238 gezdgnbvgy3tqojqgezdgnbvgy3tqojq \-\-algorithm totp \-\-digits 8\fR
.P
تولید یک رمز عبور یک‌بارمصرف:
    $ \fBnitrocli otp get 0 \-\-algorithm hotp\fR
    755224
    $ \fBnitrocli otp get 0 \-\-algorithm totp \-\-time 1234567890\fR
    89005924
.P
پاک کردن یک اسلات رمز عبور یک‌بارمصرف:
    $ \fBnitrocli otp clear 0 \-\-algorithm hotp\fR

.SS "پیکربندی (Configuration)"
پرس‌وجوی پیکربندی:
    $ \fBnitrocli config get\fR
    Config:
      numlock binding:          not set
      capslock binding:         not set
      scrollock binding:        not set
      require user PIN for OTP: true
.P
تغییر پیکربندی:
    $ \fBnitrocli config set \-\-otp\-pin\fR

.SS "گاوصندوق رمز عبور (Password safe)"
پیکربندی یک اسلات PWS:
    $ \fBnitrocli pws add example.org john.doe passw0rd\fR
    Added PWS slot 0

دریافت داده‌ها از یک اسلات:
    $ \fBnitrocli pws get 0\fR
    name:     example.org
    login:    john.doe
    password: passw0rd

کپی کردن رمز عبور در کلیپ‌بورد (نیازمند \fBxclip\fR(1)):
    $ \fBnitrocli pws get 0 \-\-password \-\-quiet | xclip \-in\fR

پرس‌وجوی اسلات‌های PWS:
    $ \fB nitrocli pws status\fR
    slot	name
    0	example.org