D2I_RSAPRIVATEKEY(3ssl)

الاسم
d2i_DSAPrivateKey, d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp, d2i_DSAPublicKey, d2i_DSA_PUBKEY, d2i_DSA_PUBKEY_bio, d2i_DSA_PUBKEY_fp, d2i_DSAparams, d2i_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp, d2i_RSAPublicKey, d2i_RSAPublicKey_bio, d2i_RSAPublicKey_fp, d2i_RSA_PUBKEY, d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp, d2i_DHparams, d2i_DHparams_bio, d2i_DHparams_fp, d2i_ECParameters, d2i_ECPrivateKey, d2i_ECPrivateKey_bio, d2i_ECPrivateKey_fp, d2i_EC_PUBKEY, d2i_EC_PUBKEY_bio, d2i_EC_PUBKEY_fp, i2d_RSAPrivateKey, i2d_RSAPrivateKey_bio, i2d_RSAPrivateKey_fp, i2d_RSAPublicKey, i2d_RSAPublicKey_bio, i2d_RSAPublicKey_fp, i2d_RSA_PUBKEY, i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp, i2d_DHparams, i2d_DHparams_bio, i2d_DHparams_fp, i2d_DSAPrivateKey, i2d_DSAPrivateKey_bio, i2d_DSAPrivateKey_fp, i2d_DSAPublicKey, i2d_DSA_PUBKEY, i2d_DSA_PUBKEY_bio, i2d_DSA_PUBKEY_fp, i2d_DSAparams, i2d_ECParameters, i2d_ECPrivateKey, i2d_ECPrivateKey_bio, i2d_ECPrivateKey_fp, i2d_EC_PUBKEY, i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp - مُهجورة

موجز
الدوال التالية أصبحت مهجورة منذ OpenSSL 3.0، ويمكن إخفاؤها تماماً عن طريق تعريف OPENSSL_API_COMPAT بقيمة إصدار مناسبة، انظر openssl_user_macros(7):

 TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
 TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
 TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
 TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);

 int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
 int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
 int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
 int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
 int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
 int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
 int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
 int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
 int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
 int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
 int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
 int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
 int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
 int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
 int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
 int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
 int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
 int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
 int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
 int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
 int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
 int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
 int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
 int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);

الوصف
جميع الدوال الموصوفة هنا مُهجورة. يُرجى استخدام OSSL_DECODER(3) بدلاً من دوال d2i و OSSL_ENCODER(3) بدلاً من دوال i2d. انظر "الترحيل" أدناه.

في الوصف هنا، يُستخدم TYPE كعنصر نائب لأي من أنواع بيانات OpenSSL، مثل RSA. معامِلا الدالة ppin و ppout يُسميان عمومًا إما كلاهما pp في الرؤوس، أو in و out.

جميع الدوال هنا تتصرف بالطريقة الموصوفة في d2i_X509(3).

يُرجى ملاحظة أن ليس كل الدوال في الملخص متاحة لجميع أنواع المفاتيح. على سبيل المثال، لا توجد d2i_RSAparams() أو i2d_RSAparams()، لأن بنية RSA في PKCS#1 لا تتضمن أي معاملات مفتاح.

d2i_TYPEPrivateKey() ومشتقاتها تفك ترميز DER لبيانات المفتاح الخاص TYPE المنظمة في بنية خاصة بالنوع.

d2i_TYPEPublicKey() ومشتقاتها تفك ترميز DER لبيانات المفتاح العام TYPE المنظمة في بنية خاصة بالنوع.

d2i_TYPEparams() ومشتقاتها تفك ترميز DER لمعاملات مفتاح TYPE المنظمة في بنية خاصة بالنوع.

d2i_TYPE_PUBKEY() ومشتقاتها تفك ترميز DER لبيانات المفتاح العام TYPE المنظمة في بنية SubjectPublicKeyInfo.

i2d_TYPEPrivateKey() ومشتقاتها ترمّز بيانات المفتاح الخاص TYPE إلى بنية مشفرة بـ DER خاصة بالنوع.

i2d_TYPEPublicKey() ومشتقاتها ترمّز بيانات المفتاح العام TYPE إلى بنية مشفرة بـ DER خاصة بالنوع.

i2d_TYPEparams() ومشتقاتها ترمّز بيانات معاملات مفتاح TYPE إلى بنية مشفرة بـ DER خاصة بالنوع.

i2d_TYPE_PUBKEY() ومشتقاتها ترمّز بيانات المفتاح العام TYPE إلى بنية SubjectPublicKeyInfo مشفرة بـ DER.

على سبيل المثال، تتوقع الدالتان d2i_RSAPrivateKey() و d2i_RSAPublicKey() البنية المُعرَّفة بواسطة PKCS#1. وبالمثل، تُنتج الدالتان i2d_RSAPrivateKey() و i2d_RSAPublicKey() سلسلة محارف مُرمَّزة بصيغة DER مُرتَّبة وفقًا لـ PKCS#1.

  الترحيل
يتطلب الانتقال من TYPEs المُتنوعة استخدام أنواع OpenSSL الجديدة المُقابلة. بالنسبة لجميع TYPEs الموصوفة هنا، النوع الجديد المُقابل هو EVP_PKEY. يفترض باقي هذا القسم أن هذا قد أُنجز، وكيفية القيام بذلك بالضبط موصوفة في مكان آخر.

يوجد مساران للانتقال:

