CRYPT(3)

الاسم
crypt, crypt_r, crypt_rn, crypt_ra - تجزئة عبارة السر

المكتبة
libcrypt

موجز
<crypt.h> char * crypt(const char *phrase, const char *setting) char * crypt_r(const char *phrase, const char *setting, struct crypt_data *data) char * crypt_rn(const char *phrase, const char *setting, struct crypt_data *data, int size) char * crypt_ra(const char *phrase, const char *setting, void **data, int *size)

الوصف
الدوال crypt و crypt_r و crypt_rn و crypt_ra تقوم بتجزئة phrase بشكل لا رجعة فيه للتخزين في قاعدة بيانات كلمات السر النظامية (shadow(5)) باستخدام “طريقة تجزئة” تعمية. تُسمى نتيجة هذه العملية “عبارة سر مُجزأة” أو ببساطة “تجزئة.” تُوصف طرق التجزئة في crypt(5).

يتحكم setting في طريقة التجزئة المستخدمة، ويوفر أيضًا معاملات مختلفة للطريقة المختارة، وأهمها “ملح” عشوائي يضمن عدم تطابق أي تجزئتين مخزنتين، حتى لو كانت سلسلتا محارف phrase متماثلتين.

وسيط data للدالة crypt_r هو بنية من النوع struct crypt_data. تحتوي على الأقل على هذه الحقول:

    struct crypt_data {
        char output[CRYPT_OUTPUT_SIZE];
        char setting[CRYPT_OUTPUT_SIZE];
        char input[CRYPT_MAX_PASSPHRASE_SIZE];
        char initialized;
    };

عند العودة بنجاح من crypt_r ، تُخزَّن عبارة السر المُجزأة في output. يُشجَّع التطبيقات، ولكن ليس إلزاميًا، على استخدام حقلي input و setting لتخزين السلاسل التي ستمررها كـ input phrase و setting إلى crypt_r. هذا يسهل مسح جميع البيانات الحساسة بعد عدم الحاجة إليها.

يجب ضبط حقل initialized على الصفر قبل أول استخدام لكائن struct crypt_data في استدعاء لـ crypt_r(). نوصي بتصفير الكائن بأكمله، وليس فقط initialized وليس فقط الحقول الموثقة، قبل الاستخدام الأول. (بالطبع، افعل هذا قبل تخزين أي شيء في setting و input.)

يجب أن يشير وسيط data للدالة crypt_rn أيضًا إلى كائن struct crypt_data ، ويجب أن يكون size هو حجم ذلك الكائن، محولاً إلى int. عند استخدامه مع crypt_rn ، يجب تصفير كائن data بأكمله (باستثناء حقلي input و setting) قبل استخدامه الأول؛ هذه ليست مجرد توصية، كما هو الحال مع crypt_r. بخلاف ذلك، لحقول الكائن نفس الاستخدامات التي لها مع crypt_r.

في أول استدعاء لـ crypt_ra ، يجب أن يكون data عنوان متغير من النوع void * مضبوط على NULL، ويجب أن يكون size عنوان متغير من النوع int مضبوط على الصفر. ستقوم crypt_ra بتخصيص وتهيئة كائن struct crypt_data ، باستخدام malloc(3) ، وكتابة عنوانه وحجمه في المتغيرين المشار إليهما بواسطة data و size. يمكن إعادة استخدام هذه في الاستدعاءات اللاحقة. بعد انتهاء التطبيق من تجزئة عبارات السر، يجب تحرير كائن struct crypt_data باستخدام free(3).

القيم المُرجعة
عند الإكمال الناجح، تُرجع الدوال crypt و crypt_r و crypt_rn و crypt_ra مؤشرًا إلى سلسلة محارف تُرمّز كلًا من عبارة السر المُعمّاة والإعدادات التي استُخدمت لتعميتها. هذه السلسلة قابلة للاستخدام مباشرة كـ setting في استدعاءات أخرى للدوال crypt و crypt_r و crypt_rn و crypt_ra ، وكـ prefix في استدعاءات الدوال crypt_gensalt و crypt_gensalt_rn و crypt_gensalt_ra. ستكون السلسلة بالكامل من محارف ASCII القابلة للطباعة، ولن تحتوي على مسافات بيضاء أو المحارف ‘’: أو ‘’; أو ‘*’ أو ‘’! أو ‘\’. انظر crypt(5) لمزيد من التفاصيل حول تنسيق عبارات السر المُعمّاة.

