.\" -*- coding: UTF-8 -*- .\" Copyright 2006, Red Hat, Inc. .\" Copyright 2016, Michael Kerrisk .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH request_key 2 "8 فبراير 2026" "صفحات دليل لينكس 6.18" .SH الاسم request_key \- طلب مفتاح من مرفق إدارة المفاتيح في النواة .SH المكتبة أدوات إدارة المفاتيح لينكس (\fIlibkeyutils\fP,\ \fI\-lkeyutils\fP) .SH موجز .nf \fB#include \fP .P \fBkey_serial_t request_key(const char *\fP\fItype\fP\fB, const char *\fP\fIdescription\fP\fB,\fP \fB const char *_Nullable \fP\fIcallout_info\fP\fB,\fP \fB key_serial_t \fP\fIdest_keyring\fP\fB);\fP .fi .SH الوصف تحاول \fBrequest_key\fP() إيجاد مفتاح من النوع \fItype\fP المحدد مع وصف (اسم) يطابق \fIdescription\fP المحدد. إذا لم يُعثر على هذا المفتاح، يُنشأ المفتاح اختيارياً. إذا وُجد المفتاح أو أُنشئ، ترفقه \fBrequest_key\fP() بحلقة المفاتيح التي يُحدد معرفها في \fIdest_keyring\fP وتعيد الرقم التسلسلي للمفتاح. .P تبحث \fBrequest_key\fP() أولاً بشكل متكرر عن مفتاح مطابق في جميع حلقات المفاتيح المرفقة بالعملية المستدعية. تُبحث حلقات المفاتيح بالترتيب: حلقة المفاتيح الخاصة بالخيط، حلقة المفاتيح الخاصة بالعملية، ثم حلقة المفاتيح الخاصة بالجلسة. .P .\" David Howells: we can then have an arbitrarily long sequence .\" of "recursive" request-key upcalls. There is no limit, other .\" than number of PIDs, etc. إذا استُدعيت \fBrequest_key\fP() من برنامج استُدعي بواسطة \fBrequest_key()\fP نيابة عن عملية أخرى لتوليد مفتاح، فسيُبحث بعد ذلك عن حلقات المفاتيح لتلك العملية الأخرى، باستخدام معرف المستخدم ومعرف المجموعة ومعرفات المجموعات الإضافية وسياق الأمان لتلك العملية الأخرى لتحديد الوصول. .P البحث في شجرة حلقة المفاتيح هو بحث عرضي أولاً: تُفحص المفاتيح في كل حلقة مفاتيح بحثاً عن تطابق قبل التعمق في أي حلقات مفاتيح فرعية. فقط المفاتيح التي يملك المستدعي إذن \fIsearch\fP لها تُوجد، وحلقات المفاتيح التي يملك المستدعي إذن \fIsearch\fP لها فقط قد تُبحث. .P إذا لم يُعثر على المفتاح وكان \fIcallout\fP فارغاً (NULL)، فشلت الاستدعاء مع الخطأ \fBENOKEY\fP. .P إذا لم يُعثر على المفتاح وكان \fIcallout\fP غير فارغ، تحاول النواة استدعاء برنامج في مساحة المستخدم لتحقيق المفتاح. التفاصيل مذكورة أدناه. .P الرقم التسلسلي \fIdest_keyring\fP قد يكون لحلقة مفاتيح صالحة يملك المستدعي إذن \fIwrite\fP لها، أو قد يكون أحد معرفات حلقة المفاتيح الخاصة التالية: .TP \fBKEY_SPEC_THREAD_KEYRING\fP يحدد هذا حلقة المفاتيح الخاصة بالخيط للمستدعي (انظر \fBthread\-keyring\fP(7)). .TP \fBKEY_SPEC_PROCESS_KEYRING\fP يحدد هذا حلقة المفاتيح الخاصة بالعملية للمستدعي (انظر \fBprocess\-keyring\fP(7)). .TP \fBKEY_SPEC_SESSION_KEYRING\fP يحدد هذا حلقة المفاتيح الخاصة بالجلسة للمستدعي (انظر \fBsession\-keyring\fP(7)). .TP \fBKEY_SPEC_USER_KEYRING\fP يحدد هذا حلقة المفاتيح الخاصة بمعرف المستخدم للمستدعي (انظر \fBuser\-keyring\fP(7)). .TP \fBKEY_SPEC_USER_SESSION_KEYRING\fP يحدد هذا حلقة مفاتيح جلسة معرف المستخدم للمستدعي (انظر \fBuser\-session\-keyring\fP(7)). .P عندما يُحدد \fIdest_keyring\fP بالصفر 0 ولم يُجرَ بناء مفتاح، فلا يُجرى أي ربط إضافي. .P وإلا، إذا كان \fIdest_keyring\fP صفراً 0 وبُني مفتاح جديد، سيُربط المفتاح الجديد بحلقة المفاتيح "المبدئية". بتعبير أدق، عندما تحاول النواة تحديد أي حلقة مفاتيح يجب ربط المفتاح المبني حديثاً بها، تجرب حلقات المفاتيح التالية، مبتدئة بحلقة المفاتيح المُعينة عبر عملية \fBkeyctl\fP(2) \fBKEYCTL_SET_REQKEY_KEYRING\fP ومستمرة بالترتيب الموضح أدناه حتى تجد أول حلقة مفاتيح موجودة: .IP \[bu] 3 .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 .\" FIXME .\" Actually, is the preceding point correct? .\" If I understand correctly, we'll only get here if .\" 'dest_keyring' is zero, in which case KEY_REQKEY_DEFL_REQUESTOR_KEYRING .\" won't refer to a keyring. Have I misunderstood? حلقة مفاتيح الطالب (\fBKEY_REQKEY_DEFL_REQUESTOR_KEYRING\fP، منذ لينكس 2.6.29). .IP \[bu] حلقة المفاتيح الخاصة بالخيط (\fBKEY_REQKEY_DEFL_THREAD_KEYRING\fP؛ انظر \fBthread\-keyring\fP(7)). .IP \[bu] حلقة المفاتيح الخاصة بالعملية (\fBKEY_REQKEY_DEFL_PROCESS_KEYRING\fP؛ انظر \fBprocess\-keyring\fP(7)). .IP \[bu] حلقة المفاتيح الخاصة بالجلسة (\fBKEY_REQKEY_DEFL_SESSION_KEYRING\fP؛ انظر \fBsession\-keyring\fP(7)). .IP \[bu] حلقة مفاتيح الجلسة لمعرف مستخدم العملية (\fBKEY_REQKEY_DEFL_USER_SESSION_KEYRING\fP؛ انظر \fBuser\-session\-keyring\fP(7)). يُتوقع أن توجد حلقة المفاتيح هذه دائماً. .IP \[bu] .\" mtk: Are there circumstances where the user sessions and UID-specific .\" keyrings do not exist? .\" .\" David Howells: .\" The uid keyrings don't exist until someone tries to access them - .\" at which point they're both created. When you log in, pam_keyinit .\" creates a link to your user keyring in the session keyring it just .\" created, thereby creating the user and user-session keyrings. .\" .\" and David elaborated that "access" means: .\" .\" It means lookup_user_key() was passed KEY_LOOKUP_CREATE. So: .\" .\" add_key() - destination keyring .\" request_key() - destination keyring .\" KEYCTL_GET_KEYRING_ID - if create arg is true .\" KEYCTL_CLEAR .\" KEYCTL_LINK - both args .\" KEYCTL_SEARCH - destination keyring .\" KEYCTL_CHOWN .\" KEYCTL_SETPERM .\" KEYCTL_SET_TIMEOUT .\" KEYCTL_INSTANTIATE - destination keyring .\" KEYCTL_INSTANTIATE_IOV - destination keyring .\" KEYCTL_NEGATE - destination keyring .\" KEYCTL_REJECT - destination keyring .\" KEYCTL_GET_PERSISTENT - destination keyring .\" .\" will all create a keyring under some circumstances. Whereas the rest, .\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't. حلقة المفاتيح الخاصة بمعرف المستخدم (\fBKEY_REQKEY_DEFL_USER_KEYRING\fP؛ انظر \fBuser\-keyring\fP(7)). يُتوقع أيضًا أن توجد حلقة المفاتيح هذه دائماً. .P .\" إذا حددت عملية \fBkeyctl\fP(2) \fBKEYCTL_SET_REQKEY_KEYRING\fP القيمة \fBKEY_REQKEY_DEFL_DEFAULT\fP (أو لم تُجرَ أي عملية \fBKEYCTL_SET_REQKEY_KEYRING\fP)، فتبحث النواة عن حلقة مفاتيح مبتدئة من بداية القائمة. .SS "طلب تحقيق مفتاح في مساحة المستخدم" إذا لم تستطع النواة إيجاد مفتاح يطابق \fItype\fP و \fIdescription\fP، وكان \fIcallout\fP غير فارغ، فتحاول النواة استدعاء برنامج في مساحة المستخدم لتحقيق مفتاح بالنوع \fItype\fP والوصف \fIdescription\fP المحددين. في هذه الحالة، تُجرى الخطوات التالية: .IP (1) 5 تنشئ النواة مفتاحاً غير محقق، U، بالنوع \fItype\fP والوصف \fIdescription\fP المطلوبين. .IP (2) .\" struct request_key_auth, defined in security/keys/internal.h تنشئ النواة مفتاح تفويض، V، يشير إلى المفتاح U ويسجل الحقائق بأن مستدعي \fBrequest_key\fP() هو: .RS .IP (2.1) 7 السياق الذي يجب فيه إنشاء المفتاح U وتأمينه، و .IP (2.2) السياق الذي يمكن من خلاله تلبية طلبات المفاتيح المرتبطة. .RE .IP يُبنى مفتاح التفويض على النحو التالي: .RS .IP \[bu] 3 نوع المفتاح هو \fI\[dq].request_key_auth\[dq]\fP. .IP \[bu] UID وGID للمفتاح هما نفس معرفات نظام الملفات المقابلة للعملية الطالبة. .IP \[bu] يمنح المفتاح صلاحيات \fIview\fP و\fIread\fP و\fIsearch\fP لحائز المفتاح بالإضافة إلى صلاحية \fIview\fP لمستخدم المفتاح. .IP \[bu] الوصف (الاسم) للمفتاح هو السلسلة السداسية العشرية التي تمثل معرف المفتاح الذي سيتم إنشاؤه في البرنامج الطالب. .IP \[bu] يؤخذ حمولة المفتاح من البيانات المحددة في \fIcallout_info\fP. .IP \[bu] داخليًا، يسجل النواة أيضًا PID العملية التي استدعت \fBrequest_key\fP(). .RE .IP (3) .\" The request\-key(8) program can be invoked in circumstances *other* than .\" when triggered by request_key(2). For example, upcalls from places such .\" as the DNS resolver. تنشئ النواة عملية تنفذ خدمة في مساحة المستخدم مثل \fBrequest\-key\fP(8) مع حلقة مفاتيح جلسة جديدة تحتوي على رابط لمفتاح التفويض V. .IP يُزود هذا البرنامج بوسائط سطر الأوامر التالية: .RS .IP [0] 5 السلسلة \fI\[dq]/sbin/request\-key\[dq]\fP. .IP [1] السلسلة \fI\[dq]create\[dq]\fP (تشير إلى أنه سيتم إنشاء مفتاح). .IP [2] معرف المفتاح الذي سيتم إنشاؤه. .IP [3] UID نظام الملفات لمستدعي \fBrequest_key\fP(). .IP [4] GID نظام الملفات لمستدعي \fBrequest_key\fP(). .IP [5] معرف حلقة مفاتيح الخيط لمستدعي \fBrequest_key\fP(). قد يكون صفرًا إذا لم يتم إنشاء حلقة المفاتيح تلك. .IP [6] معرف حلقة مفاتيح العملية لمستدعي \fBrequest_key\fP(). قد يكون صفرًا إذا لم يتم إنشاء حلقة المفاتيح تلك. .IP [7] معرف حلقة مفاتيح الجلسة لمستدعي \fBrequest_key\fP(). .RE .IP \fIملاحظة\fP: كل وسيطة من وسائط سطر الأوامر التي تمثل معرف مفتاح تُرمّز بـ \fIعشري\fP (على عكس معرفات المفاتيح المعروضة في \fI/proc/keys\fP، والتي تُعرض كقيم سداسية عشرية). .IP (4) البرنامج المنشأ في الخطوة السابقة: .RS .IP \[bu] 3 يفترض السلطة لإنشاء المفتاح U باستخدام عملية \fBkeyctl\fP(2) \fBKEYCTL_ASSUME_AUTHORITY\fP (عادةً عبر الدالة \fBkeyctl_assume_authority\fP(3)). .IP \[bu] يحصل على بيانات الاستدعاء من حمولة مفتاح التفويض V (باستخدام عملية \fBkeyctl\fP(2) \fBKEYCTL_READ\fP (أو بشكل أكثر شيوعًا، الدالة \fBkeyctl_read\fP(3)) مع قيمة معرف مفتاح \fBKEY_SPEC_REQKEY_AUTH_KEY\fP). .IP \[bu] .\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING? .\" I couldn't find a use in the keyutils git repo. .\" According to David Howells: .\" * This feature is provided, but not used at the moment. .\" * A key added to that ring is then owned by the requester ينشئ المفتاح (أو ينفذ برنامجًا آخر يؤدي تلك المهمة)، مع تحديد الحمولة وحلقة المفاتيح الوجهة. (يمكن الوصول إلى حلقة المفاتيح الوجهة التي حددها الطالب عند استدعاء \fBrequest_key\fP() باستخدام معرف المفتاح الخاص \fBKEY_SPEC_REQUESTOR_KEYRING\fP.) يتم الإنشاء باستخدام عملية \fBkeyctl\fP(2) \fBKEYCTL_INSTANTIATE\fP (أو بشكل أكثر شيوعًا، الدالة \fBkeyctl_instantiate\fP(3)). عند هذه النقطة، يكتمل استدعاء \fBrequest_key\fP()، ويمكن للبرنامج الطالب متابعة التنفيذ. .RE .P إذا لم تنجح هذه الخطوات، فسيتم إرجاع خطأ \fBENOKEY\fP إلى مستدعي \fBrequest_key\fP() وسيتم تثبيت مفتاح مؤقت منشأ بشكل سلبي في حلقة المفاتيح المحددة بواسطة \fIdest_keyring\fP. سينتهي صلاحية هذا المفتاح بعد بضع ثوانٍ، ولكنه سيتسبب في فشل الاستدعاءات اللاحقة لـ \fBrequest_key\fP() حتى ذلك الحين. الغرض من هذا المفتاح المنشأ بشكل سلبي هو منع العمليات (ربما المختلفة) من تقديم طلبات متكررة (تتطلب استدعاءات علوية مكلفة لـ \fBrequest\-key\fP(8)) لمفتاح لا يمكن (في الوقت الحالي) إنشاؤه بشكل إيجابي. .P بمجرد إنشاء المفتاح، يتم إلغاء مفتاح التفويض (\fBKEY_SPEC_REQKEY_AUTH_KEY\fP)، ولم يعد من الممكن الوصول إلى حلقة المفاتيح الوجهة (\fBKEY_SPEC_REQUESTOR_KEYRING\fP) من برنامج \fBrequest\-key\fP(8). .P إذا تم إنشاء مفتاح، فبغض النظر عما إذا كان مفتاحًا صالحًا أم مفتاحًا منشأ بشكل سلبي، فسيحل محل أي مفتاح آخر من نفس النوع والوصف من حلقة المفاتيح المحددة في \fIdest_keyring\fP. .SH "قيمة الإرجاع" عند النجاح، تُرجع \fBrequest_key\fP() الرقم التسلسلي للمفتاح الذي وجدته أو تسببت في إنشائه. عند الخطأ، تُرجع \-1 ويتم تعيين \fIerrno\fP للإشارة إلى الخطأ. .SH الأخطاء .TP \fBEACCES\fP لم تكن حلقة المفاتيح متاحة للتعديل من قبل المستخدم. .TP \fBEDQUOT\fP سَيُتَجَاوَزُ حصة المفاتيح لهذا المستخدم بإنشاء هذا المفتاح أو ربطه بحلقة المفاتيح. .TP \fBEFAULT\fP يشير أحد \fItype\fP أو \fIdescription\fP أو \fIcallout_info\fP إلى خارج مساحة العنوان القابلة للوصول للعملية. .TP \fBEINTR\fP تمت مقاطعة الطلب بواسطة إشارة؛ انظر \fBsignal\fP(7). .TP \fBEINVAL\fP حجم السلسلة (بما في ذلك بايت null النهائي) المحدد في \fItype\fP أو \fIdescription\fP تجاوز الحد (32 بايت و 4096 بايت على التوالي). .TP \fBEINVAL\fP تجاوز حجم السلسلة (بما في ذلك البايت الفارغ الختامي) المحدد في \fIcallout_info\fP حجم صفحة النظام. .TP \fBEKEYEXPIRED\fP تم العثور على مفتاح منتهي الصلاحية، لكن لا يمكن الحصول على بديل. .TP \fBEKEYREJECTED\fP تم رفض محاولة إنشاء مفتاح جديد. .TP \fBEKEYREVOKED\fP تم العثور على مفتاح ملغي، لكن لا يمكن الحصول على بديل. .TP \fBENOKEY\fP لم يتم العثور على مفتاح مطابق. .TP \fBENOMEM\fP الذاكرة غير كافية لإنشاء مفتاح. .TP \fBEPERM\fP بدأت وسيطة \fItype\fP بنقطة (\[aq].\[aq]). .SH المعايير لينكس. .SH التاريخ لينكس 2.6.10. .P .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a أُضيفت القدرة على إنشاء المفاتيح عند الطلب في Linux 2.6.13. .SH أمثلة يُوضح البرنامج أدناه استخدام \fBrequest_key\fP(). تُؤخذ وسيطات \fItype\fP و \fIdescription\fP و \fIcallout_info\fP لاستدعاء النظام من القيم المقدمة في وسيطات سطر الأوامر. يُحدد الاستدعاء حلقة المفاتيح الجلسة كحلقة مفاتيح هدف. .P لتوضيح هذا البرنامج، ننشئ أولاً إدخالاً مناسباً في الملف \fI/etc/request\-key.conf\fP. .P .in +4n .EX $\fB sudo sh\fP; #\fB echo \[aq]create user mtk:* * /bin/keyctl instantiate %k %c %S\[aq] \[rs]\fP \fB > /etc/request\-key.conf\fP; #\fB exit\fP; .EE .in .P يُحدد هذا الإدخال أنه عندما يجب إنشاء مفتاح "user" جديد بالبادئة "mtk:"، يجب تنفيذ هذه المهمة عبر عملية \fBinstantiate\fP لأمر \fBkeyctl\fP(1). الوسيطات المقدمة لعملية \fBinstantiate\fP هي: معرف المفتاح غير المنشأ (\fI%k\fP)؛ بيانات الاستدعاء المقدمة لاستدعاء \fBrequest_key\fP() (\fI%c\fP)؛ وحلقة المفاتيح الجلسة (\fI%S\fP) للطالب (أي مستدعي \fBrequest_key\fP()). انظر \fBrequest\-key.conf\fP(5) لتفاصيل هذه المحددات \fI%\fP. .P ثم نشغل البرنامج ونتحقق من محتويات \fI/proc/keys\fP للتحقق من إنشاء المفتاح المطلوب: .P .in +4n .EX $\fB ./t_request_key user mtk:key1 \[dq]Payload data\[dq]\fP; $\fB grep \[aq]2dddaf50\[aq] /proc/keys\fP; 2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12 .EE .in .P لمثال آخر على استخدام هذا البرنامج، انظر \fBkeyctl\fP(2). .SS "مصدر البرنامج" .\" SRC BEGIN (t_request_key.c) \& .EX /* t_request_key.c */ \& #include #include #include #include \& int main(int argc, char *argv[]) { key_serial_t key; \& if (argc != 4) { fprintf(stderr, "Usage: %s type description callout\-data\[rs]n", argv[0]); exit(EXIT_FAILURE); } \& key = request_key(argv[1], argv[2], argv[3], KEY_SPEC_SESSION_KEYRING); if (key == \-1) { perror("request_key"); exit(EXIT_FAILURE); } \& printf("Key ID is %jx\[rs]n", (uintmax_t) key); \& exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "انظر أيضًا" .ad l .nh \fBkeyctl\fP(1), \fBadd_key\fP(2), \fBkeyctl\fP(2), \fBkeyctl\fP(3), \fBcapabilities\fP(7), \fBkeyrings\fP(7), \fBkeyutils\fP(7), \fBpersistent\-keyring\fP(7), \fBprocess\-keyring\fP(7), \fBsession\-keyring\fP(7), \fBthread\-keyring\fP(7), \fBuser\-keyring\fP(7), \fBuser\-session\-keyring\fP(7), \fBrequest\-key\fP(8) .P ملفات مصدر النواة \fIDocumentation/security/keys/core.rst\fP و \fIDocumentation/keys/request\-key.rst\fP. .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .