CRYPTSETUP-LUKSADDKEY(8) دستورهای مدیریتی و نگهداری CRYPTSETUP-LUKSADDKEY(8)

cryptsetup-luksAddKey - افزودن گذرواژه یا کلید جدید به یک اسلات خالی در دستگاه LUKS

cryptsetup luksAddKey [<گزینه‌ها>] <دستگاه> [<فایل کلید جدید>]

یک اسلات کلید (keyslot) محافظت‌شده با یک گذرواژه جدید اضافه می‌کند. گذرواژه موجود باید به‌صورت تعاملی، از طریق --key-file یا توکن LUKS2 (پلاگین) ارائه شود. به عنوان جایگزینی برای گذرواژه موجود، کاربر می‌تواند مستقیماً کلید حجم (volume key) را (از طریق --volume-key-file یا --volume-key-keyring) ارائه دهد. گذرواژه جدیدی که قرار است اضافه شود می‌تواند به‌صورت تعاملی مشخص شود، از فایلی که به عنوان آرگومان موضعی داده شده خوانده شود (همچنین از طریق پارامتر --new-keyfile) یا از طریق توکن LUKS2 دریافت گردد.

نکته: با گزینه --unbound این عملیات یک اسلات کلید نامقید (unbound) جدید در LUKS2 ایجاد می‌کند. این اسلات کلید نمی‌تواند برای فعال‌سازی دستگاه استفاده شود. اگر کلید جدید را از طریق گزینه --volume-key-file ارائه ندهید، یک کلید تصادفی جدید تولید می‌شود. در این حالت نیازی به ارائه گذرواژه موجود برای هیچ‌یک از اسلات‌های کلید فعال نیست.

نکته: برخی از پارامترها تنها در صورتی موثر هستند که با قالب LUKS2 استفاده شوند که از پارامترهای مجزا برای هر اسلات کلید پشتیبانی می‌کند. در LUKS1، نوع PBKDF و الگوریتم درهم‌سازی (هش) همیشه برای همه اسلات‌های کلید یکسان است.

<گزینه‌ها> می‌توانند شامل موارد زیر باشند:
[--key-file, --keyfile-offset, --keyfile-size, --new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot, --new-key-slot, --volume-key-file, --volume-key-keyring, --force-password, --hash, --header, --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --unbound, --type, --keyslot-cipher, --keyslot-key-size, --key-size, --timeout, --token-id, --token-type, --token-only, --new-token-id, --verify-passphrase, --external-tokens-path].

--batch-mode, -q

تمام پرسش‌های تاییدیه را لغو می‌کند. با احتیاط استفاده کنید!

اگر گزینه --verify-passphrase مشخص نشده باشد، این گزینه بررسی صحت گذرواژه را نیز غیرفعال می‌کند.

--debug یا --debug-json

اجرا در حالت اشکال‌زدایی با گزارش‌های تشخیصی کامل. خطوط خروجی اشکال‌زدایی همیشه دارای پیشوند # هستند.

اگر از --debug-json استفاده شود، ساختارهای داده اضافی LUKS2 JSON نیز چاپ می‌شوند.

--disable-locks

قفل محافظت متادیتا روی دیسک را غیرفعال می‌کند. این گزینه فقط برای LUKS2 معتبر است و برای سایر قالب‌ها نادیده گرفته می‌شود.

هشدار: از این گزینه استفاده نکنید مگر اینکه cryptsetup را در یک محیط محدود اجرا کنید که قفل کردن در آن غیرممکن است (جایی که پوشه /run قابل استفاده نیست).

--external-tokens-path مسیر_مطلق

مسیر دایرکتوری پیش‌فرض سیستم را که در آن cryptsetup به دنبال گرداننده‌های توکن خارجی (یا پلاگین‌های توکن) می‌گردد، بازنویسی می‌کند. این مسیر باید یک مسیر مطلق باشد (که با نویسه '/' شروع شود).

--force-password

بررسی کیفیت گذرواژه را برای گذرواژه‌های جدید LUKS انجام نمی‌دهد.

اگر cryptsetup بدون پشتیبانی از بررسی کیفیت گذرواژه ساخته شده باشد، این گزینه نادیده گرفته می‌شود.

برای اطلاعات بیشتر درباره بررسی کیفیت گذرواژه، صفحه راهنمای pwquality.conf(5) و passwdqc.conf(5) را ببینید.

--hash, -h <مشخصه-هش>

هش مشخص‌شده برای PBKDF2 و تقسیم‌کننده AF استفاده می‌شود.