يضع crypt نتيجته في منطقة تخزين ثابتة، والتي تُكتب فوقها بواسطة استدعاءات لاحقة لـ crypt. ليس من الآمن استدعاء crypt من خيوط متعددة في وقت واحد. لا يُوصى أيضًا باستخدام المؤشر المُعاد كوسيطة لاستدعاء آخر لـ crypt ، حيث أن بعض التطبيقات، بما في ذلك الإصدارات السابقة من libxcrypt، قد تكتب فوق مخزن الإخراج الثابت الأساسي قبل حساب التجزئة.

تضع crypt_r و crypt_rn و crypt_ra نتيجتهن في حقل output لوسيطتهن data. من الآمن استدعاؤهن من خيوط متعددة في وقت واحد، طالما يُستخدم كائن data منفصل لكل خيط. لا يُوصى أيضًا باستخدام المؤشر المُعاد كوسيطة لاستدعاء آخر لـ crypt_r و crypt_rn و crypt_ra باستخدام نفس كائن data للاستدعاءات اللاحقة، حيث أن بعض التطبيقات، بما في ذلك الإصدارات السابقة من libxcrypt، قد تكتب فوق حقل output لوسيطة data المُمررة قبل حساب التجزئة. لا يُوصى باستدعاء crypt_ra مع معاملات phrase و/أو setting الموجودة داخل كائن data مُمرر أصغر من حجم struct crypt_data ، حيث أن بعض التطبيقات، بما في ذلك الإصدارات السابقة من libxcrypt، قد لا تحافظ على الحرفيات المُمررة، إذا كان كائن data بحاجة إلى التغيير.

عند حدوث خطأ، تكتب الدوال crypt_r و crypt_rn و crypt_ra قيمة تعمية غير صالحة إلى حقل output من معاملها data ، وتكتب الدالة crypt قيمة تعمية غير صالحة إلى منطقة تخزينها الثابتة. ستكون هذه السلسلة أقصر من 13 محرفًا، وستبدأ بـ ‘*’ ، ولن تُساوِي setting.

عند حدوث خطأ، تُرجع crypt_rn و crypt_ra مؤشرًا فارغًا. قد تُرجع crypt_r و crypt أيضًا مؤشرًا فارغًا، أو قد تُرجعان مؤشرًا إلى التجزئة غير الصالحة، اعتمادًا على كيفية تكوين libcrypt. (خيار إرجاع التجزئة غير الصالحة هو للتوافق مع التطبيقات القديمة التي تفترض أن crypt لا يمكنها إرجاع مؤشر فارغ. انظر ملاحظات قابلية النقل أدناه.)

تضبط جميع الدوال الأربع errno عند فشلها. عندما تنجح الدوال، تكون قيمة errno غير محددة ويجب عدم الاعتماد عليها.

الأخطاء

خطأ EINVAL
    الإعداد غير صالح، أو يطلب طريقة تجزئة غير مدعومة.

خطأ ERANGE
    العبارة طويلة جدًا (أكثر من CRYPT_MAX_PASSPHRASE_SIZE حرفًا؛ قد تحتوي بعض طرق التجزئة على حدود أقل).
    crypt_rn فقط: الحجم صغير جدًا لطريقة التجزئة المطلوبة بواسطة الإعداد.

خطأ ENOMEM
    فشل تخصيص ذاكرة مؤقتة داخلية.
    crypt_ra فقط: فشل تخصيص ذاكرة لـ البيانات.

خطأ ENOSYS أو خطأ EOPNOTSUPP
    تجزئة كلمات السر غير مدعومة على الإطلاق في هذا التثبيت، أو طريقة التجزئة المطلوبة بواسطة الإعداد غير مدعومة. لا تُستخدم رموز الخطأ هذه بواسطة هذا الإصدار من libcrypt، ولكن قد تُواجه على أنظمة أخرى.

ملاحظات قابلية النقل
crypt مضمنة في POSIX، لكن crypt_r و crypt_rn و crypt_ra ليست جزءًا من أي معيار.

لا يحدد POSIX أي طرق تجزئة، ولا يتطلب أن تكون كلمات السر المجزأة قابلة للنقل بين الأنظمة. عمليًا، تكون كلمات السر المجزأة قابلة للنقل طالما أن كلا النظامين يدعمان طريقة التجزئة المستخدمة. ومع ذلك، تختلف مجموعة طرق التجزئة المدعومة اختلافًا كبيرًا من نظام إلى آخر.

