.\" Copyright (c) 2018-2026 Yubico AB. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\"    1. Redistributions of source code must retain the above copyright
.\"       notice, this list of conditions and the following disclaimer.
.\"    2. Redistributions in binary form must reproduce the above copyright
.\"       notice, this list of conditions and the following disclaimer in
.\"       the documentation and/or other materials provided with the
.\"       distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.Dd $Mdocdate: December 8 2025 $
.Dt FIDO2-CRED 1
.Os
.Sh "نام (NAME)"
.Nm fido2-cred
.Nd ساخت و تایید اعتبارنامه FIDO2
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Fl M
.Op Fl bdhqruvw
.Op Fl t Ar option
.Op Fl a Ar mode
.Op Fl c Ar cred_protect
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Ar device
.Op Ar type
.Nm
.Fl V
.Op Fl dhv
.Op Fl c Ar cred_protect
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Op Ar type
.Sh "توضیحات (DESCRIPTION)"
.Nm
اعتبارنامه FIDO2 را ایجاد یا تایید صحت می‌کند.
.Pp
نوع اعتبارنامه (
.Ar type
) می‌تواند
.Em es256
(نشان‌دهنده ECDSA روی NIST P-256 با SHA-256)،
.Em es384
(نشان‌دهنده ECDSA روی NIST P-384 با SHA-384)،
.Em rs256
(نشان‌دهنده RSA با طول کلید ۲۰۴۸ بیتی با پدینگ PKCS#1.5 و SHA-256)، یا
.Em eddsa
(نشان‌دهنده EDDSA روی Curve25519 با SHA-512) باشد.
اگر
.Ar type
مشخص نشود،
.Em es256
فرض می‌شود.
.Pp
هنگام ساخت اعتبارنامه، احرازکننده‌هویت ممکن است از کاربر بخواهد با PIN احراز هویت کند.
اگر گزینه
.Fl q
مشخص نشده باشد،
.Nm
از کاربر درخواست وارد کردن PIN خواهد کرد.
اگر یک
.Em tty
در دسترس باشد،
.Nm
از آن برای دریافت PIN استفاده می‌کند.
در غیر این صورت،
.Em stdin
استفاده می‌شود.
.Pp
ورودی
.Nm
توسط پارامترهای اعتبارنامه‌ای که قرار است ایجاد یا تایید شود، تعریف می‌گردد.
برای جزئیات به بخش
.Sx "قالب ورودی (INPUT FORMAT)"
مراجعه کنید.
.Pp
خروجی
.Nm
توسط نتیجه عملیات انتخابی تعریف می‌شود.
برای جزئیات به بخش
.Sx "قالب خروجی (OUTPUT FORMAT)"
مراجعه کنید.
.Pp
اگر اعتبارنامه‌ای با موفقیت ایجاد یا تایید شود،
.Nm
با کد وضعیت 0 خارج می‌شود.
در غیر این صورت،
.Nm
با کد وضعیت 1 خارج می‌شود.
.Pp
گزینه‌ها به شرح زیر هستند:
.Bl -tag -width Ds
.It Fl M
به
.Nm
می‌گوید که یک اعتبارنامه جدید روی
.Ar device
بسازد.
.It Fl V
به
.Nm
می‌گوید که یک اعتبارنامه را تایید صحت کند.
.It Fl b
درخواست
.Dq largeBlobKey
مربوط به اعتبارنامه؛ یک کلید متقارن ۳۲ بایتی مرتبط با اعتبارنامه تولیدشده.
.It Fl a Ar mode
هنگام ساخت اعتبارنامه، درخواست تصدیق سازمانی (enterprise attestation).
لطفاً برای مجموعه مقادیر ممکن به
.In fido/param.h
مراجعه کنید.
.It Fl c Ar cred_protect
در صورت ساخت اعتبارنامه، تعیین سطح حفاظت اعتبارنامه روی
.Ar cred_protect ،
که در آن
.Ar cred_protect
سطح حفاظت اعتبارنامه در نماد ده‌دهی (دسیمال) است.
لطفاً برای مجموعه مقادیر ممکن به
.In fido/param.h
مراجعه کنید.
در صورت تایید اعتبارنامه، بررسی می‌کند که آیا سطح حفاظت اعتبارنامه توسط احرازکننده‌هویت به عنوان
.Ar cred_protect
امضا شده است یا خیر.
.It Fl d
باعث می‌شود
.Nm
خروجی اشکال‌زدایی را روی
.Em stderr
چاپ کند.
.It Fl h
در صورت ساخت اعتبارنامه، فعال‌سازی افزونه hmac-secret پروتکل FIDO2.
در صورت تایید اعتبارنامه، بررسی می‌کند که آیا بیت داده‌های افزونه توسط احرازکننده‌هویت امضا شده است یا خیر.
.It Fl i Ar input_file
به
.Nm
دستور می‌دهد پارامترهای اعتبارنامه را به جای
.Em stdin
از
.Ar input_file
بخواند.
.It Fl o Ar output_file
به
.Nm
دستور می‌دهد خروجی را به جای
.Em stdout
در
.Ar output_file
بنویسد.
.It Fl q
به
.Nm
می‌گوید که در حالت بی‌صدا کار کند.
اگر وارد کردن PIN الزامی باشد و
.Fl q
مشخص شده باشد،
.Nm
با شکست مواجه خواهد شد.
.It Fl r
ایجاد یک اعتبارنامه مقیم (resident credential).
اعتبارنامه‌های مقیم در پروتکل CTAP 2.1 با نام
.Dq discoverable credentials
شناخته می‌شوند.
.It Fl t Ar option
تغییر وضعیت یک گزینه کلید/مقدار
.Ar option ،
که در آن
.Ar option
رشته‌ای به صورت
.Dq key=value
است. گزینه‌هایی که در حال حاضر پشتیبانی می‌شوند عبارتند از:
.Bl -tag -width Ds
.It Cm uv Ns = Ns Ar true|false
از احرازکننده‌هویت درخواست می‌کند که تایید هویت کاربر فعال یا غیرفعال باشد.
.It Cm pin Ns = Ns Ar true|false
به
.Nm
می‌گوید که آیا درخواست PIN را نمایش دهد و تایید هویت کاربر را بخواهد یا خیر.
.El
.Pp
گزینه
.Fl t
می‌تواند چندین بار مشخص شود.
.It Fl u
ساخت یک اعتبارنامه U2F.
به طور پیش‌فرض،
.Nm
در صورت پشتیبانی احرازکننده‌هویت از FIDO2 استفاده می‌کند، و در غیر این صورت به U2F بازمی‌گردد.
.It Fl v
در صورت ساخت اعتبارنامه، درخواست تایید هویت کاربر.
در صورت تایید اعتبارنامه، بررسی می‌کند که آیا بیت تایید کاربر توسط احرازکننده‌هویت امضا شده است یا خیر.
.It Fl w
به
.Nm
می‌گوید که خط اول ورودی هنگام ساخت اعتبارنامه باید به عنوان داده‌های هش‌نشده سرویس‌گیرنده (unhashed client data) تفسیر شود.
این گزینه برای Windows Hello مورد نیاز است، زیرا هش داده‌های کلاینت را در درون خود محاسبه می‌کند.
.El
.Sh "قالب ورودی (INPUT FORMAT)"
ورودی
.Nm
شامل بلوک‌های base64 و رشته‌های UTF-8 است که با کاراکترهای خط جدید ('\\n') از یکدیگر جدا شده‌اند.
.Pp
هنگام ساخت اعتبارنامه،
.Nm
انتظار دارد ورودی آن شامل موارد زیر باشد:
.Pp
.Bl -enum -offset indent -compact
.It
هش داده‌های کلاینت (بلوک base64)؛
.It
شناسه طرف متکی یا Relying Party (رشته UTF-8)؛
.It
نام کاربر (رشته UTF-8)؛
.It
شناسه کاربر (بلوک base64).
.El
.Pp
هنگام تایید اعتبارنامه،
.Nm
انتظار دارد ورودی آن شامل موارد زیر باشد:
.Pp
.Bl -enum -offset indent -compact
.It
هش داده‌های کلاینت (بلوک base64)؛
.It
شناسه طرف متکی یا Relying Party (رشته UTF-8)؛
.It
قالب اعتبارنامه (رشته UTF-8)؛
.It
داده‌های احرازکننده‌هویت کدگذاری‌شده با CBOR (بلوک base64)؛
.It
شناسه اعتبارنامه (بلوک base64)؛
.It
امضای تصدیق (بلوک base64)؛
.It
گواهی تصدیق (اختیاری، بلوک base64).
.El
.Pp
رشته‌های UTF-8 ارسال‌شده به
.Nm
نباید دارای کاراکترهای خط جدید یا NUL باشند.
.Sh "قالب خروجی (OUTPUT FORMAT)"
خروجی
.Nm
شامل بلوک‌های base64، رشته‌های UTF-8 و کلیدهای عمومی با قالب کدگذاری‌شده PEM است که با کاراکترهای خط جدید ('\\n') از یکدیگر جدا شده‌اند.
.Pp
پس از تولید موفقیت‌آمیز یک اعتبارنامه،
.Nm
موارد زیر را در خروجی چاپ می‌کند:
.Pp
.Bl -enum -offset indent -compact
.It
هش داده‌های کلاینت (بلوک base64)؛
.It
شناسه طرف متکی یا Relying Party (رشته UTF-8)؛
.It
قالب اعتبارنامه (رشته UTF-8)؛
.It
داده‌های احرازکننده‌هویت کدگذاری‌شده با CBOR (بلوک base64)؛
.It
شناسه اعتبارنامه (بلوک base64)؛
.It
امضای تصدیق (بلوک base64)؛
.It
گواهی تصدیق، در صورت وجود (بلوک base64).
.It
کلید متقارن ۳۲ بایتی مرتبط با اعتبارنامه
.Pq Dq largeBlobKey ،
در صورت وجود (بلوک base64).
.El
.Pp
پس از تایید موفقیت‌آمیز یک اعتبارنامه،
.Nm
موارد زیر را در خروجی چاپ می‌کند:
.Pp
.Bl -enum -offset indent -compact
.It
شناسه اعتبارنامه (بلوک base64)؛
.It
کلید اعتبارنامه کدگذاری‌شده با PEM.
.El
.Sh "مثال‌ها (EXAMPLES)"
ساخت یک اعتبارنامه جدید
.Em es256
روی
.Pa /dev/hidraw5 ،
تایید صحت آن، و ذخیره شناسه و کلید عمومی اعتبارنامه در
.Em cred :
.Pp
.Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param
.Dl $ echo relying party >> cred_param
.Dl $ echo user name >> cred_param
.Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param
.Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred
.Sh "همچنین ببینید (SEE ALSO)"
.Xr fido2-assert 1 ,
.Xr fido2-token 1
.Sh "هشدارها (CAVEATS)"
لطفاً توجه داشته باشید که
.Nm
تصدیق پایه (Basic Attestation) و خودتصدیقی (Self Attestation) را به طور شفاف مدیریت می‌کند.
در صورت استفاده از تصدیق پایه، اعتبار گواهی تصدیق احرازکننده‌هویت بررسی و تایید
.Em نمی‌شود .