--header <دستگاه یا فایل ذخیره‌کننده هدر LUKS>

استفاده از یک فایل یا دستگاه متادیتای جداگانه (جداشده) که هدر LUKS در آن ذخیره شده است. این گزینه امکان ذخیره متن رمزگذاری‌شده و هدر LUKS را روی دستگاه‌های مختلف فراهم می‌کند.

برای دستورهایی که هدر LUKS را تغییر می‌دهند (مانند luksAddKey)، دستگاه یا فایل حاوی هدر LUKS را مستقیماً به عنوان دستگاه LUKS مشخص کنید.

--help, -?

نمایش متن راهنما و پارامترهای پیش‌فرض.

--iter-time, -i <تعداد میلی‌ثانیه>

مدت زمانی (به میلی‌ثانیه) که برای پردازش گذرواژه با PBKDF صرف می‌شود. تعیین ۰ به عنوان پارامتر، مقدار پیش‌فرض زمان کامپایل را انتخاب می‌کند.

--key-file, -d نام_فایل

خواندن گذرواژه از فایل.

اگر نام داده‌شده "-" باشد، گذرواژه از ورودی استاندارد (stdin) خوانده می‌شود. در این حالت، خواندن با رسیدن به نویسه خط جدید متوقف نخواهد شد.

گذرواژه ارائه‌شده از طریق --key-file همیشه گذرواژه اسلات کلید موجود است که توسط دستور درخواست شده است.

اگر می‌خواهید یک گذرواژه جدید را از طریق فایل کلید تنظیم کنید، باید از آرگومان موضعی یا پارامتر --new-keyfile استفاده کنید.

برای اطلاعات بیشتر، بخش NOTES ON PASSPHRASE PROCESSING را در cryptsetup(8) ببینید.

--keyfile-offset مقدار

نادیده گرفتن مقدار بایت از ابتدای فایل کلید.

--keyfile-size, -l مقدار

خواندن حداکثر مقدار بایت از فایل کلید. پیش‌فرض خواندن کل فایل تا سقف حداکثر مقدار تعیین‌شده در زمان کامپایل است که با --help قابل استعلام است. ارائه داده‌های بیشتر از حداکثر مقدار کامپایل‌شده، عملیات را متوقف می‌کند.

این گزینه به عنوان مثال برای بریدن نویسه‌های خط جدید پایانی مفید است. اگر --keyfile-offset نیز داده شده باشد، شمارش اندازه از پس از آفست آغاز می‌شود.

--key-size, -s بیت‌ها

ارائه اندازه کلید حجم بر حسب بیت. این آرگومان باید مضربی از ۸ باشد.

این گزینه زمانی لازم است که از پارامتر --volume-key-file برای ارائه کلید حجم فعلی استفاده شود. همچنین هنگامی که با مشخص کردن پارامتر --unbound یک اسلات کلید نامقید جدید ایجاد می‌شود، به کار می‌رود.

--key-slot, -S <0-N>

هنگامی که همراه با پارامتر --new-key-slot استفاده شود، به شما امکان می‌دهد مشخص کنید کدام اسلات کلید برای باز کردن قفل کلید حجم انتخاب شود.

نکته: اگر کلید حجم موجود از طریق توکن LUKS2 (پارامترهای --token-id، --token-type یا --token-only) باز شود، یا زمانی که کلید حجم مستقیماً از طریق پارامتر --volume-key-file ارائه شود، این گزینه نادیده گرفته می‌شود.

نکته: برای حفظ سازگاری با گذشته، بدون پارامتر --new-key-slot، این گزینه به شما امکان می‌دهد مشخص کنید کدام اسلات کلید برای کلید جدید انتخاب شود.

حداکثر تعداد اسلات‌های کلید به نسخه LUKS بستگی دارد. LUKS1 می‌تواند تا ۸ اسلات کلید داشته باشد. LUKS2 بسته به اندازه ناحیه اسلات کلید و اندازه کلید می‌تواند تا ۳۲ اسلات کلید داشته باشد، اما شناسه اسلات کلید معتبر برای LUKS2 همیشه می‌تواند بین ۰ تا ۳۱ باشد.

--keyslot-cipher <مشخصه-رمز>

از این گزینه می‌توان برای تعیین الگوریتم رمزنگاری مشخص برای ناحیه اسلات‌های کلید LUKS2 استفاده کرد.

--keyslot-key-size <بیت‌ها>

از این گزینه می‌توان برای تعیین اندازه کلید مشخص برای ناحیه اسلات‌های کلید LUKS2 استفاده کرد.

--new-keyfile نام_فایل

