D2I_X509(3ssl)

الاسم
d2i_ACCESS_DESCRIPTION, d2i_ADMISSIONS, d2i_ADMISSION_SYNTAX, d2i_ASIdOrRange, d2i_ASIdentifierChoice, d2i_ASIdentifiers, d2i_ASN1_BIT_STRING, d2i_ASN1_BMPSTRING, d2i_ASN1_ENUMERATED, d2i_ASN1_GENERALIZEDTIME, d2i_ASN1_GENERALSTRING, d2i_ASN1_IA5STRING, d2i_ASN1_INTEGER, d2i_ASN1_NULL, d2i_ASN1_OBJECT, d2i_ASN1_OCTET_STRING, d2i_ASN1_PRINTABLE, d2i_ASN1_PRINTABLESTRING, d2i_ASN1_SEQUENCE_ANY, d2i_ASN1_SET_ANY, d2i_ASN1_T61STRING, d2i_ASN1_TIME, d2i_ASN1_TYPE, d2i_ASN1_UINTEGER, d2i_ASN1_UNIVERSALSTRING, d2i_ASN1_UTCTIME, d2i_ASN1_UTF8STRING, d2i_ASN1_VISIBLESTRING, d2i_ASRange, d2i_AUTHORITY_INFO_ACCESS, d2i_AUTHORITY_KEYID, d2i_BASIC_CONSTRAINTS, d2i_CERTIFICATEPOLICIES, d2i_CMS_ContentInfo, d2i_CMS_ReceiptRequest, d2i_CMS_bio, d2i_CRL_DIST_POINTS, d2i_DHxparams, d2i_DIRECTORYSTRING, d2i_DISPLAYTEXT, d2i_DIST_POINT, d2i_DIST_POINT_NAME, d2i_DSA_SIG, d2i_ECDSA_SIG, d2i_ECPKParameters, d2i_EDIPARTYNAME, d2i_ESS_CERT_ID, d2i_ESS_CERT_ID_V2, d2i_ESS_ISSUER_SERIAL, d2i_ESS_SIGNING_CERT, d2i_ESS_SIGNING_CERT_V2, d2i_EXTENDED_KEY_USAGE, d2i_GENERAL_NAME, d2i_GENERAL_NAMES, d2i_IPAddressChoice, d2i_IPAddressFamily, d2i_IPAddressOrRange, d2i_IPAddressRange, d2i_ISSUER_SIGN_TOOL, d2i_ISSUING_DIST_POINT, d2i_NAMING_AUTHORITY, d2i_NETSCAPE_CERT_SEQUENCE, d2i_NETSCAPE_SPKAC, d2i_NETSCAPE_SPKI, d2i_NOTICEREF, d2i_OCSP_BASICRESP, d2i_OCSP_CERTID, d2i_OCSP_CERTSTATUS, d2i_OCSP_CRLID, d2i_OCSP_ONEREQ, d2i_OCSP_REQINFO, d2i_OCSP_REQUEST, d2i_OCSP_RESPBYTES, d2i_OCSP_RESPDATA, d2i_OCSP_RESPID, d2i_OCSP_RESPONSE, d2i_OCSP_REVOKEDINFO, d2i_OCSP_SERVICELOC, d2i_OCSP_SIGNATURE, d2i_OCSP_SINGLERESP, d2i_OSSL_AA_DIST_POINT, d2i_OSSL_ALLOWED_ATTRIBUTES_CHOICE, d2i_OSSL_ALLOWED_ATTRIBUTES_ITEM, d2i_OSSL_ALLOWED_ATTRIBUTES_SYNTAX, d2i_OSSL_ATAV, d2i_OSSL_ATTRIBUTE_DESCRIPTOR, d2i_OSSL_ATTRIBUTE_MAPPING, d2i_OSSL_ATTRIBUTE_MAPPINGS, d2i_OSSL_ATTRIBUTE_TYPE_MAPPING, d2i_OSSL_ATTRIBUTE_VALUE_MAPPING, d2i_OSSL_ATTRIBUTES_SYNTAX, d2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX, d2i_OSSL_BASIC_ATTR_CONSTRAINTS, d2i_OSSL_CMP_ATAVS, d2i_OSSL_CMP_MSG, d2i_OSSL_CMP_PKIHEADER, d2i_OSSL_CMP_PKISI, d2i_OSSL_CRMF_CERTID, d2i_OSSL_CRMF_CERTTEMPLATE, d2i_OSSL_CRMF_ENCRYPTEDKEY, d2i_OSSL_CRMF_ENCRYPTEDVALUE, d2i_OSSL_CRMF_MSG, d2i_OSSL_CRMF_MSGS, d2i_OSSL_CRMF_PBMPARAMETER, d2i_OSSL_CRMF_PKIPUBLICATIONINFO, d2i_OSSL_CRMF_SINGLEPUBINFO, d2i_OSSL_DAY_TIME, d2i_OSSL_DAY_TIME_BAND, d2i_OSSL_HASH, d2i_OSSL_IETF_ATTR_SYNTAX, d2i_OSSL_INFO_SYNTAX, d2i_OSSL_INFO_SYNTAX_POINTER, d2i_OSSL_ISSUER_SERIAL, d2i_OSSL_NAMED_DAY, d2i_OSSL_OBJECT_DIGEST_INFO, d2i_OSSL_PRIVILEGE_POLICY_ID, d2i_OSSL_ROLE_SPEC_CERT_ID, d2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX, d2i_OSSL_TARGET_CERT, d2i_OSSL_TARGET, d2i_OSSL_TARGETING_INFORMATION, d2i_OSSL_TARGETS, d2i_OSSL_TIME_PERIOD, d2i_OSSL_TIME_SPEC, d2i_OSSL_TIME_SPEC_ABSOLUTE, d2i_OSSL_TIME_SPEC_DAY, d2i_OSSL_TIME_SPEC_MONTH, d2i_OSSL_TIME_SPEC_TIME, d2i_OSSL_TIME_SPEC_WEEKS, d2i_OSSL_TIME_SPEC_X_DAY_OF, d2i_OSSL_USER_NOTICE_SYNTAX, d2i_OTHERNAME, d2i_PBE2PARAM, d2i_PBEPARAM, d2i_PBKDF2PARAM, d2i_PBMAC1PARAM, d2i_PKCS12, d2i_PKCS12_BAGS, d2i_PKCS12_MAC_DATA, d2i_PKCS12_SAFEBAG, d2i_PKCS12_bio, d2i_PKCS12_fp, d2i_PKCS7, d2i_PKCS7_DIGEST, d2i_PKCS7_ENCRYPT, d2i_PKCS7_ENC_CONTENT, d2i_PKCS7_ENVELOPE, d2i_PKCS7_ISSUER_AND_SERIAL, d2i_PKCS7_RECIP_INFO, d2i_PKCS7_SIGNED, d2i_PKCS7_SIGNER_INFO, d2i_PKCS7_SIGN_ENVELOPE, d2i_PKCS7_bio, d2i_PKCS7_fp, d2i_PKCS8_PRIV_KEY_INFO, d2i_PKCS8_PRIV_KEY_INFO_bio, d2i_PKCS8_PRIV_KEY_INFO_fp, d2i_PKCS8_bio, d2i_PKCS8_fp, d2i_PKEY_USAGE_PERIOD, d2i_POLICYINFO, d2i_POLICYQUALINFO, d2i_PROFESSION_INFO, d2i_PROXY_CERT_INFO_EXTENSION, d2i_PROXY_POLICY, d2i_RSA_OAEP_PARAMS, d2i_RSA_PSS_PARAMS, d2i_SCRYPT_PARAMS, d2i_SCT_LIST, d2i_SXNET, d2i_SXNETID, d2i_TS_ACCURACY, d2i_TS_MSG_IMPRINT, d2i_TS_MSG_IMPRINT_bio, d2i_TS_MSG_IMPRINT_fp, d2i_TS_REQ, d2i_TS_REQ_bio, d2i_TS_REQ_fp, d2i_TS_RESP, d2i_TS_RESP_bio, d2i_TS_RESP_fp, d2i_TS_STATUS_INFO, d2i_TS_TST_INFO, d2i_TS_TST_INFO_bio, d2i_TS_TST_INFO_fp, d2i_USERNOTICE, d2i_X509, d2i_X509_bio, d2i_X509_fp, d2i_X509_ACERT, d2i_X509_ACERT_bio, d2i_X509_ACERT_fp, d2i_X509_ALGOR, d2i_X509_ALGORS, d2i_X509_ATTRIBUTE, d2i_X509_CERT_AUX, d2i_X509_CINF, d2i_X509_CRL, d2i_X509_CRL_INFO, d2i_X509_CRL_bio, d2i_X509_CRL_fp, d2i_X509_EXTENSION, d2i_X509_EXTENSIONS, d2i_X509_NAME, d2i_X509_NAME_ENTRY, d2i_X509_PUBKEY, d2i_X509_PUBKEY_bio, d2i_X509_PUBKEY_fp, d2i_X509_REQ, d2i_X509_REQ_INFO, d2i_X509_REQ_bio, d2i_X509_REQ_fp, d2i_X509_REVOKED, d2i_X509_SIG, d2i_X509_VAL, i2d_ACCESS_DESCRIPTION, i2d_ADMISSIONS, i2d_ADMISSION_SYNTAX, i2d_ASIdOrRange, i2d_ASIdentifierChoice, i2d_ASIdentifiers, i2d_ASN1_BIT_STRING, i2d_ASN1_BMPSTRING, i2d_ASN1_ENUMERATED, i2d_ASN1_GENERALIZEDTIME, i2d_ASN1_GENERALSTRING, i2d_ASN1_IA5STRING, i2d_ASN1_INTEGER, i2d_ASN1_NULL, i2d_ASN1_OBJECT, i2d_ASN1_OCTET_STRING, i2d_ASN1_PRINTABLE, i2d_ASN1_PRINTABLESTRING, i2d_ASN1_SEQUENCE_ANY, i2d_ASN1_SET_ANY, i2d_ASN1_T61STRING, i2d_ASN1_TIME, i2d_ASN1_TYPE, i2d_ASN1_UNIVERSALSTRING, i2d_ASN1_UTCTIME, i2d_ASN1_UTF8STRING, i2d_ASN1_VISIBLESTRING, i2d_ASN1_bio_stream, i2d_ASRange, i2d_AUTHORITY_INFO_ACCESS, i2d_AUTHORITY_KEYID, i2d_BASIC_CONSTRAINTS, i2d_CERTIFICATEPOLICIES, i2d_CMS_ContentInfo, i2d_CMS_ReceiptRequest, i2d_CMS_bio, i2d_CRL_DIST_POINTS, i2d_DHxparams, i2d_DIRECTORYSTRING, i2d_DISPLAYTEXT, i2d_DIST_POINT, i2d_DIST_POINT_NAME, i2d_DSA_SIG, i2d_ECDSA_SIG, i2d_ECPKParameters, i2d_EDIPARTYNAME, i2d_ESS_CERT_ID, i2d_ESS_CERT_ID_V2, i2d_ESS_ISSUER_SERIAL, i2d_ESS_SIGNING_CERT, i2d_ESS_SIGNING_CERT_V2, i2d_EXTENDED_KEY_USAGE, i2d_GENERAL_NAME, i2d_GENERAL_NAMES, i2d_IPAddressChoice, i2d_IPAddressFamily, i2d_IPAddressOrRange, i2d_IPAddressRange, i2d_ISSUER_SIGN_TOOL, i2d_ISSUING_DIST_POINT, i2d_NAMING_AUTHORITY, i2d_NETSCAPE_CERT_SEQUENCE, i2d_NETSCAPE_SPKAC, i2d_NETSCAPE_SPKI, i2d_NOTICEREF, i2d_OCSP_BASICRESP, i2d_OCSP_CERTID, i2d_OCSP_CERTSTATUS, i2d_OCSP_CRLID, i2d_OCSP_ONEREQ, i2d_OCSP_REQINFO, i2d_OCSP_REQUEST, i2d_OCSP_RESPBYTES, i2d_OCSP_RESPDATA, i2d_OCSP_RESPID, i2d_OCSP_RESPONSE, i2d_OCSP_REVOKEDINFO, i2d_OCSP_SERVICELOC, i2d_OCSP_SIGNATURE, i2d_OCSP_SINGLERESP, i2d_OSSL_AA_DIST_POINT, i2d_OSSL_ALLOWED_ATTRIBUTES_CHOICE, i2d_OSSL_ALLOWED_ATTRIBUTES_ITEM, i2d_OSSL_ALLOWED_ATTRIBUTES_SYNTAX, i2d_OSSL_ATAV, i2d_OSSL_ATTRIBUTE_DESCRIPTOR, i2d_OSSL_ATTRIBUTE_MAPPING, i2d_OSSL_ATTRIBUTE_MAPPINGS, i2d_OSSL_ATTRIBUTE_TYPE_MAPPING, i2d_OSSL_ATTRIBUTE_VALUE_MAPPING, i2d_OSSL_ATTRIBUTES_SYNTAX, i2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX, i2d_OSSL_BASIC_ATTR_CONSTRAINTS, i2d_OSSL_CMP_ATAVS, i2d_OSSL_CMP_MSG, i2d_OSSL_CMP_PKIHEADER, i2d_OSSL_CMP_PKISI, i2d_OSSL_CRMF_CERTID, i2d_OSSL_CRMF_CERTTEMPLATE, i2d_OSSL_CRMF_ENCRYPTEDKEY, i2d_OSSL_CRMF_ENCRYPTEDVALUE, i2d_OSSL_CRMF_MSG, i2d_OSSL_CRMF_MSGS, i2d_OSSL_CRMF_PBMPARAMETER, i2d_OSSL_CRMF_PKIPUBLICATIONINFO, i2d_OSSL_CRMF_SINGLEPUBINFO, i2d_OSSL_HASH, i2d_OSSL_DAY_TIME, i2d_OSSL_DAY_TIME_BAND, i2d_OSSL_IETF_ATTR_SYNTAX, i2d_OSSL_INFO_SYNTAX, i2d_OSSL_INFO_SYNTAX_POINTER, i2d_OSSL_ISSUER_SERIAL, i2d_OSSL_NAMED_DAY, i2d_OSSL_OBJECT_DIGEST_INFO, i2d_OSSL_PRIVILEGE_POLICY_ID, i2d_OSSL_ROLE_SPEC_CERT_ID, i2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX, i2d_OSSL_TARGET_CERT, i2d_OSSL_TARGET, i2d_OSSL_TARGETING_INFORMATION, i2d_OSSL_TARGETS, i2d_OSSL_TIME_PERIOD, i2d_OSSL_TIME_SPEC, i2d_OSSL_TIME_SPEC_ABSOLUTE, i2d_OSSL_TIME_SPEC_DAY, i2d_OSSL_TIME_SPEC_MONTH, i2d_OSSL_TIME_SPEC_TIME, i2d_OSSL_TIME_SPEC_WEEKS, i2d_OSSL_TIME_SPEC_X_DAY_OF, i2d_OSSL_USER_NOTICE_SYNTAX, i2d_OTHERNAME, i2d_PBE2PARAM, i2d_PBEPARAM, i2d_PBKDF2PARAM, i2d_PBMAC1PARAM, i2d_PKCS12, i2d_PKCS12_BAGS, i2d_PKCS12_MAC_DATA, i2d_PKCS12_SAFEBAG, i2d_PKCS12_bio, i2d_PKCS12_fp, i2d_PKCS7, i2d_PKCS7_DIGEST, i2d_PKCS7_ENCRYPT, i2d_PKCS7_ENC_CONTENT, i2d_PKCS7_ENVELOPE, i2d_PKCS7_ISSUER_AND_SERIAL, i2d_PKCS7_NDEF, i2d_PKCS7_RECIP_INFO, i2d_PKCS7_SIGNED, i2d_PKCS7_SIGNER_INFO, i2d_PKCS7_SIGN_ENVELOPE, i2d_PKCS7_bio, i2d_PKCS7_fp, i2d_PKCS8PrivateKeyInfo_bio, i2d_PKCS8PrivateKeyInfo_fp, i2d_PKCS8_PRIV_KEY_INFO, i2d_PKCS8_PRIV_KEY_INFO_bio, i2d_PKCS8_PRIV_KEY_INFO_fp, i2d_PKCS8_bio, i2d_PKCS8_fp, i2d_PKEY_USAGE_PERIOD, i2d_POLICYINFO, i2d_POLICYQUALINFO, i2d_PROFESSION_INFO, i2d_PROXY_CERT_INFO_EXTENSION, i2d_PROXY_POLICY, i2d_RSA_OAEP_PARAMS, i2d_RSA_PSS_PARAMS, i2d_SCRYPT_PARAMS, i2d_SCT_LIST, i2d_SXNET, i2d_SXNETID, i2d_TS_ACCURACY, i2d_TS_MSG_IMPRINT, i2d_TS_MSG_IMPRINT_bio, i2d_TS_MSG_IMPRINT_fp, i2d_TS_REQ, i2d_TS_REQ_bio, i2d_TS_REQ_fp, i2d_TS_RESP, i2d_TS_RESP_bio, i2d_TS_RESP_fp, i2d_TS_STATUS_INFO, i2d_TS_TST_INFO, i2d_TS_TST_INFO_bio, i2d_TS_TST_INFO_fp, i2d_USERNOTICE, i2d_X509, i2d_X509_bio, i2d_X509_fp, i2d_X509_ACERT, i2d_X509_ACERT_bio, i2d_X509_ACERT_fp, i2d_X509_ALGOR, i2d_X509_ALGORS, i2d_X509_ATTRIBUTE, i2d_X509_CERT_AUX, i2d_X509_CINF, i2d_X509_CRL, i2d_X509_CRL_INFO, i2d_X509_CRL_bio, i2d_X509_CRL_fp, i2d_X509_EXTENSION, i2d_X509_EXTENSIONS, i2d_X509_NAME, i2d_X509_NAME_ENTRY, i2d_X509_PUBKEY, i2d_X509_PUBKEY_bio, i2d_X509_PUBKEY_fp, i2d_X509_REQ, i2d_X509_REQ_INFO, i2d_X509_REQ_bio, i2d_X509_REQ_fp, i2d_X509_REVOKED, i2d_X509_SIG, i2d_X509_VAL, - convert objects from/to ASN.1/DER representation

