diff options
author | Matt Caswell <matt@openssl.org> | 2020-04-08 11:54:53 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2020-04-15 11:24:13 +0100 |
commit | 137b274aee0cd96d64fd68cd393717d6a69ec005 (patch) | |
tree | 2764ee9acd2f74be090467ba47b52fcda692349d /doc | |
parent | d6a2bdf7f1585587c607abb2e5ae281d12dd8230 (diff) |
Document the new libctx aware private key functions
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11494)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/PEM_read_bio_PrivateKey.pod | 21 | ||||
-rw-r--r-- | doc/man3/d2i_PrivateKey.pod | 84 |
2 files changed, 83 insertions, 22 deletions
diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod index 0650b52e07..b1dfe465e7 100644 --- a/doc/man3/PEM_read_bio_PrivateKey.pod +++ b/doc/man3/PEM_read_bio_PrivateKey.pod @@ -3,7 +3,8 @@ =head1 NAME pem_password_cb, -PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, +PEM_read_bio_PrivateKey_ex, PEM_read_bio_PrivateKey, PEM_read_PrivateKey_ex, +PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, @@ -33,8 +34,14 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines typedef int pem_password_cb(char *buf, int size, int rwflag, void *u); + EVP_PKEY *PEM_read_bio_PrivateKey_ex(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, + void *u, OPENSSL_CTX *libctx, + const char *propq); EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); + EVP_PKEY *PEM_read_PrivateKey_ex(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, + void *u, OPENSSL_CTX *libctx, + const char *propq); EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc, @@ -168,6 +175,9 @@ brevity the term "B<I<TYPE>> functions" will be used below to collectively refer to the B<PEM_read_bio_I<TYPE>>(), B<PEM_read_I<TYPE>>(), B<PEM_write_bio_I<TYPE>>(), and B<PEM_write_I<TYPE>>() functions. +Some operations have additional variants that take a library context I<libctx> +and a property query string I<propq>. + The B<PrivateKey> functions read or write a private key in PEM format using an EVP_PKEY structure. The write routines use PKCS#8 private key format and are equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently @@ -307,6 +317,12 @@ arbitrary data to be passed to the callback by the application I<must> return the number of characters in the passphrase or -1 if an error occurred. +Some implementations may need to use cryptographic algorithms during their +operation. If this is the case and I<libctx> and I<propq> parameters have been +passed then any algorithm fetches will use that library context and property +query string. Otherwise the default library context and property query string +will be used. + =head1 NOTES The old B<PrivateKey> write routines are retained for compatibility. @@ -480,6 +496,9 @@ The old Netscape certificate sequences were no longer documented in OpenSSL 1.1.0; applications should use the PKCS7 standard instead as they will be formally deprecated in a future releases. +PEM_read_bio_PrivateKey_ex() and PEM_read_PrivateKey_ex() were introduced in +OpenSSL 3.0. + =head1 COPYRIGHT Copyright 2001-2019 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/d2i_PrivateKey.pod b/doc/man3/d2i_PrivateKey.pod index 4b7a326c0d..ca4876cfd9 100644 --- a/doc/man3/d2i_PrivateKey.pod +++ b/doc/man3/d2i_PrivateKey.pod @@ -2,21 +2,29 @@ =head1 NAME -d2i_PrivateKey, d2i_PublicKey, d2i_KeyParams, d2i_AutoPrivateKey, -i2d_PrivateKey, i2d_PublicKey, i2d_KeyParams, i2d_KeyParams_bio, -d2i_PrivateKey_bio, d2i_PrivateKey_fp, d2i_KeyParams_bio +d2i_PrivateKey_ex, d2i_PrivateKey, d2i_PublicKey, d2i_KeyParams, +d2i_AutoPrivateKey_ex, d2i_AutoPrivateKey, i2d_PrivateKey, i2d_PublicKey, +i2d_KeyParams, i2d_KeyParams_bio, d2i_PrivateKey_ex_bio, d2i_PrivateKey_bio, +d2i_PrivateKey_ex_fp, d2i_PrivateKey_fp, d2i_KeyParams_bio, i2d_PrivateKey_bio, +i2d_PrivateKey_fp - decode and encode functions for reading and saving EVP_PKEY structures =head1 SYNOPSIS #include <openssl/evp.h> + EVP_PKEY *d2i_PrivateKey_ex(int type, EVP_PKEY **a, const unsigned char **pp, + long length, OPENSSL_CTX *libctx, + const char *propq); EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp, long length); EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **a, const unsigned char **pp, long length); EVP_PKEY *d2i_KeyParams(int type, EVP_PKEY **a, const unsigned char **pp, long length); + EVP_PKEY *d2i_AutoPrivateKey_ex(EVP_PKEY **a, const unsigned char **pp, + long length, OPENSSL_CTX *libctx, + const char *propq); EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp, long length); @@ -24,28 +32,54 @@ d2i_PrivateKey_bio, d2i_PrivateKey_fp, d2i_KeyParams_bio int i2d_PublicKey(const EVP_PKEY *a, unsigned char **pp); int i2d_KeyParams(const EVP_PKEY *a, unsigned char **pp); int i2d_KeyParams_bio(BIO *bp, const EVP_PKEY *pkey); + EVP_PKEY *d2i_KeyParams_bio(int type, EVP_PKEY **a, BIO *in); + + #include <openssl/x509.h> + + EVP_PKEY *d2i_PrivateKey_ex_bio(BIO *bp, EVP_PKEY **a, OPENSSL_CTX *libctx, + const char *propq); EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a); + EVP_PKEY *d2i_PrivateKey_ex_fp(FILE *fp, EVP_PKEY **a, OPENSSL_CTX *libctx, + const char *propq); EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a) - EVP_PKEY *d2i_KeyParams_bio(int type, EVP_PKEY **a, BIO *in); + + int i2d_PrivateKey_bio(BIO *bp, const EVP_PKEY *pkey); + int i2d_PrivateKey_fp(FILE *fp, const EVP_PKEY *pkey); =head1 DESCRIPTION -d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to -use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The -B<type> parameter should be a public key algorithm constant such as -B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>. +d2i_PrivateKey_ex() decodes a private key using algorithm I<type>. It attempts +to use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The +I<type> parameter should be a public key algorithm constant such as +B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match I<type>. Some +private key decoding implementations may use cryptographic algorithms (for +example to automatically derive the public key if it is not explicitly +included in the encoding). In this case the supplied library context I<libctx> +and property query string I<propq> are used. +d2i_PrivateKey() does the same as d2i_PrivateKey_ex() except that the default +library context and property query string are used. d2i_PublicKey() does the same for public keys. d2i_KeyParams() does the same for key parameters. -d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to -automatically detect the private key format. +The d2i_PrivateKey_ex_bio() and d2i_PrivateKey_bio() functions are similar to +d2i_PrivateKey_ex() and d2i_PrivateKey() respectively except that they decode +the data read from the given BIO. The d2i_PrivateKey_ex_fp() and +d2i_PrivateKey_fp() functions are the same except that they read the data from +the given FILE. + +d2i_AutoPrivateKey_ex() and d2i_AutoPrivateKey() are similar to +d2i_PrivateKey_ex() and d2i_PrivateKey() respectively except that they attempt +to automatically detect the private key format. -i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is +i2d_PrivateKey() encodes I<a>. It uses a key specific format or, if none is defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format. i2d_PublicKey() does the same for public keys. i2d_KeyParams() does the same for key parameters. These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>. +i2d_PrivateKey_bio() and i2d_PrivateKey_fp() do the same thing except that they +encode to a B<BIO> or B<FILE> respectrively. Again, these work similarly to the +functions described in L<d2i_X509(3)>. =head1 NOTES @@ -53,30 +87,38 @@ All these functions use DER format and unencrypted keys. Applications wishing to encrypt or decrypt private keys should use other functions such as d2i_PKCS8PrivateKey() instead. -If the B<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey() +If the I<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey() (i.e. an existing structure is being reused) and the key format is PKCS#8 -then B<*a> will be freed and replaced on a successful call. +then I<*a> will be freed and replaced on a successful call. -To decode a key with type B<EVP_PKEY_EC>, d2i_PublicKey() requires B<*a> to be +To decode a key with type B<EVP_PKEY_EC>, d2i_PublicKey() requires I<*a> to be a non-NULL EVP_PKEY structure assigned an EC_KEY structure referencing the proper EC_GROUP. =head1 RETURN VALUES -The d2i_PrivateKey(), d2i_AutoPrivateKey(), d2i_PrivateKey_bio(), d2i_PrivateKey_fp(), -d2i_PublicKey(), d2i_KeyParams() and d2i_KeyParams_bio() functions return a valid -B<EVP_KEY> structure or B<NULL> if an error occurs. The error code can be -obtained by calling L<ERR_get_error(3)>. +The d2i_PrivateKey_ex(), d2i_PrivateKey(), d2i_AutoPrivateKey_ex(), +d2i_AutoPrivateKey(), d2i_PrivateKey_ex_bio(), d2i_PrivateKey_bio(), +d2i_PrivateKey_ex_fp(), d2i_PrivateKey_fp(), d2i_PublicKey(), d2i_KeyParams() +and d2i_KeyParams_bio() functions return a valid B<EVP_KEY> structure or B<NULL> +if an error occurs. The error code can be obtained by calling +L<ERR_get_error(3)>. -i2d_PrivateKey(), i2d_PublicKey(), i2d_KeyParams() i2d_KeyParams_bio() return -the number of bytes successfully encoded or a negative value if an error occurs. -The error code can be obtained by calling L<ERR_get_error(3)>. +i2d_PrivateKey(), i2d_PrivateKey_bio(), i2d_PrivateKey_fp(), i2d_PublicKey(), +i2d_KeyParams() i2d_KeyParams_bio() return the number of bytes successfully +encoded or a negative value if an error occurs. The error code can be obtained +by calling L<ERR_get_error(3)>. =head1 SEE ALSO L<crypto(7)>, L<d2i_PKCS8PrivateKey_bio(3)> +=head1 HISTORY + +d2i_PrivateKey_ex(), d2i_PrivateKey_ex_bio(), d2i_PrivateKey_ex_fp(), and +d2i_AutoPrivateKey_ex() were added in OpenSSL 3.0. + =head1 COPYRIGHT Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved. |