'" t
."     Title: pam_u2f
."    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
." Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
."      Date: Version\e 1.4.0
."    Manual: PAM U2F Module Manual
."    Source: pam-u2f
."  Language: English
."
.TH "PAM_U2F" "8" "Version\e 1\&.4\&.0" "pam\-u2f" "PAM U2F Module Manual"
." -----------------------------------------------------------------
." * Define some portability stuff
." -----------------------------------------------------------------
." ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
." http://bugs.debian.org/507673
." http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
." ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
." -----------------------------------------------------------------
." * set default formatting
." -----------------------------------------------------------------
." disable hyphenation
.nh
." disable justification (adjust text to left margin only)
.ad l
." -----------------------------------------------------------------
." * MAIN CONTENT STARTS HERE *
." -----------------------------------------------------------------
.SH "نام (NAME)"
pam_u2f \- ماژول PAM برای احراز هویت U2F
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBpam_u2f\fR [\&...]
.SH "توضیحات (DESCRIPTION)"
.sp
این ماژول امکان احراز هویت U2F را با استفاده از YubiKeyها و سایر احرازهویت‌کننده‌های سازگار فراهم می‌کند\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\fBdebug\fR
.RS 4
فعال‌سازی خروجی اشکال‌زدایی (دیباگ)\&.
.RE
.PP
\fBdebug_file\fR
.RS 4
نام فایل برای نوشتن پیام‌های اشکال‌زدایی در آن\&.
\fBاگر این فایل وجود نداشته باشد، هیچ پیامی ثبت نخواهد شد\fR\&. این فایل عادی
\fBباید توسط کاربر ایجاد شده باشد\fR
یا
\fBباید از قبل وجود داشته و یک فایل عادی باشد\fR
تا چیزی در آن لاگ شود\&. این فایل به عمد توسط pam\-u2f ساخته نمی‌شود (به دلایل امنیتی)\&. این نام فایل همچنین می‌تواند برابر "stderr" (پیش‌فرض)، "stdout" یا "syslog" تنظیم شود\&.
.RE
.PP
\fBorigin\fR=\fIorigin\fR
.RS 4
تنظیم شناسه طرف اعتمادکننده (relying party ID) برای فرایند احراز هویت FIDO\&. در صورت عدم تعیین مقدار، از شناسه "pam://" استفاده می‌شود\&.
.RE
.PP
\fBappid\fR=\fIappid\fR
.RS 4
تنظیم شناسه برنامه (application ID) برای فرایند احراز هویت FIDO\&. در صورت عدم تعیین مقدار، همان مقدار استفاده‌شده برای origin در نظر گرفته می‌شود (در صورت عدم تعیین origin نیز مقدار "pam://")\&. این تنظیم تنها برای اعتبارنامه‌های FIDO ایجادشده با نگارش‌های v1\&.0\&.8 یا قدیمی‌تر pamu2fcfg کاربرد دارد\&. توجه داشته باشید که در نسخه‌های v1\&.1\&.0 و v1\&.1\&.1 از pam\-u2f، پردازش این گزینه در صورتی که با مقدار origin یکسان نبود موقتاً دچار اشکال شده بود\&.
.RE
.PP
\fBauthfile\fR=\fIfile\fR
.RS 4
تعیین مکان فایلی که حاوی نگاشت‌های نام کاربری به keyHandleها و کلیدهای کاربر است\&. یک فایل جداگانه (به ازای هر کاربر) می‌تواند به صورت نسبی به پوشه خانگی کاربران پیکربندی شود، مانند "\&.ssh/u2f_keys"\&. در صورت عدم تعیین، مکان پیش‌فرض برابر /Yubico/u2f_keys است\&. اگر  تنظیم نشده باشد، از /home/ahoura/\&.config/Yubico/u2f_keys استفاده می‌شود\&. ساختار فایل authfile به این صورت است: <username>:<KeyHandle1>,<UserKey1>,<CoseType1>,<Options1>:<KeyHandle2>,<UserKey2>,<CoseType2>,<Options2>:\&...
.RE
.PP
\fBexpand\fR
.RS 4
فعال‌سازی بسط متغیرها در مسیر authfile:
عبارت %u به نام کاربری محلی (PAM_USER) و عبارت %% به % بسط داده می‌شود\&. الگوهای بسط ناشناخته منجر به خطای احراز هویت خواهند شد\&. گزینه openasuser را نیز مشاهده کنید\&.
.RE
.PP
\fBauthpending_file\fR=\fIfile\fR
.RS 4
تعیین مکان فایلی که برای اعلان‌های درخواست لمس به کار می‌رود\&. این فایل زمانی که pam\-u2f شروع به انتظار برای لمس دستگاه FIDO توسط کاربر می‌کند باز شده، و هنگامی که دیگر منتظر لمس نباشد بسته خواهد شد\&. از inotify برای گوش دادن به این رویدادها، یا از ابزارهای سطح بالاتر مانند yubikey\-touch\-detector استفاده کنید\&. مقدار پیش‌فرض: /var/run/user/1001/pam\-u2f\-authpending\&. برای غیرفعال کردن این قابلیت یک مقدار خالی تنظیم کنید: "authpending_file="\&.
.RE
.PP
\fBnouserok\fR
.RS 4
فعال کردن این گزینه باعث می‌شود تلاش‌های احراز هویت موفق شوند حتی اگر کاربری که تلاش می‌کند احراز هویت شود درون authfile یافت نشود یا اگر authfile وجود نداشته باشد یا معیوب باشد\&.
.RE
.PP
\fBopenasuser\fR
.RS 4
تغییر شناسه کاربری (Setuid) به کاربر در حال احراز هویت هنگام باز کردن authfile\&. هنگام ذخیره پوشه خانگی کاربر روی یک حجم NFS که با گزینه root_squash سوار شده است بسیار مفید خواهد بود (که root را به nobody تبدیل می‌کند و قادر به خواندن فایل نیست)\&. توجه داشته باشید که پس از نگارش 1\&.0\&.8، زمانی که هیچ authfile سراسری (با مسیر مطلق) یا متغیر محیطی XDG_CONFIG_HOME تنظیم نشده باشد، این عمل به طور پیش‌فرض انجام می‌شود\&.
.RE
.PP
\fBalwaysok\fR
.RS 4
تنظیم برای موفقیت تمام تلاش‌های احراز هویت (معروف به حالت نمایش یا presentation mode)\&.
.RE
.PP
\fBmax_devices\fR=\fIn_devices\fR
.RS 4
حداکثر تعداد احرازهویت‌کننده‌های FIDO مجاز به ازای هر کاربر (پیش‌فرض ۲۴ است)\&. احرازهویت‌کننده‌های FIDO مشخص‌شده در فایل نگاشت مجوزها که از این مقدار فراتر روند، نادیده گرفته خواهند شد\&.
.RE
.PP
\fBinteractive\fR
.RS 4
اعمال نمایش یک پیام و انتظار قبل از آزمایش حضور یک احرازهویت‌کننده FIDO\&. در صورتی که احرازهویت‌کننده شما فاقد ماشه لمسی باشد توصیه می‌شود\&.
.RE
.PP
\fB[prompt=your prompt here]\fR
.RS 4
تنظیم پیام درخواست مجزا برای حالت تعاملی\&. به براکت‌های دور این پارامتر توجه کنید تا فاصله‌ها توسط PAM به درستی تشخیص داده شوند\&.
.RE
.PP
\fBmanual\fR
.RS 4
تنظیم برای خروج به کنسول دستی که در آن چالش‌ها روی صفحه چاپ شده و پاسخ از ورودی استاندارد خوانده می‌شود\&. برای اشکال‌زدایی و نشست‌های SSH بدون پشتیبانی FIDO از سوی سرویس‌گیرنده/سرویس‌دهنده SSH کاربرد دارد\&. در صورت فعال بودن، حالت تعاملی زائد شده و اثری نخواهد داشت\&.
.RE
.PP
\fBcue\fR
.RS 4
نمایش پیامی برای یادآوری لمس دستگاه احراز هویت FIDO\&.
.RE
.PP
\fB[cue_prompt=your prompt here]\fR
.RS 4
تنظیم پیام یادآوری سفارشی برای گزینه cue\&. به براکت‌های دور این پارامتر توجه کنید تا فاصله‌ها به درستی توسط PAM شناخته شوند\&.
.RE
.PP
\fBnodetect\fR
.RS 4
صرف‌نظر کردن از تشخیص اینکه آیا یک دستگاه FIDO مناسب متصل است پیش از انجام احراز هویت کامل\&. بخش
\fBNOTES\fR
در زیر را ببینید\&.
.RE
.PP
\fBuserpresence\fR=\fIint\fR
.RS 4
اگر ۱ باشد، حضور کاربر در طول احراز هویت الزامی است\&. اگر ۰ باشد، حضور کاربر درخواست نمی‌شود\&. در صورت حذف، رفتار پیش‌فرض احرازهویت‌کننده استفاده خواهد شد\&.
.RE
.PP
\fBuserverification\fR=\fIint\fR
.RS 4
اگر ۱ باشد، اعتبارسنجی کاربر (مانند بیومتریک) در طول احراز هویت الزامی است\&. اگر ۰ باشد، درخواست نمی‌شود\&. در صورت حذف، به رفتار پیش‌فرض بازمی‌گردد\&. در صورت فعال بودن، یک دستگاه با پشتیبانی از تأیید کاربر FIDO2 مورد نیاز است\&.
.RE
.PP
\fBpinverification\fR=\fIint\fR
.RS 4
اگر ۱ باشد، اعتبارسنجی PIN در طول احراز هویت الزامی است\&. اگر ۰ باشد، درخواست نمی‌شود\&. در صورت حذف، به رفتار پیش‌فرض بازمی‌گردد\&. در صورت فعال بودن، دستگاه با پشتیبانی از PIN در FIDO2 مورد نیاز است\&.
.RE
.PP
\fBsshformat\fR
.RS 4
استفاده از اعتبارنامه‌های تولیدشده توسط نسخه‌هایی از OpenSSH که از احرازهویت‌کننده FIDO پشتیبانی می‌کنند\&. امکان ترکیب اعتبارنامه‌های بومی و اعتبارنامه‌های SSH وجود ندارد\&. پس از فعال شدن این گزینه، تمام اعتبارنامه‌ها به صورت SSH پردازش خواهند شد\&.
.RE
.PP
\fBconf\fR=\fIpath/to/pam_u2f\&.conf\fR
.RS 4
تنظیم یک مکان جایگزین برای فایل پیکربندی\&. مسیر ارائه‌شده باید مطلق بوده و منطبق بر یک فایل عادی موجود باشد\&. بخش
\fBCONFIGURATION FILE\fR
را ببینید\&.
.RE
.SH "مثال‌ها (EXAMPLES)"
.sp
احراز هویت دومرحله‌ای با واگذاری پیکربندی اعتبارسنجی کاربر به فایل نگاشت مجوزها\&.
.sp
.if n \{.RS 4
.\}
.nf
auth required pam_u2f\&.so authfile=/etc/u2f_mappings cue
.fi
.if n \{.RE
.\}
.sp
احراز هویت بدون رمز عبور با الزام به اعتبارسنجی PIN\&.
.sp
.if n \{.RS 4
.\}
.nf
auth sufficient pam_u2f\&.so authfile=/etc/u2f_mappings cue pinverification=1 userverification=0
.fi
.if n \{.RE
.\}
.sp
احراز هویت بدون رمز عبور با استفاده از UV داخلی (مانند بیومتریک) با بازگشت به PIN\&.
.sp
.if n \{.RS 4
.\}
.nf
auth sufficient pam_u2f\&.so authfile=/etc/u2f_mappings cue pinverification=0 userverification=1
auth sufficient pam_u2f\&.so authfile=/etc/u2f_mappings cue pinverification=1 userverification=0
.fi
.if n \{.RE
.\}
.SH "هشدارها (CAVEATS)"
.sp
به صورت پیش‌فرض، مسیرهای نسبی به authfile با هویت کاربر هدف باز می‌شوند، در حالی که مسیرهای مطلق با هویت "root" باز خواهند شد\&. اگر متغیر "XDG_CONFIG_HOME" تنظیم شده باشد، مجوزها رها نخواهند شد مگر اینکه گزینه پیکربندی "openasuser" تنظیم شده باشد\&.
.sp
استفاده از pam\-u2f برای ایمن‌سازی ورود به رایانه در حالی که فایل نگاشت در یک دایرکتوری خانگی رمزگذاری‌شده قرار دارد، منجر به عدم امکان ورود به سیستم خواهد شد\&. پارتیشن پس از ورود رمزگشایی می‌شود و فایل نگاشت پیش از آن قابل دسترسی نیست\&.
.SH "فایل پیکربندی (CONFIGURATION FILE)"
.sp
یک فایل پیکربندی می‌تواند برای تعیین آرگومان‌های پیش‌فرض ماژول استفاده شود\&.
.sp
.RS 4
.ie n \{\h'-04'\(bu\h'+03'\c
.\}
.el \{.sp -1
.IP \(bu 2.3
.\}
این فایل از قالب
name = value
پیروی می‌کند، و خطوط توضیحات با نویسه
#
آغاز می‌شوند\&.
.RE
.sp
.RS 4
.ie n \{\h'-04'\(bu\h'+03'\c
.\}
.el \{.sp -1
.IP \(bu 2.3
.\}
فاصله‌های خالی در ابتدای خط، انتهای خط و در اطراف علامت
=
نادیده گرفته می‌شوند\&.
.RE
.sp
.RS 4
.ie n \{\h'-04'\(bu\h'+03'\c
.\}
.el \{.sp -1
.IP \(bu 2.3
.\}
هرگونه آرگومان
conf
در فایل پیکربندی نادیده گرفته می‌شود\&.
.RE
.sp
.RS 4
.ie n \{\h'-04'\(bu\h'+03'\c
.\}
.el \{.sp -1
.IP \(bu 2.3
.\}
حداکثر اندازه مجاز برای فایل پیکربندی ۴ کیلوبایت است\&.
.RE
.sp
.RS 4
.ie n \{\h'-04'\(bu\h'+03'\c
.\}
.el \{.sp -1
.IP \(bu 2.3
.\}
مسیر پیش‌فرض برای فایل پیکربندی
/etc/security/pam_u2f\&.conf
است\&. فایل پیش‌فرض مجاز است وجود نداشته باشد\&. مسیر جایگزین را می‌توان در گزینه‌های خط فرمان ماژول تعیین کرد\&.
.RE
.sp
.RS 4
.ie n \{\h'-04'\(bu\h'+03'\c
.\}
.el \{.sp -1
.IP \(bu 2.3
.\}
گزینه‌های مشخص‌شده در خط فرمان ماژول مقادیر فایل پیکربندی را بازنویسی می‌کنند\&.
.RE
.SH "نکات (NOTES)"
.sp
\fBNodetect\fR
.sp
گزینه "nodetect" باید با احتیاط استفاده شود\&. ماژول pam_u2f پیش از انجام احراز هویت لمسی کامل، بررسی می‌کند که آیا کلید پیکربندی‌شده برای کاربر متصل است یا خیر\&. این بررسی با ارسال یک درخواست احراز هویت "فقط بررسی" (check\-only) به تمام توکن‌های متصل انجام می‌شود تا بررسی کند آیا حداقل یکی از آن‌ها پاسخ مثبت به یک یا چند کلید کاربر می‌دهد یا خیر\&. با این کار، pam_u2f می‌تواند از نمایش پیام "cue" (در صورت پیکربندی) خودداری کند، که در غیر این صورت در صورت نمایش اعلان و سپس شکست فوری کتابخانه زیربنایی، ممکن است منجر به مسائل رابط کاربری گیج‌کننده شود\&. این گزینه همچنین برای جلوگیری از تأخیر ناخواسته ۱ ثانیه‌ای پیش از احراز هویت لمسی در نسخه‌های libu2f\-host <= 1\&.1\&.5 مفید است\&.
.sp
اگر pam_u2f با گزینه‌های "cue" و "nodetect" پیکربندی شده باشد، مهاجم می‌تواند با اتصال هر توکن تصادفی U2F و تلاش برای احراز هویت، متوجه شود که pam_u2f بخشی از پشته احراز هویت است\&. در این سناریو، مهاجم پیام اعلان را دیده و به دنبال آن بلافاصله شکست می‌خورد، در حالی که در صورت فعال بودن تشخیص، احراز هویت در سکوت شکست می‌خورد\&. توجه داشته باشید که یک مهاجم می‌تواند دستگاهی را انتخاب کند که به نحوی تلاش احراز هویت "فقط بررسی" را به او هشدار دهد، بنابراین این احتیاط تنها مشکل را یک گام به عقب می‌راند\&.
.sp
به طور خلاصه، ویژگی تشخیص برای جلوگیری از ابهامات رابط کاربری و جلوگیری از افشای اطلاعات درباره پشته احراز هویت در سناریوی خاصی که "cue" پیکربندی شده افزوده شده است\&. گزینه "nodetect" برای جلوگیری از رفتار معیوب خواب (sleep) در نسخه‌های قدیمی‌تر libu2f\-host و برای توکن‌های فرضی که احراز هویت دوگانه را تحمل نمی‌کنند، اضافه شده است\&. تشخیص انجام می‌شود و به همین ترتیب "nodetect" رعایت می‌گردد، فارغ از اینکه "cue" مشخص شده باشد یا خیر\&.
.sp
\fBSELinux\fR
.sp
به دلیل مشکلی در Fedora Linux و احتمالاً در توزیع‌های دیگری که از SELinux استفاده می‌کنند، سیستمی که با pam\-u2f پیکربندی شده است ممکن است در وضعیتی قرار گیرد که دسترسی به فایل اعتبارنامه‌ها رد شود\&. اگر گزینه nouserok نیز تنظیم شده باشد، این امر منجر به احراز هویت موفق در ماژول بدون استفاده از احرازهویت‌کننده FIDO خواهد شد\&.
.sp
برای به‌روزرسانی صحیح بافت امنیتی (security context)، دستور \fBfixfiles onboot\fR باید در سیستم‌های موجود استفاده شود\&.
.sp
علاوه بر این، برای اجازه دسترسی خواندن به یک authfile یا دایرکتوری در مکانی غیراستاندارد، باید دستور
.sp
.if n \{.RS 4
.\}
.nf
# chcon \-R \-t auth_home_t /path/to/authfile
.fi
.if n \{.RE
.\}
.sp
استفاده شود\&.
.sp
برای اطلاعات بیشتر https://access\&.redhat\&.com/security/cve/CVE\-2020\-24612 را ببینید\&.
.SH "اشکالات (BUGS)"
.sp
گزارش اشکالات pam\-u2f در سامانه پیگیری: https://github\&.com/Yubico/pam\-u2f/issues
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBpam\fR(7)
.sp
صفحه خانگی pam\-u2f: https://developers\&.yubico\&.com/pam\-u2f
.sp
دستگاه‌های YubiKey از وب‌سایت Yubico قابل تهیه هستند: http://www\&.yubico\&.com