diff options
Diffstat (limited to 'secure/lib/libcrypto/man/EVP_PKEY_new.3')
| -rw-r--r-- | secure/lib/libcrypto/man/EVP_PKEY_new.3 | 111 |
1 files changed, 94 insertions, 17 deletions
diff --git a/secure/lib/libcrypto/man/EVP_PKEY_new.3 b/secure/lib/libcrypto/man/EVP_PKEY_new.3 index 2fb880c92969..3c7a5b22262e 100644 --- a/secure/lib/libcrypto/man/EVP_PKEY_new.3 +++ b/secure/lib/libcrypto/man/EVP_PKEY_new.3 @@ -128,46 +128,123 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "EVP_PKEY_new 3" -.TH EVP_PKEY_new 3 "2018-08-14" "1.0.2p" "OpenSSL" +.IX Title "EVP_PKEY_NEW 3" +.TH EVP_PKEY_NEW 3 "2018-09-11" "1.1.1" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -EVP_PKEY_new, EVP_PKEY_free \- private key allocation functions. +EVP_PKEY_new, EVP_PKEY_up_ref, 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, EVP_PKEY_get_raw_private_key, EVP_PKEY_get_raw_public_key \&\- public/private key allocation and raw key handling functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/evp.h> \& \& EVP_PKEY *EVP_PKEY_new(void); +\& int EVP_PKEY_up_ref(EVP_PKEY *key); \& void EVP_PKEY_free(EVP_PKEY *key); +\& +\& EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e, +\& const unsigned char *key, size_t keylen); +\& EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e, +\& const unsigned char *key, size_t keylen); +\& EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, +\& size_t len, const EVP_CIPHER *cipher); +\& 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" -The \fIEVP_PKEY_new()\fR function allocates an empty \fB\s-1EVP_PKEY\s0\fR -structure which is used by OpenSSL to store private keys. +The \fIEVP_PKEY_new()\fR function allocates an empty \fB\s-1EVP_PKEY\s0\fR structure which is +used by OpenSSL to store public and private keys. The reference count is set to +\&\fB1\fR. +.PP +\&\fIEVP_PKEY_up_ref()\fR increments the reference count of \fBkey\fR. +.PP +\&\fIEVP_PKEY_free()\fR decrements the reference count of \fBkey\fR and, if the reference +count is zero, frees it up. If \fBkey\fR is \s-1NULL,\s0 nothing is done. +.PP +\&\fIEVP_PKEY_new_raw_private_key()\fR allocates a new \fB\s-1EVP_PKEY\s0\fR. If \fBe\fR is non-NULL +then the new \fB\s-1EVP_PKEY\s0\fR structure is associated with the engine \fBe\fR. The +\&\fBtype\fR argument indicates what kind of key this is. The value should be a \s-1NID\s0 +for a public key algorithm that supports raw private keys, i.e. one of +\&\fB\s-1EVP_PKEY_HMAC\s0\fR, \fB\s-1EVP_PKEY_POLY1305\s0\fR, \fB\s-1EVP_PKEY_SIPHASH\s0\fR, \fB\s-1EVP_PKEY_X25519\s0\fR, +\&\fB\s-1EVP_PKEY_ED25519\s0\fR, \fB\s-1EVP_PKEY_X448\s0\fR or \fB\s-1EVP_PKEY_ED448\s0\fR. \fBkey\fR points to the +raw private key data for this \fB\s-1EVP_PKEY\s0\fR which should be of length \fBkeylen\fR. +The length should be appropriate for the type of the key. The public key data +will be automatically derived from the given private key data (if appropriate +for the algorithm type). +.PP +\&\fIEVP_PKEY_new_raw_public_key()\fR works in the same way as +\&\fIEVP_PKEY_new_raw_private_key()\fR except that \fBkey\fR points to the raw public key +data. The \fB\s-1EVP_PKEY\s0\fR structure will be initialised without any private key +information. Algorithm types that support raw public keys are +\&\fB\s-1EVP_PKEY_X25519\s0\fR, \fB\s-1EVP_PKEY_ED25519\s0\fR, \fB\s-1EVP_PKEY_X448\s0\fR or \fB\s-1EVP_PKEY_ED448\s0\fR. .PP -\&\fIEVP_PKEY_free()\fR frees up the private key \fBkey\fR. +\&\fIEVP_PKEY_new_CMAC_key()\fR works in the same way as \fIEVP_PKEY_new_raw_private_key()\fR +except it is only for the \fB\s-1EVP_PKEY_CMAC\s0\fR algorithm type. In addition to the +raw private key data, it also takes a cipher algorithm to be used during +creation of a \s-1CMAC\s0 in the \fBcipher\fR argument. +.PP +\&\fIEVP_PKEY_new_mac_key()\fR works in the same way as \fIEVP_PKEY_new_raw_private_key()\fR. +New applications should use \fIEVP_PKEY_new_raw_private_key()\fR instead. +.PP +\&\fIEVP_PKEY_get_raw_private_key()\fR fills the buffer provided by \fBpriv\fR with raw +private key data. The number of bytes written is populated in \fB*len\fR. If the +buffer \fBpriv\fR is \s-1NULL\s0 then \fB*len\fR 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: +\&\fB\s-1EVP_PKEY_HMAC\s0\fR, \fB\s-1EVP_PKEY_POLY1305\s0\fR, \fB\s-1EVP_PKEY_SIPHASH\s0\fR, \fB\s-1EVP_PKEY_X25519\s0\fR, +\&\fB\s-1EVP_PKEY_ED25519\s0\fR, \fB\s-1EVP_PKEY_X448\s0\fR or \fB\s-1EVP_PKEY_ED448\s0\fR. +.PP +\&\fIEVP_PKEY_get_raw_public_key()\fR fills the buffer provided by \fBpub\fR with raw +public key data. The number of bytes written is populated in \fB*len\fR. If the +buffer \fBpub\fR is \s-1NULL\s0 then \fB*len\fR 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: +\&\fB\s-1EVP_PKEY_X25519\s0\fR, \fB\s-1EVP_PKEY_ED25519\s0\fR, \fB\s-1EVP_PKEY_X448\s0\fR or \fB\s-1EVP_PKEY_ED448\s0\fR. .SH "NOTES" .IX Header "NOTES" -The \fB\s-1EVP_PKEY\s0\fR structure is used by various OpenSSL functions -which require a general private key without reference to any -particular algorithm. +The \fB\s-1EVP_PKEY\s0\fR structure is used by various OpenSSL functions which require a +general private key without reference to any particular algorithm. .PP -The structure returned by \fIEVP_PKEY_new()\fR is empty. To add a -private key to this empty structure the functions described in -\&\fIEVP_PKEY_set1_RSA\fR\|(3) should be used. +The structure returned by \fIEVP_PKEY_new()\fR is empty. To add a private or public +key to this empty structure use the appropriate functions described in +\&\fIEVP_PKEY_set1_RSA\fR\|(3), EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH or +EVP_PKEY_set1_EC_KEY. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fIEVP_PKEY_new()\fR returns either the newly allocated \fB\s-1EVP_PKEY\s0\fR -structure of \fB\s-1NULL\s0\fR if an error occurred. +\&\fIEVP_PKEY_new()\fR, \fIEVP_PKEY_new_raw_private_key()\fR, \fIEVP_PKEY_new_raw_public_key()\fR, +\&\fIEVP_PKEY_new_CMAC_key()\fR and \fIEVP_PKEY_new_mac_key()\fR return either the newly +allocated \fB\s-1EVP_PKEY\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred. .PP -\&\fIEVP_PKEY_free()\fR does not return a value. +\&\fIEVP_PKEY_up_ref()\fR, \fIEVP_PKEY_get_raw_private_key()\fR and +\&\fIEVP_PKEY_get_raw_public_key()\fR return 1 for success and 0 for failure. .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fIEVP_PKEY_set1_RSA\fR\|(3) +\&\fIEVP_PKEY_set1_RSA\fR\|(3), EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH or +EVP_PKEY_set1_EC_KEY .SH "HISTORY" .IX Header "HISTORY" -\&\s-1TBA\s0 +\&\fIEVP_PKEY_new()\fR and \fIEVP_PKEY_free()\fR exist in all versions of OpenSSL. +.PP +\&\fIEVP_PKEY_up_ref()\fR was first added to OpenSSL 1.1.0. +\&\fIEVP_PKEY_new_raw_private_key()\fR, \fIEVP_PKEY_new_raw_public_key()\fR, +\&\fIEVP_PKEY_new_CMAC_key()\fR, \fIEVP_PKEY_new_raw_private_key()\fR and +\&\fIEVP_PKEY_get_raw_public_key()\fR were first added to OpenSSL 1.1.1. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |