From 01d358a3ab09b0a4e79a5a492169aedcfbe8ddb3 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Wed, 23 Mar 2016 00:07:52 +0000 Subject: X509_PUBKEY docs Reviewed-by: Viktor Dukhovni --- doc/crypto/X509_PUBKEY.pod | 111 ++++++++++++++++++++++++++++++++++++++++ doc/crypto/d2i_DSAPublicKey.pod | 14 ++++- doc/crypto/d2i_RSAPublicKey.pod | 25 ++++++--- 3 files changed, 141 insertions(+), 9 deletions(-) create mode 100644 doc/crypto/X509_PUBKEY.pod (limited to 'doc') 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 + + 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 structure represents the ASN.1 B +structure defined in RFC5280 and used in certificates and certificate requests. + +X509_PUBKEY_new() allocates and initializes an B structure. + +X509_PUBKEY_free() frees up B structure B. If B is NULL +nothing is done. + +X509_PUBKEY_set() sets the public key in B<*x> to the public key contained +in the B structure B. If B<*x> is not NULL any existing +public key structure will be freed. + +X509_PUBKEY_get0() returns the public key contained in B. The returned +value is an internal pointer which B 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 be freed using +EVP_PKEY_free() after use. + +d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B structure +using B 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 or B pointer. + +X509_PUBKEY_set0_param() sets the public key parameters of B. The +OID associated with the algorithm is set to B. The type of the +algorithm parameters is set to B using the structure B. +The encoding of the public key itself is set to the B +bytes contained in buffer B. On success ownership of all the supplied +parameters is passed to B so they must not be freed after the +call. + +X509_PUBKEY_get0_param() retrieves the public key parameters from B, +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. All of the +retrieved pointers are internal and must not be freed after the +call. + +=head1 NOTES + +The B functions can be used to encode and decode public keys +in a standard format. + +In many cases applications will not call the B 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 and sets an error +code that can be obtained by L. + +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 +structure or B 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, +L, +L, + +=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 or B 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 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. +The usage of all of these functions is similar to the d2i_X509() and i2d_X509() +described in the L manual page. =head1 NOTES -- cgit v1.2.3