.\" Copyright (c) 2018-2023 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: July 3 2023 $
.Dt FIDO2-ASSERT 1
.Os
.Sh "نام (NAME)"
.Nm fido2-assert
.Nd دریافت یا اعتبارسنجی یک ادعای FIDO2
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Fl G
.Op Fl bdhpruvw
.Op Fl t Ar option
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Ar device
.Nm
.Fl V
.Op Fl dhpv
.Op Fl i Ar input_file
.Ar key_file
.Op Ar type
.Sh "توضیحات (DESCRIPTION)"
.Nm
یک ادعای (assertion) FIDO2 را دریافت یا اعتبارسنجی می‌کند.
.Pp
ورودی
.Nm
توسط پارامترهای ادعایی که قرار است دریافت یا اعتبارسنجی شود تعیین می‌شود.
برای جزئیات بیشتر به بخش
.Sx "قالب ورودی (INPUT FORMAT)"
مراجعه کنید.
.Pp
خروجی
.Nm
توسط نتیجه عملیات انتخاب‌شده تعیین می‌شود.
برای جزئیات بیشتر به بخش
.Sx "قالب خروجی (OUTPUT FORMAT)"
مراجعه کنید.
.Pp
اگر یک ادعا با موفقیت دریافت یا اعتبارسنجی شود،
.Nm
با کد وضعیت 0 خارج می‌شود.
در غیر این صورت،
.Nm
با کد وضعیت 1 خارج می‌شود.
.Pp
گزینه‌ها به شرح زیر هستند:
.Bl -tag -width Ds
.It Fl G
به
.Nm
دستور می‌دهد تا یک ادعای جدید را از
.Ar device
دریافت کند.
.It Fl V
به
.Nm
دستور می‌دهد تا یک ادعا را با استفاده از کلید عمومی با کدگذاری PEM در
.Ar key_file
از نوع
.Ar type
اعتبارسنجی کند، که در آن
.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
فرض می‌شود.
.It Fl b
درخواست
.Dq largeBlobKey
مربوط به اعتبارنامه؛ یک کلید متقارن ۳۲ بایتی مرتبط با اعتبارنامه ادعاشده.
.It Fl h
هنگام دریافت ادعا، افزونه hmac-secret در FIDO2 را فعال می‌کند.
هنگام اعتبارسنجی ادعا، بررسی می‌کند که آیا بیت داده افزونه توسط احرازکننده امضا شده است یا خیر.
.It Fl d
باعث می‌شود
.Nm
خروجی اشکال‌زدایی را روی
.Em stderr
چاپ کند.
.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 p
هنگام دریافت ادعا، حضور کاربر (user presence) را درخواست می‌کند.
هنگام اعتبارسنجی ادعا، بررسی می‌کند که آیا بیت حضور کاربر توسط احرازکننده امضا شده است یا خیر.
.It Fl r
دریافت یک ادعا با استفاده از یک اعتبارنامه مقیم (resident credential).
اگر
.Fl r
مشخص شده باشد،
.Nm
در ورودی خود انتظار شناسه اعتبارنامه را نخواهد داشت و ممکن است چندین ادعا را در خروجی ارائه دهد.
اعتبارنامه‌های مقیم در CTAP 2.1 با عنوان
.Dq discoverable credentials
(اعتبارنامه‌های قابل‌کشف) نامیده می‌شوند.
.It Fl t Ar option
یک
.Ar option
کلید/مقدار را تغییر وضعیت می‌دهد، که در آن
.Ar option
رشته‌ای به صورت
.Dq key=value
است.
گزینه‌هایی که در حال حاضر پشتیبانی می‌شوند عبارتند از:
.Bl -tag -width Ds
.It Cm up Ns = Ns Ar true|false
از احرازکننده درخواست می‌کند که حضور کاربر فعال یا غیرفعال شود.
.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
هنگام دریافت ادعا، از کاربر درخواست PIN می‌کند و اعتبارسنجی کاربر را از احرازکننده تقاضا می‌نماید.
هنگام اعتبارسنجی ادعا، بررسی می‌کند که آیا بیت اعتبارسنجی کاربر توسط احرازکننده امضا شده است یا خیر.
.It Fl w
به
.Nm
می‌گوید که هنگام دریافت یک ادعا، خط اول ورودی را به عنوان داده‌های هش‌نشده کلاینت تفسیر کند.
این مورد برای Windows Hello لازم است، که هش داده‌های کلاینت را به صورت داخلی محاسبه می‌کند.
.El
.Pp
اگر یک
.Em tty
در دسترس باشد،
.Nm
از آن برای دریافت PIN استفاده خواهد کرد.
در غیر این صورت،
.Em stdin
استفاده می‌شود.
.Sh "قالب ورودی (INPUT FORMAT)"
ورودی
.Nm
شامل داده‌های باینری (blob) در قالب base64 و رشته‌های UTF-8 است که با نویسه خط جدید ('\\n') از هم جدا شده‌اند.
.Pp
هنگام دریافت یک ادعا،
.Nm
انتظار دارد ورودی آن شامل موارد زیر باشد:
.Pp
.Bl -enum -offset indent -compact
.It
هش داده‌های کلاینت (blob در قالب base64)؛
.It
شناسه طرف متکی (relying party id) (رشته UTF-8)؛
.It
شناسه اعتبارنامه، در صورتی که اعتبارنامه مقیم نباشد (blob در قالب base64)؛
.It
سالت hmac، در صورتی که افزونه hmac-secret در FIDO2 فعال باشد (blob در قالب base64)؛
.El
.Pp
هنگام اعتبارسنجی یک ادعا،
.Nm
انتظار دارد ورودی آن شامل موارد زیر باشد:
.Pp
.Bl -enum -offset indent -compact
.It
هش داده‌های کلاینت (blob در قالب base64)؛
.It
شناسه طرف متکی (relying party id) (رشته UTF-8)؛
.It
داده‌های احرازکننده کدگذاری‌شده با CBOR (blob در قالب base64)؛
.It
امضای ادعا (blob در قالب base64)؛
.El
.Pp
رشته‌های UTF-8 ارسال‌شده به
.Nm
نباید حاوی نویسه‌های خط جدید یا NUL در میان خود باشند.
.Sh "قالب خروجی (OUTPUT FORMAT)"
خروجی
.Nm
شامل داده‌های باینری (blob) در قالب base64 و رشته‌های UTF-8 است که با نویسه خط جدید ('\\n') از هم جدا شده‌اند.
.Pp
به ازای هر ادعای تولیدشده،
.Nm
موارد زیر را در خروجی چاپ می‌کند:
.Pp
.Bl -enum -offset indent -compact
.It
هش داده‌های کلاینت (blob در قالب base64)؛
.It
شناسه طرف متکی (relying party id) (رشته UTF-8)؛
.It
داده‌های احرازکننده کدگذاری‌شده با CBOR (blob در قالب base64)؛
.It
امضای ادعا (blob در قالب base64)؛
.It
شناسه کاربر، در صورتی که اعتبارنامه مقیم باشد (blob در قالب base64)؛
.It
رمز hmac، در صورتی که افزونه hmac-secret در FIDO2 فعال باشد (blob در قالب base64)؛
.It
کلید متقارن ۳۲ بایتی مرتبط با اعتبارنامه
.Pq Dq largeBlobKey ،
در صورت درخواست (blob در قالب base64).
.El
.Pp
هنگام اعتبارسنجی یک ادعا،
.Nm
هیچ خروجی‌ای تولید نمی‌کند.
.Sh "مثال‌ها (EXAMPLES)"
با فرض اینکه
.Pa cred
شامل یک اعتبارنامه
.Em es256
است که بر اساس مراحل شرح داده شده در
.Xr fido2-cred 1
ایجاد شده است، دریافت یک ادعا از یک احرازکننده در
.Pa /dev/hidraw5
و اعتبارسنجی آن:
.Pp
.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param
.Dl $ echo relying party >> assert_param
.Dl $ head -1 cred >> assert_param
.Dl $ tail -n +2 cred > pubkey
.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256
.Sh "همچنین ببینید (SEE ALSO)"
.Xr fido2-cred 1 ,
.Xr fido2-token 1