wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Unify d2i/i2d documentation.

Browse source 
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>
This commit is contained in:
Rich Salz 2016-06-07 15:49:08 -04:00
parent fbba5d113f
commit 4692340e31
18 changed files with 658 additions and 667 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
doc/crypto/ECPKParameters_print.pod Normal file
View file

@ -0,0 +1,43 @@
=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

33
doc/crypto/d2i_ECPrivateKey.pod → doc/crypto/EC_KEY_get_enc_flags.pod
View file

@ -2,57 +2,40 @@
=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

14
doc/crypto/d2i_X509_ALGOR.pod → doc/crypto/X509_ALGOR_dup.pod
View file

@ -2,14 +2,12 @@
=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,
@ -19,12 +17,6 @@ d2i_X509_ALGOR, i2d_X509_ALGOR, X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0
=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
@ -44,10 +36,6 @@ values for the message digest B<md>.
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.

16
doc/crypto/d2i_X509_NAME.pod → doc/crypto/X509_NAME_get0_der.pod
View file

@ -2,29 +2,16 @@
=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
@ -32,9 +19,6 @@ the encoding of an B<X509_NAME> structure without copying it.
=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.

11
doc/crypto/d2i_X509_SIG.pod → doc/crypto/X509_SIG_get0.pod
View file

@ -2,26 +2,17 @@
=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.

34
doc/crypto/d2i_ASN1_OBJECT.pod
View file

@ -1,34 +0,0 @@
=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

34
doc/crypto/d2i_CMS_ContentInfo.pod
View file

@ -1,34 +0,0 @@
=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

95
doc/crypto/d2i_DSAPublicKey.pod
View file

@ -1,95 +0,0 @@
=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

93
doc/crypto/d2i_ECPKParameters.pod
View file

@ -1,93 +0,0 @@
=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

38
doc/crypto/d2i_Netscape_RSA.pod Normal file
View file

@ -0,0 +1,38 @@
=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

11
doc/crypto/d2i_PrivateKey.pod
View file

@ -2,8 +2,9 @@
=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
@ -15,6 +16,9 @@ functions for reading and saving EVP_PKEY structures
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
@ -28,8 +32,7 @@ automatically detect the private key format.
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

82
doc/crypto/d2i_RSAPublicKey.pod
View file

@ -1,82 +0,0 @@
=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

607
doc/crypto/d2i_X509.pod
View file

@ -2,95 +2,425 @@
=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);
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);
int i2d_re_X509_tbs(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);
=head1 DESCRIPTION
The X509 encode and decode routines encode and parse an
B<X509> structure, which represents an X509 certificate.
In the description here, I<TYPE> is used a placeholder
for any of the OpenSSL datatypes, such as I<X509_CRL>.
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).
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.
If the call is successful B<*in> is incremented to the byte following the
parsed data.
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_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.
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).
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
d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
to parse data from BIO B<bp>.
d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
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 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.
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>.
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.
@ -100,10 +430,58 @@ of the encoded structure.
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
@ -115,7 +493,7 @@ Allocate and encode the DER encoding of an X509 structure:
buf = NULL;
len = i2d_X509(x, &buf);
if (len < 0)
/* error */
/* error */
Attempt to decode a buffer:
@ -123,12 +501,11 @@ 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:
@ -136,17 +513,16 @@ 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;
@ -154,24 +530,22 @@ mistake is to attempt to use a buffer directly as follows:
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
@ -181,71 +555,40 @@ happen.
=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 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.
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().
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.
=head1 RETURN VALUES
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.
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_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_TYPE() returns the number of bytes successfully encoded or a negative
value if an error occurs.
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

44
doc/crypto/d2i_X509_CRL.pod
View file

@ -1,44 +0,0 @@
=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

44
doc/crypto/d2i_X509_REQ.pod
View file

@ -1,44 +0,0 @@
=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

79
doc/crypto/i2d_re_X509_tbs.pod Normal file
View file

@ -0,0 +1,79 @@
=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

44
doc/ssl/d2i_SSL_SESSION.pod
View file

@ -13,28 +13,8 @@ d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 repre
=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.
@ -42,23 +22,6 @@ One SSL_SESSION object, regardless of its reference count, must therefore
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
@ -71,7 +34,8 @@ When the session is not valid, B<0> is returned and no operation is performed.
=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

3
util/find-doc-nits.pl
View file

@ -100,7 +100,8 @@ sub check()
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/;