diff options
Diffstat (limited to 'upstream/archlinux/man3/d2i_X509.3ssl')
| -rw-r--r-- | upstream/archlinux/man3/d2i_X509.3ssl | 667 |
1 files changed, 667 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/d2i_X509.3ssl b/upstream/archlinux/man3/d2i_X509.3ssl new file mode 100644 index 00000000..029eb017 --- /dev/null +++ b/upstream/archlinux/man3/d2i_X509.3ssl @@ -0,0 +1,667 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "D2I_X509 3ssl" +.TH D2I_X509 3ssl 2024-01-30 3.2.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +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_CMP_MSG, +d2i_OSSL_CMP_PKIHEADER, +d2i_OSSL_CMP_PKISI, +d2i_OSSL_CRMF_CERTID, +d2i_OSSL_CRMF_CERTTEMPLATE, +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_OTHERNAME, +d2i_PBE2PARAM, +d2i_PBEPARAM, +d2i_PBKDF2PARAM, +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_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_CMP_MSG, +i2d_OSSL_CMP_PKIHEADER, +i2d_OSSL_CMP_PKISI, +i2d_OSSL_CRMF_CERTID, +i2d_OSSL_CRMF_CERTTEMPLATE, +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_OTHERNAME, +i2d_PBE2PARAM, +i2d_PBEPARAM, +i2d_PBKDF2PARAM, +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_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 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 3 +\& 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); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In the description here, \fR\f(BITYPE\fR\fB\fR is used a placeholder +for any of the OpenSSL datatypes, such as \fBX509_CRL\fR. +The function parameters \fIppin\fR and \fIppout\fR are generally +either both named \fIpp\fR in the headers, or \fIin\fR and \fIout\fR. +.PP +These functions convert OpenSSL objects to and from their ASN.1/DER +encoding. Unlike the C structures which can have pointers to sub-objects +within, the DER is a serialized encoding, suitable for sending over the +network, writing to a file, and so on. +.PP +\&\fBd2i_\fR\f(BITYPE\fR() attempts to decode \fIlen\fR bytes at \fI*ppin\fR. If successful a +pointer to the \fB\fR\f(BITYPE\fR\fB\fR structure is returned and \fI*ppin\fR is incremented to +the byte following the parsed data. If \fIa\fR is not NULL then a pointer +to the returned structure is also written to \fI*a\fR. If an error occurred +then NULL is returned. +.PP +On a successful return, if \fI*a\fR is not NULL then it is assumed that \fI*a\fR +contains a valid \fR\f(BITYPE\fR\fB\fR structure and an attempt is made to reuse it. +For \fB\fR\f(BITYPE\fR\fB\fR structures where it matters it is possible to set up a library +context on the decoded structure this way (see the \fBEXAMPLES\fR section). +However using the "reuse" capability for other purposes is \fBstrongly +discouraged\fR (see \fBBUGS\fR below, and the discussion in the \fBRETURN VALUES\fR +section). +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fB_bio\fR() is similar to \fBd2i_\fR\f(BITYPE\fR() except it attempts +to parse data from BIO \fIbp\fR. +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fB_fp\fR() is similar to \fBd2i_\fR\f(BITYPE\fR() except it attempts +to parse data from FILE pointer \fIfp\fR. +.PP +\&\fBi2d_\fR\f(BITYPE\fR() encodes the structure pointed to by \fIa\fR into DER format. +If \fIppout\fR is not NULL, it writes the DER encoded data to the buffer +at \fI*ppout\fR, and increments it to point after the data just written. +If the return value is negative an error occurred, otherwise it +returns the length of the encoded data. +.PP +If \fI*ppout\fR is NULL memory will be allocated for a buffer and the encoded +data written to it. In this case \fI*ppout\fR is not incremented and it points +to the start of the data just written. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() is similar to \fBi2d_\fR\f(BITYPE\fR() except it writes +the encoding of the structure \fIa\fR to BIO \fIbp\fR and it +returns 1 for success and 0 for failure. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_fp\fR() is similar to \fBi2d_\fR\f(BITYPE\fR() except it writes +the encoding of the structure \fIa\fR to FILE pointer \fIfp\fR and it +returns 1 for success and 0 for failure. +.PP +These routines do not encrypt private keys and therefore offer no +security; use \fBPEM_write_PrivateKey\fR\|(3) or similar for writing to files. +.SH NOTES +.IX Header "NOTES" +The letters \fBi\fR and \fBd\fR in \fBi2d_\fR\f(BITYPE\fR() stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So \fBi2d_\fR\f(BITYPE\fR\fB\fR() converts from internal to DER. +.PP +The functions can also understand \fBBER\fR forms. +.PP +The actual TYPE structure passed to \fBi2d_\fR\f(BITYPE\fR() must be a valid +populated \fB\fR\f(BITYPE\fR\fB\fR structure \-\- it \fBcannot\fR simply be fed with an +empty structure such as that returned by \fBTYPE_new()\fR. +.PP +The encoded data is in binary form and may contain embedded zeros. +Therefore, any FILE pointers or BIOs should be opened in binary mode. +Functions such as \fBstrlen()\fR will \fBnot\fR return the correct length +of the encoded structure. +.PP +The ways that \fI*ppin\fR and \fI*ppout\fR are incremented after the operation +can trap the unwary. See the \fBWARNINGS\fR section for some common +errors. +The reason for this-auto increment behaviour is to reflect a typical +usage of ASN1 functions: after one structure is encoded or decoded +another will be processed after it. +.PP +The following points about the data types might be useful: +.IP \fBASN1_OBJECT\fR 4 +.IX Item "ASN1_OBJECT" +Represents an ASN1 OBJECT IDENTIFIER. +.IP \fBDHparams\fR 4 +.IX Item "DHparams" +Represents a PKCS#3 DH parameters structure. +.IP \fBDHxparams\fR 4 +.IX Item "DHxparams" +Represents an ANSI X9.42 DH parameters structure. +.IP \fBECDSA_SIG\fR 4 +.IX Item "ECDSA_SIG" +Represents an ECDSA signature. +.IP \fBX509_ALGOR\fR 4 +.IX Item "X509_ALGOR" +Represents an \fBAlgorithmIdentifier\fR structure as used in IETF RFC 6960 and +elsewhere. +.IP \fBX509_NAME\fR 4 +.IX Item "X509_NAME" +Represents a \fBName\fR type as used for subject and issuer names in +IETF RFC 6960 and elsewhere. +.IP \fBX509_REQ\fR 4 +.IX Item "X509_REQ" +Represents a PKCS#10 certificate request. +.IP \fBX509_SIG\fR 4 +.IX Item "X509_SIG" +Represents the \fBDigestInfo\fR structure defined in PKCS#1 and PKCS#7. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBd2i_\fR\f(BITYPE\fR(), \fBd2i_\fR\f(BITYPE\fR\fB_bio\fR() and \fBd2i_\fR\f(BITYPE\fR\fB_fp\fR() return a valid +\&\fB\fR\f(BITYPE\fR\fB\fR structure or NULL if an error occurs. If the "reuse" capability has +been used with a valid structure being passed in via \fIa\fR, then the object is +freed in the event of error and \fI*a\fR is set to NULL. +.PP +\&\fBi2d_\fR\f(BITYPE\fR() returns the number of bytes successfully encoded or a negative +value if an error occurs. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() and \fBi2d_\fR\f(BITYPE\fR\fB_fp\fR() return 1 for success and 0 if an +error occurs. +.SH EXAMPLES +.IX Header "EXAMPLES" +Allocate and encode the DER encoding of an X509 structure: +.PP +.Vb 2 +\& int len; +\& unsigned char *buf; +\& +\& buf = NULL; +\& len = i2d_X509(x, &buf); +\& if (len < 0) +\& /* error */ +.Ve +.PP +Attempt to decode a buffer: +.PP +.Vb 4 +\& 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 */ +.Ve +.PP +Alternative technique: +.PP +.Vb 4 +\& 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 */ +.Ve +.PP +Setting up a library context and property query: +.PP +.Vb 6 +\& 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) */ +.Ve +.SH WARNINGS +.IX Header "WARNINGS" +Using a temporary variable is mandatory. A common +mistake is to attempt to use a buffer directly as follows: +.PP +.Vb 2 +\& int len; +\& unsigned char *buf; +\& +\& len = i2d_X509(x, NULL); +\& buf = OPENSSL_malloc(len); +\& ... +\& i2d_X509(x, &buf); +\& ... +\& OPENSSL_free(buf); +.Ve +.PP +This code will result in \fIbuf\fR apparently containing garbage because +it was incremented after the call to point after the data just written. +Also \fIbuf\fR will no longer contain the pointer allocated by \fBOPENSSL_malloc()\fR +and the subsequent call to \fBOPENSSL_free()\fR is likely to crash. +.PP +Another trap to avoid is misuse of the \fIa\fR argument to \fBd2i_\fR\f(BITYPE\fR(): +.PP +.Vb 1 +\& X509 *x; +\& +\& if (d2i_X509(&x, &p, len) == NULL) +\& /* error */ +.Ve +.PP +This will probably crash somewhere in \fBd2i_X509()\fR. The reason for this +is that the variable \fIx\fR is uninitialized and an attempt will be made to +interpret its (invalid) value as an \fBX509\fR structure, typically causing +a segmentation violation. If \fIx\fR is set to NULL first then this will not +happen. +.SH BUGS +.IX Header "BUGS" +In some versions of OpenSSL the "reuse" behaviour of \fBd2i_\fR\f(BITYPE\fR() when +\&\fI*a\fR is valid is broken and some parts of the reused structure may +persist if they are not present in the new one. Additionally, in versions of +OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs +the behaviour is inconsistent. Some functions behaved as described here, while +some did not free \fI*a\fR on error and did not set \fI*a\fR to NULL. +.PP +As a result of the above issues the "reuse" behaviour is strongly discouraged. +.PP +\&\fBi2d_\fR\f(BITYPE\fR() will not return an error in many versions of OpenSSL, +if mandatory fields are not initialized due to a programming error +then the encoded structure may contain invalid data or omit the +fields entirely and will not be parsed by \fBd2i_\fR\f(BITYPE\fR\fB\fR(). This may be +fixed in future so code should not assume that \fBi2d_\fR\f(BITYPE\fR\fB\fR() will +always succeed. +.PP +Any function which encodes a structure (\fBi2d_\fR\f(BITYPE\fR(), +\&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() or \fBi2d_\fR\f(BITYPE\fR\fB_fp\fR()) may return a stale encoding if the +structure has been modified after deserialization or previous +serialization. This is because some objects cache the encoding for +efficiency reasons. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 1998\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |