نام (NAME)

openssl-pkeyutl - دستور عملیات روی کلیدهای نامتقارن

خلاصه دستور (SYNOPSIS)

openssl pkeyutl [-help] [-in file] [-rawin] [-digest algorithm] [-out file] [-secret file] [-sigfile file] [-inkey filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-pubin] [-certin] [-rev] [-sign] [-verify] [-verifyrecover] [-encrypt] [-decrypt] [-derive] [-peerkey file] [-peerform DER|PEM|P12|ENGINE] [-encap] [-decap] [-kdf algorithm] [-kdflen length] [-kemop mode] [-pkeyopt opt:value] [-pkeyopt_passin opt[:passarg]] [-hexdump] [-asn1parse] [-engine id] [-engine_impl] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-provparam [name:]key=value] [-propquery propq] [-config configfile]

توضیحات (DESCRIPTION)

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

به‌طور پیش‌فرض، عملیات امضا (گزینه -sign را ببینید) در نظر گرفته می‌شود.

گزینه‌ها (OPTIONS)

-help

چاپ پیام راهنمای نحوه استفاده از دستور.

-in filename

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

-rawin

این گزینه نشان می‌دهد که داده‌های ورودی امضا یا اعتبارسنجی، داده‌های خام هستند که توسط هیچ الگوریتم خلاصه پیام (دایجِست) هش نشده‌اند. به جز در الگوریتم EdDSA، کاربر می‌تواند با استفاده از گزینه -digest یک الگوریتم دایجِست را مشخص کند. برای الگوریتم‌های امضا مانند RSA، DSA و ECDSA، الگوریتم دایجِست پیش‌فرض SHA256 است. برای SM2، این مقدار SM3 است.

این گزینه تنها همراه با -sign و -verify قابل استفاده است. برای EdDSA (الگوریتم‌های Ed25519 و Ed448) از نسخه ۳٫۵ به بعد اوپن‌اس‌اس‌ال این گزینه به‌صورت ضمنی اعمال می‌شود و در نسخه‌های پیشین الزامی بود.

گزینه -digest از نسخه ۳٫۵ به بعد اوپن‌اس‌اس‌ال متضمن -rawin است.

-digest algorithm

این گزینه فقط با -sign و -verify قابل استفاده است. این گزینه الگوریتم دایجِست مورد استفاده برای هش کردن داده‌های ورودی را پیش از امضا یا اعتبارسنجی با کلید ورودی مشخص می‌کند. اگر الگوریتم امضا پیش از امضا نیازی به پیش‌پردازش ورودی از طریق یک تابع هش متصل‌شونده نداشته باشد (برای نمونه در EdDSA)، می‌توان از این گزینه صرف‌نظر کرد. اگر از این گزینه صرف‌نظر شود اما الگوریتم امضا به آن نیاز داشته باشد و گزینه -rawin ارائه شده باشد، یک مقدار پیش‌فرض استفاده خواهد شد (برای جزئیات به -rawin مراجعه کنید). اگر این گزینه درج شده باشد، از نسخه ۳٫۵ اوپن‌اس‌اس‌ال گزینه -rawin به‌طور ضمنی در نظر گرفته می‌شود و در نسخه‌های پیشین الزامی بود.

در حال حاضر HashEdDSA (گونه ph یا «پیش‌هش‌شده» از EdDSA) پشتیبانی نمی‌شود، بنابراین گزینه -digest را نمی‌توان با EdDSA استفاده کرد.

-out filename

نام فایل خروجی برای نوشتن را مشخص می‌کند، یا به‌طور پیش‌فرض از خروجی استاندارد استفاده می‌شود.

-secret filename

نام فایل خروجی راز مشترک را هنگام اجرای کپسوله‌سازی از طریق گزینه -encap یا بازگشایی کپسول از طریق گزینه -decap مشخص می‌کند. گزینه -encap همچنین یک خروجی متن‌رمزشده (عمومی) مجزا تولید می‌کند که به‌طور پیش‌فرض در خروجی استاندارد نوشته می‌شود، اما از آنجا که داده‌های باینری غیرمتنی هستند، معمولاً به فایلی که با گزینه -out انتخاب شده است هدایت می‌شود.

-sigfile file

فایل امضا؛ فقط برای عملیات -verify الزامی و مجاز است.