موجز
 TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length);
 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);

 int i2d_TYPE(const TYPE *a, unsigned char **ppout);
 int i2d_TYPE(TYPE *a, unsigned char **ppout);
 int i2d_TYPE_fp(FILE *fp, const TYPE *a);
 int i2d_TYPE_fp(FILE *fp, TYPE *a);
 int i2d_TYPE_bio(BIO *bp, const TYPE *a);
 int i2d_TYPE_bio(BIO *bp, TYPE *a);

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

تحول هذه الدوال كائنات OpenSSL من وإلى ترميز ASN.1/DER الخاص بها. على عكس هياكل C التي يمكن أن تحتوي على مؤشرات لكائنات فرعية داخلها، فإن DER هو ترميز متسلسل، مناسب للإرسال عبر الشبكة، والكتابة إلى ملف، وما إلى ذلك.

تحاول d2i_TYPE() فك تشفير len بايت عند *ppin. إذا نجحت، يُعاد مؤشر إلى هيكل TYPE ويُزاد *ppin إلى البايت التالي للبيانات المحللة. إذا كان a ليس NULL، فسيُكتب مؤشر إلى الهيكل المُعاد أيضًا إلى *a. إذا حدث خطأ، يُعاد NULL. يحتفظ المستدعي بملكية الكائن المُعاد ويحتاج إلى تحريره عندما لا يعود بحاجة إليه، مثل استخدام X509_free() لكائنات X509 أو DSA_SIG_free() لكائنات DSA_SIG.

