+</code></pre></div><h2 id=description>DESCRIPTION<a class=headerlink href=#description title="Permanent link">¶</a></h2><p>In the description here, <strong><em>TYPE</em></strong> is used a placeholder for any of the OpenSSL datatypes, such as <strong>X509_CRL</strong>. The function parameters <em>ppin</em> and <em>ppout</em> are generally either both named <em>pp</em> in the headers, or <em>in</em> and <em>out</em>.</p><p>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.</p><p><strong>d2i_<em>TYPE</em></strong>() attempts to decode <em>len</em> bytes at <em>*ppin</em>. If successful a pointer to the <strong><em>TYPE</em></strong> structure is returned and <em>*ppin</em> is incremented to the byte following the parsed data. If <em>a</em> is not NULL then a pointer to the returned structure is also written to <em>*a</em>. If an error occurred then NULL is returned. The caller retains ownership of the returned object and needs to free it when it is no longer needed, e.g. using X509_free() for X509 objects or DSA_SIG_free() for DSA_SIG objects.</p><p>On a successful return, if <em>*a</em> is not NULL then it is assumed that <em>*a</em> contains a valid <strong><em>TYPE</em></strong> structure and an attempt is made to reuse it. For <strong><em>TYPE</em></strong> structures where it matters it is possible to set up a library context on the decoded structure this way (see the <strong>EXAMPLES</strong> section). However using the "reuse" capability for other purposes is <strong>strongly discouraged</strong> (see <strong>BUGS</strong> below, and the discussion in the <strong>RETURN VALUES</strong> section).</p><p><strong>d2i_<em>TYPE</em>_bio</strong>() is similar to <strong>d2i_<em>TYPE</em></strong>() except it attempts to parse data from BIO <em>bp</em>.</p><p><strong>d2i_<em>TYPE</em>_fp</strong>() is similar to <strong>d2i_<em>TYPE</em></strong>() except it attempts to parse data from FILE pointer <em>fp</em>.</p><p><strong>i2d_<em>TYPE</em></strong>() encodes the structure pointed to by <em>a</em> into DER format. If <em>ppout</em> is not NULL, it writes the DER encoded data to the buffer at <em>*ppout</em>, 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.</p><p>If <em>*ppout</em> is NULL memory will be allocated for a buffer and the encoded data written to it. In this case <em>*ppout</em> is not incremented and it points to the start of the data just written.</p><p><strong>i2d_<em>TYPE</em>_bio</strong>() is similar to <strong>i2d_<em>TYPE</em></strong>() except it writes the encoding of the structure <em>a</em> to BIO <em>bp</em> and it returns 1 for success and 0 for failure.</p><p><strong>i2d_<em>TYPE</em>_fp</strong>() is similar to <strong>i2d_<em>TYPE</em></strong>() except it writes the encoding of the structure <em>a</em> to FILE pointer <em>fp</em> and it returns 1 for success and 0 for failure.</p><p>These routines do not encrypt private keys and therefore offer no security; use <a href=../PEM_read_bio_PrivateKey/ >PEM_write_PrivateKey(3)</a> or similar for writing to files.</p><h2 id=notes>NOTES<a class=headerlink href=#notes title="Permanent link">¶</a></h2><p>The letters <strong>i</strong> and <strong>d</strong> in <strong>i2d_<em>TYPE</em></strong>() stand for "internal" (that is, an internal C structure) and "DER" respectively. So <strong>i2d_<em>TYPE</em></strong>() converts from internal to DER.</p><p>The functions can also understand <strong>BER</strong> forms.</p><p>The actual TYPE structure passed to <strong>i2d_<em>TYPE</em></strong>() must be a valid populated <strong><em>TYPE</em></strong> structure -- it <strong>cannot</strong> simply be fed with an empty structure such as that returned by TYPE_new().</p><p>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 strlen() will <strong>not</strong> return the correct length of the encoded structure.</p><p>The ways that <em>*ppin</em> and <em>*ppout</em> are incremented after the operation can trap the unwary. See the <strong>WARNINGS</strong> 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.</p><p>The following points about the data types might be useful:</p><ul><li><p><strong>ASN1_OBJECT</strong></p><p>Represents an ASN1 OBJECT IDENTIFIER.</p></li><li><p><strong>DHparams</strong></p><p>Represents a PKCS#3 DH parameters structure.</p></li><li><p><strong>DHxparams</strong></p><p>Represents an ANSI X9.42 DH parameters structure.</p></li><li><p><strong>ECDSA_SIG</strong></p><p>Represents an ECDSA signature.</p></li><li><p><strong>X509_ALGOR</strong></p><p>Represents an <strong>AlgorithmIdentifier</strong> structure as used in IETF RFC 6960 and elsewhere.</p></li><li><p><strong>X509_NAME</strong></p><p>Represents a <strong>Name</strong> type as used for subject and issuer names in IETF RFC 6960 and elsewhere.</p></li><li><p><strong>X509_REQ</strong></p><p>Represents a PKCS#10 certificate request.</p></li><li><p><strong>X509_SIG</strong></p><p>Represents the <strong>DigestInfo</strong> structure defined in PKCS#1 and PKCS#7.</p></li></ul><h2 id=return-values>RETURN VALUES<a class=headerlink href=#return-values title="Permanent link">¶</a></h2><p><strong>d2i_<em>TYPE</em></strong>(), <strong>d2i_<em>TYPE</em>_bio</strong>() and <strong>d2i_<em>TYPE</em>_fp</strong>() return a valid <strong><em>TYPE</em></strong> structure or NULL if an error occurs. If the "reuse" capability has been used with a valid structure being passed in via <em>a</em>, then the object is freed in the event of error and <em>*a</em> is set to NULL.</p><p><strong>i2d_<em>TYPE</em></strong>() returns the number of bytes successfully encoded or a negative value if an error occurs.</p><p><strong>i2d_<em>TYPE</em>_bio</strong>() and <strong>i2d_<em>TYPE</em>_fp</strong>(), as well as i2d_ASN1_bio_stream(), return 1 for success and 0 if an error occurs.</p><h2 id=examples>EXAMPLES<a class=headerlink href=#examples title="Permanent link">¶</a></h2><p>Allocate and encode the DER encoding of an X509 structure:</p><div class=highlight><pre><span></span><code>int len;
0 commit comments