'\" t
.\"     Title: ndctl-load-keys
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-06-30
.\"    Manual: ndctl Manual
.\"    Source: ndctl
.\"  Language: English
.\"
.TH "NDCTL\-LOAD\-KEYS" "1" "2026-06-30" "ndctl" "ndctl Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
ndctl-load-keys \- بارگذاری kek و عبارت‌های عبور رمزگذاری‌شده در دسته‌کلید (keyring)
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fIndctl load\-keys\fP [<گزینه‌ها>]
.fi
.br
.SH "توضیحات (DESCRIPTION)"
.sp
دستور \fIload\-keys\fP کلید اصلی (\fIkek\fP) و عبارت‌های عبور رمزگذاری‌شده را برای تمام NVDIMMها در دسته‌کلید کاربر (user keyring) که توسط هسته مدیریت می‌شود، بارگذاری می‌کند. انتظار می‌رود این دستور در طول مقداردهی اولیه و پیش از بارگذاری ماژول هسته libnvdimm، معمولاً از طریق یک initrd، فراخوانی شود. این سازوکار معمولاً با استفاده از یک پیکربندی modprobe تنظیم می‌شود که دستور را پیش از بارگذاری ماژول اجرا می‌کند.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
انتظار می‌رود تمام فایل‌های کلید در این قالب باشند: nvdimm_<id>_hostname
.br
نویسه \f(CR\*(Aq_\fP\*(Aq برای جداسازی بخش‌های مختلف در نام فایل استفاده می‌شود. در داخل hostname، استفاده از نویسه \f(CR\*(Aq_\fP\*(Aq مجاز است زیرا آخرین بخش از نام فایل به شمار می‌رود.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
این دستور معمولاً هرگز به صورت مستقیم توسط کاربر فراخوانی نمی‌شود.
.sp .5v
.RE
.SH "گزینه‌ها (OPTIONS)"
.sp
\-p, \-\-key\-path=
.RS 4
مسیر دایرکتوری قرارگیری فایل‌های مرتبط با کلید. این پارامتر اختیاری است و مکان پیش‌فرض آن /etc/ndctl/keys می‌باشد.
.RE
.sp
\-t, \-\-tpm\-handle=
.RS 4
یک هندل TPM ارائه می‌دهد (باید رشته‌ای مانند 0x81000001 باشد). اگر مسیر کلید (/etc/ndctl/keys) شامل فایلی به نام tpm.handle باشد که رشته هندل را در بر دارد، می‌توان این گزینه را حذف کرد تا هندل tpm مستقیماً از فایل خوانده شود. در صورت وجود هر دو مورد، مقدار این گزینه بر هر آنچه در فایل قرار دارد اولویت خواهد داشت (اما آن را بازنویسی نخواهد کرد).
.RE.SH "اصول عملکرد (THEORY OF OPERATION)"
.sp
مشخصات فنی Intel Device Specific Methods (DSM) نگارش v1.7 و v1.8 [1]
عملیات‌های مدیریت امنیت زیر را معرفی کرده است:
enable passphrase (فعال‌سازی عبارت عبور)، update passphrase (به‌روزرسانی عبارت عبور)، unlock DIMM (قفل‌گشایی DIMM)، disable security (غیرفعال‌سازی امنیت)،
freeze security (انجماد امنیت)، secure (crypto) erase (پاک‌سازی امن رمزنگاری‌شده)، overwrite (بازنویسی)، master passphrase
enable (فعال‌سازی عبارت عبور اصلی)، master passphrase update (به‌روزرسانی عبارت عبور اصلی)، و master passphrase secure erase (پاک‌سازی امن عبارت عبور اصلی).
.sp
مدیریت امنیت برای NVDIMMها از دو بخش تشکیل شده است. بخش پیشانه (front end)
از چارچوب مدیریت کلید لینوکس (کلیدهای معتمد و رمزگذاری‌شده [2]) برای
ذخیره عبارات عبور رمزگذاری‌شده در keyring مدیریت‌شده توسط هسته استفاده می‌کند. رابط
این بخش ابزار \fIkeyutils\fP است که از APIهای مدیریت کلید در
هسته لینوکس بهره می‌برد. بخش پسانه (back end) محموله رمزگشایی‌شده (که همان عبارت عبور
DIMM است) را دریافت کرده و آن را به DIMM منتقل می‌کند.
.sp
برخلاف سایر DSMها که توسط libndctl ساخته شده و از طریق
یک ioctl به هسته ارسال می‌شوند، DSMهای امنیتی از طریق مشخصه sysfs مربوط به \fIsecurity\fP
در زیر دستگاه \fIdimm\fP مدیریت می‌شوند. یک \fIkey\-ID\fP در مشخصه \fIsecurity\fP نوشته می‌شود و
هسته داده‌های کلید مربوطه را از keyring کاربری که توسط هسته
نگهداری می‌شود، واکشی می‌کند.
.sp
فرایند امنیتی با تولید یک \fImaster key\fP (کلید اصلی) آغاز می‌شود که
برای مهروموم کردن (رمزگذاری) عبارت عبور DIMM به کار می‌رود. می‌تواند یک
\fImaster key\fP مشترک وجود داشته باشد که برای رمزگذاری عبارت عبور تمام DIMMها استفاده شود، یا
یک کلید مجزا برای هر DIMM تولید گردد. به \fImaster key\fP اصطلاحاً
\fIkey\-encryption\-key\fP (kek) نیز گفته می‌شود. \fIkek\fP می‌تواند هم توسط
TPM (ماژول بستر قابل اعتماد) روی سامانه تولید شود، یا در غیر این صورت، از \fISystem
Master Key\fP نیز می‌توان به عنوان \fIkek\fP استفاده کرد.
.sp
برای اهداف آزمایشی، از یک کلید کاربری با محموله تصادفی نیز می‌توان به عنوان
یک \fIkek\fP استفاده کرد. برای جزئیات به [2] مراجعه کنید. برای انجام هرگونه عملیات امنیتی،
انتظار می‌رود که \fIkek\fP همانند مثال زیر به keyring کاربری هسته اضافه
شده باشد:
.sp
.if n .RS 4
.nf
.fam C
# keyctl show
Session Keyring
 736023423 \-\-alswrv\&      0\&     0\&  keyring: _ses
 675104189 \-\-alswrv\&      0 65534\&   \(rs_ keyring: _uid.0
 680187394 \-\-alswrv\&      0\&     0\&       \(rs_ trusted: nvdimm\-master
.fam
.fi
.if n .RE
.sp
پیش از انجام هر یک از عملیات‌های امنیتی، تمام ناحیه‌ها (regions) مرتبط
با DIMM مورد نظر باید غیرفعال شوند. برای عملیات \fIoverwrite\fP،
علاوه بر \fIregions\fP، خود \fIdimm\fP نیز باید غیرفعال گردد.
.sp
[1] \c
.URL "http://pmem.io/documents/NVDIMM_DSM_Interface\-V1.8.pdf" ""
.br
[2] \c
.URL "https://www.kernel.org/doc/Documentation/security/keys/trusted\-encrypted.rst" "" ""
.sp
زیربخش‌های زیر جزئیات مربوط به هر ویژگی امنیتی را شرح می‌دهند.
.SS "قفل‌گشایی (UNLOCK)"
.sp
قفل‌گشایی توسط هسته انجام می‌شود، با این حال پیش از آنکه DSM قفل‌گشایی
بتواند توسط هسته صادر شود، باید یک مرحله آماده‌سازی رخ دهد. انتظار می‌رود که
از درون initramfs، یک دستور راه‌اندازی (ndctl \fIload\-keys\fP) پیش از
بارگذاری ماژول libnvdimm توسط modprobe اجرا شود. این دستور،
\fIkek\fP و عبارات عبور رمزگذاری‌شده را به keyring کاربری هسته تزریق می‌کند. در طول
فرایند \fIprobe\fP درایور libnvdimm، اقدامات زیر انجام خواهد شد:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
بررسی وضعیت امنیتی دستگاه و بررسی اینکه آیا DIMM قفل است یا خیر
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
درخواست عبارت عبور رمزگذاری‌شده مربوطه از keyring کاربری هسته
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
استفاده از \fIkek\fP برای رمزگشایی عبارت عبور
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
ایجاد DSM قفل‌گشایی و رونوشت محموله رمزگشایی‌شده به درون DSM
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 5." 4.2
.\}
صدور DSM برای قفل‌گشایی DIMM
.RE
.sp
اگر DIMM از پیش قفل‌گشایی شده باشد، هسته تلاش می‌کند تا عبارت عبور را
مجدداً اعتبارسنجی کند. در صورت عدم موفقیت در اعتبارسنجی مجدد عبارت عبور، هسته امنیت را
منجمد (freeze) کرده و هرگونه تغییرات بعدی در پیکربندی امنیتی را غیرمجاز می‌سازد. یک پارامتر
ماژول هسته برای لغو این رفتار در دسترس است..SS "راه‌اندازی عبارت عبور کاربر (SETUP USER PASSPHRASE)"
.sp
برای راه‌اندازی عبارت عبور برای یک DIMM، انتظار می‌رود \fIkek\fP مورد استفاده
در keyring کاربر هسته وجود داشته باشد. کلید \fIkek\fP عبارت عبور DIMM را
با استفاده از قالب کلید \fIenc32\fP رمزگذاری می‌کند. عبارت عبور به صورت متن آشکار هرگز
توسط کاربر ارائه نشده و برای او قابل مشاهده نیست. در عوض، به صورت تصادفی توسط هسته
تولید می‌شود و فضای کاربری (userspace) به آن دسترسی ندارد. پس از رمزگذاری، یک blob باینری از
عبارت عبور در دایرکتوری ذخیره‌سازی blob عبارت عبور (/etc/ndctl/keys) نوشته می‌شود.
کاربر مسئول تهیهٔ نسخهٔ پشتیبان از blobهای عبارت عبور در یک مکان امن است.
.SS "به‌روزرسانی عبارت عبور کاربر (UPDATE USER PASSPHRASE)"
.sp
عملیات به‌روزرسانی عبارت عبور کاربر از همان دستور DSM فعال‌سازی عبارت عبور
کاربر استفاده می‌کند. بیشتر کار در سمت مدیریت کلید انجام می‌شود. کاربر این
گزینه را دارد که یک \fIkek\fP جدید برای عبارت عبور جدید ارائه دهد، اما ادامهٔ
استفاده از \fIkek\fP موجود نیز قابل قبول است.
عملیات‌های زیر برای \fIupdate\-passphrase\fP انجام می‌شوند:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
حذف عبارت عبور رمزگذاری‌شده از keyring کاربر در هسته.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
تغییر نام blob عبارت عبور به old.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
بارگذاری این blob عبارت عبور قدیمی درون keyring با نام "old".
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
ایجاد عبارت عبور جدید و رمزگذاری آن با \fIkek\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 5." 4.2
.\}
ارسال DSM همراه با عبارت‌های عبور رمزگشایی‌شدهٔ قدیمی و جدید.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 6." 4.2
.\}
حذف عبارت عبور قدیمی و blob عبارت عبور از keyring.
.RE.SS "حذف عبارت‌عبور کاربر (REMOVE USER PASSPHRASE)"
.sp
شناسه کلید (\fIkey\-ID\fP) عبارت‌عبوری که قرار است حذف شود، در sysfs نوشته می‌شود.
سپس هسته DSM را برای غیرفعال‌سازی امنیت ارسال می‌کند، پس از آن عبارت‌عبور
از keyring حذف شده و حباب (blob) عبارت‌عبور مرتبط با آن پاک می‌شود.
.SS "پاک‌سازی رمزنگارانه (ایمن) (CRYPTO (SECURE) ERASE)"
.sp
این عملیات مشابه remove\-passphrase است. هسته پیش و پس از این عملیات،
دستورالعمل WBINVD را صادر می‌کند تا از عدم خرابی داده‌ها ناشی از
کَش بیات پردازنده (CPU cache) اطمینان حاصل شود. برای انجام این عملیات،
از دستور sanitize\-dimm ابزار ndctl به همراه گزینه \f(CR\-\-crypto\-erase\fP
استفاده کنید.
.SS "بازنویسی (OVERWRITE)"
.sp
این عملیات با استفاده از گزینه \f(CR\-\-overwrite\fP برای \fIsanitize\-dimm\fP در ndctl فراخوانی می‌شود.
عملیات بازنویسی کل NVDIMM را پاک می‌کند. این عملیات می‌تواند زمان
قابل‌توجهی طول بکشد. نکته: بازگشت موفقیت‌آمیز دستور، صرفاً به این معناست
که بازنویسی با موفقیت آغاز شده است، نه اینکه بازنویسی به اتمام رسیده باشد.
در ادامه، می‌توان از \fIndctl wait\-overwrite\fP برای انتظار جهت اتمام
NVDIMMهایی که در حال انجام بازنویسی هستند استفاده کرد. پس از تکمیل موفقیت‌آمیز
یک بازنویسی، دستورالعمل WBINVD توسط هسته صادر می‌شود.
اگر هر دو گزینه \-\-crypto\-erase و \-\-overwrite ارائه شوند، ابتدا
crypto\-erase پیش از overwrite انجام می‌گیرد.
.SS "انجماد امنیتی (SECURITY FREEZE)"
.sp
این عملیات نیازی به عبارت‌عبور ندارد. این کار باعث می‌شود هرگونه دستور
امنیتی به جز استعلام وضعیت، تا راه‌اندازی بعدی سیستم مسدود شود.
.SS "راه‌اندازی، به‌روزرسانی و پاک‌سازی رمزنگارانه عبارت‌عبور اصلی (MASTER PASSPHRASE SETUP, UPDATE, and CRYPTO ERASE)"
.sp
این عملیات‌ها مشابه فعال‌سازی و به‌روزرسانی عبارت‌عبور کاربر هستند. تنها
تفاوت این است که از یک عبارت‌عبور متفاوت استفاده می‌شود. عبارت‌عبور اصلی هیچ
ارتباطی با کلید اصلی (\fIkek\fP) که برای رمزنگاری هر یک از عبارت‌های عبور
به کار می‌رود، ندارد.
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
.sp
حق نشر \(co 2016 \- 2022, Intel Corporation. مجوز GPLv2: گنو GPL
نسخه ۲ \c
.URL "http://gnu.org/licenses/gpl.html" "" "."
این یک نرم‌افزار آزاد است:
شما مجاز به تغییر و بازتوزیع آن هستید. هیچ‌گونه ضمانتی وجود ندارد،
تا حدی که قانون اجازه می‌دهد.