عند الإرجاع الناجح، إذا كان *a ليس NULL، فسيُفترض أن *a يحتوي على هيكل TYPE صالح وتُبذل محاولة لإعادة استخدامه. بالنسبة لهياكل TYPE حيث يكون ذلك مهمًا، من الممكن إعداد سياق مكتبة على الهيكل المُفكك بهذه الطريقة (انظر قسم EXAMPLES). ومع ذلك، فإن استخدام قدرة "إعادة الاستخدام" لأغراض أخرى هو غير موصى به بشدة (انظر BUGS أدناه، والنقاش في قسم RETURN VALUES).

d2i_TYPE_bio() مشابهة لـ d2i_TYPE() باستثناء أنها تحاول تحليل البيانات من BIO bp.

d2i_TYPE_fp() مشابهة لـ d2i_TYPE() باستثناء أنها تحاول تحليل البيانات من مؤشر FILE fp.

تقوم i2d_TYPE() بترميز الهيكل المشار إليه بواسطة a إلى تنسيق DER. إذا كان ppout ليس NULL، فتكتب البيانات المُرمزة بـ DER إلى المخزن المؤقت عند *ppout، وتُزيده للإشارة إلى ما بعد البيانات التي كُتبت للتو. إذا كانت قيمة الإرجاع سالبة، فقد حدث خطأ، وإلا فإنها تُرجع طول البيانات المُرمزة.

