=head1 NAME
d2i_ACCESS_DESCRIPTION,
+d2i_ADMISSIONS,
+d2i_ADMISSION_SYNTAX,
d2i_ASIdOrRange,
d2i_ASIdentifierChoice,
d2i_ASIdentifiers,
d2i_DSA_PUBKEY_fp,
d2i_DSA_SIG,
d2i_DSAparams,
+d2i_ECDSA_SIG,
d2i_ECPKParameters,
d2i_ECParameters,
d2i_ECPrivateKey,
d2i_EC_PUBKEY_fp,
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_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_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_PKEY_USAGE_PERIOD,
d2i_POLICYINFO,
d2i_POLICYQUALINFO,
+d2i_PROFESSION_INFO,
d2i_PROXY_CERT_INFO_EXTENSION,
d2i_PROXY_POLICY,
d2i_RSAPrivateKey,
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_SIG,
d2i_X509_VAL,
i2d_ACCESS_DESCRIPTION,
+i2d_ADMISSIONS,
+i2d_ADMISSION_SYNTAX,
i2d_ASIdOrRange,
i2d_ASIdentifierChoice,
i2d_ASIdentifiers,
i2d_DSA_PUBKEY_fp,
i2d_DSA_SIG,
i2d_DSAparams,
+i2d_ECDSA_SIG,
i2d_ECPKParameters,
i2d_ECParameters,
i2d_ECPrivateKey,
i2d_EC_PUBKEY_fp,
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_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_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_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_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,
=head1 SYNOPSIS
-=for comment generic
+=for openssl generic
- TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length);
+ 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 **pp);
+ 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);
=head1 DESCRIPTION
-In the description here, I<TYPE> is used a placeholder
+In the description here, B<I<TYPE>> is used a placeholder
for any of the OpenSSL datatypes, such as I<X509_CRL>.
+The function parameters I<ppin> and I<ppout> are generally
+either both named I<pp> in the headers, or I<in> and I<out>.
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.
-d2i_TYPE() attempts to decode B<len> bytes at B<*in>. If successful a
-pointer to the B<TYPE> structure is returned and B<*in> is incremented to
-the byte following the parsed data. If B<a> is not B<NULL> then a pointer
-to the returned structure is also written to B<*a>. If an error occurred
-then B<NULL> is returned.
+B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
+pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
+the byte following the parsed data. If I<a> is not NULL then a pointer
+to the returned structure is also written to I<*a>. If an error occurred
+then NULL is returned.
-On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
-contains a valid B<TYPE> structure and an attempt is made to reuse it. This
+On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
+contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This
"reuse" capability is present for historical compatibility but its use is
B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
VALUES section).
-d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
-to parse data from BIO B<bp>.
+B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
+to parse data from BIO I<bp>.
-d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
-to parse data from FILE pointer B<fp>.
+B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts
+to parse data from FILE pointer I<fp>.
-
i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
-If B<out> is not B<NULL>, it writes the DER encoded data to the buffer
-at B<*out>, and increments it to point after the data just written.
+
B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format.
+If I<ppout> is not NULL, it writes the DER encoded data to the buffer
+at I<*ppout>, 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.
-If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded
-data written to it. In this case B<*out> is not incremented and it points
+If I<*ppout> is NULL memory will be allocated for a buffer and the encoded
+data written to it. In this case I<*ppout> is not incremented and it points
to the start of the data just written.
-i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
-the encoding of the structure B<a> to BIO B<bp> and it
+B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes
+the encoding of the structure I<a> to BIO I<bp> and it
returns 1 for success and 0 for failure.
-i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
-the encoding of the structure B<a> to BIO B<bp> and it
+B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes
+the encoding of the structure I<a> to BIO I<bp> and it
returns 1 for success and 0 for failure.
These routines do not encrypt private keys and therefore offer no
=head1 NOTES
-The letters B<i> and B<d> in B<i2d_TYPE> stand for
+The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
"internal" (that is, an internal C structure) and "DER" respectively.
-So B<i2d_TYPE> converts from internal to DER.
+So B<i2d_I<TYPE>>() converts from internal to DER.
The functions can also understand B<BER> forms.
-The actual TYPE structure passed to i2d_TYPE() must be a valid
-populated B<TYPE> structure -- it B<cannot> simply be fed with an
+The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
+populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
empty structure such as that returned by TYPE_new().
-The encoded data is in binary form and may contain embedded zeroes.
+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 B<not> return the correct length
of the encoded structure.
-The ways that B<*in> and B<*out> are incremented after the operation
+The ways that I<*ppin> and I<*ppout> are incremented after the operation
can trap the unwary. See the B<WARNINGS> section for some common
errors.
The reason for this-auto increment behaviour is to reflect a typical
Represents a PKCS#3 DH parameters structure.
-=item B<DHparamx>
+=item B<DHxparams>
-Represents a ANSI X9.42 DH parameters structure.
+Represents an ANSI X9.42 DH parameters structure.
=item B<DSA_PUBKEY>
Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
-=item B<DSAPublicKey, DSAPrivateKey>
+=item B<DSAPublicKey>, B<DSAPrivateKey>
Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
-B<PEM_write_PrivateKey(3)>, or similar instead.
+L<PEM_write_PrivateKey(3)>, or similar instead.
+
+=item B<ECDSA_SIG>
+
+Represents an ECDSA signature.
=item B<RSAPublicKey>
=back
+=head1 RETURN VALUES
+
+B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
+B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
+been used with a valid structure being passed in via I<a>, then the object is
+freed in the event of error and I<*a> is set to NULL.
+
+B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
+value if an error occurs.
+
+B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
+error occurs.
+
=head1 EXAMPLES
Allocate and encode the DER encoding of an X509 structure:
...
OPENSSL_free(buf);
-This code will result in B<buf> apparently containing garbage because
+This code will result in I<buf> apparently containing garbage because
it was incremented after the call to point after the data just written.
-Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
+Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
and the subsequent call to OPENSSL_free() is likely to crash.
-Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
+Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>():
X509 *x;
/* error */
This will probably crash somewhere in d2i_X509(). The reason for this
-is that the variable B<x> is uninitialized and an attempt will be made to
+is that the variable I<x> is uninitialized and an attempt will be made to
interpret its (invalid) value as an B<X509> structure, typically causing
-a segmentation violation. If B<x> is set to NULL first then this will not
+a segmentation violation. If I<x> is set to NULL first then this will not
happen.
=head1 BUGS
-In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
-B<*px> is valid is broken and some parts of the reused structure may
-persist if they are not present in the new one. As a result the use
-of this "reuse" behaviour is strongly discouraged.
+In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when
+I<*a> 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 I<*a> on error and did not set I<*a> to NULL.
-i2d_TYPE() will not return an error in many versions of OpenSSL,
+As a result of the above issues the "reuse" behaviour is strongly discouraged.
+
+B<i2d_I<TYPE>>() 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 d2i_TYPE(). This may be
-fixed in future so code should not assume that i2d_TYPE() will
+fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be
+fixed in future so code should not assume that B<i2d_I<TYPE>>() will
always succeed.
-Any function which encodes a structure (i2d_TYPE(),
-i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
+Any function which encodes a structure (B<i2d_I<TYPE>>(),
+B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) 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.
-=head1 RETURN VALUES
-
-d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
-or B<NULL> if an error occurs. If the "reuse" capability has been used with
-a valid structure being passed in via B<a>, then the object is not freed in
-the event of error but may be in a potentially invalid or inconsistent state.
-
-i2d_TYPE() returns the number of bytes successfully encoded or a negative
-value if an error occurs.
-
-i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
-occurs.
-
=head1 COPYRIGHT
-Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 1998-2020 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+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
L<https://www.openssl.org/source/license.html>.
projects / openssl.git / blobdiff