یادداشت‌های شناخته‌شده (Known annotations)

یادداشت org.freedesktop.policykit.exec.path توسط برنامه pkexec که به همراه polkit ارائه می‌شود مورد استفاده قرار می‌گیرد - برای جزئیات به صفحه راهنمای pkexec(1) مراجعه کنید.

یادداشت org.freedesktop.policykit.imply (مقدار آن رشته‌ای حاوی فهرستی از شناسه‌های کنش جداشده با فاصله است) می‌تواند برای تعریف ابَرکنش‌ها (meta actions) استفاده شود. شیوه کار آن به این صورت است که اگر یک موضوع برای کنشی دارای این یادداشت مجاز شناخته شود، آن‌گاه برای هر کنش دیگری که توسط این یادداشت تعیین شده نیز مجاز خواهد بود. یک کاربرد معمول این یادداشت زمانی است که یک پوسته واسط کاربری دارای یک دکمه قفل واحد تعریف می‌شود که باید قفل چندین کنش از سازوکارهای متمایز را باز کند.

یادداشت org.freedesktop.policykit.owner می‌تواند برای تعریف مجموعه‌ای از کاربران استفاده شود که مجازند بررسی کنند آیا یک کلاینت برای اجرای این کنش مجاز است یا خیر. اگر این یادداشت مشخص نشود، تنها کاربر root می‌تواند بررسی کند آیا کلاینتی که با کاربر متفاوتی اجرا شده مجاز به انجام کنش است یا خیر. مقدار این یادداشت رشته‌ای حاوی فهرستی فاصله‌جدا از مدخل‌های PolkitIdentity است، برای نمونه "unix-user:42 unix-user:colord". یک کاربرد رایج این یادداشت برای پردازه‌های دیمنی است که به جای root با یک کاربر سیستمی اجرا می‌شوند.

نوع Polkit (The Polkit type)

متدهای زیر روی شیء polkit در دسترس هستند:

void addRule(polkit.Result function(action, subject) {...});

void addAdminRule(string[] function(action, subject) {...});

void log(string message);

string spawn(string[] argv);

متد addRule() برای افزودن تابعی استفاده می‌شود که هر زمان بررسی مجوز برای action و subject انجام گیرد، فراخوانی خواهد شد. توابع به همان ترتیبی که اضافه شده‌اند فراخوانی می‌شوند تا زمانی که یکی از توابع مقداری بازگرداند. بنابراین، برای افزودن یک قاعده مجوزدهی که پیش از سایر قواعد پردازش شود، آن را در فایلی در /etc/polkit-1/rules.d قرار دهید که نام آن از نظر الفبایی پیش از سایر فایل‌های قواعد مرتب شود، برای نمونه 00-early-checks.rules. هر تابع باید مقداری از polkit.Result را بازگرداند

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
};

که متناظر با مقادیری است که می‌توانند به عنوان پیش‌فرض‌ها استفاده شوند. اگر تابع polkit.Result.NOT_HANDLED، null، undefined را بازگرداند یا اصلاً مقداری بازنگرداند، تابع کاربری بعدی امتحان می‌شود.

به خاطر داشته باشید که اگر polkit.Result.AUTH_SELF_KEEP یا polkit.Result.AUTH_ADMIN_KEEP بازگردانده شود، بررسی‌های مجوزدهی برای شناسه کنش و موضوع یکسان برای مدت کوتاه بعدی (مثلاً پنج دقیقه) با موفقیت مواجه خواهند شد (یعنی مقدار polkit.Result.YES را برمی‌گردانند)، حتی اگر متغیرهای ارائه‌شده به همراه بررسی متفاوت باشند. بنابراین، اگر نتیجه یک قاعده مجوزدهی به چنین متغیرهایی وابسته است، نباید از ثابت‌های "*_KEEP" استفاده کند (اگر عملکرد مشابهی نیاز باشد، قاعده مجوزدهی می‌تواند با استفاده از نوع Date[9] برای برچسب‌های زمانی، مجوزهای موقت را به سادگی پیاده‌سازی کند).

متد addAdminRule() برای افزودن تابعی استفاده می‌شود که هر زمان احراز هویت مدیر سیستم نیاز باشد، فراخوانی خواهد شد. این تابع برای تعیین هویت‌هایی به کار می‌رود که ممکن است برای احراز هویت مدیریتی در بررسی مجوزی که با action و subject شناسایی شده، مورد استفاده قرار گیرند. توابع اضافه‌شده به ترتیبی که افزوده شده‌اند فراخوانی می‌شوند تا زمانی که یکی از آن‌ها مقداری برگرداند. هر تابع باید آرایه‌ای از رشته‌ها را برگرداند که هر رشته به شکل "unix-group:<group>", "unix-netgroup:<netgroup>" یا "unix-user:<user>" باشد. اگر تابع مقدار null، undefined یا هیچ مقداری بازنگرداند، تابع بعدی آزموده می‌شود.

هیچ تضمینی وجود ندارد که تابعی که با addRule() یا addAdminRule() ثبت شده است حتماً فراخوانی شود - برای نمونه یک فایل قواعد اولیه ممکن است تابعی را ثبت کند که همواره مقداری برمی‌گرداند و در نتیجه مانع از فراخوانی توابعی شود که بعداً اضافه شده‌اند.

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

