diff options
author | Matt Caswell <matt@openssl.org> | 2018-06-01 14:14:09 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2018-06-08 10:04:09 +0100 |
commit | edb77a4d0f6032e983c91c1a5fbd4136f9757b1c (patch) | |
tree | 375f2a9baba202f2d92ea71955681a24faad534e /doc | |
parent | 0d124b0a51d3ad8c8807cab280ea18fc68489155 (diff) | |
download | openssl-edb77a4d0f6032e983c91c1a5fbd4136f9757b1c.zip openssl-edb77a4d0f6032e983c91c1a5fbd4136f9757b1c.tar.gz openssl-edb77a4d0f6032e983c91c1a5fbd4136f9757b1c.tar.bz2 |
Document the raw key getter functions
EVP_PKEY_get_raw_private_key() and EVP_PKEY_get_raw_public_key()
Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6394)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_PKEY_new.pod | 49 |
1 files changed, 39 insertions, 10 deletions
diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod index 17ffc6b..a3532a3 100644 --- a/doc/man3/EVP_PKEY_new.pod +++ b/doc/man3/EVP_PKEY_new.pod @@ -8,8 +8,10 @@ EVP_PKEY_free, EVP_PKEY_new_raw_private_key, EVP_PKEY_new_raw_public_key, EVP_PKEY_new_CMAC_key, -EVP_PKEY_new_mac_key -- public/private key allocation functions +EVP_PKEY_new_mac_key, +EVP_PKEY_get_raw_private_key, +EVP_PKEY_get_raw_public_key +- public/private key allocation and raw key handling functions =head1 SYNOPSIS @@ -28,10 +30,16 @@ EVP_PKEY_new_mac_key EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, int keylen); + int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv, + size_t *len); + int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub, + size_t *len); + =head1 DESCRIPTION The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is -used by OpenSSL to store private keys. The reference count is set to B<1>. +used by OpenSSL to store public and private keys. The reference count is set to +B<1>. EVP_PKEY_up_ref() increments the reference count of B<key>. @@ -63,14 +71,32 @@ creation of a CMAC in the B<cipher> argument. EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). New applications should use EVP_PKEY_new_raw_private_key() instead. +EVP_PKEY_get_raw_private_key() fills the buffer provided by B<priv> with raw +private key data. The number of bytes written is populated in B<*len>. If the +buffer B<priv> is NULL then B<*len> is populated with the number of bytes +required to hold the key. The calling application is responsible for ensuring +that the buffer is large enough to receive the private key data. This function +only works for algorithms that support raw private keys. Currently this is: +B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_X25519>, +B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. + +EVP_PKEY_get_raw_public_key() fills the buffer provided by B<pub> with raw +public key data. The number of bytes written is populated in B<*len>. If the +buffer B<pub> is NULL then B<*len> is populated with the number of bytes +required to hold the key. The calling application is responsible for ensuring +that the buffer is large enough to receive the public key data. This function +only works for algorithms that support raw public keys. Currently this is: +B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. + =head1 NOTES The B<EVP_PKEY> structure is used by various OpenSSL functions which require a general private key without reference to any particular algorithm. -The structure returned by EVP_PKEY_new() is empty. To add a private key to this -empty structure the functions described in L<EVP_PKEY_set1_RSA(3)> should be -used. +The structure returned by EVP_PKEY_new() is empty. To add a private or public +key to this empty structure use the appropriate functions described in +L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA>, L<EVP_PKEY_set1_DH> or +L<EVP_PKEY_set1_EC_KEY>. =head1 RETURN VALUES @@ -78,19 +104,22 @@ EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly allocated B<EVP_PKEY> structure or B<NULL> if an error occurred. -EVP_PKEY_up_ref() returns 1 for success and 0 for failure. +EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and +EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. =head1 SEE ALSO -L<EVP_PKEY_set1_RSA(3)> +L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA>, L<EVP_PKEY_set1_DH> or +L<EVP_PKEY_set1_EC_KEY> =head1 HISTORY EVP_PKEY_new() and EVP_PKEY_free() exist in all versions of OpenSSL. EVP_PKEY_up_ref() was first added to OpenSSL 1.1.0. -EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key() and -EVP_PKEY_new_CMAC_key() were first added to OpenSSL 1.1.1. +EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), +EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and +EVP_PKEY_get_raw_public_key() were first added to OpenSSL 1.1.1. =head1 COPYRIGHT |