From 4692340e31985681f95008d409483d5761b6c213 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Tue, 7 Jun 2016 15:49:08 -0400 Subject: Unify d2i/i2d documentation. 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 --- doc/crypto/ECPKParameters_print.pod | 43 +++ doc/crypto/EC_KEY_get_enc_flags.pod | 59 ++++ doc/crypto/X509_ALGOR_dup.pod | 48 +++ doc/crypto/X509_NAME_get0_der.pod | 38 +++ doc/crypto/X509_SIG_get0.pod | 32 ++ doc/crypto/d2i_ASN1_OBJECT.pod | 34 -- doc/crypto/d2i_CMS_ContentInfo.pod | 34 -- doc/crypto/d2i_DSAPublicKey.pod | 95 ------ doc/crypto/d2i_ECPKParameters.pod | 93 ------ doc/crypto/d2i_ECPrivateKey.pod | 76 ----- doc/crypto/d2i_Netscape_RSA.pod | 38 +++ doc/crypto/d2i_PrivateKey.pod | 11 +- doc/crypto/d2i_RSAPublicKey.pod | 82 ----- doc/crypto/d2i_X509.pod | 607 ++++++++++++++++++++++++++++-------- doc/crypto/d2i_X509_ALGOR.pod | 60 ---- doc/crypto/d2i_X509_CRL.pod | 44 --- doc/crypto/d2i_X509_NAME.pod | 54 ---- doc/crypto/d2i_X509_REQ.pod | 44 --- doc/crypto/d2i_X509_SIG.pod | 41 --- doc/crypto/i2d_re_X509_tbs.pod | 79 +++++ doc/ssl/d2i_SSL_SESSION.pod | 44 +-- util/find-doc-nits.pl | 3 +- 22 files changed, 825 insertions(+), 834 deletions(-) create mode 100644 doc/crypto/ECPKParameters_print.pod create mode 100644 doc/crypto/EC_KEY_get_enc_flags.pod create mode 100644 doc/crypto/X509_ALGOR_dup.pod create mode 100644 doc/crypto/X509_NAME_get0_der.pod create mode 100644 doc/crypto/X509_SIG_get0.pod delete mode 100644 doc/crypto/d2i_ASN1_OBJECT.pod delete mode 100644 doc/crypto/d2i_CMS_ContentInfo.pod delete mode 100644 doc/crypto/d2i_DSAPublicKey.pod delete mode 100644 doc/crypto/d2i_ECPKParameters.pod delete mode 100644 doc/crypto/d2i_ECPrivateKey.pod create mode 100644 doc/crypto/d2i_Netscape_RSA.pod delete mode 100644 doc/crypto/d2i_RSAPublicKey.pod delete mode 100644 doc/crypto/d2i_X509_ALGOR.pod delete mode 100644 doc/crypto/d2i_X509_CRL.pod delete mode 100644 doc/crypto/d2i_X509_NAME.pod delete mode 100644 doc/crypto/d2i_X509_REQ.pod delete mode 100644 doc/crypto/d2i_X509_SIG.pod create mode 100644 doc/crypto/i2d_re_X509_tbs.pod diff --git a/doc/crypto/ECPKParameters_print.pod b/doc/crypto/ECPKParameters_print.pod new file mode 100644 index 0000000000..20b9cc7fe0 --- /dev/null +++ b/doc/crypto/ECPKParameters_print.pod @@ -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 + + 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 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 +or B. The output lines are indented by B spaces. + +=head1 RETURN VALUES + +ECPKParameters_print() and ECPKParameters_print_fp() +return 1 for success and 0 if an error occurs. + +=head1 SEE ALSO + +L, L, L, L, +L, L, L, +L, + +=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. + +=cut diff --git a/doc/crypto/EC_KEY_get_enc_flags.pod b/doc/crypto/EC_KEY_get_enc_flags.pod new file mode 100644 index 0000000000..abc55c148f --- /dev/null +++ b/doc/crypto/EC_KEY_get_enc_flags.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +EC_KEY_get_enc_flags, EC_KEY_set_enc_flags +- Get and set flags for encoding EC_KEY structures + +=head1 SYNOPSIS + + #include + + 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 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 +described by the point_conversion_form. See L +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 +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(). + +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. 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 is converted into ASN1 in a call to +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 + +EC_KEY_get_enc_flags() returns the value of the current encoding flags for the +EC_KEY. + +=head1 SEE ALSO + +L, L, L, +L, L, +L, +L, +L, +L + +=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. + +=cut diff --git a/doc/crypto/X509_ALGOR_dup.pod b/doc/crypto/X509_ALGOR_dup.pod new file mode 100644 index 0000000000..8f6c9b05eb --- /dev/null +++ b/doc/crypto/X509_ALGOR_dup.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0, X509_ALGOR_set_md, X509_ALGOR_cmp - AlgorithmIdentifier functions + +=head1 SYNOPSIS + + #include + + 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, + X509_ALGOR *alg); + void X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md); + int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b); + +=head1 DESCRIPTION + +X509_ALGOR_dup() returns a copy of B. + +X509_ALGOR_set0() sets the algorithm OID of B to B and the +associated parameter type to B with value B. If B is +B the parameter is omitted, otherwise B and B have +the same meaning as the B and B parameters to ASN1_TYPE_set(). +All the supplied parameters are used internally so must B be freed after +this call. + +X509_ALGOR_get0() is the inverse of X509_ALGOR_set0(): it returns the +algorithm OID in B<*paobj> and the associated parameter in B<*pptype> +and B<*ppval> from the B B. + +X509_ALGOR_set_md() sets the B B to appropriate +values for the message digest B. + +X509_ALGOR_cmp() compares B and B and returns 0 if they have identical +encodings and non-zero otherwise. + +=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. + +=cut diff --git a/doc/crypto/X509_NAME_get0_der.pod b/doc/crypto/X509_NAME_get0_der.pod new file mode 100644 index 0000000000..722fadb944 --- /dev/null +++ b/doc/crypto/X509_NAME_get0_der.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +=head1 SYNOPSIS + + #include + + int X509_NAME_get0_der(const unsigned char **pder, size_t *pderlen, + X509_NAME *nm) + + +=head1 DESCRIPTION + +The function X509_NAME_get0_der() returns an internal pointer to the +encoding of an B structure in B<*pder> and consisting of +B<*pderlen> bytes. It is useful for applications that wish to examine +the encoding of an B structure without copying it. + +=head1 RETURN VALUES + +The function X509_NAME_get0_der() returns 1 for success and 0 if an error +occurred. + +=head1 SEE ALSO + +L + +=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. + +=cut diff --git a/doc/crypto/X509_SIG_get0.pod b/doc/crypto/X509_SIG_get0.pod new file mode 100644 index 0000000000..1d61497c1c --- /dev/null +++ b/doc/crypto/X509_SIG_get0.pod @@ -0,0 +1,32 @@ +=pod + +=head1 NAME + +X509_SIG_get0 - Get DigestInfo functions + +=head1 SYNOPSIS + + #include + + void X509_SIG_get0(X509_ALGOR **palg, ASN1_OCTET_STRING **pdigest, + X509_SIG *sig); + +=head1 DESCRIPTION + +X509_SIG_get0() returns pointers to the algorithm identifier and digest +value in B. These values can then be examined or initialised. + +=head1 SEE ALSO + +L + +=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. + +=cut diff --git a/doc/crypto/d2i_ASN1_OBJECT.pod b/doc/crypto/d2i_ASN1_OBJECT.pod deleted file mode 100644 index 331335e5f1..0000000000 --- a/doc/crypto/d2i_ASN1_OBJECT.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions - -=head1 SYNOPSIS - - #include - - 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 manual page. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/d2i_CMS_ContentInfo.pod b/doc/crypto/d2i_CMS_ContentInfo.pod deleted file mode 100644 index 4f1d90fb40..0000000000 --- a/doc/crypto/d2i_CMS_ContentInfo.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -d2i_CMS_ContentInfo, i2d_CMS_ContentInfo - CMS ContentInfo functions - -=head1 SYNOPSIS - - #include - - 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 manual page. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/d2i_DSAPublicKey.pod b/doc/crypto/d2i_DSAPublicKey.pod deleted file mode 100644 index 35450b9421..0000000000 --- a/doc/crypto/d2i_DSAPublicKey.pod +++ /dev/null @@ -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 - - 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 or B 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 structure as defined in RFC2459. - -d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a -B 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 manual page. - -=head1 NOTES - -The B 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 functions should be used in preference to the B -functions when encoding public keys because they use a standard format. - -The B functions use a non standard format which is a -B consisting of the B