خواندن گذرواژه برای یک اسلات کلید جدید از فایل.

اگر نام داده‌شده "-" باشد، گذرواژه از ورودی استاندارد (stdin) خوانده خواهد شد. در این حالت، خواندن با رسیدن به نویسه خط جدید متوقف نمی‌شود.

این روش جایگزینی برای آرگومان موضعی هنگام افزودن گذرواژه جدید از طریق فایل کلید است.

--new-keyfile-offset مقدار

نادیده گرفتن مقدار بایت در ابتدا، هنگام افزودن یک گذرواژه جدید از طریق فایل کلید.

--new-keyfile-size مقدار

خواندن حداکثر مقدار بایت هنگام افزودن یک گذرواژه جدید از طریق فایل کلید. پیش‌فرض خواندن کل فایل تا سقف حداکثر طول تعیین‌شده در زمان کامپایل است که با --help قابل استعلام است. ارائه داده‌های بیشتر از حداکثر مقدار کامپایل‌شده، عملیات را متوقف می‌کند. در صورت ارائه --new-keyfile-offset، خواندن پس از آفست شروع می‌شود.

--new-key-slot <0-N>

این گزینه به شما امکان می‌دهد مشخص کنید کدام اسلات کلید برای کلید جدید انتخاب شود.

نکته: در صورت استفاده، این گزینه بر رفتار گزینه --key-slot تاثیر می‌گذارد.

حداکثر تعداد اسلات‌های کلید به نسخه LUKS بستگی دارد. LUKS1 می‌تواند تا ۸ اسلات کلید داشته باشد. LUKS2 بسته به اندازه ناحیه اسلات کلید و اندازه کلید می‌تواند تا ۳۲ اسلات کلید داشته باشد، اما شناسه اسلات کلید معتبر برای LUKS2 همیشه می‌تواند بین ۰ تا ۳۱ باشد.

--new-token-id

مشخص می‌کند که از کدام توکن برای دریافت گذرواژه برای یک اسلات کلید جدید استفاده شود.

--pbkdf <مشخصه PBKDF>

