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 =head1 NAME
i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and EC_KEY_get_enc_flags, EC_KEY_set_enc_flags
reading EC_KEY structures - Get and set flags for encoding EC_KEY structures
=head1 SYNOPSIS =head1 SYNOPSIS
#include <openssl/ec.h> #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); unsigned int EC_KEY_get_enc_flags(const EC_KEY *key);
void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
=head1 DESCRIPTION =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 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)> described by the point_conversion_form. See L<EC_GROUP_copy(3)>
for a description of point_conversion_form. for a description of point_conversion_form.
When reading a private key encoded without an associated public key (e.g. if 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 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 (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 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 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 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 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. set then the public key is not encoded along with the private key.
=head1 RETURN VALUES =head1 RETURN VALUES
d2i_ECPrivateKey() returns a valid B<EC_KEY> structure or B<NULL> if an error EC_KEY_get_enc_flags() returns the value of the current encoding flags for the
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. EC_KEY.
=head1 SEE ALSO =head1 SEE ALSO

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

@ -2,14 +2,12 @@
=head1 NAME =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 =head1 SYNOPSIS
#include <openssl/x509.h> #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); X509_ALGOR *X509_ALGOR_dup(X509_ALGOR *alg);
int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *aobj, int ptype, void *pval); 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, 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 =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_dup() returns a copy of B<alg>.
X509_ALGOR_set0() sets the algorithm OID of B<alg> to B<aobj> and the 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 X509_ALGOR_cmp() compares B<a> and B<b> and returns 0 if they have identical
encodings and non-zero otherwise. encodings and non-zero otherwise.
=head1 SEE ALSO
L<d2i_X509(3)>
=head1 COPYRIGHT =head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. 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 =head1 NAME
d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions
=head1 SYNOPSIS =head1 SYNOPSIS
#include <openssl/x509.h> #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, int X509_NAME_get0_der(const unsigned char **pder, size_t *pderlen,
X509_NAME *nm) X509_NAME *nm)
=head1 DESCRIPTION =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 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 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 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 =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 The function X509_NAME_get0_der() returns 1 for success and 0 if an error
occurred. occurred.

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

