secure/lib/libcrypto/man/man3/d2i_X509.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "D2I_X509 3"
 136 .TH D2I_X509 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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_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
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 3
 146 \& TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length);
 147 \& TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
 148 \& TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
 149 \&
 150 \& int i2d_TYPE(TYPE *a, unsigned char **ppout);
 151 \& int i2d_TYPE_fp(FILE *fp, TYPE *a);
 152 \& int i2d_TYPE_bio(BIO *bp, TYPE *a);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 In the description here, \fI\s-1TYPE\s0\fR is used a placeholder
 157 for any of the OpenSSL datatypes, such as \fIX509_CRL\fR.
 158 The function parameters \fIppin\fR and \fIppout\fR are generally
 159 either both named \fIpp\fR in the headers, or \fIin\fR and \fIout\fR.
 160 .PP
 161 These functions convert OpenSSL objects to and from their \s-1ASN.1/DER\s0
 162 encoding.  Unlike the C structures which can have pointers to sub-objects
 163 within, the \s-1DER\s0 is a serialized encoding, suitable for sending over the
 164 network, writing to a file, and so on.
 165 .PP
 166 \&\fBd2i_TYPE()\fR attempts to decode \fBlen\fR bytes at \fB*ppin\fR. If successful a
 167 pointer to the \fB\s-1TYPE\s0\fR structure is returned and \fB*ppin\fR is incremented to
 168 the byte following the parsed data.  If \fBa\fR is not \fB\s-1NULL\s0\fR then a pointer
 169 to the returned structure is also written to \fB*a\fR.  If an error occurred
 170 then \fB\s-1NULL\s0\fR is returned.
 171 .PP
 172 On a successful return, if \fB*a\fR is not \fB\s-1NULL\s0\fR then it is assumed that \fB*a\fR
 173 contains a valid \fB\s-1TYPE\s0\fR structure and an attempt is made to reuse it. This
 174 \&\*(L"reuse\*(R" capability is present for historical compatibility but its use is
 175 \&\fBstrongly discouraged\fR (see \s-1BUGS\s0 below, and the discussion in the \s-1RETURN
 176 VALUES\s0 section).
 177 .PP
 178 \&\fBd2i_TYPE_bio()\fR is similar to \fBd2i_TYPE()\fR except it attempts
 179 to parse data from \s-1BIO\s0 \fBbp\fR.
 180 .PP
 181 \&\fBd2i_TYPE_fp()\fR is similar to \fBd2i_TYPE()\fR except it attempts
 182 to parse data from \s-1FILE\s0 pointer \fBfp\fR.
 183 .PP
 184 \&\fBi2d_TYPE()\fR encodes the structure pointed to by \fBa\fR into \s-1DER\s0 format.
 185 If \fBppout\fR is not \fB\s-1NULL\s0\fR, it writes the \s-1DER\s0 encoded data to the buffer
 186 at \fB*ppout\fR, and increments it to point after the data just written.
 187 If the return value is negative an error occurred, otherwise it
 188 returns the length of the encoded data.
 189 .PP
 190 If \fB*ppout\fR is \fB\s-1NULL\s0\fR memory will be allocated for a buffer and the encoded
 191 data written to it. In this case \fB*ppout\fR is not incremented and it points
 192 to the start of the data just written.
 193 .PP
 194 \&\fBi2d_TYPE_bio()\fR is similar to \fBi2d_TYPE()\fR except it writes
 195 the encoding of the structure \fBa\fR to \s-1BIO\s0 \fBbp\fR and it
 196 returns 1 for success and 0 for failure.
 197 .PP
 198 \&\fBi2d_TYPE_fp()\fR is similar to \fBi2d_TYPE()\fR except it writes
 199 the encoding of the structure \fBa\fR to \s-1BIO\s0 \fBbp\fR and it
 200 returns 1 for success and 0 for failure.
 201 .PP
 202 These routines do not encrypt private keys and therefore offer no
 203 security; use \fBPEM_write_PrivateKey\fR\|(3) or similar for writing to files.
 204 .SH "NOTES"
 205 .IX Header "NOTES"
 206 The letters \fBi\fR and \fBd\fR in \fBi2d_TYPE\fR stand for
 207 \&\*(L"internal\*(R" (that is, an internal C structure) and \*(L"\s-1DER\*(R"\s0 respectively.
 208 So \fBi2d_TYPE\fR converts from internal to \s-1DER.\s0
 209 .PP
 210 The functions can also understand \fB\s-1BER\s0\fR forms.
 211 .PP
 212 The actual \s-1TYPE\s0 structure passed to \fBi2d_TYPE()\fR must be a valid
 213 populated \fB\s-1TYPE\s0\fR structure \*(-- it \fBcannot\fR simply be fed with an
 214 empty structure such as that returned by \fBTYPE_new()\fR.
 215 .PP
 216 The encoded data is in binary form and may contain embedded zeros.
 217 Therefore, any \s-1FILE\s0 pointers or BIOs should be opened in binary mode.
 218 Functions such as \fBstrlen()\fR will \fBnot\fR return the correct length
 219 of the encoded structure.
 220 .PP
 221 The ways that \fB*ppin\fR and \fB*ppout\fR are incremented after the operation
 222 can trap the unwary. See the \fB\s-1WARNINGS\s0\fR section for some common
 223 errors.
 224 The reason for this-auto increment behaviour is to reflect a typical
 225 usage of \s-1ASN1\s0 functions: after one structure is encoded or decoded
 226 another will be processed after it.
 227 .PP
 228 The following points about the data types might be useful:
 229 .IP "\fB\s-1ASN1_OBJECT\s0\fR" 4
 230 .IX Item "ASN1_OBJECT"
 231 Represents an \s-1ASN1 OBJECT IDENTIFIER.\s0
 232 .IP "\fBDHparams\fR" 4
 233 .IX Item "DHparams"
 234 Represents a PKCS#3 \s-1DH\s0 parameters structure.
 235 .IP "\fBDHxparams\fR" 4
 236 .IX Item "DHxparams"
 237 Represents an \s-1ANSI X9.42 DH\s0 parameters structure.
 238 .IP "\fB\s-1DSA_PUBKEY\s0\fR" 4
 239 .IX Item "DSA_PUBKEY"
 240 Represents a \s-1DSA\s0 public key using a \fBSubjectPublicKeyInfo\fR structure.
 241 .IP "\fBDSAPublicKey, DSAPrivateKey\fR" 4
 242 .IX Item "DSAPublicKey, DSAPrivateKey"
 243 Use a non-standard OpenSSL format and should be avoided; use \fB\s-1DSA_PUBKEY\s0\fR,
 244 \&\fB\fBPEM_write_PrivateKey\fB\|(3)\fR, or similar instead.
 245 .IP "\fB\s-1ECDSA_SIG\s0\fR" 4
 246 .IX Item "ECDSA_SIG"
 247 Represents an \s-1ECDSA\s0 signature.
 248 .IP "\fBRSAPublicKey\fR" 4
 249 .IX Item "RSAPublicKey"
 250 Represents a PKCS#1 \s-1RSA\s0 public key structure.
 251 .IP "\fBX509_ALGOR\fR" 4
 252 .IX Item "X509_ALGOR"
 253 Represents an \fBAlgorithmIdentifier\fR structure as used in \s-1IETF RFC 6960\s0 and
 254 elsewhere.
 255 .IP "\fBX509_Name\fR" 4
 256 .IX Item "X509_Name"
 257 Represents a \fBName\fR type as used for subject and issuer names in
 258 \&\s-1IETF RFC 6960\s0 and elsewhere.
 259 .IP "\fBX509_REQ\fR" 4
 260 .IX Item "X509_REQ"
 261 Represents a PKCS#10 certificate request.
 262 .IP "\fBX509_SIG\fR" 4
 263 .IX Item "X509_SIG"
 264 Represents the \fBDigestInfo\fR structure defined in PKCS#1 and PKCS#7.
 265 .SH "RETURN VALUES"
 266 .IX Header "RETURN VALUES"
 267 \&\fBd2i_TYPE()\fR, \fBd2i_TYPE_bio()\fR and \fBd2i_TYPE_fp()\fR return a valid \fB\s-1TYPE\s0\fR structure
 268 or \fB\s-1NULL\s0\fR if an error occurs.  If the \*(L"reuse\*(R" capability has been used with
 269 a valid structure being passed in via \fBa\fR, then the object is freed in
 270 the event of error and \fB*a\fR is set to \s-1NULL.\s0
 271 .PP
 272 \&\fBi2d_TYPE()\fR returns the number of bytes successfully encoded or a negative
 273 value if an error occurs.
 274 .PP
 275 \&\fBi2d_TYPE_bio()\fR and \fBi2d_TYPE_fp()\fR return 1 for success and 0 if an error
 276 occurs.
 277 .SH "EXAMPLES"
 278 .IX Header "EXAMPLES"
 279 Allocate and encode the \s-1DER\s0 encoding of an X509 structure:
 280 .PP
 281 .Vb 2
 282 \& int len;
 283 \& unsigned char *buf;
 284 \&
 285 \& buf = NULL;
 286 \& len = i2d_X509(x, &buf);
 287 \& if (len < 0)
 288 \&     /* error */
 289 .Ve
 290 .PP
 291 Attempt to decode a buffer:
 292 .PP
 293 .Vb 4
 294 \& X509 *x;
 295 \& unsigned char *buf;
 296 \& const unsigned char *p;
 297 \& int len;
 298 \&
 299 \& /* Set up buf and len to point to the input buffer. */
 300 \& p = buf;
 301 \& x = d2i_X509(NULL, &p, len);
 302 \& if (x == NULL)
 303 \&     /* error */
 304 .Ve
 305 .PP
 306 Alternative technique:
 307 .PP
 308 .Vb 4
 309 \& X509 *x;
 310 \& unsigned char *buf;
 311 \& const unsigned char *p;
 312 \& int len;
 313 \&
 314 \& /* Set up buf and len to point to the input buffer. */
 315 \& p = buf;
 316 \& x = NULL;
 317 \&
 318 \& if (d2i_X509(&x, &p, len) == NULL)
 319 \&     /* error */
 320 .Ve
 321 .SH "WARNINGS"
 322 .IX Header "WARNINGS"
 323 Using a temporary variable is mandatory. A common
 324 mistake is to attempt to use a buffer directly as follows:
 325 .PP
 326 .Vb 2
 327 \& int len;
 328 \& unsigned char *buf;
 329 \&
 330 \& len = i2d_X509(x, NULL);
 331 \& buf = OPENSSL_malloc(len);
 332 \& ...
 333 \& i2d_X509(x, &buf);
 334 \& ...
 335 \& OPENSSL_free(buf);
 336 .Ve
 337 .PP
 338 This code will result in \fBbuf\fR apparently containing garbage because
 339 it was incremented after the call to point after the data just written.
 340 Also \fBbuf\fR will no longer contain the pointer allocated by \fBOPENSSL_malloc()\fR
 341 and the subsequent call to \fBOPENSSL_free()\fR is likely to crash.
 342 .PP
 343 Another trap to avoid is misuse of the \fBa\fR argument to \fBd2i_TYPE()\fR:
 344 .PP
 345 .Vb 1
 346 \& X509 *x;
 347 \&
 348 \& if (d2i_X509(&x, &p, len) == NULL)
 349 \&     /* error */
 350 .Ve
 351 .PP
 352 This will probably crash somewhere in \fBd2i_X509()\fR. The reason for this
 353 is that the variable \fBx\fR is uninitialized and an attempt will be made to
 354 interpret its (invalid) value as an \fBX509\fR structure, typically causing
 355 a segmentation violation. If \fBx\fR is set to \s-1NULL\s0 first then this will not
 356 happen.
 357 .SH "BUGS"
 358 .IX Header "BUGS"
 359 In some versions of OpenSSL the \*(L"reuse\*(R" behaviour of \fBd2i_TYPE()\fR when
 360 \&\fB*a\fR is valid is broken and some parts of the reused structure may
 361 persist if they are not present in the new one. Additionally, in versions of
 362 OpenSSL prior to 1.1.0, when the \*(L"reuse\*(R" behaviour is used and an error occurs
 363 the behaviour is inconsistent. Some functions behaved as described here, while
 364 some did not free \fB*a\fR on error and did not set \fB*a\fR to \s-1NULL.\s0
 365 .PP
 366 As a result of the above issues the \*(L"reuse\*(R" behaviour is strongly discouraged.
 367 .PP
 368 \&\fBi2d_TYPE()\fR will not return an error in many versions of OpenSSL,
 369 if mandatory fields are not initialized due to a programming error
 370 then the encoded structure may contain invalid data or omit the
 371 fields entirely and will not be parsed by \fBd2i_TYPE()\fR. This may be
 372 fixed in future so code should not assume that \fBi2d_TYPE()\fR will
 373 always succeed.
 374 .PP
 375 Any function which encodes a structure (\fBi2d_TYPE()\fR,
 376 \&\fBi2d_TYPE()\fR or \fBi2d_TYPE()\fR) may return a stale encoding if the
 377 structure has been modified after deserialization or previous
 378 serialization. This is because some objects cache the encoding for
 379 efficiency reasons.
 380 .SH "COPYRIGHT"
 381 .IX Header "COPYRIGHT"
 382 Copyright 1998\-2020 The OpenSSL Project Authors. All Rights Reserved.
 383 .PP
 384 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 385 this file except in compliance with the License.  You can obtain a copy
 386 in the file \s-1LICENSE\s0 in the source distribution or at
 387 <https://www.openssl.org/source/license.html>.