=head1 NAME
d2i_ACCESS_DESCRIPTION,
+d2i_ADMISSIONS,
+d2i_ADMISSION_SYNTAX,
d2i_ASIdOrRange,
d2i_ASIdentifierChoice,
d2i_ASIdentifiers,
d2i_DSAPrivateKey_bio,
d2i_DSAPrivateKey_fp,
d2i_DSAPublicKey,
+d2i_DSA_PUBKEY,
d2i_DSA_PUBKEY_bio,
d2i_DSA_PUBKEY_fp,
d2i_DSA_SIG,
d2i_IPAddressOrRange,
d2i_IPAddressRange,
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_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_PublicKey,
d2i_RSAPrivateKey,
d2i_RSAPrivateKey_bio,
d2i_RSAPrivateKey_fp,
d2i_RSA_PUBKEY,
d2i_RSA_PUBKEY_bio,
d2i_RSA_PUBKEY_fp,
+d2i_SCRYPT_PARAMS,
d2i_SCT_LIST,
d2i_SXNET,
d2i_SXNETID,
d2i_X509_SIG,
d2i_X509_VAL,
i2d_ACCESS_DESCRIPTION,
+i2d_ADMISSIONS,
+i2d_ADMISSION_SYNTAX,
i2d_ASIdOrRange,
i2d_ASIdentifierChoice,
i2d_ASIdentifiers,
i2d_DSAPrivateKey_bio,
i2d_DSAPrivateKey_fp,
i2d_DSAPublicKey,
+i2d_DSA_PUBKEY,
i2d_DSA_PUBKEY_bio,
i2d_DSA_PUBKEY_fp,
i2d_DSA_SIG,
i2d_IPAddressOrRange,
i2d_IPAddressRange,
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_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_RSA_PUBKEY,
i2d_RSA_PUBKEY_bio,
i2d_RSA_PUBKEY_fp,
+i2d_SCRYPT_PARAMS,
i2d_SCT_LIST,
i2d_SXNET,
i2d_SXNETID,
=for comment 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
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
+d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a
+pointer to the B<TYPE> structure is returned and B<*ppin> 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.
to parse data from FILE pointer B<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.
+If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer
+at B<*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 B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded
+data written to it. In this case B<*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
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 B<*ppin> and B<*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
The following points about the data types might be useful:
-=over
+=over 4
=item B<ASN1_OBJECT>
=item B<DHparamx>
-Represents a ANSI X9.42 DH parameters structure.
+Represents an ANSI X9.42 DH parameters structure.
=item B<DSA_PUBKEY>
=item B<X509_ALGOR>
-Represents an B<AlogrithmIdentifier> structure as used in IETF RFC 6960 and
+Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and
elsewhere.
=item B<X509_Name>
=back
+=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 freed in
+the event of error and B<*a> is set to NULL.
+
+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 EXAMPLES
Allocate and encode the DER encoding of an X509 structure:
=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.
+B<*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 B<*a> on error and did not set B<*a> to NULL.
+
+As a result of the above issues the "reuse" behaviour is strongly discouraged.
i2d_TYPE() will not return an error in many versions of OpenSSL,
if mandatory fields are not initialized due to a programming error
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-2018 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