'\" t
.\"     Title: cryptsetup-luksconvertkey
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-07-21
.\"    Manual: دستورهای مدیریتی و نگهداری
.\"    Source: cryptsetup 2.8.7
.\"  Language: Persian
.\"
.TH "CRYPTSETUP\-LUKSCONVERTKEY" "8" "2026-07-21" "cryptsetup 2.8.7" "دستورهای مدیریتی و نگهداری"
.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)"
cryptsetup-luksConvertKey \- تبدیل یک اسلات کلید موجود LUKS2 به پارامترهای جدید PBKDF
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBcryptsetup \fIluksConvertKey\fP [<\fIگزینه‌ها\fP>] <\fIدستگاه\fP>\fP
.SH "توضیحات (DESCRIPTION)"
.sp
یک اسلات کلید (keyslot) موجود LUKS2 را به پارامترهای جدید PBKDF تبدیل می‌کند.
گذرواژه مربوط به اسلات کلیدی که باید تبدیل شود، باید به‌صورت تعاملی یا از طریق \fB\-\-key\-file\fP ارائه شود.
اگر هیچ پارامتر \fB\-\-pbkdf\fP مشخص نشده باشد، مقادیر پیش‌فرض PBKDF در LUKS2 اعمال خواهند شد.
.sp
اگر یک اسلات کلید مشخص شده باشد (از طریق \fB\-\-key\-slot\fP)، باید گذرواژه همان اسلات کلید ارائه گردد.
اگر هیچ اسلات کلیدی مشخص نشده باشد و همچنان یک اسلات کلید خالی وجود داشته باشد، پیش از پاک‌سازی اسلات کلید حاوی پارامترهای قدیمی، پارامترهای جدید در یک اسلات کلید خالی قرار داده می‌شوند.
اگر هیچ اسلات کلید خالی وجود نداشته باشد، اسلات کلید حاوی پارامترهای قدیمی مستقیماً رونویسی می‌شود.
.sp
\fBهشدار:\fP اگر یک اسلات کلید رونویسی شود، بروز خرابی در رسانه ذخیره‌سازی حین این عملیات می‌تواند پس از پاک شدن پارامترهای قدیمی باعث شکست رونویسی شده و در نتیجه کانتینر LUKS را برای همیشه غیرقابل دسترسی کند.
.sp
<\fBگزینه‌ها\fP> می‌توانند شامل موارد زیر باشند:
.br
[\fB\-\-key\-file\fP, \fB\-\-keyfile\-offset\fP, \fB\-\-keyfile\-size\fP, \fB\-\-key\-slot\fP, \fB\-\-hash\fP, \fB\-\-header\fP, \fB\-\-disable\-locks\fP, \fB\-\-iter\-time\fP, \fB\-\-pbkdf\fP, \fB\-\-pbkdf\-force\-iterations\fP, \fB\-\-pbkdf\-memory\fP, \fB\-\-pbkdf\-parallel\fP, \fB\-\-keyslot\-cipher\fP, \fB\-\-keyslot\-key\-size\fP, \fB\-\-timeout\fP, \fB\-\-verify\-passphrase\fP].
.SH "گزینه‌ها (OPTIONS)"
.sp
\fB\-\-batch\-mode\fP, \fB\-q\fP
.RS 4
تمام پرسش‌های تاییدیه را لغو می‌کند.
با احتیاط استفاده کنید!
.sp
اگر گزینه \fB\-\-verify\-passphrase\fP مشخص نشده باشد، این گزینه تایید و اعتبارسنجی گذرواژه را نیز غیرفعال می‌کند.
.RE
.sp
\fB\-\-debug\fP یا \fB\-\-debug\-json\fP
.RS 4
اجرا در حالت اشکال‌زدایی با گزارش‌های تشخیصی کامل.
خطوط خروجی اشکال‌زدایی همیشه دارای پیشوند \fB#\fP هستند.
.sp
اگر از \fB\-\-debug\-json\fP استفاده شود، ساختارهای داده اضافی LUKS2 JSON نیز چاپ می‌شوند.
.RE
.sp
\fB\-\-disable\-locks\fP
.RS 4
غیرفعال کردن حفاظت قفل برای متاداده روی دیسک.
این گزینه فقط برای LUKS2 معتبر است و برای سایر قالب‌ها نادیده گرفته می‌شود.
.sp
\fBهشدار:\fP از این گزینه استفاده نکنید مگر اینکه cryptsetup را در محیطی محدود اجرا کنید که در آن قفل کردن غیرممکن باشد (جایی که دایرکتوری \fB/run\fP قابل استفاده نیست).
.RE
.sp
\fB\-\-force\-password\fP
.RS 4
عدم استفاده از بررسی کیفیت گذرواژه برای گذرواژه‌های جدید LUKS.
.sp
در صورتی که cryptsetup بدون پشتیبانی از بررسی کیفیت گذرواژه ساخته شده باشد، این گزینه نادیده گرفته می‌شود.
.sp
برای اطلاعات بیشتر درباره بررسی کیفیت گذرواژه، صفحه راهنمای \fBpwquality.conf\fP(5) و \fBpasswdqc.conf\fP(5) را ببینید.
.RE
.sp
\fB\-\-hash\fP, \fB\-h\fP \fI<مشخصه\-هش>\fP
.RS 4
هش مشخص‌شده برای PBKDF2 و تقسیم‌کننده AF استفاده می‌شود.
.RE
.sp
\fB\-\-header\fP \fI<دستگاه یا فایل ذخیره‌کننده هدر LUKS>\fP
.RS 4
استفاده از یک دستگاه یا فایل متاداده جداشده (مستقل) که هدر LUKS در آن ذخیره شده است.
این گزینه امکان ذخیره متن رمزشده و هدر LUKS را روی دستگاه‌های مجزا فراهم می‌کند.
.sp
برای دستوراتی که هدر LUKS را تغییر می‌دهند (مانند \fIluksAddKey\fP)، دستگاه یا فایل حاوی هدر LUKS را مستقیماً به عنوان دستگاه LUKS مشخص کنید.
.RE
.sp
\fB\-\-help\fP, \fB\-?\fP
.RS 4
نمایش متن راهنما و پارامترهای پیش‌فرض.
.RE
.sp
\fB\-\-iter\-time\fP, \fB\-i\fP \fI<تعداد میلی‌ثانیه‌ها>\fP
.RS 4
تعداد میلی‌ثانیه‌هایی که باید صرف پردازش گذرواژه در PBKDF شود.
مشخص کردن ۰ به عنوان پارامتر، مقدار پیش‌فرض زمان کامپایل را انتخاب می‌کند.
.RE
.sp
\fB\-\-key\-file\fP, \fB\-d\fP \fIفایل\fP
.RS 4
خواندن گذرواژه از فایل.
.sp
اگر نام داده‌شده "\-" باشد، گذرواژه از ورودی استاندارد (stdin) خوانده خواهد شد.
در این حالت، خواندن با نویسه‌های خط جدید متوقف نخواهد شد.
.sp
برای اطلاعات بیشتر، بخش \fINOTES ON PASSPHRASE PROCESSING\fP را در \fBcryptsetup\fP(8) ببینید.
.RE
.sp
\fB\-\-keyfile\-offset\fP \fIمقدار\fP
.RS 4
نادیده گرفتن \fIمقدار\fP بایت از ابتدای فایل کلید.
.RE
.sp
\fB\-\-keyfile\-size\fP, \fB\-l\fP \fIمقدار\fP
.RS 4
خواندن حداکثر \fIمقدار\fP بایت از فایل کلید.
حالت پیش‌فرض خواندن کل فایل تا سقف حداکثر مقدار تعریف‌شده در زمان کامپایل است که می‌توان با \fB\-\-help\fP آن را استعلام کرد.
ارائه داده‌های بیشتر از حداکثر مقدار کامپایل‌شده عملیات را متوقف می‌کند.
.sp
این گزینه برای مثال جهت حذف خطوط جدید پایانی مفید است.
اگر \fB\-\-keyfile\-offset\fP نیز داده شده باشد، شمارش اندازه پس از آفست آغاز می‌شود.
.RE
.sp
\fB\-\-key\-slot\fP, \fB\-S\fP \fI<0\-N>\fP
.RS 4
برای عملیات‌های LUKS که ماده کلید اضافه می‌کنند، این گزینه به شما امکان می‌دهد مشخص کنید کدام اسلات کلید برای کلید جدید انتخاب شود.
.sp
حداکثر تعداد اسلات‌های کلید به نسخه LUKS بستگی دارد.
LUKS1 می‌تواند تا ۸ اسلات کلید داشته باشد.
LUKS2 بسته به اندازه ناحیه اسلات کلید و اندازه کلید می‌تواند تا ۳۲ اسلات کلید داشته باشد، اما شناسه اسلات کلید معتبر برای LUKS2 همیشه می‌تواند بین ۰ تا ۳۱ باشد.
.RE
.sp
\fB\-\-keyslot\-cipher\fP \fI<مشخصه\-رمز>\fP
.RS 4
از این گزینه می‌توان برای تعیین الگوریتم رمزنگاری مشخص برای ناحیه اسلات‌های کلید LUKS2 استفاده کرد.
.RE
.sp
\fB\-\-keyslot\-key\-size\fP \fI<بیت‌ها>\fP
.RS 4
از این گزینه می‌توان برای تعیین اندازه کلید مشخص برای ناحیه اسلات‌های کلید LUKS2 استفاده کرد.
.RE
.sp
\fB\-\-new\-keyfile\-offset\fP \fIمقدار\fP
.RS 4
نادیده گرفتن \fIمقدار\fP بایت در ابتدا، هنگام افزودن یک گذرواژه جدید از طریق فایل کلید.
.RE
.sp
\fB\-\-new\-keyfile\-size\fP \fIمقدار\fP
.RS 4
خواندن حداکثر \fIمقدار\fP بایت هنگام افزودن یک گذرواژه جدید از طریق فایل کلید.
حالت پیش‌فرض خواندن کل فایل تا سقف حداکثر طول تعریف‌شده در زمان کامپایل است که با \fB\-\-help\fP قابل استعلام است.
ارائه داده‌های بیشتر از حداکثر مقدار کامپایل‌شده عملیات را متوقف می‌کند.
در صورت ارائه \fB\-\-new\-keyfile\-offset\fP، خواندن پس از آفست شروع می‌شود.
.RE
.sp
\fB\-\-pbkdf\fP \fI<مشخصه PBKDF>\fP
.RS 4
تنظیم الگوریتم تابع اشتقاق کلید مبتنی بر گذرواژه (PBKDF) برای اسلات کلید LUKS.
مقدار PBKDF می‌تواند شامل موارد زیر باشد: \fIpbkdf2\fP (برای PBKDF2 طبق استاندارد RFC2898)، \fIargon2i\fP برای Argon2i یا \fIargon2id\fP برای Argon2id (برای اطلاعات بیشتر به \c
.URL "https://www.cryptolux.org/index.php/Argon2" "Argon2" ""
مراجعه کنید).
.sp
برای LUKS1، فقط PBKDF2 پذیرفته می‌شود (نیازی به استفاده از این گزینه نیست).
الگوریتم پیش‌فرض PBKDF برای LUKS2 در زمان کامپایل تنظیم شده و در خروجی \fIcryptsetup \-\-help\fP در دسترس است.
.sp
تابع PBKDF برای افزایش هزینه حملات فرهنگ‌لغت (dictionary) و جستجوی فراگیر (brute-force) روی گذرواژه‌های اسلات کلید استفاده می‌شود.
پارامترها می‌توانند شامل هزینه زمان، حافظه و موازی‌سازی باشند.
.sp
برای PBKDF2، فقط هزینه زمان (تعداد تکرارها) اعمال می‌شود.
برای Argon2i/id، هزینه حافظه (میزان حافظه مورد نیاز در طول فرآیند اشتقاق کلید) و هزینه موازی‌سازی (تعداد رشته‌هایی که به طور هم‌روند در طول اشتقاق کلید اجرا می‌شوند) نیز وجود دارد.
.sp
توجه داشته باشید که افزایش هزینه حافظه باعث افزایش زمان نیز می‌شود، بنابراین مقادیر نهایی پارامترها توسط یک بنچمارک (آزمون کارایی) سنجیده می‌شوند.
بنچمارک سعی می‌کند زمان تکرار (\fB\-\-iter\-time\fP) را با هزینه حافظه درخواستی \fB\-\-pbkdf\-memory\fP مطابقت دهد.
اگر این کار ممکن نباشد، هزینه حافظه نیز کاهش می‌یابد.
هزینه موازی‌سازی \fB\-\-pbkdf\-parallel\fP ثابت است و بر اساس هسته‌های موجود پردازنده (CPU) بررسی می‌شود.
.sp
می‌توانید تمام پارامترهای PBKDF را برای یک اسلات کلید خاص در LUKS2 با دستور \fBcryptsetup\-luksDump\fP(8) مشاهده کنید.
.sp
اگر نمی‌خواهید از بنچمارک استفاده کنید و می‌خواهید تمام پارامترها را مستقیماً تعیین نمایید، از \fB\-\-pbkdf\-force\-iterations\fP همراه با \fB\-\-pbkdf\-memory\fP و \fB\-\-pbkdf\-parallel\fP استفاده کنید.
این کار مقادیر را بدون اجرای بنچمارک بازنویسی می‌کند.
توجه داشته باشید که این کار می‌تواند باعث زمان بازگشایی قفل بسیار طولانی شده یا به دلیل کمبود حافظه (out-of-memory) منجر به خاتمه اجباری فرآیند شود.
فقط در موارد خاص از آن استفاده کنید؛ به عنوان مثال اگر می‌دانید دستگاه قالب‌بندی‌شده قرار است در یک سیستم تعبیه‌شده (embedded) کوچک استفاده شود.
.sp
\fBحداقل و حداکثر هزینه‌های PBKDF:\fP برای \fBPBKDF2\fP، حداقل تعداد تکرار ۱۰۰۰ و حداکثر ۴۲۹۴۹۶۷۲۹۵ است (حداکثر مقدار برای یک عدد صحیح ۳۲ بیتی بدون علامت).
هزینه‌های حافظه و موازی‌سازی برای PBKDF2 پشتیبانی نمی‌شوند.
برای \fBArgon2i\fP و \fBArgon2id\fP، حداقل تعداد تکرار (هزینه CPU) برابر ۴ و حداکثر ۴۲۹۴۹۶۷۲۹۵ است (حداکثر برای عدد صحیح ۳۲ بیتی بدون علامت).
حداقل هزینه حافظه ۳۲ کیلوبایت (KiB) و حداکثر ۴ گیگابایت (GiB) است.
اگر پارامتر هزینه حافظه با بنچمارک تعیین شود (با پارامتر مشخص نشده باشد)، همیشه در بازه ۶۴ مگابایت (MiB) تا ۱ گیگابایت (GiB) قرار دارد.
هزینه حافظه بالاتر از ۱ گیگابایت (تا سقف حداکثر ۴ گیگابایت) تنها با استفاده از پارامتر \fB\-\-pbkdf\-memory\fP قابل تنظیم است.
حداقل هزینه موازی‌سازی ۱ و حداکثر ۴ است (در صورتی که هسته‌های پردازنده کافی موجود باشد، در غیر این صورت بر اساس هسته‌های موجود پردازنده کاهش می‌یابد).
.sp
\fBهشدار:\fP افزایش هزینه‌های محاسباتی PBKDF بالاتر از محدودیت‌های ذکرشده، بهبود امنیتی بسیار ناچیزی فراهم می‌کند.
در حالی که افزایش هزینه‌ها به طور چشمگیری سربار جستجوی فراگیر (brute-force) را افزایش می‌دهد، اما محافظت ناچیزی در برابر حملات فرهنگ‌لغت ارائه می‌کند.
افزایش هزینه حاشیه‌ای برای پردازش کل یک فرهنگ‌لغت اساساً ناکافی باقی می‌ماند.
.sp
محدودیت‌های سخت‌کدشده PBKDF نشان‌دهنده یک مصالحه مهندسی‌شده بین امنیت رمزنگاری و قابلیت استفاده عملیاتی است.
LUKS قابلیت حمل را حفظ می‌کند و باید در زمان معقولی روی سیستم‌های با منابع محدود قابل استفاده باشد.
ابزار cryptsetup به دلیل محدودیت‌های معماری (مانند سیستم‌های تعبیه‌شده و قدیمی)، پارامترهای حداکثر هزینه حافظه (۴ گیگابایت) و هزینه موازی‌سازی (۴) را به طور عمدی محدود می‌کند.
.sp
هزینه حافظه PBKDF نیازمند تخصیص حافظه فیزیکی RAM واقعی با عملیات نوشتن متمرکز است که باید در RAM فیزیکی باقی بماند.
هرگونه استفاده از فضای تعویض (swap) منجر به افت کارایی غیرقابل قبولی خواهد شد.
مدیریت حافظه اغلب حافظه را بیش از حد ظرفیت فیزیکی موجود (overcommit) تخصیص می‌دهد، با این انتظار که بیشتر حافظه تخصیص‌یافته دست‌نخورده باقی بماند.
در چنین شرایطی، از آنجا که PBKDF همیشه از تمام حافظه تخصیص‌یافته استفاده می‌کند، مکرراً باعث خطاهای کمبود حافظه شده و عملیات‌های cryptsetup را متوقف می‌سازد.
.RE
.sp
\fB\-\-pbkdf\-force\-iterations\fP \fIتعداد\fP
.RS 4
جلوگیری از اجرای بنچمارک PBKDF و تنظیم مستقیم هزینه زمان (تکرارها).
این گزینه فقط برای دستگاه‌های LUKS/LUKS2 قابل استفاده است.
برای اطلاعات بیشتر گزینه \fB\-\-pbkdf\fP را ببینید.
.RE
.sp
\fB\-\-pbkdf\-memory\fP \fIتعداد\fP
.RS 4
تنظیم هزینه حافظه برای PBKDF (برای Argon2i/id این عدد بیانگر کیلوبایت است).
توجه داشته باشید که این حداکثر مقدار است؛ بنچمارک PBKDF یا حافظه فیزیکی موجود ممکن است آن را کاهش دهد.
این گزینه برای PBKDF2 در دسترس نیست.
.RE
.sp
\fB\-\-pbkdf\-parallel\fP \fIتعداد\fP
.RS 4
تنظیم هزینه موازی‌سازی برای PBKDF (تعداد رشته‌ها، تا ۴ عدد).
توجه داشته باشید که این حداکثر مقدار است؛ در صورتی که تعداد هسته‌های فعال (آنلاین) پردازنده کمتر باشد، به طور خودکار کاهش می‌یابد.
این گزینه برای PBKDF2 در دسترس نیست.
.RE
.sp
\fB\-\-timeout\fP, \fB\-t\fP \fIثانیه\fP
.RS 4
تعداد ثانیه‌های انتظار پیش از سرآمدن زمان مهلت (تایم‌اوت) هنگام ورود گذرواژه از طریق ترمینال.
این مقدار هر بار که گذرواژه‌ای درخواست شود اعمال می‌شود.
در صورت استفاده هم‌زمان با \fB\-\-key\-file\fP هیچ اثری ندارد.
.sp
این گزینه زمانی مفید است که سیستم در صورت عدم ورود گذرواژه توسط کاربر نباید متوقف شود؛ برای مثال هنگام بوت سیستم.
مقدار پیش‌فرض ۰ ثانیه است که به معنای انتظار نامحدود است.
.RE
.sp
\fB\-\-usage\fP
.RS 4
نمایش راهنمای کوتاه گزینه‌ها.
.RE
.sp
\fB\-\-verify\-passphrase\fP, \fB\-y\fP
.RS 4
هنگام درخواست گذرواژه به‌صورت تعاملی، آن را دو بار درخواست کرده و در صورت عدم تطابق ورودی‌ها، خطا اعلام می‌کند.
در ورودی از فایل یا ورودی استاندارد (stdin) نادیده گرفته می‌شود.
.RE
.sp
\fB\-\-version\fP, \fB\-V\fP
.RS 4
نمایش نسخه برنامه.
.RE
.SH "گزارش باگ‌ها (REPORTING BUGS)"
.sp
گزارش باگ‌ها در \c
.MTO "cryptsetup\(atlists.linux.dev" "لیست پستی cryptsetup" ""
یا در \c
.URL "https://gitlab.com/cryptsetup/cryptsetup/\-/issues/new" "بخش مسائل پروژه" "."
.sp
لطفاً خروجی دستور ناموفق را با افزودن گزینه \fB\-\-debug\fP پیوست کنید.
.SH "همچنین ببینید (SEE ALSO)"
.sp
.URL "https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions" "پرسش‌های متداول Cryptsetup (FAQ)" ""
.sp
\fBcryptsetup\fP(8), \fBintegritysetup\fP(8) و \fBveritysetup\fP(8)
.SH "کریپت‌ست‌آپ (CRYPTSETUP)"
.sp
بخشی از \c
.URL "https://gitlab.com/cryptsetup/cryptsetup" "پروژه cryptsetup" "."