doc/man3/EVP_PKEY_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_new,
   6 EVP_PKEY_up_ref,
   7 EVP_PKEY_free,
   8 EVP_PKEY_new_raw_private_key_with_libctx,
   9 EVP_PKEY_new_raw_private_key,
  10 EVP_PKEY_new_raw_public_key_with_libctx,
  11 EVP_PKEY_new_raw_public_key,
  12 EVP_PKEY_new_CMAC_key_with_libctx,
  13 EVP_PKEY_new_CMAC_key,
  14 EVP_PKEY_new_mac_key,
  15 EVP_PKEY_get_raw_private_key,
  16 EVP_PKEY_get_raw_public_key
  17 - public/private key allocation and raw key handling functions
  18
  19 =head1 SYNOPSIS
  20
  21  #include <openssl/evp.h>
  22
  23  EVP_PKEY *EVP_PKEY_new(void);
  24  int EVP_PKEY_up_ref(EVP_PKEY *key);
  25  void EVP_PKEY_free(EVP_PKEY *key);
  26
  27  EVP_PKEY *EVP_PKEY_new_raw_private_key_with_libctx(OPENSSL_CTX *libctx,
  28                                                     const char *keytype,
  29                                                     const char *propq,
  30                                                     const unsigned char *key,
  31                                                     size_t keylen);
  32  EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e,
  33                                         const unsigned char *key, size_t keylen);
  34  EVP_PKEY *EVP_PKEY_new_raw_public_key_with_libctx(OPENSSL_CTX *libctx,
  35                                                    const char *keytype,
  36                                                    const char *propq,
  37                                                    const unsigned char *key,
  38                                                    size_t keylen);
  39  EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e,
  40                                        const unsigned char *key, size_t keylen);
  41  EVP_PKEY *EVP_PKEY_new_CMAC_key_with_libctx(const unsigned char *priv,
  42                                              size_t len,
  43                                              const char *cipher_name,
  44                                              OPENSSL_CTX *libctx,
  45                                              const char *propq);
  46  EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv,
  47                                  size_t len, const EVP_CIPHER *cipher);
  48  EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key,
  49                                 int keylen);
  50
  51  int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv,
  52                                   size_t *len);
  53  int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub,
  54                                  size_t *len);
  55
  56 =head1 DESCRIPTION
  57
  58 The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is
  59 used by OpenSSL to store public and private keys. The reference count is set to
  60 B<1>.
  61
  62 EVP_PKEY_up_ref() increments the reference count of I<key>.
  63
  64 EVP_PKEY_free() decrements the reference count of I<key> and, if the reference
  65 count is zero, frees it up. If I<key> is NULL, nothing is done.
  66
  67 EVP_PKEY_new_raw_private_key_with_libctx() allocates a new B<EVP_PKEY>. Unless
  68 an engine should be used for the key type, a provider for the key is found using
  69 the library context I<libctx> and the property query string I<propq>. The
  70 I<keytype> argument indicates what kind of key this is. The value should be a
  71 string for a public key algorithm that supports raw private keys, i.e one of
  72 "POLY1305", "SIPHASH", "X25519", "ED25519", "X448" or "ED448". Note that you may
  73 also use "HMAC" which is not a public key algorithm but is treated as such by
  74 some OpenSSL APIs. You are encouraged to use the EVP_MAC APIs instead for HMAC
  75 (see L<EVP_MAC(3)>). I<key> points to the raw private key data for this
  76 B<EVP_PKEY> which should be of length I<keylen>. The length should be
  77 appropriate for the type of the key. The public key data will be automatically
  78 derived from the given private key data (if appropriate for the algorithm type).
  79
  80 EVP_PKEY_new_raw_private_key() does the same as
  81 EVP_PKEY_new_raw_private_key_with_libctx() except that the default library
  82 context and default property query are used instead. If I<e> is non-NULL then
  83 the new B<EVP_PKEY> structure is associated with the engine I<e>. The I<type>
  84 argument indicates what kind of key this is. The value should be a NID for a
  85 public key algorithm that supports raw private keys, i.e. one of
  86 B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_X25519>,
  87 B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. As for
  88 EVP_PKEY_new_raw_private_key_with_libctx() you may also use B<EVP_PKEY_HMAC>.
  89
  90 EVP_PKEY_new_raw_public_key_with_libctx() works in the same way as
  91 EVP_PKEY_new_raw_private_key_with_libctx() except that I<key> points to the raw
  92 public key data. The B<EVP_PKEY> structure will be initialised without any
  93 private key information. Algorithm types that support raw public keys are
  94 "X25519", "ED25519", "X448" or "ED448".
  95
  96 EVP_PKEY_new_raw_public_key() works in the same way as
  97 EVP_PKEY_new_raw_private_key() except that I<key> points to the raw public key
  98 data. The B<EVP_PKEY> structure will be initialised without any private key
  99 information. Algorithm types that support raw public keys are
 100 B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
 101
 102 EVP_PKEY_new_CMAC_key_with_libctx() works in the same way as
 103 EVP_PKEY_new_raw_private_key() except it is only for the B<EVP_PKEY_CMAC>
 104 algorithm type. In addition to the raw private key data, it also takes a cipher
 105 algorithm to be used during creation of a CMAC in the I<cipher> argument. The
 106 cipher should be a standard encryption only cipher. For example AEAD and XTS
 107 ciphers should not be used. Finally it also takes a library context I<libctx>
 108 and property query I<propq> which are used when fetching any cryptographic
 109 algorithms which may be NULL to use the default values.
 110
 111 EVP_PKEY_new_CMAC_key() is the same as EVP_PKEY_new_CMAC_key_with_libctx()
 112 except that the default values are used for I<libctx> and I<propq>.
 113
 114 EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key().
 115 New applications should use EVP_PKEY_new_raw_private_key() instead.
 116
 117 EVP_PKEY_get_raw_private_key() fills the buffer provided by I<priv> with raw
 118 private key data. The size of the I<priv> buffer should be in I<*len> on entry
 119 to the function, and on exit I<*len> is updated with the number of bytes
 120 actually written. If the buffer I<priv> is NULL then I<*len> is populated with
 121 the number of bytes required to hold the key. The calling application is
 122 responsible for ensuring that the buffer is large enough to receive the private
 123 key data. This function only works for algorithms that support raw private keys.
 124 Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>,
 125 B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
 126
 127 EVP_PKEY_get_raw_public_key() fills the buffer provided by I<pub> with raw
 128 public key data. The size of the I<pub> buffer should be in I<*len> on entry
 129 to the function, and on exit I<*len> is updated with the number of bytes
 130 actually written. If the buffer I<pub> is NULL then I<*len> is populated with
 131 the number of bytes required to hold the key. The calling application is
 132 responsible for ensuring that the buffer is large enough to receive the public
 133 key data. This function only works for algorithms that support raw public  keys.
 134 Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or
 135 B<EVP_PKEY_ED448>.
 136
 137 =head1 NOTES
 138
 139 The B<EVP_PKEY> structure is used by various OpenSSL functions which require a
 140 general private key without reference to any particular algorithm.
 141
 142 The structure returned by EVP_PKEY_new() is empty. To add a private or public
 143 key to this empty structure use the appropriate functions described in
 144 L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or
 145 L<EVP_PKEY_set1_EC_KEY(3)>.
 146
 147 =head1 RETURN VALUES
 148
 149 EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(),
 150 EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly
 151 allocated B<EVP_PKEY> structure or B<NULL> if an error occurred.
 152
 153 EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and
 154 EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure.
 155
 156 =head1 SEE ALSO
 157
 158 L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or
 159 L<EVP_PKEY_set1_EC_KEY(3)>
 160
 161 =head1 HISTORY
 162
 163 The
 164 EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL.
 165
 166 The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0.
 167
 168 The
 169 EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(),
 170 EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and
 171 EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1.
 172
 173 The EVP_PKEY_new_raw_private_key_with_libctx(),
 174 EVP_PKEY_new_raw_public_key_with_libctx() and
 175 EVP_PKEY_new_CMAC_key_with_libctx() functions were added in OpenSSL 3.0.
 176
 177 =head1 COPYRIGHT
 178
 179 Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.
 180
 181 Licensed under the Apache License 2.0 (the "License").  You may not use
 182 this file except in compliance with the License.  You can obtain a copy
 183 in the file LICENSE in the source distribution or at
 184 L<https://www.openssl.org/source/license.html>.
 185
 186 =cut