إذا كان *ppout هو NULL، فسيُخصص ذاكرة لمخزن مؤقت وتُكتب البيانات المُرمزة إليه. في هذه الحالة، لا يُزاد *ppout ويشير إلى بداية البيانات التي كُتبت للتو.

i2d_TYPE_bio() مشابهة لـ i2d_TYPE() باستثناء أنها تكتب ترميز الهيكل a إلى BIO bp وتُعيد 1 للنجاح و0 للفشل.

i2d_TYPE_fp() مشابهة لـ i2d_TYPE() باستثناء أنها تكتب ترميز الهيكل a إلى مؤشر FILE fp وتُعيد 1 للنجاح و0 للفشل.

لا تقوم هذه الإجراءات بتعمية المفاتيح الخاصة وبالتالي لا توفر أي أمان؛ استخدم PEM_write_PrivateKey(3) أو ما شابه ذلك للكتابة إلى الملفات.

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

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

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

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

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

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

ASN1_OBJECT
    يمثل مُعرِّف كائن ASN1.

DHparams
    يمثل هيكل معاملات DH وفقًا لـ PKCS#3.

DHxparams
    يمثل هيكل معاملات DH وفقًا لـ ANSI X9.42.

ECDSA_SIG
    يمثل توقيع ECDSA.

