diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/d2i_X509.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/d2i_X509.3 | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/d2i_X509.3 b/secure/lib/libcrypto/man/man3/d2i_X509.3 new file mode 100644 index 000000000000..024c8dcefd63 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/d2i_X509.3 @@ -0,0 +1,385 @@ +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39) +.\" +.\" 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 +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. 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 +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "D2I_X509 3" +.TH D2I_X509 3 "2019-09-10" "1.1.1d" "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_DSAPrivateKey, d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp, d2i_DSAPublicKey, d2i_DSA_PUBKEY, d2i_DSA_PUBKEY_bio, d2i_DSA_PUBKEY_fp, d2i_DSA_SIG, d2i_DSAparams, d2i_ECDSA_SIG, d2i_ECPKParameters, d2i_ECParameters, d2i_ECPrivateKey, d2i_ECPrivateKey_bio, d2i_ECPrivateKey_fp, d2i_EC_PUBKEY, d2i_EC_PUBKEY_bio, d2i_EC_PUBKEY_fp, d2i_EDIPARTYNAME, d2i_ESS_CERT_ID, d2i_ESS_ISSUER_SERIAL, d2i_ESS_SIGNING_CERT, d2i_EXTENDED_KEY_USAGE, d2i_GENERAL_NAME, d2i_GENERAL_NAMES, d2i_IPAddressChoice, d2i_IPAddressFamily, d2i_IPAddressOrRange, d2i_IPAddressRange, 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_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_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp, d2i_RSAPublicKey, d2i_RSAPublicKey_bio, d2i_RSAPublicKey_fp, d2i_RSA_OAEP_PARAMS, d2i_RSA_PSS_PARAMS, d2i_RSA_PUBKEY, d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp, 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_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_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_DSAPrivateKey, i2d_DSAPrivateKey_bio, i2d_DSAPrivateKey_fp, i2d_DSAPublicKey, i2d_DSA_PUBKEY, i2d_DSA_PUBKEY_bio, i2d_DSA_PUBKEY_fp, i2d_DSA_SIG, i2d_DSAparams, i2d_ECDSA_SIG, i2d_ECPKParameters, i2d_ECParameters, i2d_ECPrivateKey, i2d_ECPrivateKey_bio, i2d_ECPrivateKey_fp, i2d_EC_PUBKEY, i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp, i2d_EDIPARTYNAME, i2d_ESS_CERT_ID, i2d_ESS_ISSUER_SERIAL, i2d_ESS_SIGNING_CERT, i2d_EXTENDED_KEY_USAGE, i2d_GENERAL_NAME, i2d_GENERAL_NAMES, i2d_IPAddressChoice, i2d_IPAddressFamily, i2d_IPAddressOrRange, i2d_IPAddressRange, 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_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_PublicKey, i2d_RSAPrivateKey, i2d_RSAPrivateKey_bio, i2d_RSAPrivateKey_fp, i2d_RSAPublicKey, i2d_RSAPublicKey_bio, i2d_RSAPublicKey_fp, i2d_RSA_OAEP_PARAMS, i2d_RSA_PSS_PARAMS, i2d_RSA_PUBKEY, i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp, 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_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_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, unsigned char **ppin, long length); +\& TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); +\& TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); +\& +\& int i2d_TYPE(TYPE *a, unsigned char **ppout); +\& int i2d_TYPE_fp(FILE *fp, TYPE *a); +\& int i2d_TYPE_bio(BIO *bp, TYPE *a); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +In the description here, \fI\s-1TYPE\s0\fR is used a placeholder +for any of the OpenSSL datatypes, such as \fIX509_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 \s-1ASN.1/DER\s0 +encoding. Unlike the C structures which can have pointers to sub-objects +within, the \s-1DER\s0 is a serialized encoding, suitable for sending over the +network, writing to a file, and so on. +.PP +\&\fBd2i_TYPE()\fR attempts to decode \fBlen\fR bytes at \fB*ppin\fR. If successful a +pointer to the \fB\s-1TYPE\s0\fR structure is returned and \fB*ppin\fR is incremented to +the byte following the parsed data. If \fBa\fR is not \fB\s-1NULL\s0\fR then a pointer +to the returned structure is also written to \fB*a\fR. If an error occurred +then \fB\s-1NULL\s0\fR is returned. +.PP +On a successful return, if \fB*a\fR is not \fB\s-1NULL\s0\fR then it is assumed that \fB*a\fR +contains a valid \fB\s-1TYPE\s0\fR structure and an attempt is made to reuse it. This +\&\*(L"reuse\*(R" capability is present for historical compatibility but its use is +\&\fBstrongly discouraged\fR (see \s-1BUGS\s0 below, and the discussion in the \s-1RETURN +VALUES\s0 section). +.PP +\&\fBd2i_TYPE_bio()\fR is similar to \fBd2i_TYPE()\fR except it attempts +to parse data from \s-1BIO\s0 \fBbp\fR. +.PP +\&\fBd2i_TYPE_fp()\fR is similar to \fBd2i_TYPE()\fR except it attempts +to parse data from \s-1FILE\s0 pointer \fBfp\fR. +.PP +\&\fBi2d_TYPE()\fR encodes the structure pointed to by \fBa\fR into \s-1DER\s0 format. +If \fBppout\fR is not \fB\s-1NULL\s0\fR, it writes the \s-1DER\s0 encoded data to the buffer +at \fB*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 \fB*ppout\fR is \fB\s-1NULL\s0\fR memory will be allocated for a buffer and the encoded +data written to it. In this case \fB*ppout\fR is not incremented and it points +to the start of the data just written. +.PP +\&\fBi2d_TYPE_bio()\fR is similar to \fBi2d_TYPE()\fR except it writes +the encoding of the structure \fBa\fR to \s-1BIO\s0 \fBbp\fR and it +returns 1 for success and 0 for failure. +.PP +\&\fBi2d_TYPE_fp()\fR is similar to \fBi2d_TYPE()\fR except it writes +the encoding of the structure \fBa\fR to \s-1BIO\s0 \fBbp\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_TYPE\fR stand for +\&\*(L"internal\*(R" (that is, an internal C structure) and \*(L"\s-1DER\*(R"\s0 respectively. +So \fBi2d_TYPE\fR converts from internal to \s-1DER.\s0 +.PP +The functions can also understand \fB\s-1BER\s0\fR forms. +.PP +The actual \s-1TYPE\s0 structure passed to \fBi2d_TYPE()\fR must be a valid +populated \fB\s-1TYPE\s0\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 zeroes. +Therefore any \s-1FILE\s0 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 \fB*ppin\fR and \fB*ppout\fR are incremented after the operation +can trap the unwary. See the \fB\s-1WARNINGS\s0\fR section for some common +errors. +The reason for this-auto increment behaviour is to reflect a typical +usage of \s-1ASN1\s0 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 "\fB\s-1ASN1_OBJECT\s0\fR" 4 +.IX Item "ASN1_OBJECT" +Represents an \s-1ASN1 OBJECT IDENTIFIER.\s0 +.IP "\fBDHparams\fR" 4 +.IX Item "DHparams" +Represents a PKCS#3 \s-1DH\s0 parameters structure. +.IP "\fBDHparamx\fR" 4 +.IX Item "DHparamx" +Represents an \s-1ANSI X9.42 DH\s0 parameters structure. +.IP "\fB\s-1DSA_PUBKEY\s0\fR" 4 +.IX Item "DSA_PUBKEY" +Represents a \s-1DSA\s0 public key using a \fBSubjectPublicKeyInfo\fR structure. +.IP "\fBDSAPublicKey, DSAPrivateKey\fR" 4 +.IX Item "DSAPublicKey, DSAPrivateKey" +Use a non-standard OpenSSL format and should be avoided; use \fB\s-1DSA_PUBKEY\s0\fR, +\&\fB\fBPEM_write_PrivateKey\fB\|(3)\fR, or similar instead. +.IP "\fB\s-1ECDSA_SIG\s0\fR" 4 +.IX Item "ECDSA_SIG" +Represents an \s-1ECDSA\s0 signature. +.IP "\fBRSAPublicKey\fR" 4 +.IX Item "RSAPublicKey" +Represents a PKCS#1 \s-1RSA\s0 public key structure. +.IP "\fBX509_ALGOR\fR" 4 +.IX Item "X509_ALGOR" +Represents an \fBAlgorithmIdentifier\fR structure as used in \s-1IETF RFC 6960\s0 and +elsewhere. +.IP "\fBX509_Name\fR" 4 +.IX Item "X509_Name" +Represents a \fBName\fR type as used for subject and issuer names in +\&\s-1IETF RFC 6960\s0 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_TYPE()\fR, \fBd2i_TYPE_bio()\fR and \fBd2i_TYPE_fp()\fR return a valid \fB\s-1TYPE\s0\fR structure +or \fB\s-1NULL\s0\fR if an error occurs. If the \*(L"reuse\*(R" capability has been used with +a valid structure being passed in via \fBa\fR, then the object is freed in +the event of error and \fB*a\fR is set to \s-1NULL.\s0 +.PP +\&\fBi2d_TYPE()\fR returns the number of bytes successfully encoded or a negative +value if an error occurs. +.PP +\&\fBi2d_TYPE_bio()\fR and \fBi2d_TYPE_fp()\fR return 1 for success and 0 if an error +occurs. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Allocate and encode the \s-1DER\s0 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 3 +\& X509 *x; +\& unsigned char *buf, *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 3 +\& X509 *x; +\& unsigned char *buf, *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 +.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 \fBbuf\fR apparently containing garbage because +it was incremented after the call to point after the data just written. +Also \fBbuf\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 \fBa\fR argument to \fBd2i_TYPE()\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 \fBx\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 \fBx\fR is set to \s-1NULL\s0 first then this will not +happen. +.SH "BUGS" +.IX Header "BUGS" +In some versions of OpenSSL the \*(L"reuse\*(R" behaviour of \fBd2i_TYPE()\fR when +\&\fB*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 \*(L"reuse\*(R" behaviour is used and an error occurs +the behaviour is inconsistent. Some functions behaved as described here, while +some did not free \fB*a\fR on error and did not set \fB*a\fR to \s-1NULL.\s0 +.PP +As a result of the above issues the \*(L"reuse\*(R" behaviour is strongly discouraged. +.PP +\&\fBi2d_TYPE()\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_TYPE()\fR. This may be +fixed in future so code should not assume that \fBi2d_TYPE()\fR will +always succeed. +.PP +Any function which encodes a structure (\fBi2d_TYPE()\fR, +\&\fBi2d_TYPE()\fR or \fBi2d_TYPE()\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\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |