add_key(2)

الاسم
add_key - إضافة مفتاح إلى مرفق إدارة المفاتيح في النواة

المكتبة
مكتبة سي المعيارية (libc، -lc)

موجز
#include <keyutils.h>

key_serial_t add_key(size_t size;
                     const char *type, const char *description,
                     const void payload[size], size_t size,
                     key_serial_t keyring);

ملاحظة: لا يوجد مغلف glibc لنداء النظام هذا؛ انظر NOTES.

الوصف
تنشئ add_key() أو تحدث مفتاحًا من type و description المعطيين، وتنشئه باستخدام payload بحجم size، وتعلقه بـ keyring المعين، وتعيد الرقم التسلسلي للمفتاح.

قد يُرفض المفتاح إذا كانت البيانات المقدمة بتنسيق خاطئ أو غير صالحة بطريقة أخرى.

إذا كان keyring الوجهة يحتوي بالفعل على مفتاح يطابق type و description المحددين، فعندئذ، إذا كان نوع المفتاح يدعم ذلك، يُحدث ذلك المفتاح بدلاً من إنشاء مفتاح جديد؛ وإلا، يُنشأ مفتاح جديد (بمعرف مختلف) ويحل محل الرابط للمفتاح الموجود من keyring.

قد يكون الرقم التسلسلي لـ keyring الوجهة هو رقم keyring صالح يملك المتصل إذن write له. بدلاً من ذلك، قد يكون أحد معرفات keyring الخاصة التالية:

KEY_SPEC_THREAD_KEYRING
    يحدد هذا keyring الخاص بالخيط للمتصل (thread-keyring(7)).

KEY_SPEC_PROCESS_KEYRING
    يحدد هذا keyring الخاص بالعملية للمتصل (process-keyring(7)).

KEY_SPEC_SESSION_KEYRING
    يحدد هذا keyring الخاص بالجلسة للمتصل (session-keyring(7)).

KEY_SPEC_USER_KEYRING
    يحدد هذا keyring الخاص بمعرف المستخدم للمتصل (user-keyring(7)).

KEY_SPEC_USER_SESSION_KEYRING
    يحدد هذا keyring جلسة معرف المستخدم للمتصل (user-session-keyring(7)).

  أنواع المفاتيح
type المفتاح هو سلسلة تحدد نوع المفتاح. داخليًا، تعرف النواة عددًا من أنواع المفاتيح المتاحة في كود إدارة المفاتيح الأساسي. من بين الأنواع المتاحة لاستخدام مساحة المستخدم والتي يمكن تحديدها كوسيطة type لـ add_key() ما يلي:

"keyring"
    Keyrings هي أنواع مفاتيح خاصة قد تحتوي على روابط لتسلسلات مفاتيح أخرى من أي نوع. إذا استُخدمت هذه الواجهة لإنشاء keyring، فيجب أن يكون payload NULL و size صفرًا.

"user"
    هذا نوع مفتاح للأغراض العامة يمكن لتطبيقات مساحة المستخدم قراءة حمولته وتحديثها. يُحتفظ بالمفتاح بالكامل داخل ذاكرة النواة. حمولة مفاتيح هذا النوع هي كتلة من بيانات عشوائية يصل حجمها إلى 32,767 بايت.

"logon" (منذ لينكس 3.3)
    نوع المفتاح هذا هو نفسه بشكل أساسي "user"، لكنه لا يسمح بقراءة المفتاح. هذا مناسب لتخزين حمولات لا تريد أن تكون قابلة للقراءة من مساحة المستخدم.

يفحص نوع المفتاح هذا description لضمان تأهيله ببادئة "service"، عن طريق التحقق من أن description يحتوي على ':' يسبقه أحرف أخرى.

"big_key" (منذ لينكس 3.13)
    نوع المفتاح هذا مشابه لـ "user"، لكنه قد يحمل حمولة تصل إلى 1 MiB. إذا كانت حمولة المفتاح كبيرة بما يكفي، فقد تُخزن مشفرة في tmpfs (التي يمكن استبدالها) بدلاً من ذاكرة النواة.

لمزيد من التفاصيل حول أنواع المفاتيح هذه، انظر keyrings(7).

قيمة الإرجاع
عند النجاح، تعيد add_key() الرقم التسلسلي للمفتاح الذي أنشأته أو حدثته. عند الخطأ، تُعاد -1 ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EACCES
    لم تكن حلقة المفاتيح متاحة للتعديل من قبل المستخدم.

EDQUOT
    سَيُتَجَاوَزُ حصة المفاتيح لهذا المستخدم بإنشاء هذا المفتاح أو ربطه بحلقة المفاتيح.

EFAULT
    واحد أو أكثر من type و description و payload يشير إلى خارج مساحة العنوان القابلة للوصول للعملية.

EINVAL
    حجم السلسلة (بما في ذلك بايت null النهائي) المحدد في type أو description تجاوز الحد (32 بايت و 4096 بايت على التوالي).

EINVAL
    بيانات الحمولة كانت غير صالحة.

EINVAL
    كان type هو "logon" ولم يكن description مؤهلاً بسلسلة بادئة من الشكل "service:".

EKEYEXPIRED
    انتهت صلاحية keyring.

EKEYREVOKED
    أُلغي keyring.

ENOKEY
    keyring غير موجود.

ENOMEM
    الذاكرة غير كافية لإنشاء مفتاح.

EPERM
    بدأ type بنقطة ('.'). أنواع المفاتيح التي تبدأ بنقطة محجوزة للتنفيذ.

EPERM
    كان type هو "keyring" وبدأ description بنقطة ('.'). Keyrings ذات الأوصاف (الأسماء) التي تبدأ بنقطة محجوزة للتنفيذ.

المعايير
لينكس.

التاريخ
لينكس 2.6.10.

ملاحظات
لا توفر glibc غلافًا لاستدعاء النظام هذا. يُوفر غلاف في مكتبة libkeyutils. (توفر الحزمة المصاحبة ملف الرأس <keyutils.h>.) عند استخدام الغلاف في تلك المكتبة، اربط مع -lkeyutils.

أمثلة
ينشئ البرنامج أدناه مفتاحًا بالنوع والوصف والحمولة المحددة في وسائط سطر الأوامر، ويربط ذلك المفتاح في keyring الجلسة. توضح جلسة الصدفة التالية استخدام البرنامج:

    $ ./a.out user mykey "Some payload";
    Key ID is 64a4dca
    $ grep '64a4dca' /proc/keys;
    064a4dca I--Q---    1 perm 3f010000  1000  1000 user    mykey: 12

  مصدر البرنامج
    #include <keyutils.h>
    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>

    int
    main(int argc, char *argv[])
    {
        key_serial_t key;

        if (argc != 4) {
            fprintf(stderr, "Usage: %s type description payload\n",
                    argv[0]);
            exit(EXIT_FAILURE);
        }

        key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
                      KEY_SPEC_SESSION_KEYRING);
        if (key == -1) {
            perror("add_key");
            exit(EXIT_FAILURE);
        }

        printf("Key ID is %jx\n", (uintmax_t) key);

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
keyctl(1), keyctl(2), request_key(2), keyctl(3), keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7)

ملفات مصدر النواة Documentation/security/keys/core.rst و Documentation/keys/request-key.rst.

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.