X509_ALGOR
    يمثل هيكل AlgorithmIdentifier المستخدم في IETF RFC 6960 وفي أماكن أخرى.

X509_NAME
    يمثل نوع Name المستخدم لأسماء الموضوع والمُصدِر في IETF RFC 6960 وفي أماكن أخرى.

X509_REQ
    يمثل طلب شهادة وفقًا لـ PKCS#10.

X509_SIG
    يمثل هيكل DigestInfo المُعرَّف في PKCS#1 وPKCS#7.

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

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

تُرجع i2d_TYPE_bio() و i2d_TYPE_fp()، بالإضافة إلى i2d_ASN1_bio_stream()، القيمة 1 عند النجاح و0 إذا حدث خطأ.

عند حدوث خطأ، قد تُسجِّل هذه الدوال الخطأ في طابور أخطاء OpenSSL. يمكن فحص طابور الأخطاء هذا باستخدام عائلة دوال ERR، مثل ERR_print_errors(3) و ERR_peek_last_error_all(3).

أمثلة
تخصيص وترميز ترميز DER لبنية X509:

 int len;
 unsigned char *buf;

 buf = NULL;
 len = i2d_X509(x, &buf);
 if (len < 0)
     /* error */

محاولة فك ترميز خبيئة:

 X509 *x;
 unsigned char *buf;
 const unsigned char *p;
 int len;

 /* Set up buf and len to point to the input buffer. */
 p = buf;
 x = d2i_X509(NULL, &p, len);
 if (x == NULL)
     /* error */

