Make d2i_X509 a generic d2i/i2d manpage.
Pull common stuff out of other d2i/i2d docs.
Update find-doc-nits to know about "generic" manpages.
Cleanup some overlap.
Fix up a bunch of other references.
Reviewed-by: Matt Caswell <matt@openssl.org>
--- /dev/null
+=pod
+
+=head1 NAME
+
+ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off);
+ int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off);
+
+=head1 DESCRIPTION
+
+The ECPKParameters represent the public parameters for an
+B<EC_GROUP> structure, which represents a curve.
+
+The ECPKParameters_print() and ECPKParameters_print_fp() functions print
+a human-readable output of the public parameters of the EC_GROUP to B<bp>
+or B<fp>. The output lines are indented by B<off> spaces.
+
+=head1 RETURN VALUES
+
+ECPKParameters_print() and ECPKParameters_print_fp()
+return 1 for success and 0 if an error occurs.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
+L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
+L<EC_GFp_simple_method(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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>.
+
+=cut
=head1 NAME
-i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and
-reading EC_KEY structures
+EC_KEY_get_enc_flags, EC_KEY_set_enc_flags
+- Get and set flags for encoding EC_KEY structures
=head1 SYNOPSIS
#include <openssl/ec.h>
- EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len);
- int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out);
-
unsigned int EC_KEY_get_enc_flags(const EC_KEY *key);
void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
=head1 DESCRIPTION
-The ECPrivateKey encode and decode routines encode and parse an
-B<EC_KEY> structure into a binary format (ASN.1 DER) and back again.
-
-These functions are similar to the d2i_X509() functions, and you should refer to
-that page for a detailed description (see L<d2i_X509(3)>).
-
The format of the external representation of the public key written by
-i2d_ECPrivateKey (such as whether it is stored in a compressed form or not) is
+i2d_ECPrivateKey() (such as whether it is stored in a compressed form or not) is
described by the point_conversion_form. See L<EC_GROUP_copy(3)>
for a description of point_conversion_form.
When reading a private key encoded without an associated public key (e.g. if
-EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey generates
+EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey() generates
the missing public key automatically. Private keys encoded without parameters
(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using
-d2i_ECPrivateKey.
+d2i_ECPrivateKey().
-The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the
+The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the
value of the encoding flags for the B<key>. There are two encoding flags
currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags
define the behaviour of how the B<key> is converted into ASN1 in a call to
-i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for
+i2d_ECPrivateKey(). If EC_PKEY_NO_PARAMETERS is set then the public parameters for
the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is
set then the public key is not encoded along with the private key.
=head1 RETURN VALUES
-d2i_ECPrivateKey() returns a valid B<EC_KEY> structure or B<NULL> if an error
-occurs. The error code that can be obtained by
-L<ERR_get_error(3)>.
-
-i2d_ECPrivateKey() returns the number of bytes successfully encoded or a
-negative value if an error occurs. The error code can be obtained by
-L<ERR_get_error(3)>.
-
-EC_KEY_get_enc_flags returns the value of the current encoding flags for the
+EC_KEY_get_enc_flags() returns the value of the current encoding flags for the
EC_KEY.
=head1 SEE ALSO
=head1 NAME
-d2i_X509_ALGOR, i2d_X509_ALGOR, X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0, X509_ALGOR_set_md, X509_ALGOR_cmp - AlgorithmIdentifier functions
+X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0, X509_ALGOR_set_md, X509_ALGOR_cmp - AlgorithmIdentifier functions
=head1 SYNOPSIS
#include <openssl/x509.h>
- X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length);
- int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp);
X509_ALGOR *X509_ALGOR_dup(X509_ALGOR *alg);
int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *aobj, int ptype, void *pval);
void X509_ALGOR_get0(ASN1_OBJECT **paobj, int *pptype, void **ppval,
=head1 DESCRIPTION
-The functions d2i_X509() and i2d_X509() decode and encode an B<X509_ALGOR>
-structure which is equivalent to the B<AlgorithmIdentifier> structure.
-
-Otherwise they behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
X509_ALGOR_dup() returns a copy of B<alg>.
X509_ALGOR_set0() sets the algorithm OID of B<alg> to B<aobj> and the
X509_ALGOR_cmp() compares B<a> and B<b> and returns 0 if they have identical
encodings and non-zero otherwise.
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 NAME
-d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions
-
=head1 SYNOPSIS
#include <openssl/x509.h>
- X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length);
- int i2d_X509_NAME(X509_NAME *a, unsigned char **pp);
-
int X509_NAME_get0_der(const unsigned char **pder, size_t *pderlen,
X509_NAME *nm)
=head1 DESCRIPTION
-The functions d2i_X509_NAME() and i2d_X509_NAME() decode and encode an
-B<X509_NAME> structure which is the same as the B<Name> type defined in
-RFC3280 (and elsewhere) and used for example in certificate subject and
-issuer names.
-
-Otherwise the functions behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
The function X509_NAME_get0_der() returns an internal pointer to the
encoding of an B<X509_NAME> structure in B<*pder> and consisting of
B<*pderlen> bytes. It is useful for applications that wish to examine
=head1 RETURN VALUES
-The meanings of the return values of d2i_X509_NAME() and i2d_X509_NAME()
-are similar to those for d2i_X509() and i2d_X509().
-
The function X509_NAME_get0_der() returns 1 for success and 0 if an error
occurred.
=head1 NAME
-d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions
+X509_SIG_get0 - Get DigestInfo functions
=head1 SYNOPSIS
#include <openssl/x509.h>
- X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length);
- int i2d_X509_SIG(X509_SIG *a, unsigned char **pp);
void X509_SIG_get0(X509_ALGOR **palg, ASN1_OCTET_STRING **pdigest,
X509_SIG *sig);
=head1 DESCRIPTION
-The functions d2i_X509_SIG() and i2d_X509_SIG() decode and encode an
-X509_SIG structure which is equivalent to the B<DigestInfo> structure
-defined in PKCS#1 and PKCS#7.
-
-Otherwise they behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
X509_SIG_get0() returns pointers to the algorithm identifier and digest
value in B<sig>. These values can then be examined or initialised.
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions
-
-=head1 SYNOPSIS
-
- #include <openssl/objects.h>
-
- ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length);
- int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp);
-
-=head1 DESCRIPTION
-
-These functions decode and encode an ASN1 OBJECT IDENTIFIER.
-
-Otherwise these behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_CMS_ContentInfo, i2d_CMS_ContentInfo - CMS ContentInfo functions
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_ContentInfo *d2i_CMS_ContentInfo(CMS_ContentInfo **a, unsigned char **pp, long length);
- int i2d_CMS_ContentInfo(CMS_ContentInfo *a, unsigned char **pp);
-
-=head1 DESCRIPTION
-
-These functions decode and encode an CMS ContentInfo structure.
-
-Otherwise they behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey,
-d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams,
-d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding and parsing functions
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length);
-
- int i2d_DSAPublicKey(const DSA *a, unsigned char **pp);
-
- DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length);
-
- int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp);
-
- DSA *d2i_DSA_PUBKEY_bio(BIO *bp, DSA **dsa);
- DSA *d2i_DSA_PUBKEY_fp(FILE *fp, DSA **dsa);
-
- int i2d_DSA_PUBKEY_bio(BIO *bp, DSA *dsa);
- int i2d_DSA_PUBKEY_fp(FILE *fp, DSA *dsa);
-
- DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length);
-
- int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp);
-
- DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length);
-
- int i2d_DSAparams(const DSA *a, unsigned char **pp);
-
- DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length);
-
- int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp);
-
-=head1 DESCRIPTION
-
-d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key
-components structure.
-
-d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using
-a SubjectPublicKeyInfo (certificate public key) structure.
-
-d2i_DSA_PUBKEY_bio(), d2i_DSA_PUBKEY_fp(), i2d_DSA_PUBKEY_bio() and
-i2d_DSA_PUBKEY_fp() are similar to d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY()
-except they decode or encode using a B<BIO> or B<FILE> pointer.
-
-d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key
-components.
-
-d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using
-a B<Dss-Parms> structure as defined in RFC2459.
-
-d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a
-B<Dss-Sig-Value> structure as defined in RFC2459.
-
-The usage of all of these functions is similar to the d2i_X509() and
-i2d_X509() described in the L<d2i_X509(3)> manual page.
-
-=head1 NOTES
-
-The B<DSA> structure passed to the private key encoding functions should have
-all the private key components present.
-
-The data encoded by the private key functions is unencrypted and therefore
-offers no private key security.
-
-The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey>
-functions when encoding public keys because they use a standard format.
-
-The B<DSAPublicKey> functions use a non standard format which is a
-B<SEQUENCE> consisting of the B<p>, B<q>, B<g> and B<pub_key> fields
-respectively.
-
-The B<DSAPrivateKey> functions also use a non standard structure consisting
-consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and
-B<priv_key> fields respectively.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len);
- int i2d_ECPKParameters(const EC_GROUP *x, unsigned char **out);
- #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x)
- #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x)
- #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \
- (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x))
- #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \
- (unsigned char *)(x))
- int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off);
- int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off);
-
-
-=head1 DESCRIPTION
-
-The ECPKParameters encode and decode routines encode and parse the public parameters for an
-B<EC_GROUP> structure, which represents a curve.
-
-d2i_ECPKParameters() attempts to decode B<len> bytes at B<*in>. If
-successful a pointer to the B<EC_GROUP> structure is returned. If an error
-occurred then B<NULL> is returned. If B<px> is not B<NULL> then the
-returned structure is written to B<*px>. If B<*px> is not B<NULL>
-then it is assumed that B<*px> contains a valid B<EC_GROUP>
-structure and an attempt is made to reuse it. If the call is
-successful B<*in> is incremented to the byte following the
-parsed data.
-
-i2d_ECPKParameters() encodes the structure pointed to by B<x> into DER format.
-If B<out> is not B<NULL> is writes the DER encoded data to the buffer
-at B<*out>, 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 to
-the start of the data just written.
-
-d2i_ECPKParameters_bio() is similar to d2i_ECPKParameters() except it attempts
-to parse data from BIO B<bp>.
-
-d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts
-to parse data from FILE pointer B<fp>.
-
-i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes
-the encoding of the structure B<x> to BIO B<bp> and it
-returns 1 for success and 0 for failure.
-
-i2d_ECPKParameters_fp() is similar to i2d_ECPKParameters() except it writes
-the encoding of the structure B<x> to BIO B<bp> and it
-returns 1 for success and 0 for failure.
-
-These functions are very similar to the X509 functions described in L<d2i_X509(3)>,
-where further notes and examples are available.
-
-The ECPKParameters_print and ECPKParameters_print_fp functions print a human-readable output
-of the public parameters of the EC_GROUP to B<bp> or B<fp>. The output lines are indented by B<off> spaces.
-
-=head1 RETURN VALUES
-
-d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B<EC_GROUP> structure
-or B<NULL> if an error occurs.
-
-i2d_ECPKParameters() returns the number of bytes successfully encoded or a negative
-value if an error occurs.
-
-i2d_ECPKParameters_bio(), i2d_ECPKParameters_fp(), ECPKParameters_print and ECPKParameters_print_fp
-return 1 for success and 0 if an error occurs.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
-L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)>, L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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>.
-
-=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+i2d_Netscape_RSA,
+d2i_Netscape_RSA
+- insecure RSA public and private key encoding functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
+ RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)());
+
+=head1 DESCRIPTION
+
+These functions decode and encode an RSA private
+key in NET format. These functions are present to provide compatibility
+with very old software. This format has some severe security weaknesses
+and should be avoided if possible.
+
+These functions are similar to the B<d2i_RSAPrivateKey> functions.
+
+=head1 SEE ALSO
+
+L<d2i_RSAPrivateKey(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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>.
+
+=cut
=head1 NAME
-d2i_Private_key, d2i_AutoPrivateKey, i2d_PrivateKey - decode and encode
-functions for reading and saving EVP_PKEY structures
+d2i_Private_key, d2i_AutoPrivateKey, i2d_PrivateKey,
+d2i_PrivateKey_bio, d2i_PrivateKey_fp
+- decode and encode functions for reading and saving EVP_PKEY structures
=head1 SYNOPSIS
long length);
int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp);
+ EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a);
+ EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a)
+
=head1 DESCRIPTION
d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to
i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is
defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format.
-These functions are similar to the d2i_X509() functions, and you should refer to
-that page for a detailed description (see L<d2i_X509(3)>).
+These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>.
=head1 NOTES
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey,
-d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp,
-i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp, i2d_Netscape_RSA,
-d2i_Netscape_RSA - RSA public and private key encoding functions
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length);
-
- int i2d_RSAPublicKey(RSA *a, unsigned char **pp);
-
- RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length);
-
- int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp);
-
- RSA *d2i_RSA_PUBKEY_bio(BIO *bp, RSA **rsa);
- RSA *d2i_RSA_PUBKEY_fp(FILE *fp, RSA **rsa);
-
- int i2d_RSA_PUBKEY_bio(BIO *bp, RSA *rsa);
- int i2d_RSA_PUBKEY_fp(FILE *fp, RSA *rsa);
-
- RSA * d2i_RSAPrivateKey(RSA **a, const unsigned char **pp, long length);
-
- int i2d_RSAPrivateKey(RSA *a, unsigned char **pp);
-
- int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
-
- RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)());
-
-=head1 DESCRIPTION
-
-d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1
-RSAPublicKey structure.
-
-d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using
-a SubjectPublicKeyInfo (certificate public key) structure.
-
-d2i_RSA_PUBKEY_bio(), d2i_RSA_PUBKEY_fp(), i2d_RSA_PUBKEY_bio() and
-i2d_RSA_PUBKEY_fp() are similar to d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY()
-except they decode or encode using a B<BIO> or B<FILE> pointer.
-
-d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1
-RSAPrivateKey structure.
-
-d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in
-NET format.
-
-The usage of all of these functions is similar to the d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
-=head1 NOTES
-
-The B<RSA> structure passed to the private key encoding functions should have
-all the PKCS#1 private key components present.
-
-The data encoded by the private key functions is unencrypted and therefore
-offers no private key security.
-
-The NET format functions are present to provide compatibility with certain very
-old software. This format has some severe security weaknesses and should be
-avoided if possible.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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>.
-
-=cut
=head1 NAME
-d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio,
-i2d_X509_fp - X509 encode and decode functions
+d2i_ACCESS_DESCRIPTION,
+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_bio,
+d2i_DSA_PUBKEY_fp,
+d2i_DSA_SIG,
+d2i_DSAparams,
+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_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_PROXY_CERT_INFO_EXTENSION,
+d2i_PROXY_POLICY,
+d2i_PublicKey,
+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_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_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_bio,
+i2d_DSA_PUBKEY_fp,
+i2d_DSA_SIG,
+i2d_DSAparams,
+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_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_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_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
+
+=for comment generic
=head1 SYNOPSIS
- #include <openssl/x509.h>
+ TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length);
+ TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
+ TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
- X509 *d2i_X509(X509 **px, const unsigned char **in, long len);
- X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len);
- int i2d_X509(X509 *x, unsigned char **out);
- int i2d_X509_AUX(X509 *x, unsigned char **out);
+ int i2d_TYPE(TYPE *a, unsigned char **pp);
+ int i2d_TYPE_fp(FILE *fp, TYPE *a);
+ int i2d_TYPE_bio(BIO *bp, TYPE *a);
- X509 *d2i_X509_bio(BIO *bp, X509 **x);
- X509 *d2i_X509_fp(FILE *fp, X509 **x);
-
- int i2d_X509_bio(BIO *bp, X509 *x);
- int i2d_X509_fp(FILE *fp, X509 *x);
+=head1 DESCRIPTION
- int i2d_re_X509_tbs(X509 *x, unsigned char **out);
+In the description here, I<TYPE> is used a placeholder
+for any of the OpenSSL datatypes, such as I<X509_CRL>.
-=head1 DESCRIPTION
+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.
-The X509 encode and decode routines encode and parse an
-B<X509> structure, which represents an X509 certificate.
+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.
-d2i_X509() attempts to decode B<len> bytes at B<*in>. If
-successful a pointer to the B<X509> structure is returned. If an error
-occurred then B<NULL> is returned. If B<px> is not B<NULL> then the
-returned structure is written to B<*px>. If B<*px> is not B<NULL>
-then it is assumed that B<*px> contains a valid B<X509>
-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).
+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
+"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).
-If the call is successful B<*in> is incremented to the byte following the
-parsed data.
+d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
+to parse data from BIO B<bp>.
-d2i_X509_AUX() is similar to d2i_X509() but the input is expected to consist of
-an X509 certificate followed by auxiliary trust information.
-This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects.
-This function should not be called on untrusted input.
+d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
+to parse data from FILE pointer B<fp>.
-i2d_X509() encodes the structure pointed to by B<x> into DER format.
-If B<out> is not B<NULL> is writes the DER encoded data to the buffer
+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 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 to the start of the
-data just written.
-
-i2d_X509_AUX() is similar to i2d_X509(), but the encoded output contains both
-the certificate and any auxiliary trust information.
-This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects.
-Note, this is a non-standard OpenSSL-specific data format.
-
-d2i_X509_bio() is similar to d2i_X509() except it attempts
-to parse data from BIO B<bp>.
-
-d2i_X509_fp() is similar to d2i_X509() except it attempts
-to parse data from FILE pointer B<fp>.
+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
+to the start of the data just written.
-i2d_X509_bio() is similar to i2d_X509() except it writes
-the encoding of the structure B<x> to BIO B<bp> and it
+i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
+the encoding of the structure B<a> to BIO B<bp> and it
returns 1 for success and 0 for failure.
-i2d_X509_fp() is similar to i2d_X509() except it writes
-the encoding of the structure B<x> to BIO B<bp> and it
+i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
+the encoding of the structure B<a> to BIO B<bp> and it
returns 1 for success and 0 for failure.
-i2d_re_X509_tbs() is similar to i2d_X509() except it encodes
-only the TBSCertificate portion of the certificate.
+These routines do not encrypt private keys and therefore offer no
+security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
=head1 NOTES
-The letters B<i> and B<d> in for example B<i2d_X509> stand for
-"internal" (that is an internal C structure) and "DER". So
-B<i2d_X509> converts from internal to DER. The "re" in
-B<i2d_re_X509_tbs> stands for "re-encode", and ensures that a fresh
-encoding is generated in case the object has been modified after
-creation (see the BUGS section).
+The letters B<i> and B<d> in B<i2d_TYPE> stand for
+"internal" (that is, an internal C structure) and "DER" respectively.
+So B<i2d_TYPE> converts from internal to DER.
The functions can also understand B<BER> forms.
-The actual X509 structure passed to i2d_X509() must be a valid
-populated B<X509> structure it can B<not> simply be fed with an
-empty structure such as that returned by X509_new().
+The actual TYPE structure passed to i2d_TYPE() must be a valid
+populated B<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.
Therefore any FILE pointers or BIOs should be opened in binary mode.
The ways that B<*in> and B<*out> are incremented after the operation
can trap the unwary. See the B<WARNINGS> section for some common
errors.
-
-The reason for the auto increment behaviour is to reflect a typical
+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 processed after it.
+another will be processed after it.
+
+The following points about the data types might be useful:
+
+=over
+
+=item B<ASN1_OBJECT>
+
+Represents an ASN1 OBJECT IDENTIFIER.
+
+=item B<DHparams>
+
+Represents a PKCS#3 DH parameters structure.
+
+=item B<DHparamx>
+
+Represents a ANSI X9.42 DH parameters structure.
+
+=item B<DSA_PUBKEY>
+
+Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
+
+=item B<DSAPublicKey, DSAPrivateKey>
+
+Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
+B<PEM_write_PrivateKey(3)>, or similar instead.
+
+=item B<RSAPublicKey>
+
+Represents a PKCS#1 RSA public key structure.
+
+=item B<X509_ALGOR>
+
+Represents an B<AlogrithmIdentifier> structure as used in IETF RFC 6960 and
+elsewhere.
+
+=item B<X509_Name>
+
+Represents a B<Name> type as used for subject and issuer names in
+IETF RFC 6960 and elsewhere.
+
+=item B<X509_REQ>
+
+Represents a PKCS#10 certificate request.
+
+=item B<X509_SIG>
+
+Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
+
+=back
=head1 EXAMPLES
buf = NULL;
len = i2d_X509(x, &buf);
if (len < 0)
- /* error */
+ /* error */
Attempt to decode a buffer:
unsigned char *buf, *p;
int len;
- /* Something to setup buf and len */
+ /* Set up buf and len to point to the input buffer. */
p = buf;
x = d2i_X509(NULL, &p, len);
-
if (x == NULL)
- /* Some error */
+ /* error */
Alternative technique:
unsigned char *buf, *p;
int len;
- /* Something to setup buf and len */
+ /* Set up buf and len to point to the input buffer. */
p = buf;
x = NULL;
- if (!d2i_X509(&x, &p, len))
- /* Some error */
-
+ if (d2i_X509(&x, &p, len) == NULL)
+ /* error */
=head1 WARNINGS
-The use of temporary variable is mandatory. A common
+Using a temporary variable is mandatory. A common
mistake is to attempt to use a buffer directly as follows:
int len;
len = i2d_X509(x, NULL);
buf = OPENSSL_malloc(len);
- if (buf == NULL)
- /* error */
-
+ ...
i2d_X509(x, &buf);
- /* Other stuff ... */
+ ...
OPENSSL_free(buf);
This code will result in B<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()
-and the subsequent call to OPENSSL_free() may well crash.
+and the subsequent call to OPENSSL_free() is likely to crash.
-Another trap to avoid is misuse of the B<xp> argument to d2i_X509():
+Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
X509 *x;
- if (!d2i_X509(&x, &p, len))
- /* Some error */
+ if (d2i_X509(&x, &p, len) == NULL)
+ /* 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
=head1 BUGS
-In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when
+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.
-i2d_X509() will not return an error in many versions of OpenSSL,
+i2d_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_X509(). This may be
-fixed in future so code should not assume that i2d_X509() will
+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
always succeed.
-The encoding of the TBSCertificate portion of a certificate is cached
-in the B<X509> structure internally to improve encoding performance
-and to ensure certificate signatures are verified correctly in some
-certificates with broken (non-DER) encodings.
+Any function which encodes a structure (i2d_TYPE(),
+i2d_TYPE() or i2d_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.
-Any function which encodes an X509 structure such as i2d_X509(),
-i2d_X509_fp() or i2d_X509_bio() may return a stale encoding if the
-B<X509> structure has been modified after deserialization or previous
-serialization.
+=head1 RETURN VALUES
-If, after modification, the B<X509> object is re-signed with X509_sign(),
-the encoding is automatically renewed. Otherwise, the encoding of the
-TBSCertificate portion of the B<X509> can be manually renewed by calling
-i2d_re_X509_tbs().
+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.
-=head1 RETURN VALUES
+i2d_TYPE() returns the number of bytes successfully encoded or a negative
+value if an error occurs.
-d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure
-or B<NULL> if an error occurs. The error code that can be obtained by
-L<ERR_get_error(3)>. If the "reuse" capability has been used
-with a valid X509 structure being passed in via B<px> then the object is not
-freed in the event of error but may be in a potentially invalid or inconsistent
-state.
-
-i2d_X509() returns the number of bytes successfully encoded or a negative
-value if an error occurs. The error code can be obtained by
-L<ERR_get_error(3)>.
-
-i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error
-occurs The error code can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
+i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
+occurs.
=head1 COPYRIGHT
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_X509_CRL_fp,
-i2d_X509_CRL_bio, i2d_X509_CRL_fp, i2d_re_X509_CRL_tbs - CRL functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- X509_CRL *d2i_X509_CRL(X509_CRL **a, const unsigned char **pp, long length);
- int i2d_X509_CRL(X509_CRL *a, unsigned char **pp);
-
- X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x);
- X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x);
-
- int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x);
- int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x);
-
- int i2d_re_X509_CRL_tbs(X509_CRL *x, unsigned char **out);
-
-=head1 DESCRIPTION
-
-These functions decode and encode an X509 CRL (certificate revocation
-list).
-
-Otherwise the functions behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp,
-i2d_X509_REQ_bio, i2d_X509_REQ_fp, i2d_re_X509_REQ_tbs - PKCS#10 certificate
-request functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- X509_REQ *d2i_X509_REQ(X509_REQ **a, const unsigned char **pp, long length);
- int i2d_X509_REQ(X509_REQ *a, unsigned char **pp);
-
- X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x);
- X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x);
-
- int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x);
- int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x);
-
- int i2d_re_X509_REQ_tbs(X509_REQ *x, unsigned char **out);
-
-=head1 DESCRIPTION
-
-These functions decode and encode a PKCS#10 certificate request.
-
-Otherwise these behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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>.
-
-=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+d2i_X509_AUX, i2d_X509_AUX,
+i2d_re_X509_tbs, i2d_re_X509_CRL_tbs, i2d_re_X509_REQ_tbs
+- X509 encode and decode functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len);
+ int i2d_X509_AUX(X509 *x, unsigned char **out);
+ int i2d_re_X509_tbs(X509 *x, unsigned char **out);
+ int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **pp);
+ int i2d_re_X509_REQ_tbs(X509_REQ *req, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+The X509 encode and decode routines encode and parse an
+B<X509> structure, which represents an X509 certificate.
+
+d2i_X509_AUX() is similar to L<d2i_X509(3)> but the input is expected to
+consist of an X509 certificate followed by auxiliary trust information.
+This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects.
+This function should not be called on untrusted input.
+
+i2d_X509_AUX() is similar to L<i2d_X509(3)>, but the encoded output
+contains both the certificate and any auxiliary trust information.
+This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects.
+Note that this is a non-standard OpenSSL-specific data format.
+
+i2d_re_X509_tbs() is similar to L<i2d_X509(3)> except it encodes only
+the TBSCertificate portion of the certificate. i2d_re_X509_CRL_tbs()
+and i2d_re_X509_REQ_tbs() are analogous for CRL and certificate request,
+respectively. The "re" in B<i2d_re_X509_tbs> stands for "re-encode",
+and ensures that a fresh encoding is generated in case the object has been
+modified after creation (see the BUGS section).
+
+The encoding of the TBSCertificate portion of a certificate is cached
+in the B<X509> structure internally to improve encoding performance
+and to ensure certificate signatures are verified correctly in some
+certificates with broken (non-DER) encodings.
+
+If, after modification, the B<X509> object is re-signed with X509_sign(),
+the encoding is automatically renewed. Otherwise, the encoding of the
+TBSCertificate portion of the B<X509> can be manually renewed by calling
+i2d_re_X509_tbs().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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>.
+
+=cut
=head1 DESCRIPTION
-d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS
-session, stored as binary data at location B<pp> with length B<length>, into
-an SSL_SESSION object.
-
-i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1
-representation and stores it into the memory location pointed to by B<pp>.
-The length of the resulting ASN1 representation is returned. If B<pp> is
-the NULL pointer, only the length is calculated and returned.
-
-=head1 NOTES
-
-The SSL_SESSION object is built from several malloc()ed parts, it can
-therefore not be moved, copied or stored directly. In order to store
-session data on disk or into a database, it must be transformed into
-a binary ASN1 representation.
-
-When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically
-allocated. The reference count is 1, so that the session must be
-explicitly removed using L<SSL_SESSION_free(3)>,
-unless the SSL_SESSION object is completely taken over, when being called
-inside the get_session_cb() (see
-L<SSL_CTX_sess_set_get_cb(3)>).
+These functions decode and encode an SSL_SESSION object.
+For encoding details see L<d2i_X509(3)>.
SSL_SESSION objects keep internal link information about the session cache
list, when being inserted into one SSL_CTX object's session cache.
only be used with one SSL_CTX object (and the SSL objects created
from this SSL_CTX object).
-When using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be
-large enough to hold the binary representation of the session. There is no
-known limit on the size of the created ASN1 representation, so the necessary
-amount of space should be obtained by first calling i2d_SSL_SESSION() with
-B<pp=NULL>, and obtain the size needed, then allocate the memory and
-call i2d_SSL_SESSION() again.
-Note that this will advance the value contained in B<*pp> so it is necessary
-to save a copy of the original allocation.
-For example:
- int i,j;
- char *p, *temp;
- i = i2d_SSL_SESSION(sess, NULL);
- p = temp = malloc(i);
- j = i2d_SSL_SESSION(sess, &temp);
- assert(i == j);
- assert(p+i == temp);
-
=head1 RETURN VALUES
d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION
=head1 SEE ALSO
L<ssl(3)>, L<SSL_SESSION_free(3)>,
-L<SSL_CTX_sess_set_get_cb(3)>
+L<SSL_CTX_sess_set_get_cb(3)>,
+L<d2i_X509(3)>
=head1 COPYRIGHT
my $id = "${filename}:1:";
- &name_synopsis($id, $filename, $contents);
+ &name_synopsis($id, $filename, $contents)
+ unless $contents =~ /=for comment generic/;
print "$id doesn't start with =pod\n"
if $contents !~ /^=pod/;
projects / openssl.git / commitdiff