From 137b274aee0cd96d64fd68cd393717d6a69ec005 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 8 Apr 2020 11:54:53 +0100 Subject: [PATCH] Document the new libctx aware private key functions Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/11494) --- doc/man3/PEM_read_bio_PrivateKey.pod | 21 ++++++- doc/man3/d2i_PrivateKey.pod | 84 +++++++++++++++++++++------- util/missingcrypto.txt | 2 - 3 files changed, 83 insertions(+), 24 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> functions" will be used below to collectively refer to the B>(), B>(), B>(), and B>() functions. +Some operations have additional variants that take a library context I +and a property query string I. + The B 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 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 and I 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 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 + 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 + + 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. It attempts to -use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The -B parameter should be a public key algorithm constant such as -B. An error occurs if the decoded key does not match B. +d2i_PrivateKey_ex() decodes a private key using algorithm I. It attempts +to use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The +I parameter should be a public key algorithm constant such as +B. An error occurs if the decoded key does not match I. 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 +and property query string I 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. It uses a key specific format or, if none is +i2d_PrivateKey() encodes I. 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. +i2d_PrivateKey_bio() and i2d_PrivateKey_fp() do the same thing except that they +encode to a B or B respectrively. Again, these work similarly to the +functions described in L. =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, d2i_PublicKey() requires B<*a> to be +To decode a key with type B, 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 structure or B if an error occurs. The error code can be -obtained by calling L. +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 structure or B +if an error occurs. The error code can be obtained by calling +L. -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. +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. =head1 SEE ALSO L, L +=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. diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index 6ce32388a2..cb8049b832 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -1564,8 +1564,6 @@ i2a_ASN1_STRING(3) i2b_PVK_bio(3) i2b_PrivateKey_bio(3) i2b_PublicKey_bio(3) -i2d_PrivateKey_bio(3) -i2d_PrivateKey_fp(3) i2d_X509_bio(3) i2d_X509_fp(3) i2o_ECPublicKey(3) -- 2.25.1