'\" t .\" Title: polkit .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: February 2021 .\" Manual: polkit .\" Source: polkit .\" Language: Persian .\" .TH "POLKIT" "8" "February 2021" "polkit" "polkit" .\" ----------------------------------------------------------------- .\" * 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)" polkit \- مدیر مجوزدهی .SH "نمای کلی (OVERVIEW)" .PP ابزار polkit یک API مجوزدهی ارائه می‌دهد که برای استفاده توسط برنامه‌های دارای دسترسی ویژه (\(lqMECHANISMS\(rq یا سازوکارها) در هنگام ارائه خدمات به برنامه‌های فاقد دسترسی ویژه (\(lqSUBJECTS\(rq یا موضوع‌ها)، اغلب از طریق نوعی سازوکار ارتباط بین‌پردازشی (IPC) طراحی شده است\&. در این سناریو، سازوکار معمولاً با موضوع به عنوان موجودیتی غیرقابل‌اعتماد رفتار می‌کند\&. به ازای هر درخواست از جانب یک موضوع، سازوکار باید تعیین کند که آیا درخواست مجاز است یا باید از ارائه خدمات به موضوع امتناع ورزد\&. با استفاده از APIهای polkit، سازوکار می‌تواند این تصمیم‌گیری را به یک مرجع قابل‌اعتماد واگذار کند: مرجع polkit (یا همان polkit authority)\&. .PP مرجع polkit به صورت یک دیمن سیستمی پیاده‌سازی شده است، \fBpolkitd\fR(8)، که خودش دسترسی‌های اندکی دارد زیرا با کاربر سیستمی \fIpolkitd\fR اجرا می‌شود\&. سازوکارها، موضوع‌ها و عامل‌های احراز هویت با استفاده از گذرگاه پیام سیستم (system message bus) با مرجع ارتباط برقرار می‌کنند\&. .PP علاوه بر عمل به عنوان یک مرجع، polkit به کاربران اجازه می‌دهد تا از طریق احراز هویت یک کاربر مدیریتی یا مالک نشستی که کلاینت به آن تعلق دارد، مجوز موقت دریافت کنند\&. این ویژگی برای سناریوهایی مفید است که در آن‌ها یک سازوکار نیاز دارد تأیید کند که گرداننده سیستم واقعاً همان کاربر یا یک کاربر مدیریتی است\&. .SH "معماری سامانه (SYSTEM ARCHITECTURE)" .PP معماری سامانه polkit از \fIمرجع (Authority)\fR (پیاده‌سازی‌شده به عنوان یک سرویس روی گذرگاه پیام سیستم) و یک \fIعامل احراز هویت (Authentication Agent)\fR به ازای هر نشست کاربری (ارائه‌شده و راه‌اندازی‌شده توسط محیط گرافیکی کاربر) تشکیل شده است\&. \fIکنش‌ها (Actions)\fR توسط برنامه‌ها تعریف می‌شوند\&. توزیع‌کنندگان، سازمان‌ها و مدیران سیستم می‌توانند سیاست‌های مجوزدهی را از طریق \fIقواعد مجوزدهی (Authorization Rules)\fR کنترل کنند\&. .sp .RS 4 [IMAGE]\&\s-2\u[1]\d\s+2 .sp .if n \{\ .RS 4 .\} .nf +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | Authentication | | Agent | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | libpolkit\-agent\-1 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ ^ +\-\-\-\-\-\-\-\-\-+ | | Subject | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-+ | ^ | | User Session | | =======================|========================|============= System Context | | | | | +\-\-\-+ V | /\-\-\-\-\-\-\-\-\-\-\-\-\e | | System Bus | | \e\-\-\-\-\-\-\-\-\-\-\-\-/ | ^ ^ V | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | | Mechanism | | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ V +\-\-\-\-> | libpolkit\-gobject\-1 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | polkitd(8) | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | org\&.freedesktop\&. | | PolicyKit1 |<\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | ^ | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | | /etc/polkit\-1/actions/*\&.policy | | | /run/polkit\-1/actions/*\&.policy | | | /usr/local/share/polkit\-1/actions/*\&.policy | | | /usr/share/polkit\-1/actions/*\&.policy | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | /etc/polkit\-1/rules\&.d/*\&.rules | | /run/polkit\-1/rules\&.d/*\&.rules | | /usr/local/share/polkit\-1/rules\&.d/*\&.rules | | /usr/share/polkit\-1/rules\&.d/*\&.rules | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .fi .if n \{\ .RE .\} .RE .PP برای سهولت، کتابخانه libpolkit\-gobject\-1 API مبتنی بر D\-Bus پامک polkit را کپسوله‌سازی می‌کند و از هر برنامه C/C++ و همچنین زبان‌های سطح بالاتری که از \m[blue]\fBGObjectIntrospection\fR\m[]\&\s-2\u[2]\d\s+2 پشتیبانی می‌کنند (مانند JavaScript و Python) قابل استفاده است\&. یک سازوکار همچنین می‌تواند مستقیماً از API د-باس یا دستور \fBpkcheck\fR(1) برای بررسی مجوزها استفاده کند\&. کتابخانه libpolkit\-agent\-1 یک انتزاع از سیستم احراز هویت بومی، مانند \fBpam\fR(8)، و همچنین امکاناتی برای ثبت‌نام و ارتباط با سرویس D\-Bus در polkit فراهم می‌آورد\&. .PP برای اطلاعات بیشتر درباره نوشتن برنامه‌های polkit به \m[blue]\fBمستندات توسعه‌دهندگان\fR\m[]\&\s-2\u[3]\d\s+2 مراجعه فرمایید\&. .SH "عامل‌های احراز هویت (AUTHENTICATION AGENTS)" .PP یک عامل احراز هویت برای این استفاده می‌شود که کاربر یک نشست ثابت کند واقعاً همان کاربر است (با احراز هویت به عنوان خود کاربر) یا یک کاربر مدیریتی است (با احراز هویت به عنوان مدیر سیستم)\&. برای یکپارچگی مناسب با سایر بخش‌های نشست کاربر (برای نمونه تطابق با ظاهر و احساس بصری)، عامل‌های احراز هویت باید توسط همان نشست کاربری که کاربر از آن استفاده می‌کند ارائه شوند\&. برای نمونه، یک عامل احراز هویت ممکن است این‌گونه باشد: .sp .RS 4 [IMAGE]\&\s-2\u[4]\d\s+2 .sp .if n \{\ .RS 4 .\} .nf +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | | | [Icon] Authentication required | | | | Authentication is required to format INTEL | | SSDSA2MH080G1GC (/dev/sda) | | | | Administrator | | | | Password: [__________________________________] | | | | [Cancel] [Authenticate] | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .fi .if n \{\ .RE .\} .RE .PP اگر سیستم بدون حساب \fIroot\fR پیکربندی شده باشد، ممکن است برای کاربری خاص که به عنوان کاربر مدیریتی تعیین شده است اعلان هویت نمایش دهد: .sp .RS 4 [IMAGE]\&\s-2\u[5]\d\s+2 .sp .if n \{\ .RS 4 .\} .nf +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | | | [Icon] Authentication required | | | | Authentication is required to format INTEL | | SSDSA2MH080G1GC (/dev/sda) | | | | [Icon] David Zeuthen | | | | Password: [__________________________________] | | | | [Cancel] [Authenticate] | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .fi .if n \{\ .RE .\} .RE .PP برنامه‌هایی که تحت یک محیط رومیزی اجرا نمی‌شوند (برای نمونه، اگر از طریق نشست ورودی \fBssh\fR(1) راه‌اندازی شده باشند) ممکن است عامل احراز هویت مرتبطی در اختیار نداشته باشند\&. چنین برنامه‌هایی می‌توانند از نوع PolkitAgentTextListener یا ابزار کمکی \fBpkttyagent\fR(1) استفاده کنند تا کاربر بتواند با یک رابط متنی احراز هویت را انجام دهد\&. .SH "تعریف کنش‌ها (DECLARING ACTIONS)" .PP یک سازوکار برای استفاده از polkit باید مجموعه‌ای از \fIکنش‌ها (actions)\fR را اعلان کند\&. کنش‌ها متناظر با عملیاتی هستند که کلاینت‌ها می‌توانند از سازوکار درخواست کنند تا انجام دهد و در فایل‌های XML تعریف می‌شوند که سازوکار آن‌ها را در دایرکتوری /usr/share/polkit\-1/actions نصب می‌کند\&. .PP کنش‌های polkit دارای فضای‌نام (namespaced) هستند و فقط می‌توانند شامل نویسه‌های "[A\-Z][a\-z][0\-9]\&.\-" باشند، مانند ASCII، ارقام، نقطه و خط تیره\&. هر فایل XML می‌تواند شامل بیش از یک کنش باشد اما تمام کنش‌ها باید در همان فضای‌نام قرار داشته باشند و نام فایل نیز باید بر اساس فضای‌نام نام‌گذاری شده و دارای پسوند \&.policy باشد\&. .PP فایل XML باید دارای اعلان نوع سند (doctype) زیر باشد: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .PP عنصر \fIpolicyconfig\fR باید دقیقاً یک بار وجود داشته باشد\&. عناصری که می‌توانند درون \fIpolicyconfig\fR استفاده شوند عبارتند از: .PP \fIvendor\fR .RS 4 نام پروژه یا توزیع‌کننده‌ای که کنش‌ها را در سند XML فراهم می‌کند\&. اختیاری\&. .RE .PP \fIvendor_url\fR .RS 4 نشانی اینترنتی پروژه یا توزیع‌کننده‌ای که کنش‌ها را در سند XML فراهم می‌کند\&. اختیاری\&. .RE .PP \fIicon_name\fR .RS 4 آیکونی که نشان‌دهنده پروژه یا سازنده‌ای است که کنش‌ها را در سند XML ارائه می‌دهد\&. نام آیکون باید مطابق با \m[blue]\fBشیوه‌نامه نام‌گذاری آیکون Freedesktop\&.org\fR\m[]\&\s-2\u[6]\d\s+2 باشد\&. اختیاری\&. .RE .PP \fIaction\fR .RS 4 یک کنش را اعلان می‌کند\&. نام کنش با استفاده از ویژگی id مشخص می‌شود و فقط می‌تواند حاوی نویسه‌های "[A\-Z][a\-z][0\-9]\&.\-" باشد، مانند ASCII، ارقام، نقطه و خط تیره\&. .RE .PP عناصری که می‌توانند درون \fIaction\fR استفاده شوند شامل موارد زیر است: .PP \fIdescription\fR .RS 4 شرح قابل‌خواندن برای انسان از کنش، برای نمونه \(lqInstall unsigned software\(rq (نصب نرم‌افزار بدون امضا)\&. .RE .PP \fImessage\fR .RS 4 پیامی قابل‌خواندن برای انسان که در زمان نیاز به احراز هویت و درخواست اعتبارنامه‌ها به کاربر نمایش داده می‌شود، برای نمونه \(lqInstalling unsigned software requires authentication\(rq (نصب نرم‌افزار بدون امضا نیازمند احراز هویت است)\&. .RE .PP \fIdefaults\fR .RS 4 این عنصر برای تعیین مجوزهای ضمنی برای کلاینت‌ها استفاده می‌شود\&. عناصری که می‌توانند درون \fIdefaults\fR استفاده شوند شامل موارد زیر است: .PP \fIallow_any\fR .RS 4 مجوزهای ضمنی که برای هر کلاینتی اعمال می‌شوند\&. اختیاری\&. .RE .PP \fIallow_inactive\fR .RS 4 مجوزهای ضمنی که برای کلاینت‌ها در نشست‌های غیرفعال روی کنسول‌های محلی اعمال می‌شوند\&. اختیاری\&. .RE .PP \fIallow_active\fR .RS 4 مجوزهای ضمنی که برای کلاینت‌ها در نشست‌های فعال روی کنسول‌های محلی اعمال می‌شوند\&. اختیاری\&. .RE .sp هر یک از عناصر \fIallow_any\fR، \fIallow_inactive\fR و \fIallow_active\fR می‌توانند حاوی مقادیر زیر باشند: .PP no .RS 4 مجاز نیست\&. .RE .PP yes .RS 4 مجاز است\&. .RE .PP auth_self .RS 4 احراز هویت توسط مالک نشستی که کلاینت از آن نشأت گرفته الزامی است\&. توجه داشته باشید که این گزینه برای بیشتر کاربردها در سامانه‌های چندکاربره به اندازه کافی محدودکننده نیست؛ معمولاً *auth_admin پیشنهاد می‌شود\&. .RE .PP auth_admin .RS 4 احراز هویت توسط یک کاربر مدیریتی الزامی است\&. .RE .PP auth_self_keep .RS 4 مانند auth_self است ولی مجوز برای مدت کوتاهی (مثلاً پنج دقیقه) حفظ می‌شود\&. هشدار ذکرشده درباره auth_self در بالا برای این گزینه نیز صدق می‌کند\&. .RE .PP auth_admin_keep .RS 4 مانند auth_admin است ولی مجوز برای مدت کوتاهی (مثلاً پنج دقیقه) حفظ می‌شود\&. .RE .RE .PP \fIannotate\fR .RS 4 برای یادداشت‌گذاری یک کنش با یک جفت کلید/مقدار استفاده می‌شود\&. کلید با ویژگی key و مقدار با ویژگی value مشخص می‌گردد\&. این عنصر ممکن است صفر یا چند بار ظاهر شود\&. برای یادداشت‌های شناخته‌شده بخش زیر را ببینید\&. .RE .PP \fIvendor\fR .RS 4 برای بازنویسی نام توزیع‌کننده بر مبنای هر کنش جداگانه استفاده می‌شود\&. اختیاری\&. .RE .PP \fIvendor_url\fR .RS 4 برای بازنویسی نشانی اینترنتی توزیع‌کننده بر مبنای هر کنش جداگانه استفاده می‌شود\&. اختیاری\&. .RE .PP \fIicon_name\fR .RS 4 برای بازنویسی نام آیکون بر مبنای هر کنش جداگانه استفاده می‌شود\&. اختیاری\&. .RE .PP برای بومی‌سازی، عناصر \fIdescription\fR و \fImessage\fR می‌توانند چندین بار با ویژگی‌های مختلف xml:lang ظاهر شوند\&. .PP برای فهرست کردن کنش‌های نصب‌شده polkit، از دستور \fBpkaction\fR(1) استفاده کنید\&. .SS "یادداشت‌های شناخته‌شده (Known annotations)" .PP یادداشت org\&.freedesktop\&.policykit\&.exec\&.path توسط برنامه \fBpkexec\fR که به همراه polkit ارائه می‌شود مورد استفاده قرار می‌گیرد \- برای جزئیات به صفحه راهنمای \fBpkexec\fR(1) مراجعه کنید\&. .PP یادداشت org\&.freedesktop\&.policykit\&.imply (مقدار آن رشته‌ای حاوی فهرستی از شناسه‌های کنش جداشده با فاصله است) می‌تواند برای تعریف \fIابَرکنش‌ها (meta actions)\fR استفاده شود\&. شیوه کار آن به این صورت است که اگر یک موضوع برای کنشی دارای این یادداشت مجاز شناخته شود، آن‌گاه برای هر کنش دیگری که توسط این یادداشت تعیین شده نیز مجاز خواهد بود\&. یک کاربرد معمول این یادداشت زمانی است که یک پوسته واسط کاربری دارای یک دکمه قفل واحد تعریف می‌شود که باید قفل چندین کنش از سازوکارهای متمایز را باز کند\&. .PP یادداشت org\&.freedesktop\&.policykit\&.owner می‌تواند برای تعریف مجموعه‌ای از کاربران استفاده شود که مجازند بررسی کنند آیا یک کلاینت برای اجرای این کنش مجاز است یا خیر\&. اگر این یادداشت مشخص نشود، تنها کاربر root می‌تواند بررسی کند آیا کلاینتی که با کاربر متفاوتی اجرا شده مجاز به انجام کنش است یا خیر\&. مقدار این یادداشت رشته‌ای حاوی فهرستی فاصله‌جدا از مدخل‌های PolkitIdentity است، برای نمونه "unix\-user:42 unix\-user:colord"\&. یک کاربرد رایج این یادداشت برای پردازه‌های دیمنی است که به جای root با یک کاربر سیستمی اجرا می‌شوند\&. .SH "قواعد مجوزدهی (AUTHORIZATION RULES)" .PP دیمن \fBpolkitd\fR فایل‌های دارای پسوند \&.rules را از دایرکتوری‌های زیر و به همین ترتیب می‌خواند: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /etc/polkit\-1/rules\&.d .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /run/polkit\-1/rules\&.d .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /usr/local/share/polkit\-1/rules\&.d .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /usr/share/polkit\-1/rules\&.d .RE .PP این دایرکتوری‌ها بر اساس نام پایه (basename) هر فایل به ترتیب واژگانی پردازش می‌شوند\&. در صورت تساوی نام، فایل‌های موجود در دایرکتوری‌هایی که بالاتر در فهرست قرار دارند زودتر پردازش می‌شوند\&. برای نمونه، برای چهار فایل زیر، ترتیب پردازش چنین است: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /etc/polkit\-1/rules\&.d/10\-auth\&.rules .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /run/polkit\-1/rules\&.d/10\-auth\&.rules .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /usr/local/share/polkit\-1/rules\&.d/10\-auth\&.rules .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} /usr/share/polkit\-1/rules\&.d/10\-auth\&.rules .RE .PP تمامی این دایرکتوری‌ها پایش می‌شوند، بنابراین اگر یک فایل قواعد تغییر کند، اضافه شود یا حذف گردد، قواعد موجود پاکسازی شده و تمامی فایل‌ها دوباره خوانده و پردازش می‌شوند\&. فایل‌های قواعد با زبان برنامه‌نویسی \m[blue]\fBJavaScript\fR\m[]\&\s-2\u[7]\d\s+2 نوشته می‌شوند و از طریق شیء عمومی polkit (از نوع \fBPolkit\fR) با \fBpolkitd\fR تعامل برقرار می‌کنند\&. .PP اگرچه مفسر جاوااسکریپت استفاده‌شده در نسخه‌های خاصی از polkit ممکن است از ویژگی‌های غیراستاندارد (مانند کلمه کلیدی \fIlet\fR) پشتیبانی کند، اما قواعد مجوزدهی باید با \m[blue]\fBECMA\-262 ویرایش ۵\fR\m[]\&\s-2\u[8]\d\s+2 سازگار باشند (به بیان دیگر، مفسر جاوااسکریپت مورداستفاده ممکن است در نسخه‌های آینده polkit تغییر کند)\&. .PP قواعد مجوزدهی تنها برای دو گروه مخاطب مشخص در نظر گرفته شده‌اند: .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 .\} سیستم‌عامل‌ها و محیط‌های ویژه و خاص‌منظوره .RE .PP و فقط همین مخاطبان\&. به ویژه، برنامه‌ها، سازوکارها و سیستم‌عامل‌های چندمنظوره هرگز نباید هیچ قاعده مجوزدهی در خود بگنجانند\&. .SS "نوع Polkit (The Polkit type)" .PP متدهای زیر روی شیء polkit در دسترس هستند: .HP \w'void\ addRule('u .BI "void addRule(polkit\&.Result\ function(" "action" ",\ " "subject" ")\ {\&.\&.\&.});" .HP \w'void\ addAdminRule('u .BI "void addAdminRule(string[]\ function(" "action" ",\ " "subject" ")\ {\&.\&.\&.});" .HP \w'void\ log('u .BI "void log(string\ " "message" ");" .HP \w'string\ spawn('u .BI "string spawn(string[]\ " "argv" ");" .PP متد \fBaddRule()\fR برای افزودن تابعی استفاده می‌شود که هر زمان بررسی مجوز برای \fIaction\fR و \fIsubject\fR انجام گیرد، فراخوانی خواهد شد\&. توابع به همان ترتیبی که اضافه شده‌اند فراخوانی می‌شوند تا زمانی که یکی از توابع مقداری بازگرداند\&. بنابراین، برای افزودن یک قاعده مجوزدهی که پیش از سایر قواعد پردازش شود، آن را در فایلی در /etc/polkit\-1/rules\&.d قرار دهید که نام آن از نظر الفبایی پیش از سایر فایل‌های قواعد مرتب شود، برای نمونه 00\-early\-checks\&.rules\&. هر تابع باید مقداری از polkit\&.Result را بازگرداند .sp .if n \{\ .RS 4 .\} .nf polkit\&.Result = { NO : "no", YES : "yes", AUTH_SELF : "auth_self", AUTH_SELF_KEEP : "auth_self_keep", AUTH_ADMIN : "auth_admin", AUTH_ADMIN_KEEP : "auth_admin_keep", NOT_HANDLED : null }; .fi .if n \{\ .RE .\} .PP که متناظر با مقادیری است که می‌توانند به عنوان پیش‌فرض‌ها استفاده شوند\&. اگر تابع \fBpolkit\&.Result\&.NOT_HANDLED\fR، \fBnull\fR، \fBundefined\fR را بازگرداند یا اصلاً مقداری بازنگرداند، تابع کاربری بعدی امتحان می‌شود\&. .PP به خاطر داشته باشید که اگر \fBpolkit\&.Result\&.AUTH_SELF_KEEP\fR یا \fBpolkit\&.Result\&.AUTH_ADMIN_KEEP\fR بازگردانده شود، بررسی‌های مجوزدهی برای شناسه کنش و موضوع یکسان برای مدت کوتاه بعدی (مثلاً پنج دقیقه) با موفقیت مواجه خواهند شد (یعنی مقدار \fBpolkit\&.Result\&.YES\fR را برمی‌گردانند)، \fIحتی اگر\fR متغیرهای ارائه‌شده به همراه بررسی متفاوت باشند\&. بنابراین، اگر نتیجه یک قاعده مجوزدهی به چنین متغیرهایی وابسته است، نباید از ثابت‌های \fB"*_KEEP"\fR استفاده کند (اگر عملکرد مشابهی نیاز باشد، قاعده مجوزدهی می‌تواند با استفاده از نوع \m[blue]\fB\fBDate\fR\fR\m[]\&\s-2\u[9]\d\s+2 برای برچسب‌های زمانی، مجوزهای موقت را به سادگی پیاده‌سازی کند)\&. .PP متد \fBaddAdminRule()\fR برای افزودن تابعی استفاده می‌شود که هر زمان احراز هویت مدیر سیستم نیاز باشد، فراخوانی خواهد شد\&. این تابع برای تعیین هویت‌هایی به کار می‌رود که ممکن است برای احراز هویت مدیریتی در بررسی مجوزی که با \fIaction\fR و \fIsubject\fR شناسایی شده، مورد استفاده قرار گیرند\&. توابع اضافه‌شده به ترتیبی که افزوده شده‌اند فراخوانی می‌شوند تا زمانی که یکی از آن‌ها مقداری برگرداند\&. هر تابع باید آرایه‌ای از رشته‌ها را برگرداند که هر رشته به شکل "unix\-group:", "unix\-netgroup:" یا "unix\-user:" باشد\&. اگر تابع مقدار \fBnull\fR، \fBundefined\fR یا هیچ مقداری بازنگرداند، تابع بعدی آزموده می‌شود\&. .PP هیچ تضمینی وجود ندارد که تابعی که با \fBaddRule()\fR یا \fBaddAdminRule()\fR ثبت شده است حتماً فراخوانی شود \- برای نمونه یک فایل قواعد اولیه ممکن است تابعی را ثبت کند که همواره مقداری برمی‌گرداند و در نتیجه مانع از فراخوانی توابعی شود که بعداً اضافه شده‌اند\&. .PP اگر اجرای کد ارائه‌شده توسط کاربر زمان زیادی طول بکشد، استثنایی ایجاد نخواهد شد و اسکریپت بلافاصله خاتمه داده می‌شود (محدودیت فعلی ۱۵ ثانیه است)\&. این کار برای مهار اسکریپت‌های مهارنشدنی استفاده می‌شود\&. .PP متد \fBspawn()\fR یک برنامه کمکی بیرونی را که با بردار آرگومان‌های \fIargv\fR مشخص شده اجرا می‌کند و منتظر پایان آن می‌ماند\&. اگر خطایی رخ دهد یا برنامه کمکی به صورت عادی با کد خروج ۰ پایان نیابد، یک استثنا صادر می‌شود\&. اگر برنامه کمکی ظرف مدت ۱۰ ثانیه به پایان نرسد، متوقف و کشته خواهد شد\&. در غیر این صورت، \fIخروجی استاندارد\fR برنامه به عنوان یک رشته بازگردانده می‌شود\&. متد \fBspawn()\fR باید با احتیاط و به ندرت استفاده شود زیرا برنامه‌های کمکی ممکن است زمان طولانی یا نامشخصی برای تکمیل نیاز داشته باشند و در زمان اجرای آن‌ها هیچ بررسی مجوز دیگری قابل انجام نیست\&. توجه داشته باشید که برنامه‌های اجراشده با کاربر سیستمی فاقد امتیاز \fIpolkitd\fR اجرا خواهند شد\&. .PP متد \fBlog()\fR پیام \fImessage\fR داده‌شده را با پیشوند نام فایل جاوااسکریپت و شماره خط در ثبت‌کننده وقایع سیستم (logger) می‌نویسد\&. ورودی‌های لاگ با فلگ \fBLOG_AUTHPRIV\fR ارسال می‌شوند به این معنی که معمولاً در فایل /var/log/secure قرار می‌گیرند\&. متد \fBlog()\fR معمولاً فقط هنگام اشکال‌زدایی قواعد به کار می‌رود\&. انواع \fBAction\fR و \fBSubject\fR متدهای مناسب \fBtoString()\fR را برای لاگ‌گیری آسان تعریف کرده‌اند، برای نمونه: .sp .if n \{\ .RS 4 .\} .nf polkit\&.addRule(function(action, subject) { if (action\&.id == "org\&.freedesktop\&.policykit\&.exec") { polkit\&.log("action=" + action); polkit\&.log("subject=" + subject); } }); .fi .if n \{\ .RE .\} .PP هنگامی که کاربر دستور \(aqpkexec \-u bateman bash \-i\(aq را از یک پوسته اجرا کند، خروجی زیر تولید خواهد شد: .sp .if n \{\ .RS 4 .\} .nf May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit\-1/rules\&.d/10\-test\&.rules:3: action=[Action id=\*(Aqorg\&.freedesktop\&.policykit\&.exec\*(Aq command_line=\*(Aq/usr/bin/bash \-i\*(Aq program=\*(Aq/usr/bin/bash\*(Aq user=\*(Aqbateman\*(Aq user\&.gecos=\*(AqPatrick Bateman\*(Aq user\&.display=\*(AqPatrick Bateman (bateman)\*(Aq] May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit\-1/rules\&.d/10\-test\&.rules:4: subject=[Subject pid=1352 user=\*(Aqdavidz\*(Aq groups=davidz,wheel, seat=\*(Aqseat0\*(Aq session=\*(Aq1\*(Aq local=true active=true] .fi .if n \{\ .RE .\} .SS "نوع Action (The Action type)" .PP پارامتر \fIaction\fR که به توابع کاربری فرستاده می‌شود شیئی حاوی اطلاعاتی درباره کنش در حال بررسی است\&. این شیء از نوع \fBAction\fR بوده و دارای ویژگی زیر است: .PP \fBstring\fR id .RS 4 شناسه کنش، برای نمونه \fIorg\&.freedesktop\&.policykit\&.exec\fR\&. .RE .PP متدهای زیر روی نوع \fBAction\fR در دسترس هستند: .HP \w'string\ lookup('u .BI "string lookup(string\ " "key" ");" .PP متد \fBlookup()\fR برای جستجوی متغیرهای polkit که از سازوکار ارسال شده‌اند استفاده می‌شود\&. برای نمونه، سازوکار \fBpkexec\fR(1) متغیر \fIprogram\fR را تنظیم می‌کند که می‌توان آن را در جاوااسکریپت با استفاده از عبارت action\&.lookup("program") به دست آورد\&. اگر هیچ مقداری برای \fIkey\fR داده‌شده وجود نداشته باشد، مقدار \fBundefined\fR بازگردانده می‌شود\&. .PP برای اینکه بدانید چه متغیرهایی برای هر کنش در دسترس هستند به مستندات هر سازوکار مراجعه کنید\&. .SS "نوع Subject (The Subject type)" .PP پارامتر \fIsubject\fR که به توابع کاربری ارسال می‌شود شیئی با اطلاعاتی درباره پردازه در حال بررسی است\&. این شیء از نوع \fBSubject\fR بوده و دارای ویژگی‌های زیر است: .PP \fBint\fR pid .RS 4 شناسه پردازه (PID)\&. .RE .PP \fBint\fR uid .RS 4 شناسه کاربری (UID) کاربرِ پردازه موضوع\&. .RE .PP \fBstring\fR user .RS 4 نام کاربر\&. .RE .PP \fBstring[]\fR groups .RS 4 آرایه‌ای از گروه‌هایی که کاربر \fIuser\fR به آن‌ها تعلق دارد\&. .RE .PP \fBstring\fR seat .RS 4 جایگاهی (seat) که موضوع به آن مرتبط است \- در صورتی که روی جایگاه محلی نباشد خالی خواهد بود\&. .RE .PP \fBstring\fR session .RS 4 نشستی که موضوع به آن مرتبط است\&. .RE .PP \fBstring\fR system_unit .RS 4 واحد systemd که پردازه موضوع بخشی از آن است (در صورت وجود)\&. توجه داشته باشید که این ویژگی تنها با واحدهای سیستمی تطابق می‌یابد، زیرا واحدهای کاربری می‌توانند بدون دسترسی ویژه با هر نامی ایجاد شوند (برخلاف واحدهای سیستمی که ایجاد آن‌ها نیازمند دسترسی root است)\&. پردازه‌ای که در یک واحد کاربری اجرا می‌شود، واحد نشست کاربر را در این ویژگی بازمی‌گرداند (مانند user\-1000\&.service)\&. .RE .PP \fBboolean\fR local .RS 4 فقط زمانی روی \fBtrue\fR تنظیم می‌شود که جایگاه، محلی باشد\&. .RE .PP \fBboolean\fR no_new_privileges .RS 4 تنها در صورتی تنظیم می‌شود که \fIsystem_unit\fR خالی نباشد، و فقط در صورتی روی \fBtrue\fR تنظیم می‌شود که واحد سرویس ارجاع‌شده در systemd دارای تنظیم \fINoNewPrivileges=\fR فعال باشد\&. این ویژگی تضمین می‌کند که پردازه نتواند با اجرای باینری‌های setuid دسترسی‌های جدیدی به دست آورد\&. .RE .PP \fBboolean\fR active .RS 4 فقط در صورتی روی \fBtrue\fR تنظیم می‌شود که نشست فعال باشد\&. .RE .PP متدهای زیر روی نوع \fBSubject\fR در دسترس هستند: .HP \w'boolean\ isInGroup('u .BI "boolean isInGroup(string\ " "groupName" ");" .HP \w'boolean\ isInNetGroup('u .BI "boolean isInNetGroup(string\ " "netGroupName" ");" .PP متد \fBisInGroup()\fR می‌تواند برای بررسی عضویت موضوع در یک گروه مشخص استفاده شود و \fBisInNetGroup()\fR می‌تواند برای بررسی اینکه آیا موضوع در یک netgroup مشخص قرار دارد یا خیر به کار رود\&. .SS "مثال‌های قواعد مجوزدهی (Authorization Rules Examples)" .PP اجازه به تمام کاربران در گروه admin برای انجام مدیریت کاربران بدون تغییر سیاست برای سایر کاربران: .sp .if n \{\ .RS 4 .\} .nf polkit\&.addRule(function(action, subject) { if (action\&.id == "org\&.freedesktop\&.accounts\&.user\-administration" && subject\&.isInGroup("admin")) { return polkit\&.Result\&.YES; } }); .fi .if n \{\ .RE .\} .PP تعریف کاربران گروه wheel به عنوان کاربران مدیریتی: .sp .if n \{\ .RS 4 .\} .nf polkit\&.addAdminRule(function(action, subject) { return ["unix\-group:wheel"]; }); .fi .if n \{\ .RE .\} .PP منع کاربران در گروه children از تغییر پیکربندی نام میزبان (یعنی هر کنشی با شناسه‌ای که با org\&.freedesktop\&.hostname1\&. آغاز می‌شود) و اجازه دادن به دیگران پس از احراز هویت به عنوان خودشان: .sp .if n \{\ .RS 4 .\} .nf polkit\&.addRule(function(action, subject) { if (action\&.id\&.indexOf("org\&.freedesktop\&.hostname1\&.") == 0) { if (subject\&.isInGroup("children")) { return polkit\&.Result\&.NO; } else { return polkit\&.Result\&.AUTH_SELF_KEEP; } } }); .fi .if n \{\ .RE .\} .PP اجرای یک برنامه کمکی خارجی برای تعیین اینکه آیا کاربر فعلی می‌تواند سیستم را مجدداً راه‌اندازی کند: .sp .if n \{\ .RS 4 .\} .nf polkit\&.addRule(function(action, subject) { if (action\&.id\&.indexOf("org\&.freedesktop\&.login1\&.reboot") == 0) { try { // user\-may\-reboot exits with success (exit code 0) // only if the passed username is authorized polkit\&.spawn(["/opt/company/bin/user\-may\-reboot", subject\&.user]); return polkit\&.Result\&.YES; } catch (error) { // Nope, but do allow admin authentication return polkit\&.Result\&.AUTH_ADMIN; } } }); .fi .if n \{\ .RE .\} .PP مثال زیر نشان می‌دهد که چگونه تصمیم مجوزدهی می‌تواند به متغیرهای ارسال‌شده توسط سازوکار \fBpkexec\fR(1) وابسته باشد: .sp .if n \{\ .RS 4 .\} .nf polkit\&.addRule(function(action, subject) { if (action\&.id == "org\&.freedesktop\&.policykit\&.exec" && action\&.lookup("program") == "/usr/bin/cat") { return polkit\&.Result\&.AUTH_ADMIN; } }); .fi .if n \{\ .RE .\} .PP مثال زیر کاربرد دیگری از متغیرهای ارسال‌شده از سازوکار را نشان می‌دهد\&. در این حالت، سازوکار \m[blue]\fBUDisks\fR\m[]\&\s-2\u[10]\d\s+2 است که مجموعه‌ای از \m[blue]\fBکنش‌ها و متغیرها\fR\m[]\&\s-2\u[11]\d\s+2 را تعریف می‌کند که برای تطبیق استفاده می‌شوند: .sp .if n \{\ .RS 4 .\} .nf // Allow users in group \*(Aqengineers\*(Aq to perform any operation on // some drives without having to authenticate // polkit\&.addRule(function(action, subject) { if (action\&.id\&.indexOf("org\&.freedesktop\&.udisks2\&.") == 0 && action\&.lookup("drive\&.vendor") == "SEAGATE" && action\&.lookup("drive\&.model") == "ST3300657SS" && subject\&.isInGroup("engineers")) { return polkit\&.Result\&.YES; } } }); .fi .if n \{\ .RE .\} .PP اجازه به تمام پردازه‌هایی که به عنوان بخشی از واحد سیستمی admin\&.service در systemd اجرا می‌شوند برای انجام مدیریت کاربران، تا زمانی که نتوانند دسترسی‌های جدید کسب کنند: .sp .if n \{\ .RS 4 .\} .nf polkit\&.addRule(function(action, subject) { if (action\&.id == "org\&.freedesktop\&.accounts\&.user\-administration" && subject\&.system_unit == "admin\&.service" && subject\&.no_new_privileges) { return polkit\&.Result\&.YES; } }); .fi .if n \{\ .RE .\} .SH "نویسندگان (AUTHORS)" .PP نوشته‌شده توسط David Zeuthen با کمک‌های بسیار از جانب دیگران\&. .SH "گزارش باگ‌ها (BUGS)" .PP لطفاً گزارش‌های باگ را به توزیع خود یا به لیست پستی polkit\-devel ارسال کنید، ببینید: \m[blue]\fB\%https://github.com/polkit-org/polkit#bugs-and-development\fR\m[]\&. .SH "همچنین ببینید (SEE ALSO)" .PP \fBpolkitd\fR(8), \fBpkaction\fR(1), \fBpkcheck\fR(1), \fBpkexec\fR(1), \fBpkttyagent\fR(1) .SH "یادداشت‌ها (NOTES)" .IP " 1." 4 /usr/share/gtk-doc/html/polkit-1/polkit-architecture.png .IP " 2." 4 GObjectIntrospection .RS 4 \%https://live.gnome.org/GObjectIntrospection .RE .IP " 3." 4 مستندات توسعه‌دهندگان .RS 4 \%http://www.freedesktop.org/software/polkit/docs/latest .RE .IP " 4." 4 /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-example.png .IP " 5." 4 /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-example-wheel.png .IP " 6." 4 شیوه‌نامه نام‌گذاری آیکون Freedesktop.org .RS 4 \%http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html .RE .IP " 7." 4 JavaScript .RS 4 \%http://en.wikipedia.org/wiki/JavaScript .RE .IP " 8." 4 ECMA-262 ویرایش ۵ .RS 4 \%http://en.wikipedia.org/wiki/ECMAScript#ECMAScript.2C_5th_Edition .RE .IP " 9." 4 \fBDate\fR .RS 4 \%https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date .RE .IP "10." 4 UDisks .RS 4 \%http://udisks.freedesktop.org/docs/latest/udisks.8.html .RE .IP "11." 4 کنش‌ها و متغیرها .RS 4 \%http://udisks.freedesktop.org/docs/latest/udisks-polkit-actions.html .RE