-inkey filename|uri

کلید ورودی؛ به‌طور پیش‌فرض باید یک کلید خصوصی باشد.

-keyform DER|PEM|P12|ENGINE

قالب کلید؛ به‌طور پیش‌فرض مشخص نشده است. برای جزئیات بیشتر به openssl-format-options(1) مراجعه کنید.

-passin arg

منبع عبارت عبور برای کلید ورودی. برای اطلاعات بیشتر در مورد قالب arg به openssl-passphrase-options(1) مراجعه کنید.

-pubin

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

-certin

ورودی یک گواهی حاوی کلید عمومی است.

-rev

ترتیب بایت‌های بافر ورودی را معکوس می‌کند. این گزینه برای برخی کتابخانه‌ها (مانند CryptoAPI) که بافر را در قالب اندیان کوچک (little-endian) نمایش می‌دهند مفید است. این گزینه نمی‌تواند همراه با -rawin استفاده شود.

-sign

داده‌های ورودی را امضا کرده و نتیجه امضا را در خروجی قرار می‌دهد. این کار نیازمند کلید خصوصی است. استفاده از یک عملیات دایجِست پیام به همراه این گزینه، در صورت کاربرد، توصیه می‌شود؛ برای جزئیات به گزینه‌های -rawin و -digest مراجعه کنید. در غیر این صورت، داده‌های ورودی ارائه‌شده با گزینه -in پیشاپیش یک دایجِست در نظر گرفته می‌شوند، اما این کار ممکن است در برخی موارد (به‌عنوان مثال، RSA با حالت پدینگ پیش‌فرض PKCS#1) نیازمند گزینه اضافی -pkeyopt "digest:"md باشد. حتی برای الگوریتم‌های دیگری مانند ECDSA که گزینه اضافی -pkeyopt بر خروجی امضا تأثیری ندارد، استفاده از آن توصیه می‌شود، زیرا امکان بررسی همخوانی طول ورودی با دایجِست مورد نظر را فراهم می‌سازد.

-verify

داده‌های ورودی را در برابر امضای ارائه‌شده با گزینه -sigfile اعتبارسنجی کرده و موفقیت یا شکست اعتبارسنجی را مشخص می‌کند. داده‌های ورودی ارائه‌شده با گزینه -in یک مقدار هش در نظر گرفته می‌شوند مگر آنکه گزینه -rawin مشخص شده یا ضمنی باشد. در صورت استفاده از داده‌های خام، هنگامی که الگوریتم دایجِست کاربرد دارد، اگرچه ممکن است از امضا استنباط شود یا مقدار پیش‌فرضی به خود بگیرد، بهتر است آن نیز به‌طور صریح مشخص گردد.

-verifyrecover

امضای ارائه‌شده را اعتبارسنجی کرده و داده‌های بازیابی‌شده (بار داده امضا) را در خروجی قرار می‌دهد. برای نمونه، در مورد RSA PKCS#1 داده‌های بازیابی‌شده همان کدگذاری DER ساختار EMSA-PKCS-v1_5 از OID الگوریتم دایجِست و مقدار آن است، همان‌گونه که در بخش ۹٫۲ از RFC8017 https://datatracker.ietf.org/doc/html/rfc8017#section-9.2 مشخص شده است.

توجه داشته باشید که در اینجا ورودی ارائه‌شده با گزینه -in ورودی امضا نیست (مانند گزینه‌های -sign و -verify)، بلکه یک مقدار خروجی امضا است که معمولاً با استفاده از گزینه -sign تولید شده است.

این گزینه فقط برای استفاده با کلیدهای RSA در دسترس است.

-encrypt

داده‌های ورودی را با استفاده از یک کلید عمومی رمزگذاری می‌کند.

-decrypt

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

-derive

یک راز مشترک را با استفاده از کلید خصوصی (EC)DH خودی و کلید طرف مقابل (peer) مشتق می‌کند.

-peerkey file

فایلی شامل کلید عمومی یا خصوصی (EC)DH طرف مقابل که باید در عملیات اشتقاق (توافق) کلید استفاده شود. نوع این کلید باید با نوع کلید خصوصی خودی ارائه‌شده با گزینه -inkey مطابقت داشته باشد.

-peerform DER|PEM|P12|ENGINE

قالب کلید طرف مقابل؛ به‌طور پیش‌فرض مشخص نشده است. برای جزئیات بیشتر به openssl-format-options(1) مراجعه کنید.

-encap

استفاده از سازوکار کپسوله‌سازی کلید (KEM) برای کپسوله‌سازی یک راز مشترک برای کلید عمومی طرف مقابل. نتیجه کپسوله‌شده (یا متن‌رمزشده، داده‌های باینری غیرمتنی) به‌طور پیش‌فرض در خروجی استاندارد یا در فایلی که با -out مشخص شده است نوشته می‌شود. گزینه -secret نیز باید برای مشخص کردن فایل خروجی برای مقدار راز مشترک مشتق‌شده که در فرایند کپسوله‌سازی تولید می‌شود ارائه گردد. کپسوله‌سازی در حال حاضر با چندین الگوریتم کلید عمومی پشتیبانی می‌شود: ML-KEM، X25519، X448 و EC. الگوریتم‌های ECX و EC از ساختار DHKEM طبق RFC9180 https://www.rfc-editor.org/rfc/rfc9180 استفاده می‌کنند. کپسوله‌سازی با کلیدهای RSA نیز از طریق ساختار RSASVE پشتیبانی می‌شود.

در سطح API، کپسوله‌سازی و بازگشایی کپسول برای چند الگوریتم ترکیبی (hybrid) شامل ECDHE (بدون DHKEM) به همراه ML-KEM نیز پشتیبانی می‌شود، اما این الگوریتم‌ها اصولاً برای استفاده در TLS طراحی شده‌اند و نباید به‌صورت مستقل به کار روند. به هر روی، قالب استانداردی برای کلیدهای عمومی و خصوصی الگوریتم‌های ترکیبی وجود ندارد، بنابراین فراهم کردن داده‌های کلید مورد نیاز ممکن نیست.

-decap

رمزگشایی یک راز کپسوله‌شده با استفاده از یک کلید خصوصی، برای مشتق کردن همان راز مشترکی که هنگام کپسوله‌سازی راز با کلید عمومی مربوطه حاصل شده بود. راز کپسوله‌شده به‌طور پیش‌فرض از ورودی استاندارد یا از فایلی که با -in مشخص شده خوانده می‌شود. راز مشترک مشتق‌شده در فایلی که با گزینه -secret مشخص شده نوشته می‌شود که ارائه آن الزامی است. بازگشایی کپسول در حال حاضر با تعدادی از الگوریتم‌های کلید عمومی پشتیبانی می‌شود: ML-KEM، X25519، X448 و EC. الگوریتم‌های ECX و EC از ساختار DHKEM طبق RFC9180 https://www.rfc-editor.org/rfc/rfc9180 استفاده می‌کنند. بازگشایی کپسول با کلیدهای RSA نیز از طریق ساختار RSASVE پشتیبانی می‌شود.

-kemop mode

این گزینه همراه با دستورات -encap/-decap استفاده می‌شود و حالت (mode) خاص KEM برای الگوریتم کلید را زمانی که روش پیش‌فرضی برای کپسوله‌سازی و بازگشایی رازهای مشترک با نوع کلید انتخابی وجود ندارد مشخص می‌کند. در حال حاضر تمامی الگوریتم‌های پشتیبانی‌شده فقط از mode پیش‌فرض خود پشتیبانی می‌کنند، بنابراین این گزینه گرچه موجود است اما الزامی نیست.

-kdf algorithm

استفاده از الگوریتم تابع اشتقاق کلید (algorithm). الگوریتم‌های پشتیبانی‌شده در حال حاضر عبارتند از TLS1-PRF و HKDF. توجه: معمولاً برای عملکرد صحیح باید پارامترهای اضافی و طول خروجی KDF تنظیم شوند. برای پارامترهای رشته‌ای پشتیبانی‌شده هر الگوریتم به EVP_PKEY_CTX_set_hkdf_md(3) و EVP_PKEY_CTX_set_tls1_prf_md(3) مراجعه کنید.

-kdflen length

تنظیم طول خروجی برای KDF.

-pkeyopt opt:value

گزینه‌های کلید عمومی که به‌صورت opt:value مشخص می‌شوند. برای جزئیات بیشتر به بخش «یادداشت‌ها» در ادامه مراجعه کنید.

-pkeyopt_passin opt[:passarg]

امکان خواندن یک گزینه کلید عمومی opt از ورودی استاندارد (stdin) یا منبع گذرواژه را فراهم می‌کند. اگر فقط opt مشخص شود، از کاربر در stdin خواسته می‌شود تا گذرواژه‌ای را وارد کند. همچنین می‌توان passarg را مشخص کرد که می‌تواند هر مقداری باشد که توسط openssl-passphrase-options(1) پشتیبانی می‌شود.

-hexdump

نمایش هگزادسیمال (hexdump) داده‌های خروجی.

-asn1parse

تجزیه داده‌های خروجی ASN.1 برای بررسی کدگذاری DER آن و چاپ هرگونه خطا. هنگامی که این گزینه با گزینه -verifyrecover ترکیب شود، در مواردی که یک ساختار کدگذاری‌شده DER از نوع ASN.1 مستقیماً (بدون هش کردن) امضا شده باشد و هنگام بررسی امضا در قالب PKCS#1 v1.5 که دارای کدگذاری DER است، می‌تواند مفید باشد.

-engine id

بخش "Engine Options" را در openssl(1) ببینید. این گزینه منسوخ شده است.

-engine_impl

هنگامی که با گزینه -engine استفاده شود، مشخص می‌کند که از موتور id برای عملیات رمزنگاری نیز استفاده شود.

-rand files, -writerand file

برای جزئیات بیشتر بخش "Random State Options" را در openssl(1) ببینید.

-provider name

-provider-path path

-provparam [name:]key=value

-propquery propq

بخش "Provider Options" را در openssl(1)، provider(7) و property(7) ببینید.

-config configfile

بخش "Configuration Option" را در openssl(1) ببینید.

یادداشت‌ها (NOTES)

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

مگر در مواردی که خلاف آن ذکر شده باشد، گزینه -pkeyopt برای تمامی انواع کلیدهای عمومی از آرگومان "digest:"alg پشتیبانی می‌کند که دایجِست مورد استفاده برای عملیات امضا و اعتبارسنجی را مشخص می‌سازد. مقدار alg باید نام یک دایجِست باشد، همان‌گونه که در تابع EVP_get_digestbyname() استفاده می‌شود؛ برای نمونه sha256. این مقدار برای هش کردن داده‌های ورودی استفاده نمی‌شود، بلکه (توسط برخی الگوریتم‌ها) برای بررسی صحت طول داده‌های ارائه‌شده و ایجاد ساختارهایی که امضا را تشکیل می‌دهند (مانند DigestInfo در امضاهای RSASSA PKCS#1 v1.5) به کار می‌رود.

برای مثال، اگر مقدار آرگومان "digest" در گزینه -pkeyopt برابر sha256 باشد، ورودی امضا یا اعتبارسنجی باید مقدار باینری ۳۲ بایتی حاصل از تابع هش SHA256 باشد.

مگر در صورتی که -rawin استفاده شده باشد یا به‌طور ضمنی اعمال گردد، این دستور داده‌های ورودی را هش نمی‌کند، بلکه داده‌ها را مستقیماً به‌عنوان ورودی الگوریتم امضا استفاده خواهد کرد. بسته به نوع کلید، نوع امضا و حالت پدینگ (padding)، حداکثر طول معقول داده‌های ورودی متفاوت است. در RSA، داده‌های امضاشده نمی‌توانند طولانی‌تر از مدول (modulus) کلید باشند. در مورد ECDSA و DSA، داده‌ها نباید طولانی‌تر از اندازه میدان (field size) باشند، در غیر این صورت بدون اعلان به اندازه میدان برش داده می‌شوند (truncate). در هر صورت، اندازه ورودی نباید بزرگ‌تر از بیشترین اندازه خروجی دایجِست پشتیبانی‌شده یعنی EVP_MAX_MD_SIZE باشد که در حال حاضر ۶۴ بایت است.

الگوریتم RSA (RSA ALGORITHM)

الگوریتم RSA عموماً از عملیات encrypt، decrypt، sign، verify و verifyrecover پشتیبانی می‌کند. با این حال، برخی حالت‌های پدینگ فقط از زیرمجموعه‌ای از این عملیات پشتیبانی می‌کنند. مقادیر اضافی pkeyopt زیر پشتیبانی می‌شوند:

rsa_padding_mode:mode

این گزینه حالت پدینگ RSA را تعیین می‌کند. مقادیر مجاز برای mode عبارتند از: pkcs1 برای پدینگ PKCS#1، none برای بدون پدینگ، oaep برای حالت OAEP، x931 برای حالت X9.31 و pss برای PSS.

در پدینگ PKCS#1، اگر دایجِست پیام تنظیم نشده باشد، داده‌های ارائه‌شده به‌جای استفاده از ساختار DigestInfo، مستقیماً امضا یا اعتبارسنجی می‌شوند. اگر دایجِست تنظیم شده باشد، ساختار DigestInfo استفاده می‌شود و طول آن باید متناسب با نوع دایجِست باشد.

توجه داشته باشید که برای پدینگ pkcs1، به‌عنوان محافظتی در برابر حمله بلیخن‌باخر (Bleichenbacher attack)، در صورت شکست بررسی پدینگ، عملیات رمزگشایی با شکست روبرو نخواهد شد. از گزینه none و بررسی دستی پیام رمزگشایی‌شده برای اطمینان از اینکه مقدار رمزگشایی‌شده دارای پدینگ صحیح PKCS#1 v1.5 است استفاده کنید.

برای حالت oaep فقط رمزگذاری و رمزگشایی پشتیبانی می‌شود.

برای x931 اگر نوع دایجِست تنظیم شده باشد، از آن برای قالب‌بندی داده‌های بلوک استفاده می‌شود، در غیر این صورت بایت اول برای تعیین شناسه دایجِست X9.31 به کار می‌رود. عملیات Sign، verify و verifyrecover در این حالت قابل اجرا هستند.

برای حالت pss فقط امضا و اعتبارسنجی (sign و verify) پشتیبانی می‌شود و نوع دایجِست باید حتماً مشخص گردد.

rsa_pss_saltlen:len

فقط برای حالت pss، این گزینه طول سالت (salt) را مشخص می‌کند. سه مقدار ویژه پشتیبانی می‌شود: digest طول سالت را برابر با طول دایجِست قرار می‌دهد؛ max طول سالت را روی حداکثر مقدار مجاز تنظیم می‌کند؛ در هنگام اعتبارسنجی، auto باعث می‌شود طول سالت به‌طور خودکار بر اساس ساختار بلوک PSS تعیین گردد.

rsa_mgf1_md:digest

برای پدینگ PSS و OAEP، دایجِست MGF1 را تعیین می‌کند. اگر دایجِست MGF1 در حالت PSS به‌طور صریح تنظیم نشده باشد، از دایجِست امضا استفاده می‌شود.

rsa_oaep_md:digest

دایجِست مورد استفاده برای تابع هش OAEP را تنظیم می‌کند. در صورت عدم تنظیم صریح، از SHA1 استفاده خواهد شد.

rsa_pkcs1_implicit_rejection:flag

استفاده از رد ضمنی (implicit rejection) را در رمزگشایی PKCS#1 v1.5 غیرفعال (در صورت تنظیم روی 0) یا فعال (در صورت تنظیم روی 1) می‌کند. در صورت فعال بودن (حالت پیش‌فرض)، کتابخانه به‌عنوان محافظتی در برابر حمله بلیخن‌باخر، یک متن آشکار تصادفی قطعی (deterministic random plaintext) تولید کرده و در صورت شکست بررسی پدینگ به فراخوان‌کننده برمی‌گرداند. هنگام غیرفعال بودن، رسیدگی به خطاهای برگشتی به روشی امن و بدون نشت کانال جانبی (side-channel) بر عهده فراخوان‌کننده است.

الگوریتم RSA-PSS (RSA-PSS ALGORITHM)

الگوریتم RSA-PSS نسخه‌ای محدودشده از الگوریتم RSA است که فقط از عملیات امضا و اعتبارسنجی (sign و verify) با پدینگ PSS پشتیبانی می‌کند. مقادیر اضافی -pkeyopt زیر پشتیبانی می‌شوند:

rsa_padding_mode:mode, rsa_pss_saltlen:len, rsa_mgf1_md:digest

این گزینه‌ها همان معنای ذکرشده در الگوریتم RSA را همراه با چند محدودیت اضافی دارند. حالت پدینگ فقط می‌تواند روی pss تنظیم شود که مقدار پیش‌فرض است.

اگر کلید دارای محدودیت‌های پارامتری باشد، دایجِست، دایجِست MGF1 و طول سالت بر روی مقادیر مشخص‌شده در پارامترها تنظیم می‌شوند. دایجِست و MGF قابل تغییر نیستند و طول سالت را نمی‌توان روی مقداری کمتر از حداقل محدودیت تعیین‌شده قرار داد.

الگوریتم DSA (DSA ALGORITHM)

الگوریتم DSA فقط از عملیات امضا و اعتبارسنجی پشتیبانی می‌کند. در حال حاضر گزینه اضافی دیگری در -pkeyopt به جز digest وجود ندارد. دایجِست SHA256 به‌طور پیش‌فرض در نظر گرفته می‌شود.

الگوریتم DH (DH ALGORITHM)

الگوریتم DH فقط از عملیات اشتقاق کلید (derivation) پشتیبانی می‌کند و فاقد هرگونه گزینه اضافی -pkeyopt است.

الگوریتم EC (EC ALGORITHM)

الگوریتم EC از عملیات sign، verify و derive پشتیبانی می‌کند. عملیات sign و verify از ECDSA و derive از ECDH استفاده می‌کند. برای گزینه digest در -pkeyopt به‌طور پیش‌فرض مقدار SHA256 در نظر گرفته می‌شود.

الگوریتم‌های X25519 و X448 (X25519 AND X448 ALGORITHMS)

الگوریتم‌های X25519 و X448 فقط از اشتقاق کلید پشتیبانی می‌کنند. در حال حاضر هیچ گزینه اضافی وجود ندارد.

الگوریتم‌های ML-DSA-44، ML-DSA-65 و ML-DSA-87 (ML-DSA-44, ML-DSA-65 AND ML-DSA-87 ALGORITHMS)

الگوریتم‌های ML-DSA الگوریتم‌های امضای پساکوانتومی هستند که از امضا و اعتبارسنجی پیام‌های «خام» پشتیبانی می‌کنند. هیچ هش‌کردن مقدماتی انجام نمی‌شود. هنگام استفاده از ML-DSA همراه با pkeyutl، گزینه‌های زیر در دسترس هستند:

-sign

امضای داده‌های ورودی با استفاده از یک کلید خصوصی ML-DSA. برای مثال:

$ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig

-verify

اعتبارسنجی امضا با استفاده از یک کلید عمومی ML-DSA. برای مثال:

$ openssl pkeyutl -verify -in file.txt -inkey mldsa65.pem -sigfile sig

-pkeyopt opt:value

گزینه‌های اضافی برای امضا و اعتبارسنجی ML-DSA:

context-string:string

یک رشته زمینه (context string) برای هر دو عملیات امضا و اعتبارسنجی مشخص می‌کند. رشته زمینه باید برای موفقیت اعتبارسنجی یکسان باشد. برای مثال:

$ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt context-string:mycontext
$ openssl pkeyutl -verify -in file.txt -inkey mldsa65.pem -sigfile sig -pkeyopt context-string:mycontext

hexcontext-string:string

یک رشته زمینه را در قالب هگزادسیمال مشخص می‌کند که امکان مقادیر کنترلی باینری را فراهم می‌سازد. برای مثال:

$ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt hexcontext-string:6d79636f6e74657874

عملیات امضا از گزینه deterministic:bool پشتیبانی می‌کند؛ در صورتی که bool روی 1 تنظیم شود، یک امضای قطعی با یک ورودی تصادفی ثابت کاملاً صفر تولید می‌شود. به‌طور پیش‌فرض، یا اگر bool برابر با 0 باشد، یک مقدار آنتروپی تصادفی استفاده می‌شود. نتیجه قطعی را همچنین می‌توان با مشخص کردن صریح یک مقدار آنتروپی از طریق پارامتر hextest-entropy:value به دست آورد. امضای قطعی ML-DSA فقط باید در آزمون‌ها استفاده شود.

برای جزئیات بیشتر پیرامون الگوریتم‌های ML-DSA و پیاده‌سازی آن‌ها به EVP_SIGNATURE-ML-DSA(7) مراجعه کنید.

الگوریتم‌های ML-KEM-512، ML-KEM-768 و ML-KEM-1024 (ML-KEM-512, ML-KEM-768 AND ML-KEM-1024 ALGORITHMS)

الگوریتم‌های ML-KEM فقط از کپسوله‌سازی و بازگشایی کپسول پشتیبانی می‌کنند. عملیات کپسوله‌سازی از گزینه hexikme:entropy پشتیبانی می‌کند که در آن entropy کدگذاری ۶۴ رقمی هگزادسیمال یک مقدار ۳۲ بایتی است. این گزینه فقط باید در آزمون‌ها استفاده شود؛ مقادیر شناخته‌شده یا فاش‌شده این گزینه ممکن است امنیت راز مشترک تولیدشده را به خطر بیندازند.

برای جزئیات بیشتر به EVP_KEM-ML-KEM(7) مراجعه کنید.

الگوریتم‌های ED25519 و ED448 (ED25519 AND ED448 ALGORITHMS)

این الگوریتم‌ها فقط از امضا و اعتبارسنجی پشتیبانی می‌کنند. اوپن‌اس‌اس‌ال فقط گونه‌های «خالص» (pure) این الگوریتم‌ها را پیاده‌سازی می‌کند، بنابراین داده‌های خام می‌توانند بدون اینکه ابتدا هش شوند، مستقیماً به آن‌ها ارسال شوند. اوپن‌اس‌اس‌ال فقط از عملیات «تک‌مرحله‌ای» (oneshot) با این الگوریتم‌ها پشتیبانی می‌کند. این بدان معناست که کل فایل مورد نظر برای امضا/اعتبارسنجی پیش از پردازش باید در حافظه خوانده شود. از امضا یا اعتبارسنجی فایل‌های بسیار حجیم باید خودداری شود. علاوه بر این، اندازه فایل برای عملکرد صحیح باید مشخص باشد. اگر اندازه فایل قابل تعیین نباشد (برای مثال اگر ورودی، ورودی استاندارد stdin باشد)، عملیات امضا یا اعتبارسنجی با شکست روبرو خواهد شد.

الگوریتم SM2 (SM2)

الگوریتم SM2 از عملیات sign، verify، encrypt و decrypt پشتیبانی می‌کند. برای عملیات sign و verify، الگوریتم SM2 نیازمند ارسال یک رشته شناسه تمایز (Distinguishing ID) است. مقادیر -pkeyopt زیر پشتیبانی می‌شوند:

distid:string

رشته شناسه (ID) مورد استفاده در عملیات امضا یا اعتبارسنجی SM2 را تنظیم می‌کند. هنگام اعتبارسنجی امضای SM2، رشته شناسه باید دقیقاً همان شناسه‌ای باشد که هنگام امضای داده‌ها استفاده شده است؛ در غیر این صورت اعتبارسنجی شکست خواهد خورد.

hexdistid:hex_string

رشته شناسه مورد استفاده در عملیات امضا یا اعتبارسنجی SM2 را تنظیم می‌کند. هنگام اعتبارسنجی امضای SM2، رشته شناسه باید همان شناسه‌ای باشد که هنگام امضای داده‌ها به کار رفته است؛ در غیر این صورت اعتبارسنجی با شکست مواجه می‌شود. رشته شناسه ارائه‌شده با این گزینه باید یک مقدار هگزادسیمال معتبر باشد.

مثال‌ها (EXAMPLES)

امضای داده‌ها با استفاده از یک کلید خصوصی:

openssl pkeyutl -sign -in file -inkey key.pem -out sig

بازیابی داده‌های امضاشده (مثلاً در صورت استفاده از کلید RSA):

openssl pkeyutl -verifyrecover -in sig -inkey key.pem

اعتبارسنجی امضا (مثلاً با یک کلید DSA):

openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem

امضای داده‌ها با استفاده از مقدار دایجِست پیام (این مورد در حال حاضر فقط برای RSA معتبر است):

openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256

مشتق کردن مقدار یک راز مشترک:

openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret

نمایش هگزادسیمال (hexdump) مقدار ۴۸ بایت از TLS1 PRF با استفاده از دایجِست SHA256 و راز مشترک و سید (seed) متشکل از تک‌بایت 0xFF:

openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
   -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump

اشتقاق کلید با استفاده از scrypt که در آن گذرواژه از خط فرمان خوانده می‌شود:

openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \
   -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1

اشتقاق با استفاده از همان الگوریتم، اما خواندن کلید از متغیر محیطی MYPASS:

openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \
   -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1

امضای داده‌ها با استفاده از یک کلید خصوصی SM2(7) و یک شناسه مشخص:

openssl pkeyutl -sign -in file -inkey sm2.key -out sig -rawin -digest sm3 \
   -pkeyopt distid:someid

اعتبارسنجی داده‌ها با استفاده از یک گواهی SM2(7) و یک شناسه مشخص:

openssl pkeyutl -verify -certin -in file -inkey sm2.cert -sigfile sig \
   -rawin -digest sm3 -pkeyopt distid:someid

رمزگشایی داده‌ها با استفاده از کلید خصوصی با پدینگ OAEP و با استفاده از SHA256:

openssl pkeyutl -decrypt -in file -inkey key.pem -out secret \
   -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

ایجاد یک جفت‌کلید ML-DSA و امضای داده‌ها با یک رشته زمینه مشخص:

$ openssl genpkey -algorithm ML-DSA-65 -out mldsa65.pem
$ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt context-string:example

اعتبارسنجی امضا با استفاده از ML-DSA با همان رشته زمینه:

$ openssl pkeyutl -verify -in file.txt -inkey mldsa65.pem -sigfile sig -pkeyopt context-string:example

تولید یک جفت‌کلید ML-KEM و استفاده از آن برای کپسوله‌سازی:

$ openssl genpkey -algorithm ML-KEM-768 -out mlkem768.pem
$ openssl pkey -in mlkem768.pem -pubout -out mlkem768_pub.pem
$ openssl pkeyutl -encap -inkey mlkem768_pub.pem -pubin -out ciphertext -secret shared_secret.bin

بازگشایی کپسول راز مشترک با استفاده از کلید خصوصی ML-KEM:

$ openssl pkeyutl -decap -inkey mlkem768.pem -in ciphertext -secret decapsulated_secret.bin

ایجاد یک جفت‌کلید SLH-DSA و امضای داده‌ها:

$ openssl genpkey -algorithm SLH-DSA-SHA2-128s -out slh-dsa.pem
$ openssl pkeyutl -sign -in file.txt -inkey slh-dsa.pem -out sig

اعتبارسنجی امضا با استفاده از SLH-DSA:

$ openssl pkeyutl -verify -in file.txt -inkey slh-dsa.pem -sigfile sig

همچنین ببینید (SEE ALSO)

openssl(1)، openssl-genpkey(1)، openssl-pkey(1)، openssl-rsautl(1)، openssl-dgst(1)، openssl-rsa(1)، openssl-genrsa(1)، openssl-kdf(1)، EVP_PKEY_CTX_set_hkdf_md(3)، EVP_PKEY_CTX_set_tls1_prf_md(3)

تاریخچه (HISTORY)

از نسخه ۳٫۵ اوپن‌اس‌اس‌ال، گزینه -digest متضمن -rawin است. گزینه -rawin هنگام امضا یا اعتبارسنجی با نوع کلیدی که از دایجِست پیش‌هش (prehash) پشتیبانی نمی‌کند، مانند Ed25519، Ed448، ML-DSA یا SLH-DSA، دیگر الزامی نیست. برای این انواع کلید، -digest پشتیبانی نمی‌شود.

همچنین از نسخه ۳٫۵ اوپن‌اس‌اس‌ال، گزینه -kemop دیگر برای هیچ‌یک از الگوریتم‌های پشتیبانی‌شده الزامی نیست؛ تنها حالت (mode) پشتیبانی‌شده در حال حاضر حالت پیش‌فرض است.

گزینه -engine در نسخه ۳٫۰ اوپن‌اس‌اس‌ال منسوخ شد.

حق نشر (COPYRIGHT)

حق نشر ۲۰۰۶-۲۰۲۶ نویسندگان پروژه OpenSSL. تمامی حقوق محفوظ است.

تحت مجوز آپاچی نسخه ۲٫۰ («مجوز») منتشر شده است. شما نمی‌توانید از این فایل استفاده کنید مگر با رعایت مقررات مجوز. می‌توانید نسخه‌ای از مجوز را در فایل LICENSE در توزیع مبدا یا در https://www.openssl.org/source/license.html دریافت کنید.