تقنية بديلة:

 X509 *x;
 unsigned char *buf;
 const unsigned char *p;
 int len;

 /* Set up buf and len to point to the input buffer. */
 p = buf;
 x = NULL;

 if (d2i_X509(&x, &p, len) == NULL)
     /* error */

إعداد سياق مكتبة واستعلام خاصية:

 X509 *x;
 unsigned char *buf;
 const unsigned char *p;
 int len;
 OSSL_LIB_CTX *libctx = ....;
 const char *propq = ....;

 /* Set up buf and len to point to the input buffer. */
 p = buf;
 x = X509_new_ex(libctx, propq);

 if (d2i_X509(&x, &p, len) == NULL)
     /* error, x was freed and NULL assigned to it (see RETURN VALUES) */

تحذيرات
استخدام متغير مؤقت إلزامي. خطأ شائع هو محاولة استخدام خبيئة مباشرة كما يلي:

 int len;
 unsigned char *buf;

 len = i2d_X509(x, NULL);
 buf = OPENSSL_malloc(len);
 ...
 i2d_X509(x, &buf);
 ...
 OPENSSL_free(buf);

سيؤدي هذا الكود إلى أن يحتوي buf ظاهريًا على بيانات غير صالحة لأنه زِيد بعد الاستدعاء للإشارة إلى ما بعد البيانات المكتوبة للتو. أيضًا لن يحتوي buf بعد الآن على المؤشر المخصص بواسطة OPENSSL_malloc() ومن المحتمل أن يتعطل الاستدعاء اللاحق لـ OPENSSL_free().