متد spawn() یک برنامه کمکی بیرونی را که با بردار آرگومان‌های argv مشخص شده اجرا می‌کند و منتظر پایان آن می‌ماند. اگر خطایی رخ دهد یا برنامه کمکی به صورت عادی با کد خروج ۰ پایان نیابد، یک استثنا صادر می‌شود. اگر برنامه کمکی ظرف مدت ۱۰ ثانیه به پایان نرسد، متوقف و کشته خواهد شد. در غیر این صورت، خروجی استاندارد برنامه به عنوان یک رشته بازگردانده می‌شود. متد spawn() باید با احتیاط و به ندرت استفاده شود زیرا برنامه‌های کمکی ممکن است زمان طولانی یا نامشخصی برای تکمیل نیاز داشته باشند و در زمان اجرای آن‌ها هیچ بررسی مجوز دیگری قابل انجام نیست. توجه داشته باشید که برنامه‌های اجراشده با کاربر سیستمی فاقد امتیاز polkitd اجرا خواهند شد.

متد log() پیام message داده‌شده را با پیشوند نام فایل جاوااسکریپت و شماره خط در ثبت‌کننده وقایع سیستم (logger) می‌نویسد. ورودی‌های لاگ با فلگ LOG_AUTHPRIV ارسال می‌شوند به این معنی که معمولاً در فایل /var/log/secure قرار می‌گیرند. متد log() معمولاً فقط هنگام اشکال‌زدایی قواعد به کار می‌رود. انواع Action و Subject متدهای مناسب toString() را برای لاگ‌گیری آسان تعریف کرده‌اند، برای نمونه:

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.policykit.exec") {
        polkit.log("action=" + action);
        polkit.log("subject=" + subject);
    }
});

هنگامی که کاربر دستور 'pkexec -u bateman bash -i' را از یک پوسته اجرا کند، خروجی زیر تولید خواهد شد:

May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:3: action=[Action id='org.freedesktop.policykit.exec' command_line='/usr/bin/bash -i' program='/usr/bin/bash' user='bateman' user.gecos='Patrick Bateman' user.display='Patrick Bateman (bateman)']
May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:4: subject=[Subject pid=1352 user='davidz' groups=davidz,wheel, seat='seat0' session='1' local=true active=true]

نوع Action (The Action type)

پارامتر action که به توابع کاربری فرستاده می‌شود شیئی حاوی اطلاعاتی درباره کنش در حال بررسی است. این شیء از نوع Action بوده و دارای ویژگی زیر است:

string id

متدهای زیر روی نوع Action در دسترس هستند:

string lookup(string key);

متد lookup() برای جستجوی متغیرهای polkit که از سازوکار ارسال شده‌اند استفاده می‌شود. برای نمونه، سازوکار pkexec(1) متغیر program را تنظیم می‌کند که می‌توان آن را در جاوااسکریپت با استفاده از عبارت action.lookup("program") به دست آورد. اگر هیچ مقداری برای key داده‌شده وجود نداشته باشد، مقدار undefined بازگردانده می‌شود.

برای اینکه بدانید چه متغیرهایی برای هر کنش در دسترس هستند به مستندات هر سازوکار مراجعه کنید.

نوع Subject (The Subject type)

پارامتر subject که به توابع کاربری ارسال می‌شود شیئی با اطلاعاتی درباره پردازه در حال بررسی است. این شیء از نوع Subject بوده و دارای ویژگی‌های زیر است:

int pid

int uid

string user

string[] groups

string seat

string session

string system_unit

boolean local

boolean no_new_privileges

boolean active

متدهای زیر روی نوع Subject در دسترس هستند:

boolean isInGroup(string groupName);

boolean isInNetGroup(string netGroupName);

متد isInGroup() می‌تواند برای بررسی عضویت موضوع در یک گروه مشخص استفاده شود و isInNetGroup() می‌تواند برای بررسی اینکه آیا موضوع در یک netgroup مشخص قرار دارد یا خیر به کار رود.

مثال‌های قواعد مجوزدهی (Authorization Rules Examples)

اجازه به تمام کاربران در گروه admin برای انجام مدیریت کاربران بدون تغییر سیاست برای سایر کاربران:

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.accounts.user-administration" &&
        subject.isInGroup("admin")) {
        return polkit.Result.YES;
    }
});

تعریف کاربران گروه wheel به عنوان کاربران مدیریتی:

polkit.addAdminRule(function(action, subject) {
    return ["unix-group:wheel"];
});

منع کاربران در گروه children از تغییر پیکربندی نام میزبان (یعنی هر کنشی با شناسه‌ای که با org.freedesktop.hostname1. آغاز می‌شود) و اجازه دادن به دیگران پس از احراز هویت به عنوان خودشان:

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;
        }
    }
});

اجرای یک برنامه کمکی خارجی برای تعیین اینکه آیا کاربر فعلی می‌تواند سیستم را مجدداً راه‌اندازی کند:

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;
        }
    }
});

مثال زیر نشان می‌دهد که چگونه تصمیم مجوزدهی می‌تواند به متغیرهای ارسال‌شده توسط سازوکار pkexec(1) وابسته باشد:

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.policykit.exec" &&
        action.lookup("program") == "/usr/bin/cat") {
        return polkit.Result.AUTH_ADMIN;
    }
});

مثال زیر کاربرد دیگری از متغیرهای ارسال‌شده از سازوکار را نشان می‌دهد. در این حالت، سازوکار UDisks[10] است که مجموعه‌ای از کنش‌ها و متغیرها[11] را تعریف می‌کند که برای تطبیق استفاده می‌شوند:

// Allow users in group 'engineers' 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;
        }
    }
});

اجازه به تمام پردازه‌هایی که به عنوان بخشی از واحد سیستمی admin.service در systemd اجرا می‌شوند برای انجام مدیریت کاربران، تا زمانی که نتوانند دسترسی‌های جدید کسب کنند:

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;
    }
});