سلوك crypt عند الأخطاء ليس موحدًا بشكل جيد. بعض التطبيقات ببساطة لا يمكنها الفشل (باستثناء تعطل البرنامج)، وأخرى تُرجع مؤشرًا فارغًا أو سلسلة محارف ثابتة. معظم التطبيقات لا تضبط errno ، لكن بعضها يفعل. يحدد POSIX إرجاع مؤشر فارغ وضبط errno ، لكنه يعرف خطأً واحدًا فقط ممكنًا، ENOSYS ، في حالة عدم دعم crypt على الإطلاق. بعض التطبيقات القديمة غير مستعدة للتعامل مع المؤشرات الفارغة التي تُرجعها crypt. السلوك الموصوف أعلاه لهذا التطبيق، ضبط errno وإرجاع تجزئة غير صالحة مختلفة عن الإعداد ، اختير لجعل هذه التطبيقات تفشل بشكل مغلق عند حدوث خطأ.

بسبب القيود التاريخية على تصدير البرامج التشفيرية من الولايات المتحدة، crypt هي مكون اختياري في POSIX. لذلك يجب أن تكون التطبيقات مستعدة لعدم توفر crypt ، أو فشلها دائمًا (ضبط errno إلى ENOSYS) في وقت التشغيل.

يحدد POSIX أن crypt معلنة في <unistd.h،> ولكن فقط إذا كان الماكرو _XOPEN_CRYPT معرفًا وله قيمة أكبر من أو تساوي الصفر. نظرًا لأن libcrypt لا توفر <unistd.h،> تُعلن عن crypt و crypt_r و crypt_rn و crypt_ra في <crypt.h> بدلاً من ذلك.

على أقلية من الأنظمة (خاصة الإصدارات الحديثة من Solaris)، يستخدم crypt مخزنًا ثابتًا خاصًا بالخيط، مما يجعله آمنًا للاستدعاء من خيوط متعددة في وقت واحد، لكنه لا يمنع كل استدعاء داخل خيط من الكتابة فوق نتائج الاستدعاء السابق.

العلل
بعض تطبيقات crypt ، عند حدوث خطأ، تُرجع تجزئة غير صالحة مخزنة في موقع للقراءة فقط أو مهيأة مرة واحدة فقط، مما يعني أنه من الآمن فقط مسح المخزن المشار إليه بقيمة إرجاع crypt إذا لم يحدث خطأ.

قد يكون struct crypt_data كبيرًا جدًا (32 كيلوبايت في هذا التطبيق من libcrypt؛ وأكثر من 128 كيلوبايت في بعض التطبيقات الأخرى). هذا كبير بما يكفي ليكون من غير الحكيم تخصيصه على المكدس.

بعض طرق التجزئة المصممة حديثًا تحتاج إلى ذاكرة مؤقتة أكبر، لكن واجهة crypt_r تجعل من المستحيل تغيير حجم struct crypt_data دون كسر التوافق الثنائي. يمكن لواجهة crypt_rn استيعاب تخصيصات أكبر لطرق تجزئة محددة، لكن المستدعي لـ crypt_rn ليس لديه طريقة لمعرفة مقدار الذاكرة المراد تخصيصها. يقوم crypt_ra بالتخصيص بنفسه، لكن يمكنه فقط إجراء استدعاء واحد لـ malloc(3).

السمات
لشرح المصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
 | سلامة الخيوط | غير آمن للمسارات المتعددة (MT-Unsafe) سباق:crypt
 | سلامة الخيوط | MT-Safe

التاريخ
ظهرت دالة crypt المعتمدة على الدوار في AT&T UNIX. ظهرت crypt التقليدية المعتمدة على DES لأول مرة في AT&T UNIX.

نشأت crypt_r من مكتبة GNU C. توجد أيضًا دالة crypt_r على HP-UX وMKS Toolkit، لكن النماذج الأولية والدلالات تختلف.

نشأت crypt_rn و crypt_ra من مشروع Openwall.

انظر أيضًا
crypt_gensalt(3) ، getpass(3) ، getpwent(3) ، shadow(3) ، login(1) ، passwd(1) ، crypt(5) ، passwd(5) ، shadow(5) ، pam(8)

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

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

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