, B, B and B fields -respectively. - -The B functions also use a non standard structure consisting -consisting of a SEQUENCE containing the B

, B, B and B and -B fields respectively. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/d2i_ECPKParameters.pod b/doc/crypto/d2i_ECPKParameters.pod deleted file mode 100644 index 560795f992..0000000000 --- a/doc/crypto/d2i_ECPKParameters.pod +++ /dev/null @@ -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 - - 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 structure, which represents a curve. - -d2i_ECPKParameters() attempts to decode B bytes at B<*in>. If -successful a pointer to the B structure is returned. If an error -occurred then B is returned. If B is not B then the -returned structure is written to B<*px>. If B<*px> is not B -then it is assumed that B<*px> contains a valid B -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 into DER format. -If B is not B 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 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. - -d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts -to parse data from FILE pointer B. - -i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes -the encoding of the structure B to BIO B 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 to BIO B and it -returns 1 for success and 0 for failure. - -These functions are very similar to the X509 functions described in L, -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 or B. The output lines are indented by B spaces. - -=head1 RETURN VALUES - -d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B structure -or B 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, L, L, L, -L, L, L, -L, L - -=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. - -=cut diff --git a/doc/crypto/d2i_ECPrivateKey.pod b/doc/crypto/d2i_ECPrivateKey.pod deleted file mode 100644 index 6cd24f24a8..0000000000 --- a/doc/crypto/d2i_ECPrivateKey.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and -reading EC_KEY structures - -=head1 SYNOPSIS - - #include - - 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 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). - -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 -described by the point_conversion_form. See L -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 -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. - -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. 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 is converted into ASN1 in a call to -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 structure or B if an error -occurs. The error code that can be obtained by -L. - -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. - -EC_KEY_get_enc_flags returns the value of the current encoding flags for the -EC_KEY. - -=head1 SEE ALSO - -L, L, L, -L, L, -L, -L, -L, -L - -=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. - -=cut diff --git a/doc/crypto/d2i_Netscape_RSA.pod b/doc/crypto/d2i_Netscape_RSA.pod new file mode 100644 index 0000000000..ee39bd817a --- /dev/null +++ b/doc/crypto/d2i_Netscape_RSA.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +i2d_Netscape_RSA, +d2i_Netscape_RSA +- insecure RSA public and private key encoding functions + +=head1 SYNOPSIS + + #include + + 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 functions. + +=head1 SEE ALSO + +L + +=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. + +=cut diff --git a/doc/crypto/d2i_PrivateKey.pod b/doc/crypto/d2i_PrivateKey.pod index 1b2089ccdb..a221b0f93f 100644 --- a/doc/crypto/d2i_PrivateKey.pod +++ b/doc/crypto/d2i_PrivateKey.pod @@ -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. It attempts to @@ -28,8 +32,7 @@ automatically detect the private key format. i2d_PrivateKey() encodes B. 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). +These functions are similar to the d2i_X509() functions; see L. =head1 NOTES diff --git a/doc/crypto/d2i_RSAPublicKey.pod b/doc/crypto/d2i_RSAPublicKey.pod deleted file mode 100644 index 902bacdfb6..0000000000 --- a/doc/crypto/d2i_RSAPublicKey.pod +++ /dev/null @@ -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 - - 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 or B 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 manual page. - -=head1 NOTES - -The B 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 - -=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. - -=cut diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod index 422edfcf83..06546a4875 100644 --- a/doc/crypto/d2i_X509.pod +++ b/doc/crypto/d2i_X509.pod @@ -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 + TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length); + TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); + TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); - X509 *d2i_X509(X509 **px, const unsigned char **in, long len); - X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); - int i2d_X509(X509 *x, unsigned char **out); - int i2d_X509_AUX(X509 *x, unsigned char **out); + int i2d_TYPE(TYPE *a, unsigned char **pp); + int i2d_TYPE_fp(FILE *fp, TYPE *a); + int i2d_TYPE_bio(BIO *bp, TYPE *a); - X509 *d2i_X509_bio(BIO *bp, X509 **x); - X509 *d2i_X509_fp(FILE *fp, X509 **x); - - int i2d_X509_bio(BIO *bp, X509 *x); - int i2d_X509_fp(FILE *fp, X509 *x); +=head1 DESCRIPTION - int i2d_re_X509_tbs(X509 *x, unsigned char **out); +In the description here, I is used a placeholder +for any of the OpenSSL datatypes, such as I. -=head1 DESCRIPTION +These functions convert OpenSSL objects to and from their ASN.1/DER +encoding. Unlike the C structures which can have pointers to sub-objects +within, the DER is a serialized encoding, suitable for sending over the +network, writing to a file, and so on. -The X509 encode and decode routines encode and parse an -B structure, which represents an X509 certificate. +d2i_TYPE() attempts to decode B bytes at B<*in>. If successful a +pointer to the B structure is returned and B<*in> is incremented to +the byte following the parsed data. If B is not B then a pointer +to the returned structure is also written to B<*a>. If an error occurred +then B is returned. -d2i_X509() attempts to decode B bytes at B<*in>. If -successful a pointer to the B structure is returned. If an error -occurred then B is returned. If B is not B then the -returned structure is written to B<*px>. If B<*px> is not B -then it is assumed that B<*px> contains a valid B -structure and an attempt is made to reuse it. This "reuse" capability is present -for historical compatibility but its use is B (see BUGS -below, and the discussion in the RETURN VALUES section). +On a successful return, if B<*a> is not B then it is assumed that B<*a> +contains a valid B structure and an attempt is made to reuse it. This +"reuse" capability is present for historical compatibility but its use is +B (see BUGS below, and the discussion in the RETURN +VALUES section). -If the call is successful B<*in> is incremented to the byte following the -parsed data. +d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts +to parse data from BIO B. -d2i_X509_AUX() is similar to d2i_X509() but the input is expected to consist of -an X509 certificate followed by auxiliary trust information. -This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. -This function should not be called on untrusted input. +d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts +to parse data from FILE pointer B. -i2d_X509() encodes the structure pointed to by B into DER format. -If B is not B is writes the DER encoded data to the buffer +i2d_TYPE() encodes the structure pointed to by B into DER format. +If B is not B, 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 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. - -d2i_X509_fp() is similar to d2i_X509() except it attempts -to parse data from FILE pointer B. +If B<*out> is B memory will be allocated for a buffer and the encoded +data written to it. In this case B<*out> is not incremented and it points +to the start of the data just written. -i2d_X509_bio() is similar to i2d_X509() except it writes -the encoding of the structure B to BIO B and it +i2d_TYPE_bio() is similar to i2d_TYPE() except it writes +the encoding of the structure B to BIO B 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 to BIO B and it +i2d_TYPE_fp() is similar to i2d_TYPE() except it writes +the encoding of the structure B to BIO B 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 or similar for writing to files. =head1 NOTES -The letters B and B in for example B stand for -"internal" (that is an internal C structure) and "DER". So -B converts from internal to DER. The "re" in -B 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 and B in B stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So B converts from internal to DER. The functions can also understand B forms. -The actual X509 structure passed to i2d_X509() must be a valid -populated B structure it can B 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 structure -- it B 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 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 + +Represents an ASN1 OBJECT IDENTIFIER. + +=item B + +Represents a PKCS#3 DH parameters structure. + +=item B + +Represents a ANSI X9.42 DH parameters structure. + +=item B + +Represents a DSA public key using a B structure. + +=item B + +Use a non-standard OpenSSL format and should be avoided; use B, +B, or similar instead. + +=item B + +Represents a PKCS#1 RSA public key structure. + +=item B + +Represents an B structure as used in IETF RFC 6960 and +elsewhere. + +=item B + +Represents a B type as used for subject and issuer names in +IETF RFC 6960 and elsewhere. + +=item B + +Represents a PKCS#10 certificate request. + +=item B + +Represents the B 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 apparently containing garbage because it was incremented after the call to point after the data just written. Also B 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 argument to d2i_X509(): +Another trap to avoid is misuse of the B 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 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 structure internally to improve encoding performance -and to ensure certificate signatures are verified correctly in some -certificates with broken (non-DER) encodings. +Any function which encodes a structure (i2d_TYPE(), +i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the +structure has been modified after deserialization or previous +serialization. This is because some objects cache the encoding for +efficiency reasons. -Any function which encodes an X509 structure such as i2d_X509(), -i2d_X509_fp() or i2d_X509_bio() may return a stale encoding if the -B structure has been modified after deserialization or previous -serialization. +=head1 RETURN VALUES -If, after modification, the B object is re-signed with X509_sign(), -the encoding is automatically renewed. Otherwise, the encoding of the -TBSCertificate portion of the B can be manually renewed by calling -i2d_re_X509_tbs(). +d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B structure +or B if an error occurs. If the "reuse" capability has been used with +a valid structure being passed in via B, then the object is not freed in +the event of error but may be in a potentially invalid or inconsistent state. -=head1 RETURN VALUES +i2d_TYPE() returns the number of bytes successfully encoded or a negative +value if an error occurs. -d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B structure -or B if an error occurs. The error code that can be obtained by -L. If the "reuse" capability has been used -with a valid X509 structure being passed in via B 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. - -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. - -=head1 SEE ALSO - -L -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L +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 diff --git a/doc/crypto/d2i_X509_ALGOR.pod b/doc/crypto/d2i_X509_ALGOR.pod deleted file mode 100644 index 13c1223efe..0000000000 --- a/doc/crypto/d2i_X509_ALGOR.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=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 - -=head1 SYNOPSIS - - #include - - 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, - X509_ALGOR *alg); - void X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md); - int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b); - -=head1 DESCRIPTION - -The functions d2i_X509() and i2d_X509() decode and encode an B -structure which is equivalent to the B structure. - -Otherwise they behave in a similar way to d2i_X509() and i2d_X509() -described in the L manual page. - -X509_ALGOR_dup() returns a copy of B. - -X509_ALGOR_set0() sets the algorithm OID of B to B and the -associated parameter type to B with value B. If B is -B the parameter is omitted, otherwise B and B have -the same meaning as the B and B parameters to ASN1_TYPE_set(). -All the supplied parameters are used internally so must B be freed after -this call. - -X509_ALGOR_get0() is the inverse of X509_ALGOR_set0(): it returns the -algorithm OID in B<*paobj> and the associated parameter in B<*pptype> -and B<*ppval> from the B B. - -X509_ALGOR_set_md() sets the B B to appropriate -values for the message digest B. - -X509_ALGOR_cmp() compares B and B and returns 0 if they have identical -encodings and non-zero otherwise. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/d2i_X509_CRL.pod b/doc/crypto/d2i_X509_CRL.pod deleted file mode 100644 index 8726af24b6..0000000000 --- a/doc/crypto/d2i_X509_CRL.pod +++ /dev/null @@ -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 - - 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 manual page. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/d2i_X509_NAME.pod b/doc/crypto/d2i_X509_NAME.pod deleted file mode 100644 index f30ebabf73..0000000000 --- a/doc/crypto/d2i_X509_NAME.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions - -=head1 SYNOPSIS - - #include - - 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 structure which is the same as the B 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 manual page. - -The function X509_NAME_get0_der() returns an internal pointer to the -encoding of an B structure in B<*pder> and consisting of -B<*pderlen> bytes. It is useful for applications that wish to examine -the encoding of an B 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. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/d2i_X509_REQ.pod b/doc/crypto/d2i_X509_REQ.pod deleted file mode 100644 index 7503415ebd..0000000000 --- a/doc/crypto/d2i_X509_REQ.pod +++ /dev/null @@ -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 - - 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 manual page. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/d2i_X509_SIG.pod b/doc/crypto/d2i_X509_SIG.pod deleted file mode 100644 index 8fade21555..0000000000 --- a/doc/crypto/d2i_X509_SIG.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions - -=head1 SYNOPSIS - - #include - - 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 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 manual page. - -X509_SIG_get0() returns pointers to the algorithm identifier and digest -value in B. These values can then be examined or initialised. - -=head1 SEE ALSO - -L - -=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. - -=cut diff --git a/doc/crypto/i2d_re_X509_tbs.pod b/doc/crypto/i2d_re_X509_tbs.pod new file mode 100644 index 0000000000..672c7ab5ae --- /dev/null +++ b/doc/crypto/i2d_re_X509_tbs.pod @@ -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 + + 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 structure, which represents an X509 certificate. + +d2i_X509_AUX() is similar to L 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, 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 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 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 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 object is re-signed with X509_sign(), +the encoding is automatically renewed. Otherwise, the encoding of the +TBSCertificate portion of the B can be manually renewed by calling +i2d_re_X509_tbs(). + +=head1 SEE ALSO + +L +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=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. + +=cut diff --git a/doc/ssl/d2i_SSL_SESSION.pod b/doc/ssl/d2i_SSL_SESSION.pod index 628c7e42b1..d6b17071f6 100644 --- a/doc/ssl/d2i_SSL_SESSION.pod +++ b/doc/ssl/d2i_SSL_SESSION.pod @@ -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 with length B, into -an SSL_SESSION object. - -i2d_SSL_SESSION() transforms the SSL_SESSION object B into the ASN1 -representation and stores it into the memory location pointed to by B. -The length of the resulting ASN1 representation is returned. If B 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, -unless the SSL_SESSION object is completely taken over, when being called -inside the get_session_cb() (see -L). +These functions decode and encode an SSL_SESSION object. +For encoding details see L. 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 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, 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, L, -L +L, +L =head1 COPYRIGHT diff --git a/util/find-doc-nits.pl b/util/find-doc-nits.pl index 59647f9294..cd30dfeb26 100755 --- a/util/find-doc-nits.pl +++ b/util/find-doc-nits.pl @@ -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/; -- cgit v1.2.3