•   استبدل d2i_TYPEPrivateKey() بـ d2i_PrivateKey(3)، d2i_TYPEPublicKey() بـ d2i_PublicKey(3)، d2i_TYPEparams() بـ d2i_KeyParams(3)، d2i_TYPE_PUBKEY() بـ d2i_PUBKEY(3)، i2d_TYPEPrivateKey() بـ i2d_PrivateKey(3)، i2d_TYPEPublicKey() بـ i2d_PublicKey(3)، i2d_TYPEparams() بـ i2d_KeyParams(3)، i2d_TYPE_PUBKEY() بـ i2d_PUBKEY(3). تحذير هو أن i2d_PrivateKey(3) قد يُخرج بنية PKCS#8 مُعمّاة بـ DER كأبعد بنية بدلاً من البنية الخاصة بالنوع، وأن d2i_PrivateKey(3) يتعرف على بنى PKCS#8 ويفكّها.

•   استخدم OSSL_DECODER(3) و OSSL_ENCODER(3). كيفية الترحيل موصوفة أدناه. تفترض كل تلك الأوصاف أن المفتاح المراد تعميته موجود في المتغير pkey.

ترحيل دوال i2d إلى OSSL_ENCODER

المخرج الدقيق لـ OSSL_ENCODER(3) يُحدد بالوسائط بدلاً من أسماء الدوال. الكود النموذجي للحصول على مخرج مُعمّى بـ DER في بنية خاصة بالنوع موحد، والأشياء الوحيدة التي تختلف هي اختيار أي جزء من EVP_PKEY يجب إخراجه، والبنية. لذلك يمكن ترجمة أسماء دوال i2d إلى متغيرين، selection و structure كالتالي:

i2d_TYPEPrivateKey() يُترجم إلى:
     int selection = EVP_PKEY_KEYPAIR;
     const char *structure = "type-specific";

i2d_TYPEPublicKey() يُترجم إلى:
     int selection = EVP_PKEY_PUBLIC_KEY;
     const char *structure = "type-specific";

i2d_TYPEparams() يُترجم إلى:
     int selection = EVP_PKEY_PARAMETERS;
     const char *structure = "type-specific";

i2d_TYPE_PUBKEY() يُترجم إلى:
     int selection = EVP_PKEY_PUBLIC_KEY;
     const char *structure = "SubjectPublicKeyInfo";

الكود النموذجي التالي يقوم ببقية العمل:

 unsigned char *p = buffer;     /* |buffer| is supplied by the caller */
 size_t len = buffer_size;      /* assumed be the size of |buffer| */
 OSSL_ENCODER_CTX *ctx =
     OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
                                   NULL, NULL);
 if (ctx == NULL) {
     /* fatal error handling */
 }
 if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
     OSSL_ENCODER_CTX_free(ctx);
     /* non-fatal error handling */
 }
 if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
     OSSL_ENCODER_CTX_free(ctx);
     /* error handling */
 }
 OSSL_ENCODER_CTX_free(ctx);

ملاحظات
الحرفان i و d في i2d_TYPE() يرمزان إلى "internal" (أي هيكل C داخلي) و "DER" على التوالي. لذا تقوم i2d_TYPE() بالتحويل من الداخلي إلى DER.

يمكن للدوال أيضًا فهم صيغ BER.

يجب أن يكون هيكل TYPE الفعلي الممرر إلى i2d_TYPE() هيكل TYPE صالحًا ومملوءًا -- لا يمكن ببساطة تزويده بهيكل فارغ مثل الذي يعيده TYPE_new().

البيانات المشفرة بصيغة ثنائية وقد تحتوي على أصفار مدمجة. لذلك، يجب فتح أي مؤشرات ملفات (FILE pointers) أو BIOs في الوضع الثنائي. لن تعيد الدوال مثل strlen() الطول الصحيح للهيكل المشفر.

طرق زيادة *ppin و *ppout بعد العملية يمكن أن تصطاد غير الحذر. انظر قسم WARNINGS في d2i_X509(3) لبعض الأخطاء الشائعة. سبب سلوك الزيادة الآلية هذا هو عكس استخدام نموذجي لدوال ASN1: بعد تعمية أو فك بنية واحدة، ستُعالج أخرى بعدها.

قد تكون النقاط التالية حول أنواع البيانات مفيدة:

DSA_PUBKEY
    تمثل مفتاح DSA عام باستخدام هيكل SubjectPublicKeyInfo.

DSAPublicKey، DSAPrivateKey
    استخدم تنسيق OpenSSL غير قياسي ويجب تجنبه؛ استخدم DSA_PUBKEY، PEM_write_PrivateKey(3)، أو ما شابه بدلاً من ذلك.

القيم المُرجعة
d2i_TYPE()، و d2i_TYPE_bio()، و d2i_TYPE_fp() تعيد بنية TYPE صالحة أو NULL في حال حدوث خطأ. إذا استُخدمت قدرة "إعادة الاستخدام" مع تمرير بنية صالحة عبر a، فسيُحرر الكائن في حال حدوث خطأ ويُضبط *a إلى NULL.

i2d_TYPE() تعيد عدد البايتات التي رُمزت بنجاح أو قيمة سالبة في حال حدوث خطأ.

i2d_TYPE_bio() و i2d_TYPE_fp() يُرجعان 1 للنجاح و0 إذا حدث خطأ.

انظر أيضًا
OSSL_ENCODER(3)، OSSL_DECODER(3)، d2i_PrivateKey(3)، d2i_PublicKey(3)، d2i_KeyParams(3)، d2i_PUBKEY(3)، i2d_PrivateKey(3)، i2d_PublicKey(3)، i2d_KeyParams(3)، i2d_PUBKEY(3)

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

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

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

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

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