@ -2,26 +2,17 @@
=head1 NAME =head1 NAME
d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions X509_SIG_get0 - Get DigestInfo functions
=head1 SYNOPSIS =head1 SYNOPSIS
#include <openssl/x509.h> #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, void X509_SIG_get0(X509_ALGOR **palg, ASN1_OCTET_STRING **pdigest,
X509_SIG *sig); X509_SIG *sig);
=head1 DESCRIPTION =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 X509_SIG_get0() returns pointers to the algorithm identifier and digest
value in B<sig>. These values can then be examined or initialised. 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 =head1 NAME
d2i_Private_key, d2i_AutoPrivateKey, i2d_PrivateKey - decode and encode d2i_Private_key, d2i_AutoPrivateKey, i2d_PrivateKey,
functions for reading and saving EVP_PKEY structures d2i_PrivateKey_bio, d2i_PrivateKey_fp
- decode and encode functions for reading and saving EVP_PKEY structures
=head1 SYNOPSIS =head1 SYNOPSIS
@ -15,6 +16,9 @@ functions for reading and saving EVP_PKEY structures
long length); long length);
int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp); 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 =head1 DESCRIPTION
d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to 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 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. defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format.
These functions are similar to the d2i_X509() functions, and you should refer to These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>.
that page for a detailed description (see L<d2i_X509(3)>).
=head1 NOTES =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 =head1 NAME
d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, d2i_ACCESS_DESCRIPTION,
i2d_X509_fp - X509 encode and decode functions 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 =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); int i2d_TYPE(TYPE *a, unsigned char **pp);
X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); int i2d_TYPE_fp(FILE *fp, TYPE *a);
int i2d_X509(X509 *x, unsigned char **out); int i2d_TYPE_bio(BIO *bp, TYPE *a);
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);
=head1 DESCRIPTION =head1 DESCRIPTION
The X509 encode and decode routines encode and parse an In the description here, I<TYPE> is used a placeholder
B<X509> structure, which represents an X509 certificate. for any of the OpenSSL datatypes, such as I<X509_CRL>.
d2i_X509() attempts to decode B<len> bytes at B<*in>. If These functions convert OpenSSL objects to and from their ASN.1/DER
successful a pointer to the B<X509> structure is returned. If an error encoding. Unlike the C structures which can have pointers to sub-objects
occurred then B<NULL> is returned. If B<px> is not B<NULL> then the within, the DER is a serialized encoding, suitable for sending over the
returned structure is written to B<*px>. If B<*px> is not B<NULL> network, writing to a file, and so on.
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).
If the call is successful B<*in> is incremented to the byte following the d2i_TYPE() attempts to decode B<len> bytes at B<*in>. If successful a
parsed data. 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 On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
an X509 certificate followed by auxiliary trust information. contains a valid B<TYPE> structure and an attempt is made to reuse it. This
This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. "reuse" capability is present for historical compatibility but its use is
This function should not be called on untrusted input. 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. d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
If B<out> is not B<NULL> is writes the DER encoded data to the buffer 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. at B<*out>, and increments it to point after the data just written.
If the return value is negative an error occurred, otherwise it If the return value is negative an error occurred, otherwise it
returns the length of the encoded data. returns the length of the encoded data.
If B<*out> is B<NULL> memory will be If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded
allocated for a buffer and the encoded data written to it. In this data written to it. In this case B<*out> is not incremented and it points
case B<*out> is not incremented and it points to the start of the to the start of the data just written.
data just written.
i2d_X509_AUX() is similar to i2d_X509(), but the encoded output contains both i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
the certificate and any auxiliary trust information. the encoding of the structure B<a> to BIO B<bp> and it
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
returns 1 for success and 0 for failure. returns 1 for success and 0 for failure.
i2d_X509_fp() is similar to i2d_X509() except it writes i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
the encoding of the structure B<x> to BIO B<bp> and it the encoding of the structure B<a> to BIO B<bp> and it
returns 1 for success and 0 for failure. returns 1 for success and 0 for failure.
i2d_re_X509_tbs() is similar to i2d_X509() except it encodes These routines do not encrypt private keys and therefore offer no
only the TBSCertificate portion of the certificate. security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
=head1 NOTES =head1 NOTES
The letters B<i> and B<d> in for example B<i2d_X509> stand for The letters B<i> and B<d> in B<i2d_TYPE> stand for
"internal" (that is an internal C structure) and "DER". So "internal" (that is, an internal C structure) and "DER" respectively.
B<i2d_X509> converts from internal to DER. The "re" in So B<i2d_TYPE> converts from internal to DER.
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 functions can also understand B<BER> forms. The functions can also understand B<BER> forms.
The actual X509 structure passed to i2d_X509() must be a valid The actual TYPE structure passed to i2d_TYPE() must be a valid
populated B<X509> structure it can B<not> simply be fed with an populated B<TYPE> structure -- it B<cannot> simply be fed with an
empty structure such as that returned by X509_new(). empty structure such as that returned by TYPE_new().
The encoded data is in binary form and may contain embedded zeroes. The encoded data is in binary form and may contain embedded zeroes.
Therefore any FILE pointers or BIOs should be opened in binary mode. 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 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 can trap the unwary. See the B<WARNINGS> section for some common
errors. errors.
The reason for this-auto increment behaviour is to reflect a typical
The reason for the auto increment behaviour is to reflect a typical
usage of ASN1 functions: after one structure is encoded or decoded 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 =head1 EXAMPLES
@ -115,7 +493,7 @@ Allocate and encode the DER encoding of an X509 structure:
buf = NULL; buf = NULL;
len = i2d_X509(x, &buf); len = i2d_X509(x, &buf);
if (len < 0) if (len < 0)
/* error */ /* error */
Attempt to decode a buffer: Attempt to decode a buffer:
@ -123,12 +501,11 @@ Attempt to decode a buffer:
unsigned char *buf, *p; unsigned char *buf, *p;
int len; int len;
/* Something to setup buf and len */ /* Set up buf and len to point to the input buffer. */
p = buf; p = buf;
x = d2i_X509(NULL, &p, len); x = d2i_X509(NULL, &p, len);
if (x == NULL) if (x == NULL)
/* Some error */ /* error */
Alternative technique: Alternative technique:
@ -136,17 +513,16 @@ Alternative technique:
unsigned char *buf, *p; unsigned char *buf, *p;
int len; int len;
/* Something to setup buf and len */ /* Set up buf and len to point to the input buffer. */
p = buf; p = buf;
x = NULL; x = NULL;
if (!d2i_X509(&x, &p, len)) if (d2i_X509(&x, &p, len) == NULL)
/* Some error */ /* error */
=head1 WARNINGS =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: mistake is to attempt to use a buffer directly as follows:
int len; int len;
@ -154,24 +530,22 @@ mistake is to attempt to use a buffer directly as follows:
len = i2d_X509(x, NULL); len = i2d_X509(x, NULL);
buf = OPENSSL_malloc(len); buf = OPENSSL_malloc(len);
if (buf == NULL) ...
/* error */
i2d_X509(x, &buf); i2d_X509(x, &buf);
/* Other stuff ... */ ...
OPENSSL_free(buf); OPENSSL_free(buf);
This code will result in B<buf> apparently containing garbage because This code will result in B<buf> apparently containing garbage because
it was incremented after the call to point after the data just written. it was incremented after the call to point after the data just written.
Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc() Also 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; X509 *x;
if (!d2i_X509(&x, &p, len)) if (d2i_X509(&x, &p, len) == NULL)
/* Some error */ /* error */
This will probably crash somewhere in d2i_X509(). The reason for this This will probably crash somewhere in d2i_X509(). The reason for this
is that the variable B<x> is uninitialized and an attempt will be made to is that the variable B<x> is uninitialized and an attempt will be made to
@ -181,71 +555,40 @@ happen.
=head1 BUGS =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 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 persist if they are not present in the new one. As a result the use
of this "reuse" behaviour is strongly discouraged. 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 if mandatory fields are not initialized due to a programming error
then the encoded structure may contain invalid data or omit the then the encoded structure may contain invalid data or omit the
fields entirely and will not be parsed by d2i_X509(). This may be fields entirely and will not be parsed by d2i_TYPE(). This may be
fixed in future so code should not assume that i2d_X509() will fixed in future so code should not assume that i2d_TYPE() will
always succeed. always succeed.
The encoding of the TBSCertificate portion of a certificate is cached Any function which encodes a structure (i2d_TYPE(),
in the B<X509> structure internally to improve encoding performance i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
and to ensure certificate signatures are verified correctly in some structure has been modified after deserialization or previous
certificates with broken (non-DER) encodings. 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.
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 RETURN VALUES =head1 RETURN VALUES
d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
or B<NULL> if an error occurs. The error code that can be obtained by or B<NULL> if an error occurs. If the "reuse" capability has been used with
L<ERR_get_error(3)>. If the "reuse" capability has been used a valid structure being passed in via B<a>, then the object is not freed in
with a valid X509 structure being passed in via B<px> then the object is not the event of error but may be in a potentially invalid or inconsistent state.
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 i2d_TYPE() returns the number of bytes successfully encoded or a negative
value if an error occurs. The error code can be obtained by value if an error occurs.
L<ERR_get_error(3)>.
i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
occurs The error code can be obtained by L<ERR_get_error(3)>. occurs.
=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 =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 Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy 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 =head1 DESCRIPTION
d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS These functions decode and encode an SSL_SESSION object.
session, stored as binary data at location B<pp> with length B<length>, into For encoding details see L<d2i_X509(3)>.
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)>).
SSL_SESSION objects keep internal link information about the session cache SSL_SESSION objects keep internal link information about the session cache
list, when being inserted into one SSL_CTX object's 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 only be used with one SSL_CTX object (and the SSL objects created
from this SSL_CTX object). 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 =head1 RETURN VALUES
d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION 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 =head1 SEE ALSO
L<ssl(3)>, L<SSL_SESSION_free(3)>, 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 =head1 COPYRIGHT

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

@ -100,7 +100,8 @@ sub check()
my $id = "${filename}:1:"; 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" print "$id doesn't start with =pod\n"
if $contents !~ /^=pod/; if $contents !~ /^=pod/;