الاسم¶

CMS_sign, CMS_sign_ex - إنشاء بنية CMS SignedData

موجز¶

 #include <openssl/cms.h>
 CMS_ContentInfo *CMS_sign_ex(X509 *signcert, EVP_PKEY *pkey,
                              STACK_OF(X509) *certs, BIO *data,
                              unsigned int flags, OSSL_LIB_CTX *ctx,
                              const char *propq);
 CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
                           BIO *data, unsigned int flags);

الوصف¶

CMS_sign_ex() تنشئ وتُعيد بنية CMS SignedData. signcert هي الشهادة المستخدمة للتوقيع، pkey هو المفتاح الخاص المقابل. certs هي مجموعة اختيارية إضافية من الشهادات لتضمينها في بنية CMS (مثل أي مراجع تصديق وسيطة في السلسلة). يُستخدم سياق المكتبة libctx واستعلام الخاصية propq عند استرجاع الخوارزميات من المزودين. يمكن أن تكون أي أو كل هذه المعاملات NULL، انظر NOTES أدناه.

تُقرأ البيانات المراد توقيعها من BIO data.

flags هي مجموعة اختيارية من الوسوم.

CMS_sign() مشابهة لـ CMS_sign_ex() لكنها تستخدم قيماً مبدئية NULL لسياق المكتبة libctx واستعلام الخاصية propq.

ملاحظات¶

يمكن تمرير أي من العلامات التالية (مجتمعة بعلامة OR) في معامل flags.

يتوقع العديد من عملاء S/MIME أن يتضمن المحتوى الموقع رؤوس MIME صالحة. إذا وُضعت علامة CMS_TEXT، تُسبق رؤوس MIME من النوع text/plain إلى البيانات.

إذا ضُبط CMS_NOCERTS فلن تُضمن شهادة الموقع في بنية CMS_ContentInfo، ومع ذلك يجب توفير شهادة الموقع في معامل signcert. يمكن لهذا تقليل حجم التوقيع إذا كان من الممكن الحصول على شهادة الموقع بوسائل أخرى: مثل رسالة موقعة سابقا.

تُضمن البيانات التي تُوقع في بنية CMS_ContentInfo، ما لم تُوضع CMS_DETACHED حيث تُحذف في هذه الحالة. يُستخدم هذا للتوقيعات المنفصلة CMS_ContentInfo المستخدمة في رسائل S/MIME النصية الموقعة على سبيل المثال.

عادةً يُترجم المحتوى المقدم إلى تنسيق MIME القانوني (كما هو مطلوب بمواصفات S/MIME) إذا وُضعت CMS_BINARY لا تحدث ترجمة. يجب استخدام هذا الخيار إذا كانت البيانات المقدمة بتنسيق ثنائي وإلا ستُفسد الترجمة البيانات.

يتضمن هيكل SignedData عدة CMS signedAttributes بما في ذلك وقت التوقيع، ونوع محتوى CMS وقائمة الشفرات المدعومة في سمة SMIMECapabilities. إذا ضُبط CMS_NOATTR فلن تُستخدم أي signedAttributes على الإطلاق. إذا ضُبط CMS_NOSMIMECAP فستُحذف SMIMECapabilities. إذا ضُبط CMS_NO_SIGNING_TIME فسيُحذف وقت التوقيع.

إذا وجدت سمة SMIMECapabilities، فإنها تشير إلى دعم الخوارزميات التالية حسب ترتيب الأفضلية: AES بـ 256 بت، وGost R3411-94، وGost 28147-89، وAES بـ 192 بت، وAES بـ 128 بت، وDES الثلاثي، وRC2 بـ 128 بت، وRC2 بـ 64 بت، وDES، وRC2 بـ 40 بت. إذا لم تتوفر أي من هذه الخوارزميات فلن تُضمّن: على سبيل المثال لن تُضمّن خوارزميات GOST إذا لم يُحمّل محرك GOST.

سيقوم OpenSSL مبدئيًا بتحديد شهادات التوقيع باستخدام اسم المصدر والرقم التسلسلي. إذا جرى ضبط CMS_USE_KEYID فسيستخدم قيمة معرف مفتاح الموضوع بدلاً من ذلك. سيحدث خطأ إذا كانت شهادة التوقيع لا تحتوي على امتداد معرف مفتاح الموضوع.

إذا وُضعت العلامات CMS_STREAM فإن بنية CMS_ContentInfo المعادة تُهيأ فقط لتكون جاهزة لتنفيذ عملية التوقيع. لكن التوقيع لا يُنفذ ولا تُقرأ البيانات المراد توقيعها من معامل data. يُؤجل التوقيع حتى بعد كتابة البيانات. بهذه الطريقة يمكن توقيع البيانات في تمريرة واحدة.

إذا وُضعت علامة CMS_PARTIAL تُخرج بنية CMS_ContentInfo جزئية يمكن إضافة موقعين وقدرات إضافية إليها قبل الإنهاء.

إذا ضُبطت الراية CMS_STREAM، فإن بنية CMS_ContentInfo المعادة ليست كاملة، وإخراج محتوياتها عبر دالة لا تنهي بنية CMS_ContentInfo بشكل صحيح سيعطي نتائج لا يمكن التنبؤ بها.

تقوم عدة دوال بما في ذلك SMIME_write_CMS() و i2d_CMS_bio_stream() و PEM_write_bio_CMS_stream() بإنهاء البنية. بدلاً من ذلك، يمكن إجراء الإنهاء بالحصول على تدفق ASN1 BIO مباشرة باستخدام BIO_new_CMS().

إذا حُدد موقع، فسيستخدم الملخص المبدئي لخوارزمية التوقيع. هذا الملخص هو SHA256 لكل من مفاتيح RSA و DSA.

إذا كان signcert و pkey NULL، تُخرج بنية CMS تحتوي على شهادات فقط.

الدالة CMS_sign() هي دالة توقيع CMS أساسية سيكون مخرجها مناسباً لأغراض عديدة. للتحكم الدقيق بتنسيق المخرج، يمكن أن تكون جميع معاملات certs و signcert و pkey NULL وتُوضع علامة CMS_PARTIAL. ثم يمكن إضافة موقع واحد أو أكثر باستخدام الدالة CMS_add1_signer()، ويمكن استخدام ملخصات غير مبدئية وإضافة سمات مخصصة. يجب بعد ذلك استدعاء CMS_final() لإنهاء البنية إذا لم يكن البث ممكناً.

العلل¶

بعض السمات مثل التوقيعات المضادة غير مدعومة.

القيم المُرجعة¶

CMS_sign_ex() و CMS_sign() تُعيدان إما بنية CMS_ContentInfo صالحة أو NULL إذا حدث خطأ. يمكن الحصول على الخطأ من ERR_get_error(3).

انظر أيضًا¶

ERR_get_error(3)، CMS_verify(3)

التاريخ¶

علامة CMS_STREAM مدعومة فقط للبيانات المنفصلة في OpenSSL 0.9.8، وهي مدعومة للبيانات المضمنة في OpenSSL 1.0.0 والإصدارات الأحدث.

أُضيفت طريقة CMS_sign_ex() في OpenSSL 3.0.

منذ OpenSSL 3.2، تتجاهل CMS_sign_ex() و CMS_sign() أي شهادات مكررة في وسيط certs الخاص بها ولم تعد تطرح خطأً لها.

حقوق النسخ¶

حقوق النشر 2008-2025 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“). لا يجوز لك استخدام هذا الملف إلا وفقًا لشروط الرخصة. يمكنك الحصول على نسخة منها في الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط <https://www.openssl.org/source/license.html>.

ترجمة¶

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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