diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2016-03-23 01:07:52 +0100 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2016-04-13 03:18:30 +0200 |
commit | 01d358a3ab09b0a4e79a5a492169aedcfbe8ddb3 (patch) | |
tree | b3e43cc1d4998b505ef54b844f86e0d2bd5817ec | |
parent | Fix setting of debug callback in apps/enc.c (diff) | |
download | openssl-01d358a3ab09b0a4e79a5a492169aedcfbe8ddb3.tar.xz openssl-01d358a3ab09b0a4e79a5a492169aedcfbe8ddb3.zip |
X509_PUBKEY docs
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
-rw-r--r-- | doc/crypto/X509_PUBKEY.pod | 111 | ||||
-rw-r--r-- | doc/crypto/d2i_DSAPublicKey.pod | 14 | ||||
-rw-r--r-- | doc/crypto/d2i_RSAPublicKey.pod | 25 |
3 files changed, 141 insertions, 9 deletions
diff --git a/doc/crypto/X509_PUBKEY.pod b/doc/crypto/X509_PUBKEY.pod new file mode 100644 index 0000000000..7b85ffa16d --- /dev/null +++ b/doc/crypto/X509_PUBKEY.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0, +X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, +i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, +X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions. + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509_PUBKEY *X509_PUBKEY_new(void); + void X509_PUBKEY_free(X509_PUBKEY *a); + + int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); + EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key); + EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key); + + EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length); + int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp); + + EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a); + EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a); + + int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey); + int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey); + + int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj, + int ptype, void *pval, + unsigned char *penc, int penclen); + int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg, + const unsigned char **pk, int *ppklen, + X509_ALGOR **pa, X509_PUBKEY *pub); + +=head1 DESCRIPTION + +The B<X509_PUBKEY> structure represents the ASN.1 B<SubjectPublicKeyInfo> +structure defined in RFC5280 and used in certificates and certificate requests. + +X509_PUBKEY_new() allocates and initializes an B<X509_PUBKEY> structure. + +X509_PUBKEY_free() frees up B<X509_PUBKEY> structure B<a>. If B<a> is NULL +nothing is done. + +X509_PUBKEY_set() sets the public key in B<*x> to the public key contained +in the B<EVP_PKEY> structure B<pkey>. If B<*x> is not NULL any existing +public key structure will be freed. + +X509_PUBKEY_get0() returns the public key contained in B<key>. The returned +value is an internal pointer which B<MUST NOT> be freed after use. + +X509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference +count on the returned key is incremented so it B<MUST> be freed using +EVP_PKEY_free() after use. + +d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B<EVP_PKEY> structure +using B<SubjectPublicKeyInfo> format. They otherise follow the conventions of +other ASN.1 functions such as d2i_X509(). + +d2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are +similar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a +B<BIO> or B<FILE> pointer. + +X509_PUBKEY_set0_param() sets the public key parameters of B<pub>. The +OID associated with the algorithm is set to B<aobj>. The type of the +algorithm parameters is set to B<type> using the structure B<pval>. +The encoding of the public key itself is set to the B<penclen> +bytes contained in buffer B<penc>. On success ownership of all the supplied +parameters is passed to B<pub> so they must not be freed after the +call. + +X509_PUBKEY_get0_param() retrieves the public key parameters from B<pub>, +B<*ppkalg> is set to the associated OID and the encoding consists of +B<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated +AlgorithmIdentifier for the public key. If the value of any of these +parameters is not required it can be set to B<NULL>. All of the +retrieved pointers are internal and must not be freed after the +call. + +=head1 NOTES + +The B<X509_PUBKEY> functions can be used to encode and decode public keys +in a standard format. + +In many cases applications will not call the B<X509_PUBKEY> functions +directly: they will instead call wrapper functions such as X509_get0_pubkey(). + +=head1 RETURN VALUES + +If the allocation fails, X509_PUBKEY_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)>. + +Otherwise it returns a pointer to the newly allocated structure. + +X509_PUBKEY_free() does not return a value. + +X509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B<EVP_PKEY> +structure or B<NULL> if an error occurs. + +X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param() +return 1 for success and 0 if an error occurred. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_get_pubkey(3)>, + +=cut diff --git a/doc/crypto/d2i_DSAPublicKey.pod b/doc/crypto/d2i_DSAPublicKey.pod index 7acb329f23..1344b00a46 100644 --- a/doc/crypto/d2i_DSAPublicKey.pod +++ b/doc/crypto/d2i_DSAPublicKey.pod @@ -3,8 +3,8 @@ =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. +d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, +d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding and parsing functions. =head1 SYNOPSIS @@ -19,6 +19,12 @@ and parsing functions. 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); @@ -39,6 +45,10 @@ 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. diff --git a/doc/crypto/d2i_RSAPublicKey.pod b/doc/crypto/d2i_RSAPublicKey.pod index 9786d75201..946fe0f907 100644 --- a/doc/crypto/d2i_RSAPublicKey.pod +++ b/doc/crypto/d2i_RSAPublicKey.pod @@ -3,7 +3,8 @@ =head1 NAME d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, -d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, +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 @@ -19,6 +20,12 @@ d2i_Netscape_RSA - RSA public and private key encoding functions. 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); @@ -29,20 +36,24 @@ d2i_Netscape_RSA - RSA public and private key encoding functions. =head1 DESCRIPTION -d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 RSAPublicKey -structure. +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_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 RSAPrivateKey -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. +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 |