فخ آخر يجب تجنبه هو إساءة استخدام الوسيط a لـ d2i_TYPE():

 X509 *x;

 if (d2i_X509(&x, &p, len) == NULL)
     /* error */

سيؤدي هذا على الأرجح إلى تعطل في مكان ما داخل d2i_X509(). السبب في ذلك هو أن المتغير x غير مهيأ وستُبذل محاولة لتفسير قيمته (غير الصالحة) كبنية X509، مما يسبب عادةً انتهاكًا للتجزئة. إذا ضُبط x على NULL أولاً فلن يحدث هذا.

العلل
في بعض إصدارات OpenSSL، سلوك "إعادة الاستخدام" لـ d2i_TYPE() عندما يكون *a صالحًا معطل وقد تبقى بعض أجزاء البنية المعاد استخدامها إذا لم تكن موجودة في البنية الجديدة. بالإضافة إلى ذلك، في إصدارات OpenSSL قبل 1.1.0، عند استخدام سلوك "إعادة الاستخدام" وحدوث خطأ، يكون السلوك غير متناسق. تصرفت بعض الدوال كما هو موصوف هنا، بينما لم تحرر بعضها *a عند الخطأ ولم تضبط *a على NULL.

نتيجة للمشكلات المذكورة أعلاه، يُثبط بشدة سلوك "إعادة الاستخدام".

لن تُرجع i2d_TYPE() خطأ في العديد من إصدارات OpenSSL، إذا لم تُهيأ الحقول الإلزامية بسبب خطأ برمجي فقد تحتوي البنية المشفرة على بيانات غير صالحة أو تحذف الحقول بالكامل ولن تُحلل بواسطة d2i_TYPE(). قد يُصلح هذا في المستقبل لذا لا ينبغي للكود أن يفترض أن i2d_TYPE() ستنجح دائمًا.

أي دالة ترمِّز بنية (i2d_TYPE()، i2d_TYPE_bio() أو i2d_TYPE_fp()) قد تُرجع ترميزًا قديمًا إذا عُدلت البنية بعد إلغاء التسلسل أو التسلسل السابق. هذا لأن بعض الكائنات تخبئ الترميز لأسباب تتعلق بالكفاءة.

انظر أيضًا
ERR_print_errors(3), ERR_peek_last_error_all(3)

التاريخ
أُضيفت d2i_OSSL_ATTRIBUTES_SYNTAX(), d2i_OSSL_BASIC_ATTR_CONSTRAINTS(), d2i_OSSL_CMP_ATAVS(), d2i_OSSL_IETF_ATTR_SYNTAX(), d2i_OSSL_TARGET(), d2i_OSSL_TARGETING_INFORMATION(), d2i_OSSL_TARGETS(), d2i_OSSL_USER_NOTICE_SYNTAX(), d2i_PBMAC1PARAM(), d2i_X509_ACERT(), d2i_X509_ACERT_bio(), d2i_X509_ACERT_fp(), i2d_OSSL_ATTRIBUTES_SYNTAX(), i2d_OSSL_BASIC_ATTR_CONSTRAINTS(), i2d_OSSL_CMP_ATAVS(), i2d_OSSL_IETF_ATTR_SYNTAX(), i2d_OSSL_TARGET(), i2d_OSSL_TARGETING_INFORMATION(), i2d_OSSL_TARGETS(), i2d_OSSL_USER_NOTICE_SYNTAX(), i2d_PBMAC1PARAM(), i2d_X509_ACERT(), i2d_X509_ACERT_bio(), i2d_X509_ACERT_fp() في OpenSSL 3.4.

