الاسم¶

PKCS7_sign_ex, PKCS7_sign - إنشاء بنية PKCS#7 signedData

موجز¶

 #include <openssl/pkcs7.h>
 PKCS7 *PKCS7_sign_ex(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
                      BIO *data, int flags, OSSL_LIB_CTX *libctx,
                      const char *propq);
 PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
                   BIO *data, int flags);

الوصف¶

تنشئ الدالة PKCS7_sign_ex() بنية PKCS#7 signedData وتُعيدها. signcert هو الشهادة المستخدمة للتوقيع، وpkey هو المفتاح الخاص المقابل. certs هي مجموعة اختيارية من الشهادات الإضافية لإدراجها في بنية PKCS#7 (مثل أي شهادات CA وسيطة في السلسلة). يُستخدم سياق المكتبة libctx واستعلام الخاصية propq عند استرداد الخوارزميات من المزوّدين.

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

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

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

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

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

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

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

يتضمن هيكل signedData عدة PKCS#7 authenticatedAttributes بما في ذلك وقت التوقيع، ونوع محتوى PKCS#7 وقائمة التعميات المدعومة في سمة SMIMECapabilities. إذا ضُبط PKCS7_NOATTR فلن تُستخدم أي authenticatedAttributes. وإذا ضُبط PKCS7_NOSMIMECAP فستُحذف فقط SMIMECapabilities.

إذا وجدت سمة SMIMECapabilities، فإنها تشير إلى دعم الخوارزميات التالية: DES الثلاثي، وRC2 بـ 128 بت، وRC2 بـ 64 بت، وDES، وRC2 بـ 40 بت. إذا عُطّلت أي من هذه الخوارزميات فلن تُضمّن.

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

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

إذا ضُبِط علم PKCS7_STREAM، فإن هيكل PKCS7 المرتجع ليس مكتملاً، وإخراج محتوياته عبر دالة لا تنهي هيكل PKCS7 بشكل صحيح سيؤدي إلى نتائج غير متوقعة.

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

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

يمكن أن تكون المعاملات certs وsigncert وpkey كلها NULL إذا وُضع العلم PKCS7_PARTIAL. يمكن إضافة موقّع واحد أو أكثر باستخدام الدالة PKCS7_sign_add_signer(). يجب أيضًا استدعاء PKCS7_final() لإنهاء البنية إذا لم يكن البث مُفعّلاً. يمكن أيضًا تحديد ملخصات توقيع بديلة باستخدام هذه الطريقة.

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

في إصدارات OpenSSL قبل 1.0.0، يجب ألا تكون المعاملات signcert وpkey NULL.

تشبه PKCS7_sign() PKCS7_sign_ex() باستثناء أنها تستخدم قيمًا مبدئية NULL لسياق المكتبة libctx واستعلام الخاصية propq. يُحتفظ بهذا للتوافق العكسي لواجهة API.

العلل¶

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

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

تُرجع الدالتان PKCS7_sign_ex() و PKCS7_sign() إما بنية PKCS7 صالحة أو NULL إذا حدث خطأ. يمكن الحصول على الخطأ من ERR_get_error(3).

انظر أيضًا¶

ERR_get_error(3), PKCS7_verify(3)

التاريخ¶

أُضيفت الدالة PKCS7_sign_ex() في OpenSSL 3.0.

أُضيفت العلامة PKCS7_PARTIAL، وإمكانية أن تكون المعاملات certs و signcert و pkey NULL في OpenSSL 1.0.0.

أُضيف علم PKCS7_STREAM في OpenSSL 1.0.0.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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