تنظیم الگوریتم تابع اشتقاق کلید مبتنی بر گذرواژه (PBKDF) برای اسلات کلید LUKS. مقدار PBKDF می‌تواند شامل موارد زیر باشد: pbkdf2 (برای PBKDF2 طبق استاندارد RFC2898)، argon2i برای Argon2i یا argon2id برای Argon2id (برای اطلاعات بیشتر به Argon2 https://www.cryptolux.org/index.php/Argon2 مراجعه کنید).

برای LUKS1، فقط PBKDF2 پذیرفته می‌شود (نیازی به استفاده از این گزینه نیست). الگوریتم پیش‌فرض PBKDF برای LUKS2 در زمان کامپایل تنظیم شده و در خروجی cryptsetup --help در دسترس است.

تابع PBKDF برای افزایش هزینه حملات فرهنگ‌لغت (dictionary) و جستجوی فراگیر (brute-force) روی گذرواژه‌های اسلات کلید استفاده می‌شود. پارامترها می‌توانند شامل هزینه زمان، حافظه و موازی‌سازی باشند.

برای PBKDF2، فقط هزینه زمان (تعداد تکرارها) اعمال می‌شود. برای Argon2i/id، علاوه بر زمان، هزینه حافظه (میزان حافظه مورد نیاز در طول فرآیند اشتقاق کلید) و هزینه موازی‌سازی (تعداد رشته‌هایی که به طور هم‌روند در طول اشتقاق کلید اجرا می‌شوند) نیز وجود دارد.

توجه داشته باشید که افزایش هزینه حافظه باعث افزایش زمان نیز می‌شود، بنابراین مقادیر نهایی پارامترها توسط یک بنچمارک (آزمون کارایی) سنجیده می‌شوند. بنچمارک سعی می‌کند زمان تکرار (--iter-time) را با هزینه حافظه درخواستی (--pbkdf-memory) مطابقت دهد. اگر این کار ممکن نباشد، هزینه حافظه نیز کاهش می‌یابد. هزینه موازی‌سازی (--pbkdf-parallel) ثابت است و بر اساس هسته‌های موجود پردازنده (CPU) بررسی می‌شود.

می‌توانید تمام پارامترهای PBKDF را برای یک اسلات کلید خاص در LUKS2 با دستور cryptsetup-luksDump(8) مشاهده کنید.

نکته: اگر نمی‌خواهید از بنچمارک استفاده کنید و می‌خواهید تمام پارامترها را مستقیماً تعیین نمایید، از --pbkdf-force-iterations همراه با --pbkdf-memory و --pbkdf-parallel استفاده کنید. این کار مقادیر را بدون اجرای بنچمارک بازنویسی می‌کند. توجه داشته باشید که این کار می‌تواند باعث زمان بازگشایی قفل بسیار طولانی شده یا به دلیل کمبود حافظه (out-of-memory) منجر به خاتمه اجباری فرآیند شود. فقط در موارد خاص از آن استفاده کنید؛ به عنوان مثال، اگر می‌دانید دستگاه قالب‌بندی‌شده قرار است در یک سیستم تعبیه‌شده (embedded) کوچک استفاده شود.

حداقل و حداکثر هزینه‌های PBKDF: برای PBKDF2، حداقل تعداد تکرار ۱۰۰۰ و حداکثر ۴۲۹۴۹۶۷۲۹۵ است (حداکثر مقدار برای یک عدد صحیح ۳۲ بیتی بدون علامت). هزینه‌های حافظه و موازی‌سازی برای PBKDF2 استفاده نمی‌شوند. برای Argon2i و Argon2id، حداقل تعداد تکرار (هزینه CPU) برابر ۴ و حداکثر ۴۲۹۴۹۶۷۲۹۵ است (حداکثر برای عدد صحیح ۳۲ بیتی بدون علامت). حداقل هزینه حافظه ۳۲ کیلوبایت (KiB) و حداکثر ۴ گیگابایت (GiB) است (به حافظه قابل آدرس‌دهی در برخی پلتفرم‌های CPU محدود می‌شود). اگر پارامتر هزینه حافظه با بنچمارک تعیین شود (با پارامتر مشخص نشده باشد)، همیشه در بازه ۶۴ مگابایت (MiB) تا ۱ گیگابایت (GiB) قرار دارد. حداقل هزینه موازی‌سازی ۱ و حداکثر ۴ است (در صورتی که هسته‌های پردازنده کافی موجود باشد، در غیر این صورت کاهش می‌یابد).

--pbkdf-force-iterations <تعداد>

جلوگیری از اجرای بنچمارک PBKDF و تنظیم مستقیم هزینه زمان (تکرارها). این گزینه فقط برای دستگاه‌های LUKS/LUKS2 قابل استفاده است. برای اطلاعات بیشتر گزینه --pbkdf را ببینید.

--pbkdf-memory <عدد>

تنظیم هزینه حافظه برای PBKDF (برای Argon2i/id این عدد بیانگر کیلوبایت است). توجه داشته باشید که این حداکثر مقدار است؛ بنچمارک PBKDF یا حافظه فیزیکی موجود ممکن است آن را کاهش دهد. این گزینه برای PBKDF2 در دسترس نیست.

--pbkdf-parallel <عدد>

تنظیم هزینه موازی‌سازی برای PBKDF (تعداد رشته‌ها، تا ۴ عدد). توجه داشته باشید که این حداکثر مقدار است و در صورتی که تعداد هسته‌های آنلاین پردازنده کمتر باشد، به طور خودکار کاهش می‌یابد. این گزینه برای PBKDF2 در دسترس نیست.

--timeout, -t <تعداد ثانیه‌ها>

تعداد ثانیه‌های انتظار قبل از سرآمدن زمان مهلت (تایم‌اوت) هنگام ورود گذرواژه از طریق ترمینال. این گزینه در هر بار درخواست گذرواژه اعمال می‌شود. در صورت استفاده هم‌زمان با --key-file تاثیری ندارد.

این گزینه زمانی مفید است که سیستم در صورت عدم ورود گذرواژه توسط کاربر نباید متوقف بماند؛ به عنوان مثال هنگام بوت سیستم. مقدار پیش‌فرض ۰ ثانیه است که به معنای انتظار نامحدود است.

--token-id

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

--token-only

تنها استفاده از توکن‌های LUKS2 برای باز کردن قفل کلید حجم موجود.

نکته: برای ایجاد یک اسلات کلید جدید با استفاده از گذرواژه ارائه‌شده توسط یک توکن، از پارامتر --new-token-id استفاده کنید.

--token-type نوع

مشخص می‌کند که هنگام باز کردن قفل اسلات کلید موجود برای دریافت کلید حجم، از چه نوع توکنی (تمام توکن‌های از این نوع) استفاده شود.

--type <نوع-دستگاه>

نوع دستگاه مورد نظر را مشخص می‌کند؛ برای اطلاعات بیشتر بخش BASIC ACTIONS را در cryptsetup(8) بخوانید.

--unbound

یک اسلات کلید نامقید (unbound) جدید در LUKS2 ایجاد می‌کند.

--usage

نمایش راهنمای کوتاه گزینه‌ها.

--verify-passphrase, -y

هنگام درخواست تعاملی گذرواژه، آن را دوبار می‌پرسد و در صورت عدم تطابق هشدار می‌دهد. در ورودی از فایل یا ورودی استاندارد (stdin) نادیده گرفته می‌شود.

--version, -V

نمایش نسخه برنامه.

--volume-key-file, --master-key-file (نام مستعار منسوخ‌شده)

استفاده از یک کلید حجم ذخیره‌شده در یک فایل. این گزینه امکان افزودن اسلات کلید جدید را بدون نیاز به دانستن گذرواژه اسلات موجود فراهم می‌کند. همچنین زمانی که هیچ اسلات کلیدی فعال نیست، قابل استفاده است.

هشدار: اگر کلید حجم اختصاصی خود را ایجاد می‌کنید، باید مطمئن شوید که آن را به درستی انجام می‌دهید. در غیر این صورت، ممکن است با یک کلید حجم با آنتروپی پایین یا تا حدی قابل پیش‌بینی مواجه شوید که امنیت را به خطر می‌اندازد.

--volume-key-keyring <شرح کلید>

استفاده از یک کلید حجم ذخیره‌شده در جاکلیدی هسته (keyring). این گزینه امکان باز کردن انواع دستگاه‌ها و luks را بدون وارد کردن گذرواژه فراهم می‌کند. کلید و نوع مرتبط با آن باید از فضای کاربری قابل خواندن باشد تا خلاصه (digest) کلید حجم پیش از فعال‌سازی قابل اعتبارسنجی باشد.

عبارت <شرح کلید> از نحو سازگار با keyctl استفاده می‌کند. این می‌تواند یک شناسه عددی کلید یا نام رشته‌ای در قالب %<نوع کلید>:<نام کلید> باشد. همچنین بخش KEY IDENTIFIERS در keyctl(1) را ببینید. در صورتی که پیشوند %<نوع کلید>: مشخص نشده باشد، فرض می‌شود نوع کلید user (نوع پیش‌فرض) است.

نکته: در صورتی که روش دیگری مشخص نشده باشد، درخواست تعاملی گذرواژه همیشه روش پیش‌فرض است.

افزودن اسلات کلید جدید با استفاده از درخواست تعاملی گذرواژه هم برای گذرواژه موجود و هم برای گذرواژه جدید:

cryptsetup luksAddKey /dev/device

افزودن اسلات کلید جدید با استفاده از توکن‌های LUKS2 برای باز کردن قفل اسلات کلید موجود، همراه با درخواست تعاملی گذرواژه برای گذرواژه جدید:

cryptsetup luksAddKey --token-only /dev/device

افزودن اسلات کلید جدید با استفاده از توکن‌های systemd-tpm2 در LUKS2 برای باز کردن قفل اسلات کلید موجود، همراه با درخواست تعاملی گذرواژه برای گذرواژه جدید (پلاگین توکن systemd-tpm2 باید در دسترس باشد):

cryptsetup luksAddKey --token-type systemd-tpm2 /dev/device

افزودن اسلات کلید جدید با استفاده از درخواست تعاملی گذرواژه برای اسلات کلید موجود، و خواندن گذرواژه جدید از key_file:

cryptsetup luksAddKey --new-keyfile key_file /dev/device یا cryptsetup luksAddKey /dev/device key_file

افزودن اسلات کلید جدید با استفاده از کلید حجم ذخیره‌شده در volume_key_file و توکن LUKS2 در اسلات ۵ برای دریافت گذرواژه اسلات کلید جدید (توکن در اسلات ۵ باید وجود داشته باشد و پلاگین توکن مربوطه نیز در دسترس باشد):

cryptsetup luksAddKey --volume-key-file volume_key_file --new-token-id 5 /dev/device

گزارش باگ‌ها در لیست پستی cryptsetup <cryptsetup@lists.linux.dev> یا در بخش مسائل پروژه https://gitlab.com/cryptsetup/cryptsetup/-/issues/new.

لطفاً خروجی دستور ناموفق را همراه با گزینه --debug پیوست کنید.

پرسش‌های متداول cryptsetup (FAQ) https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions

cryptsetup(8), integritysetup(8) و veritysetup(8)

بخشی از پروژه cryptsetup https://gitlab.com/cryptsetup/cryptsetup.

مه ۲۰۲۵ cryptsetup 2.7.5