أُضيفت d2i_OSSL_AA_DIST_POINT(), d2i_OSSL_ALLOWED_ATTRIBUTES_CHOICE(), d2i_OSSL_ALLOWED_ATTRIBUTES_ITEM(), d2i_OSSL_ALLOWED_ATTRIBUTES_SYNTAX(), d2i_OSSL_ATAV(), d2i_OSSL_ATTRIBUTE_DESCRIPTOR(), d2i_OSSL_ATTRIBUTE_MAPPING(), d2i_OSSL_ATTRIBUTE_MAPPINGS(), d2i_OSSL_ATTRIBUTE_TYPE_MAPPING(), d2i_OSSL_ATTRIBUTE_VALUE_MAPPING(), d2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), d2i_OSSL_HASH(), d2i_OSSL_INFO_SYNTAX(), d2i_OSSL_INFO_SYNTAX_POINTER(), d2i_OSSL_PRIVILEGE_POLICY_ID(), d2i_OSSL_ROLE_SPEC_CERT_ID(), d2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), i2d_OSSL_AA_DIST_POINT(), i2d_OSSL_ALLOWED_ATTRIBUTES_CHOICE(), i2d_OSSL_ALLOWED_ATTRIBUTES_ITEM(), i2d_OSSL_ALLOWED_ATTRIBUTES_SYNTAX(), i2d_OSSL_ATAV(), i2d_OSSL_ATTRIBUTE_DESCRIPTOR(), i2d_OSSL_ATTRIBUTE_MAPPING(), i2d_OSSL_ATTRIBUTE_MAPPINGS(), i2d_OSSL_ATTRIBUTE_TYPE_MAPPING(), i2d_OSSL_ATTRIBUTE_VALUE_MAPPING(), i2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX(), i2d_OSSL_HASH(), i2d_OSSL_INFO_SYNTAX(), i2d_OSSL_INFO_SYNTAX_POINTER(), i2d_OSSL_PRIVILEGE_POLICY_ID(), i2d_OSSL_ROLE_SPEC_CERT_ID(), i2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX(), d2i_OSSL_CRMF_ENCRYPTEDKEY(), i2d_OSSL_CRMF_ENCRYPTEDKEY(), d2i_OSSL_DAY_TIME(), d2i_OSSL_DAY_TIME_BAND(), d2i_OSSL_NAMED_DAY(), d2i_OSSL_TIME_PERIOD(), d2i_OSSL_TIME_SPEC(), d2i_OSSL_TIME_SPEC_ABSOLUTE(), d2i_OSSL_TIME_SPEC_DAY(), d2i_OSSL_TIME_SPEC_MONTH(), d2i_OSSL_TIME_SPEC_TIME(), d2i_OSSL_TIME_SPEC_WEEKS(), d2i_OSSL_TIME_SPEC_X_DAY_OF(), i2d_OSSL_DAY_TIME(), i2d_OSSL_DAY_TIME_BAND(), i2d_OSSL_NAMED_DAY(), i2d_OSSL_TIME_PERIOD(), i2d_OSSL_TIME_SPEC(), i2d_OSSL_TIME_SPEC_ABSOLUTE(), i2d_OSSL_TIME_SPEC_DAY(), i2d_OSSL_TIME_SPEC_MONTH(), i2d_OSSL_TIME_SPEC_TIME(), i2d_OSSL_TIME_SPEC_WEEKS(), i2d_OSSL_TIME_SPEC_X_DAY_OF() في OpenSSL 3.5.

حقوق النسخ
حقوق النشر 1998-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.