'\" t
.\"     Title: ndctl-setup-passphrase
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-06-30
.\"    Manual: ndctl Manual
.\"    Source: ndctl
.\"  Language: English
.\"
.TH "NDCTL\-SETUP\-PASSPHRASE" "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-setup-passphrase \- راه‌اندازی و فعال‌سازی عبارت عبور امنیتی برای یک NVDIMM
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fIndctl setup\-passphrase\fP <nmem0> [<nmem1>..<nmemN>] \-k <key_handle> [<options>]
.fi
.br
.SH "توضیحات (DESCRIPTION)"
.sp
راه‌اندازی و فعال‌سازی یک عبارت عبور امنیتی برای یک یا چند NVDIMM.
.sp
برای اجرای موفقیت‌آمیز این دستور، انتظار می‌رود کلید اصلی (master key) از قبل در دسته‌کلید کاربر (user keyring) بارگذاری شده باشد. اطلاعات بیشتر درباره نحوه انجام این کار را می‌توانید در مستندات هسته در نشانی زیر بیابید:
.URL "https://www.kernel.org/doc/html/latest/security/keys/trusted\-encrypted.html" "" ""
.sp
داده‌های باینری عبارت عبور (blobها) در دایرکتوری /etc/ndctl/keys با قالب نام فایل \f(CR"nvdimm_<dimm\-unique\-id>_<hostname>.blob"\fP ایجاد می‌شوند.
.sp
اگر عبارت عبور از پیش در دسته‌کلید کاربر موجود باشد یا فایل blob عبارت عبور از قبل در /etc/ndctl/keys وجود داشته باشد، این دستور با شکست مواجه خواهد شد.
.SH "گزینه‌ها (OPTIONS)"
.sp
<dimm>
.RS 4
یک نام دستگاه \fInmemX\fP یا یک شماره شناسه dimm. عملیات را به dimm(های) مشخص‌شده محدود می‌کند. کلمه کلیدی \fIall\fP را می‌توان برای مشخص کردن عدم وجود هرگونه محدودیت تعیین کرد، اگرچه این حالت دقیقاً مشابه عدم ارائه گزینه \-\-dimm است.
.RE
.sp
\-b, \-\-bus=
.RS 4
یک شماره شناسه گذرگاه، یا یک رشته ارائه‌دهنده (مانند "ACPI.NFIT"). عملیات را به گذرگاه(های) مشخص‌شده محدود می‌کند. کلمه کلیدی \fIall\fP را می‌توان برای مشخص کردن عدم وجود هرگونه محدودیت تعیین کرد، اگرچه این حالت تفاوتی با مشخص نکردن گزینه \-\-bus ندارد.
.RE
.sp
\-k, \-\-key_handle=
.RS 4
شناسه دستگیره (handle) برای \fIkek\fP اصلی (key\-encryption\-key) که برای پلمپ کردن عبارت(های) عبور مربوط به DIMM(های) مشخص‌شده به کار می‌رود. قالب آن به صورت زیر است:
\f(CR<key type>:<key description>\fP
برای مثال: \f(CRtrusted:nvdimm\-master\fP
.br
نکته: انتظار می‌رود \fIkek\fP از قبل در دسته‌کلید کاربر بارگذاری شده باشد.
.RE
.sp
\-m, \-\-master\-passphrase
.RS 4
مشخص می‌کند که به جای عبارت عبور کاربر، عبارت عبور اصلی (master passphrase) مدیریت می‌شود.
.RE
.sp
\-v, \-\-verbose
.RS 4
نمایش پیام‌های اشکال‌زدایی.
.RE.SH "سازوکار عملکرد (THEORY OF OPERATION)"
.sp
مشخصات Intel Device Specific Methods (DSM) نسخهٔ ۱.۷ و ۱.۸ [1] عملیات مدیریت امنیت زیر را معرفی کرده است:
فعال‌سازی عبارت‌عبور (enable passphrase)، به‌روزرسانی عبارت‌عبور (update passphrase)، باز کردن قفل DIMM (unlock 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) بار دادهٔ (payload) رمزگشایی‌شده (که همان عبارت‌عبور DIMM است) را دریافت کرده و به DIMM منتقل می‌کند.
.sp
برخلاف سایر DSMها که توسط libndctl تشکیل شده و از طریق یک ioctl به هسته ارسال می‌شوند، DSMهای امنیتی از طریق مشخصهٔ sysfs به نام \fIsecurity\fP ذیل دستگاه \fIdimm\fP مدیریت می‌شوند. یک \fIkey\-ID\fP در مشخصهٔ \fIsecurity\fP نوشته می‌شود و هسته محتوای کلید مربوطه را از دسته‌کلید کاربر (user 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
برای اهداف آزمایشی، یک کلید کاربری (user key) با محمولهٔ تصادفی نیز می‌تواند به‌عنوان یک \fIkek\fP استفاده شود. برای جزئیات به [2] مراجعه کنید. برای انجام هرگونه عملیات امنیتی، انتظار می‌رود که \fIkek\fP همان‌طور که در مثال زیر نشان داده شده، به دسته‌کلید کاربرِ هسته اضافه شده باشد:
.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
پیش از انجام هرگونه عملیات امنیتی، تمامی ناحیه‌ها (\fIregions\fP) مرتبط با 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 و عبارت‌های عبور رمزگذاری‌شده را به دسته‌کلید کاربرِ هسته تزریق می‌کند. در طول فرایند \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
.\}
درخواست عبارت‌عبور رمزگذاری‌شدهٔ مرتبط از دسته‌کلید کاربرِ هسته
.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 قفل‌گشایی و کپی کردن بار دادهٔ (payload) رمزگشایی‌شده در داخل 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 مورد استفاده
در user keyring هسته موجود باشد. کلید \fIkek\fP عبارت عبور DIMM را با استفاده
از قالب کلید \fIenc32\fP رمزگذاری می‌کند. عبارت عبور متن‌ساده (plaintext) هرگز توسط
کاربر ارائه نشده و برای او قابل مشاهده نخواهد بود؛ در عوض به‌صورت تصادفی توسط هسته
تولید می‌شود و فضای کاربری (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
.\}
حذف عبارت عبور رمزگذاری‌شده از user 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 با نام \(lqold\(rq.
.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 خراب نمی‌شود.
برای اجرای این عملیات از دستور 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
این عملیات به عبارت عبور نیازی ندارد. این کار باعث می‌شود هرگونه دستور امنیتی به غیر از
پرس‌وجوی وضعیت (status query)، تا بوت بعدی مسدود و قفل شود.
.SS "راه‌اندازی، به‌روزرسانی و پاک‌سازی رمزی عبارت عبور اصلی (MASTER PASSPHRASE SETUP, UPDATE, and CRYPTO ERASE)"
.sp
این عملیات‌ها مشابه فعال‌سازی و به‌روزرسانی عبارت عبور کاربر هستند. تنها تفاوت این است که
از عبارت عبور متفاوتی استفاده می‌شود. عبارت عبور اصلی ارتباطی با کلید اصلی (\fIkek\fP)
که برای رمزنگاری هر یک از عبارت‌های عبور به کار می‌رود، ندارد.
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
.sp
حق نشر \(co 2016 \- 2022، شرکت Intel Corporation. مجوز GPLv2: گنو GPL
نسخه 2 \c
.URL "http://gnu.org/licenses/gpl.html" "" "."
این نرم‌افزار آزاد است:
شما مختارید آن را تغییر داده و توزیع کنید. هیچ‌گونه ضمانتی وجود ندارد،
تا حدی که قانون اجازه می‌دهد.
.SH "همچنین ببینید (SEE ALSO)"
.sp
ndctl\-update\-passphrase(1), ndctl\-remove\-passphrase(1)