Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 1 | /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) |
| 2 | * All rights reserved. |
| 3 | * |
| 4 | * This package is an SSL implementation written |
| 5 | * by Eric Young (eay@cryptsoft.com). |
| 6 | * The implementation was written so as to conform with Netscapes SSL. |
| 7 | * |
| 8 | * This library is free for commercial and non-commercial use as long as |
| 9 | * the following conditions are aheared to. The following conditions |
| 10 | * apply to all code found in this distribution, be it the RC4, RSA, |
| 11 | * lhash, DES, etc., code; not just the SSL code. The SSL documentation |
| 12 | * included with this distribution is covered by the same copyright terms |
| 13 | * except that the holder is Tim Hudson (tjh@cryptsoft.com). |
| 14 | * |
| 15 | * Copyright remains Eric Young's, and as such any Copyright notices in |
| 16 | * the code are not to be removed. |
| 17 | * If this package is used in a product, Eric Young should be given attribution |
| 18 | * as the author of the parts of the library used. |
| 19 | * This can be in the form of a textual message at program startup or |
| 20 | * in documentation (online or textual) provided with the package. |
| 21 | * |
| 22 | * Redistribution and use in source and binary forms, with or without |
| 23 | * modification, are permitted provided that the following conditions |
| 24 | * are met: |
| 25 | * 1. Redistributions of source code must retain the copyright |
| 26 | * notice, this list of conditions and the following disclaimer. |
| 27 | * 2. Redistributions in binary form must reproduce the above copyright |
| 28 | * notice, this list of conditions and the following disclaimer in the |
| 29 | * documentation and/or other materials provided with the distribution. |
| 30 | * 3. All advertising materials mentioning features or use of this software |
| 31 | * must display the following acknowledgement: |
| 32 | * "This product includes cryptographic software written by |
| 33 | * Eric Young (eay@cryptsoft.com)" |
| 34 | * The word 'cryptographic' can be left out if the rouines from the library |
| 35 | * being used are not cryptographic related :-). |
| 36 | * 4. If you include any Windows specific code (or a derivative thereof) from |
| 37 | * the apps directory (application code) you must include an acknowledgement: |
| 38 | * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)" |
| 39 | * |
| 40 | * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND |
| 41 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 42 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 43 | * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 44 | * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 45 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 46 | * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 47 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 48 | * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 49 | * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 50 | * SUCH DAMAGE. |
| 51 | * |
| 52 | * The licence and distribution terms for any publically available version or |
| 53 | * derivative of this code cannot be changed. i.e. this code cannot simply be |
| 54 | * copied and put under another distribution licence |
| 55 | * [including the GNU Public Licence.] */ |
| 56 | |
| 57 | #ifndef OPENSSL_HEADER_EVP_H |
| 58 | #define OPENSSL_HEADER_EVP_H |
| 59 | |
| 60 | #include <openssl/base.h> |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 61 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 62 | #include <openssl/thread.h> |
| 63 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 64 | // OpenSSL included digest and cipher functions in this header so we include |
| 65 | // them for users that still expect that. |
| 66 | // |
| 67 | // TODO(fork): clean up callers so that they include what they use. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 68 | #include <openssl/aead.h> |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 69 | #include <openssl/base64.h> |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 70 | #include <openssl/cipher.h> |
| 71 | #include <openssl/digest.h> |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 72 | #include <openssl/nid.h> |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 73 | |
| 74 | #if defined(__cplusplus) |
| 75 | extern "C" { |
| 76 | #endif |
| 77 | |
| 78 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 79 | // EVP abstracts over public/private key algorithms. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 80 | |
| 81 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 82 | // Public key objects. |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 83 | // |
| 84 | // An |EVP_PKEY| object represents a public or private key. A given object may |
| 85 | // be used concurrently on multiple threads by non-mutating functions, provided |
| 86 | // no other thread is concurrently calling a mutating function. Unless otherwise |
| 87 | // documented, functions which take a |const| pointer are non-mutating and |
| 88 | // functions which take a non-|const| pointer are mutating. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 89 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 90 | // EVP_PKEY_new creates a new, empty public-key object and returns it or NULL |
| 91 | // on allocation failure. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 92 | OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new(void); |
| 93 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 94 | // EVP_PKEY_free frees all data referenced by |pkey| and then frees |pkey| |
| 95 | // itself. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 96 | OPENSSL_EXPORT void EVP_PKEY_free(EVP_PKEY *pkey); |
| 97 | |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 98 | // EVP_PKEY_up_ref increments the reference count of |pkey| and returns one. It |
| 99 | // does not mutate |pkey| for thread-safety purposes and may be used |
| 100 | // concurrently. |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 101 | OPENSSL_EXPORT int EVP_PKEY_up_ref(EVP_PKEY *pkey); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 102 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 103 | // EVP_PKEY_is_opaque returns one if |pkey| is opaque. Opaque keys are backed by |
| 104 | // custom implementations which do not expose key material and parameters. It is |
| 105 | // an error to attempt to duplicate, export, or compare an opaque key. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 106 | OPENSSL_EXPORT int EVP_PKEY_is_opaque(const EVP_PKEY *pkey); |
| 107 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 108 | // EVP_PKEY_cmp compares |a| and |b| and returns one if they are equal, zero if |
| 109 | // not and a negative number on error. |
| 110 | // |
| 111 | // WARNING: this differs from the traditional return value of a "cmp" |
| 112 | // function. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 113 | OPENSSL_EXPORT int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); |
| 114 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 115 | // EVP_PKEY_copy_parameters sets the parameters of |to| to equal the parameters |
| 116 | // of |from|. It returns one on success and zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 117 | OPENSSL_EXPORT int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); |
| 118 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 119 | // EVP_PKEY_missing_parameters returns one if |pkey| is missing needed |
| 120 | // parameters or zero if not, or if the algorithm doesn't take parameters. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 121 | OPENSSL_EXPORT int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); |
| 122 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 123 | // EVP_PKEY_size returns the maximum size, in bytes, of a signature signed by |
| 124 | // |pkey|. For an RSA key, this returns the number of bytes needed to represent |
| 125 | // the modulus. For an EC key, this returns the maximum size of a DER-encoded |
| 126 | // ECDSA signature. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 127 | OPENSSL_EXPORT int EVP_PKEY_size(const EVP_PKEY *pkey); |
| 128 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 129 | // EVP_PKEY_bits returns the "size", in bits, of |pkey|. For an RSA key, this |
| 130 | // returns the bit length of the modulus. For an EC key, this returns the bit |
| 131 | // length of the group order. |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 132 | OPENSSL_EXPORT int EVP_PKEY_bits(const EVP_PKEY *pkey); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 133 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 134 | // EVP_PKEY_id returns the type of |pkey|, which is one of the |EVP_PKEY_*| |
| 135 | // values. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 136 | OPENSSL_EXPORT int EVP_PKEY_id(const EVP_PKEY *pkey); |
| 137 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 138 | // EVP_PKEY_type returns |nid| if |nid| is a known key type and |NID_undef| |
| 139 | // otherwise. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 140 | OPENSSL_EXPORT int EVP_PKEY_type(int nid); |
| 141 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 142 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 143 | // Getting and setting concrete public key types. |
| 144 | // |
| 145 | // The following functions get and set the underlying public key in an |
| 146 | // |EVP_PKEY| object. The |set1| functions take an additional reference to the |
Robert Sloan | d9e572d | 2018-08-27 12:27:00 -0700 | [diff] [blame] | 147 | // underlying key and return one on success or zero if |key| is NULL. The |
| 148 | // |assign| functions adopt the caller's reference and return one on success or |
| 149 | // zero if |key| is NULL. The |get1| functions return a fresh reference to the |
| 150 | // underlying object or NULL if |pkey| is not of the correct type. The |get0| |
| 151 | // functions behave the same but return a non-owning pointer. |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 152 | // |
| 153 | // The |get0| and |get1| functions take |const| pointers and are thus |
| 154 | // non-mutating for thread-safety purposes, but mutating functions on the |
| 155 | // returned lower-level objects are considered to also mutate the |EVP_PKEY| and |
| 156 | // may not be called concurrently with other operations on the |EVP_PKEY|. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 157 | |
| 158 | OPENSSL_EXPORT int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); |
| 159 | OPENSSL_EXPORT int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 160 | OPENSSL_EXPORT RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey); |
| 161 | OPENSSL_EXPORT RSA *EVP_PKEY_get1_RSA(const EVP_PKEY *pkey); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 162 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 163 | OPENSSL_EXPORT int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 164 | OPENSSL_EXPORT int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 165 | OPENSSL_EXPORT DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey); |
| 166 | OPENSSL_EXPORT DSA *EVP_PKEY_get1_DSA(const EVP_PKEY *pkey); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 167 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 168 | OPENSSL_EXPORT int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 169 | OPENSSL_EXPORT int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 170 | OPENSSL_EXPORT EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey); |
| 171 | OPENSSL_EXPORT EC_KEY *EVP_PKEY_get1_EC_KEY(const EVP_PKEY *pkey); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 172 | |
Srinivas Paladugu | dd42a61 | 2019-08-09 19:30:39 +0000 | [diff] [blame^] | 173 | // EVP_PKEY_new_ed25519_public returns a newly allocated |EVP_PKEY| wrapping an |
| 174 | // Ed25519 public key, or NULL on allocation error. |
| 175 | OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new_ed25519_public( |
| 176 | const uint8_t public_key[32]); |
| 177 | |
| 178 | // EVP_PKEY_new_ed25519_private returns a newly allocated |EVP_PKEY| wrapping an |
| 179 | // Ed25519 private key, or NULL on allocation error. |
| 180 | OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new_ed25519_private( |
| 181 | const uint8_t private_key[64]); |
| 182 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 183 | #define EVP_PKEY_NONE NID_undef |
| 184 | #define EVP_PKEY_RSA NID_rsaEncryption |
Adam Vartanian | bfcf3a7 | 2018-08-10 14:55:24 +0100 | [diff] [blame] | 185 | #define EVP_PKEY_RSA_PSS NID_rsassaPss |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 186 | #define EVP_PKEY_DSA NID_dsa |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 187 | #define EVP_PKEY_EC NID_X9_62_id_ecPublicKey |
Robert Sloan | 8ff0355 | 2017-06-14 12:40:58 -0700 | [diff] [blame] | 188 | #define EVP_PKEY_ED25519 NID_ED25519 |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 189 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 190 | // EVP_PKEY_assign sets the underlying key of |pkey| to |key|, which must be of |
Robert Sloan | d9e572d | 2018-08-27 12:27:00 -0700 | [diff] [blame] | 191 | // the given type. It returns one if successful or zero if the |type| argument |
| 192 | // is not one of the |EVP_PKEY_*| values or if |key| is NULL. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 193 | OPENSSL_EXPORT int EVP_PKEY_assign(EVP_PKEY *pkey, int type, void *key); |
| 194 | |
Robert Sloan | d9e572d | 2018-08-27 12:27:00 -0700 | [diff] [blame] | 195 | // EVP_PKEY_set_type sets the type of |pkey| to |type|. It returns one if |
| 196 | // successful or zero if the |type| argument is not one of the |EVP_PKEY_*| |
| 197 | // values. If |pkey| is NULL, it simply reports whether the type is known. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 198 | OPENSSL_EXPORT int EVP_PKEY_set_type(EVP_PKEY *pkey, int type); |
| 199 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 200 | // EVP_PKEY_cmp_parameters compares the parameters of |a| and |b|. It returns |
| 201 | // one if they match, zero if not, or a negative number of on error. |
| 202 | // |
| 203 | // WARNING: the return value differs from the usual return value convention. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 204 | OPENSSL_EXPORT int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, |
| 205 | const EVP_PKEY *b); |
| 206 | |
| 207 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 208 | // ASN.1 functions |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 209 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 210 | // EVP_parse_public_key decodes a DER-encoded SubjectPublicKeyInfo structure |
| 211 | // (RFC 5280) from |cbs| and advances |cbs|. It returns a newly-allocated |
Robert Sloan | d9e572d | 2018-08-27 12:27:00 -0700 | [diff] [blame] | 212 | // |EVP_PKEY| or NULL on error. If the key is an EC key, the curve is guaranteed |
| 213 | // to be set. |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 214 | // |
| 215 | // The caller must check the type of the parsed public key to ensure it is |
| 216 | // suitable and validate other desired key properties such as RSA modulus size |
| 217 | // or EC curve. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 218 | OPENSSL_EXPORT EVP_PKEY *EVP_parse_public_key(CBS *cbs); |
| 219 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 220 | // EVP_marshal_public_key marshals |key| as a DER-encoded SubjectPublicKeyInfo |
| 221 | // structure (RFC 5280) and appends the result to |cbb|. It returns one on |
| 222 | // success and zero on error. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 223 | OPENSSL_EXPORT int EVP_marshal_public_key(CBB *cbb, const EVP_PKEY *key); |
| 224 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 225 | // EVP_parse_private_key decodes a DER-encoded PrivateKeyInfo structure (RFC |
| 226 | // 5208) from |cbs| and advances |cbs|. It returns a newly-allocated |EVP_PKEY| |
| 227 | // or NULL on error. |
| 228 | // |
| 229 | // The caller must check the type of the parsed private key to ensure it is |
| 230 | // suitable and validate other desired key properties such as RSA modulus size |
| 231 | // or EC curve. |
| 232 | // |
| 233 | // A PrivateKeyInfo ends with an optional set of attributes. These are not |
| 234 | // processed and so this function will silently ignore any trailing data in the |
| 235 | // structure. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 236 | OPENSSL_EXPORT EVP_PKEY *EVP_parse_private_key(CBS *cbs); |
| 237 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 238 | // EVP_marshal_private_key marshals |key| as a DER-encoded PrivateKeyInfo |
| 239 | // structure (RFC 5208) and appends the result to |cbb|. It returns one on |
| 240 | // success and zero on error. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 241 | OPENSSL_EXPORT int EVP_marshal_private_key(CBB *cbb, const EVP_PKEY *key); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 242 | |
| 243 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 244 | // Signing |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 245 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 246 | // EVP_DigestSignInit sets up |ctx| for a signing operation with |type| and |
| 247 | // |pkey|. The |ctx| argument must have been initialised with |
| 248 | // |EVP_MD_CTX_init|. If |pctx| is not NULL, the |EVP_PKEY_CTX| of the signing |
| 249 | // operation will be written to |*pctx|; this can be used to set alternative |
| 250 | // signing options. |
| 251 | // |
| 252 | // For single-shot signing algorithms which do not use a pre-hash, such as |
| 253 | // Ed25519, |type| should be NULL. The |EVP_MD_CTX| itself is unused but is |
| 254 | // present so the API is uniform. See |EVP_DigestSign|. |
| 255 | // |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 256 | // This function does not mutate |pkey| for thread-safety purposes and may be |
| 257 | // used concurrently with other non-mutating functions on |pkey|. |
| 258 | // |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 259 | // It returns one on success, or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 260 | OPENSSL_EXPORT int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, |
| 261 | const EVP_MD *type, ENGINE *e, |
| 262 | EVP_PKEY *pkey); |
| 263 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 264 | // EVP_DigestSignUpdate appends |len| bytes from |data| to the data which will |
| 265 | // be signed in |EVP_DigestSignFinal|. It returns one. |
| 266 | // |
| 267 | // This function performs a streaming signing operation and will fail for |
| 268 | // signature algorithms which do not support this. Use |EVP_DigestSign| for a |
| 269 | // single-shot operation. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 270 | OPENSSL_EXPORT int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *data, |
| 271 | size_t len); |
| 272 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 273 | // EVP_DigestSignFinal signs the data that has been included by one or more |
| 274 | // calls to |EVP_DigestSignUpdate|. If |out_sig| is NULL then |*out_sig_len| is |
| 275 | // set to the maximum number of output bytes. Otherwise, on entry, |
| 276 | // |*out_sig_len| must contain the length of the |out_sig| buffer. If the call |
| 277 | // is successful, the signature is written to |out_sig| and |*out_sig_len| is |
| 278 | // set to its length. |
| 279 | // |
| 280 | // This function performs a streaming signing operation and will fail for |
| 281 | // signature algorithms which do not support this. Use |EVP_DigestSign| for a |
| 282 | // single-shot operation. |
| 283 | // |
| 284 | // It returns one on success, or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 285 | OPENSSL_EXPORT int EVP_DigestSignFinal(EVP_MD_CTX *ctx, uint8_t *out_sig, |
| 286 | size_t *out_sig_len); |
| 287 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 288 | // EVP_DigestSign signs |data_len| bytes from |data| using |ctx|. If |out_sig| |
| 289 | // is NULL then |*out_sig_len| is set to the maximum number of output |
| 290 | // bytes. Otherwise, on entry, |*out_sig_len| must contain the length of the |
| 291 | // |out_sig| buffer. If the call is successful, the signature is written to |
| 292 | // |out_sig| and |*out_sig_len| is set to its length. |
| 293 | // |
| 294 | // It returns one on success and zero on error. |
Robert Sloan | 8ff0355 | 2017-06-14 12:40:58 -0700 | [diff] [blame] | 295 | OPENSSL_EXPORT int EVP_DigestSign(EVP_MD_CTX *ctx, uint8_t *out_sig, |
| 296 | size_t *out_sig_len, const uint8_t *data, |
| 297 | size_t data_len); |
| 298 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 299 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 300 | // Verifying |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 301 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 302 | // EVP_DigestVerifyInit sets up |ctx| for a signature verification operation |
| 303 | // with |type| and |pkey|. The |ctx| argument must have been initialised with |
| 304 | // |EVP_MD_CTX_init|. If |pctx| is not NULL, the |EVP_PKEY_CTX| of the signing |
| 305 | // operation will be written to |*pctx|; this can be used to set alternative |
| 306 | // signing options. |
| 307 | // |
| 308 | // For single-shot signing algorithms which do not use a pre-hash, such as |
| 309 | // Ed25519, |type| should be NULL. The |EVP_MD_CTX| itself is unused but is |
| 310 | // present so the API is uniform. See |EVP_DigestVerify|. |
| 311 | // |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 312 | // This function does not mutate |pkey| for thread-safety purposes and may be |
| 313 | // used concurrently with other non-mutating functions on |pkey|. |
| 314 | // |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 315 | // It returns one on success, or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 316 | OPENSSL_EXPORT int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, |
| 317 | const EVP_MD *type, ENGINE *e, |
| 318 | EVP_PKEY *pkey); |
| 319 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 320 | // EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which |
| 321 | // will be verified by |EVP_DigestVerifyFinal|. It returns one. |
| 322 | // |
| 323 | // This function performs streaming signature verification and will fail for |
| 324 | // signature algorithms which do not support this. Use |EVP_PKEY_verify_message| |
| 325 | // for a single-shot verification. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 326 | OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data, |
| 327 | size_t len); |
| 328 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 329 | // EVP_DigestVerifyFinal verifies that |sig_len| bytes of |sig| are a valid |
| 330 | // signature for the data that has been included by one or more calls to |
| 331 | // |EVP_DigestVerifyUpdate|. It returns one on success and zero otherwise. |
| 332 | // |
| 333 | // This function performs streaming signature verification and will fail for |
| 334 | // signature algorithms which do not support this. Use |EVP_PKEY_verify_message| |
| 335 | // for a single-shot verification. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 336 | OPENSSL_EXPORT int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const uint8_t *sig, |
| 337 | size_t sig_len); |
| 338 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 339 | // EVP_DigestVerify verifies that |sig_len| bytes from |sig| are a valid |
| 340 | // signature for |data|. It returns one on success or zero on error. |
Robert Sloan | 8ff0355 | 2017-06-14 12:40:58 -0700 | [diff] [blame] | 341 | OPENSSL_EXPORT int EVP_DigestVerify(EVP_MD_CTX *ctx, const uint8_t *sig, |
| 342 | size_t sig_len, const uint8_t *data, |
| 343 | size_t len); |
| 344 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 345 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 346 | // Signing (old functions) |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 347 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 348 | // EVP_SignInit_ex configures |ctx|, which must already have been initialised, |
| 349 | // for a fresh signing operation using the hash function |type|. It returns one |
| 350 | // on success and zero otherwise. |
| 351 | // |
| 352 | // (In order to initialise |ctx|, either obtain it initialised with |
| 353 | // |EVP_MD_CTX_create|, or use |EVP_MD_CTX_init|.) |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 354 | OPENSSL_EXPORT int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, |
| 355 | ENGINE *impl); |
| 356 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 357 | // EVP_SignInit is a deprecated version of |EVP_SignInit_ex|. |
| 358 | // |
| 359 | // TODO(fork): remove. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 360 | OPENSSL_EXPORT int EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); |
| 361 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 362 | // EVP_SignUpdate appends |len| bytes from |data| to the data which will be |
| 363 | // signed in |EVP_SignFinal|. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 364 | OPENSSL_EXPORT int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *data, |
| 365 | size_t len); |
| 366 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 367 | // EVP_SignFinal signs the data that has been included by one or more calls to |
| 368 | // |EVP_SignUpdate|, using the key |pkey|, and writes it to |sig|. On entry, |
| 369 | // |sig| must point to at least |EVP_PKEY_size(pkey)| bytes of space. The |
| 370 | // actual size of the signature is written to |*out_sig_len|. |
| 371 | // |
| 372 | // It returns one on success and zero otherwise. |
| 373 | // |
| 374 | // It does not modify |ctx|, thus it's possible to continue to use |ctx| in |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 375 | // order to sign a longer message. It also does not mutate |pkey| for |
| 376 | // thread-safety purposes and may be used concurrently with other non-mutating |
| 377 | // functions on |pkey|. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 378 | OPENSSL_EXPORT int EVP_SignFinal(const EVP_MD_CTX *ctx, uint8_t *sig, |
| 379 | unsigned int *out_sig_len, EVP_PKEY *pkey); |
| 380 | |
| 381 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 382 | // Verifying (old functions) |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 383 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 384 | // EVP_VerifyInit_ex configures |ctx|, which must already have been |
| 385 | // initialised, for a fresh signature verification operation using the hash |
| 386 | // function |type|. It returns one on success and zero otherwise. |
| 387 | // |
| 388 | // (In order to initialise |ctx|, either obtain it initialised with |
| 389 | // |EVP_MD_CTX_create|, or use |EVP_MD_CTX_init|.) |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 390 | OPENSSL_EXPORT int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, |
| 391 | ENGINE *impl); |
| 392 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 393 | // EVP_VerifyInit is a deprecated version of |EVP_VerifyInit_ex|. |
| 394 | // |
| 395 | // TODO(fork): remove. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 396 | OPENSSL_EXPORT int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); |
| 397 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 398 | // EVP_VerifyUpdate appends |len| bytes from |data| to the data which will be |
| 399 | // signed in |EVP_VerifyFinal|. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 400 | OPENSSL_EXPORT int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *data, |
| 401 | size_t len); |
| 402 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 403 | // EVP_VerifyFinal verifies that |sig_len| bytes of |sig| are a valid |
| 404 | // signature, by |pkey|, for the data that has been included by one or more |
| 405 | // calls to |EVP_VerifyUpdate|. |
| 406 | // |
| 407 | // It returns one on success and zero otherwise. |
| 408 | // |
| 409 | // It does not modify |ctx|, thus it's possible to continue to use |ctx| in |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 410 | // order to verify a longer message. It also does not mutate |pkey| for |
| 411 | // thread-safety purposes and may be used concurrently with other non-mutating |
| 412 | // functions on |pkey|. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 413 | OPENSSL_EXPORT int EVP_VerifyFinal(EVP_MD_CTX *ctx, const uint8_t *sig, |
| 414 | size_t sig_len, EVP_PKEY *pkey); |
| 415 | |
| 416 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 417 | // Printing |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 418 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 419 | // EVP_PKEY_print_public prints a textual representation of the public key in |
| 420 | // |pkey| to |out|. Returns one on success or zero otherwise. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 421 | OPENSSL_EXPORT int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, |
| 422 | int indent, ASN1_PCTX *pctx); |
| 423 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 424 | // EVP_PKEY_print_private prints a textual representation of the private key in |
| 425 | // |pkey| to |out|. Returns one on success or zero otherwise. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 426 | OPENSSL_EXPORT int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, |
| 427 | int indent, ASN1_PCTX *pctx); |
| 428 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 429 | // EVP_PKEY_print_params prints a textual representation of the parameters in |
| 430 | // |pkey| to |out|. Returns one on success or zero otherwise. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 431 | OPENSSL_EXPORT int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, |
| 432 | int indent, ASN1_PCTX *pctx); |
| 433 | |
| 434 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 435 | // Password stretching. |
| 436 | // |
| 437 | // Password stretching functions take a low-entropy password and apply a slow |
| 438 | // function that results in a key suitable for use in symmetric |
| 439 | // cryptography. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 440 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 441 | // PKCS5_PBKDF2_HMAC computes |iterations| iterations of PBKDF2 of |password| |
| 442 | // and |salt|, using |digest|, and outputs |key_len| bytes to |out_key|. It |
Robert Sloan | d9e572d | 2018-08-27 12:27:00 -0700 | [diff] [blame] | 443 | // returns one on success and zero on allocation failure or if iterations is 0. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 444 | OPENSSL_EXPORT int PKCS5_PBKDF2_HMAC(const char *password, size_t password_len, |
| 445 | const uint8_t *salt, size_t salt_len, |
| 446 | unsigned iterations, const EVP_MD *digest, |
| 447 | size_t key_len, uint8_t *out_key); |
| 448 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 449 | // PKCS5_PBKDF2_HMAC_SHA1 is the same as PKCS5_PBKDF2_HMAC, but with |digest| |
| 450 | // fixed to |EVP_sha1|. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 451 | OPENSSL_EXPORT int PKCS5_PBKDF2_HMAC_SHA1(const char *password, |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 452 | size_t password_len, |
| 453 | const uint8_t *salt, size_t salt_len, |
| 454 | unsigned iterations, size_t key_len, |
| 455 | uint8_t *out_key); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 456 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 457 | // EVP_PBE_scrypt expands |password| into a secret key of length |key_len| using |
| 458 | // scrypt, as described in RFC 7914, and writes the result to |out_key|. It |
Robert Sloan | d9e572d | 2018-08-27 12:27:00 -0700 | [diff] [blame] | 459 | // returns one on success and zero on allocation failure, if the memory required |
| 460 | // for the operation exceeds |max_mem|, or if any of the parameters are invalid |
| 461 | // as described below. |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 462 | // |
| 463 | // |N|, |r|, and |p| are as described in RFC 7914 section 6. They determine the |
Robert Sloan | d9e572d | 2018-08-27 12:27:00 -0700 | [diff] [blame] | 464 | // cost of the operation. If |max_mem| is zero, a defult limit of 32MiB will be |
| 465 | // used. |
| 466 | // |
| 467 | // The parameters are considered invalid under any of the following conditions: |
| 468 | // - |r| or |p| are zero |
| 469 | // - |p| > (2^30 - 1) / |r| |
| 470 | // - |N| is not a power of two |
| 471 | // - |N| > 2^32 |
| 472 | // - |N| > 2^(128 * |r| / 8) |
Robert Sloan | 8ff0355 | 2017-06-14 12:40:58 -0700 | [diff] [blame] | 473 | OPENSSL_EXPORT int EVP_PBE_scrypt(const char *password, size_t password_len, |
| 474 | const uint8_t *salt, size_t salt_len, |
| 475 | uint64_t N, uint64_t r, uint64_t p, |
| 476 | size_t max_mem, uint8_t *out_key, |
| 477 | size_t key_len); |
| 478 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 479 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 480 | // Public key contexts. |
| 481 | // |
| 482 | // |EVP_PKEY_CTX| objects hold the context of an operation (e.g. signing or |
| 483 | // encrypting) that uses a public key. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 484 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 485 | // EVP_PKEY_CTX_new allocates a fresh |EVP_PKEY_CTX| for use with |pkey|. It |
| 486 | // returns the context or NULL on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 487 | OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); |
| 488 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 489 | // EVP_PKEY_CTX_new_id allocates a fresh |EVP_PKEY_CTX| for a key of type |id| |
| 490 | // (e.g. |EVP_PKEY_HMAC|). This can be used for key generation where |
| 491 | // |EVP_PKEY_CTX_new| can't be used because there isn't an |EVP_PKEY| to pass |
| 492 | // it. It returns the context or NULL on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 493 | OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); |
| 494 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 495 | // EVP_PKEY_CTX_free frees |ctx| and the data it owns. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 496 | OPENSSL_EXPORT void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); |
| 497 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 498 | // EVP_PKEY_CTX_dup allocates a fresh |EVP_PKEY_CTX| and sets it equal to the |
| 499 | // state of |ctx|. It returns the fresh |EVP_PKEY_CTX| or NULL on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 500 | OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); |
| 501 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 502 | // EVP_PKEY_CTX_get0_pkey returns the |EVP_PKEY| associated with |ctx|. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 503 | OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_CTX_get0_pkey(EVP_PKEY_CTX *ctx); |
| 504 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 505 | // EVP_PKEY_sign_init initialises an |EVP_PKEY_CTX| for a signing operation. It |
| 506 | // should be called before |EVP_PKEY_sign|. |
| 507 | // |
| 508 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 509 | OPENSSL_EXPORT int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); |
| 510 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 511 | // EVP_PKEY_sign signs |digest_len| bytes from |digest| using |ctx|. If |sig| is |
| 512 | // NULL, the maximum size of the signature is written to |
| 513 | // |out_sig_len|. Otherwise, |*sig_len| must contain the number of bytes of |
| 514 | // space available at |sig|. If sufficient, the signature will be written to |
| 515 | // |sig| and |*sig_len| updated with the true length. |
| 516 | // |
| 517 | // This function expects a pre-hashed input and will fail for signature |
| 518 | // algorithms which do not support this. Use |EVP_DigestSignInit| to sign an |
| 519 | // unhashed input. |
| 520 | // |
| 521 | // WARNING: Setting |sig| to NULL only gives the maximum size of the |
| 522 | // signature. The actual signature may be smaller. |
| 523 | // |
| 524 | // It returns one on success or zero on error. (Note: this differs from |
| 525 | // OpenSSL, which can also return negative values to indicate an error. ) |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 526 | OPENSSL_EXPORT int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, uint8_t *sig, |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 527 | size_t *sig_len, const uint8_t *digest, |
| 528 | size_t digest_len); |
| 529 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 530 | // EVP_PKEY_verify_init initialises an |EVP_PKEY_CTX| for a signature |
| 531 | // verification operation. It should be called before |EVP_PKEY_verify|. |
| 532 | // |
| 533 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 534 | OPENSSL_EXPORT int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); |
| 535 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 536 | // EVP_PKEY_verify verifies that |sig_len| bytes from |sig| are a valid |
| 537 | // signature for |digest|. |
| 538 | // |
| 539 | // This function expects a pre-hashed input and will fail for signature |
| 540 | // algorithms which do not support this. Use |EVP_DigestVerifyInit| to verify a |
| 541 | // signature given the unhashed input. |
| 542 | // |
| 543 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 544 | OPENSSL_EXPORT int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, const uint8_t *sig, |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 545 | size_t sig_len, const uint8_t *digest, |
| 546 | size_t digest_len); |
| 547 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 548 | // EVP_PKEY_encrypt_init initialises an |EVP_PKEY_CTX| for an encryption |
| 549 | // operation. It should be called before |EVP_PKEY_encrypt|. |
| 550 | // |
| 551 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 552 | OPENSSL_EXPORT int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); |
| 553 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 554 | // EVP_PKEY_encrypt encrypts |in_len| bytes from |in|. If |out| is NULL, the |
| 555 | // maximum size of the ciphertext is written to |out_len|. Otherwise, |*out_len| |
| 556 | // must contain the number of bytes of space available at |out|. If sufficient, |
| 557 | // the ciphertext will be written to |out| and |*out_len| updated with the true |
| 558 | // length. |
| 559 | // |
| 560 | // WARNING: Setting |out| to NULL only gives the maximum size of the |
| 561 | // ciphertext. The actual ciphertext may be smaller. |
| 562 | // |
| 563 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 564 | OPENSSL_EXPORT int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, uint8_t *out, |
| 565 | size_t *out_len, const uint8_t *in, |
| 566 | size_t in_len); |
| 567 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 568 | // EVP_PKEY_decrypt_init initialises an |EVP_PKEY_CTX| for a decryption |
| 569 | // operation. It should be called before |EVP_PKEY_decrypt|. |
| 570 | // |
| 571 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 572 | OPENSSL_EXPORT int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); |
| 573 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 574 | // EVP_PKEY_decrypt decrypts |in_len| bytes from |in|. If |out| is NULL, the |
| 575 | // maximum size of the plaintext is written to |out_len|. Otherwise, |*out_len| |
| 576 | // must contain the number of bytes of space available at |out|. If sufficient, |
| 577 | // the ciphertext will be written to |out| and |*out_len| updated with the true |
| 578 | // length. |
| 579 | // |
| 580 | // WARNING: Setting |out| to NULL only gives the maximum size of the |
| 581 | // plaintext. The actual plaintext may be smaller. |
| 582 | // |
| 583 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 584 | OPENSSL_EXPORT int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, uint8_t *out, |
| 585 | size_t *out_len, const uint8_t *in, |
| 586 | size_t in_len); |
| 587 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 588 | // EVP_PKEY_verify_recover_init initialises an |EVP_PKEY_CTX| for a public-key |
| 589 | // decryption operation. It should be called before |EVP_PKEY_verify_recover|. |
| 590 | // |
| 591 | // Public-key decryption is a very obscure operation that is only implemented |
| 592 | // by RSA keys. It is effectively a signature verification operation that |
| 593 | // returns the signed message directly. It is almost certainly not what you |
| 594 | // want. |
| 595 | // |
| 596 | // It returns one on success or zero on error. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 597 | OPENSSL_EXPORT int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); |
| 598 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 599 | // EVP_PKEY_verify_recover decrypts |sig_len| bytes from |sig|. If |out| is |
| 600 | // NULL, the maximum size of the plaintext is written to |out_len|. Otherwise, |
| 601 | // |*out_len| must contain the number of bytes of space available at |out|. If |
| 602 | // sufficient, the ciphertext will be written to |out| and |*out_len| updated |
| 603 | // with the true length. |
| 604 | // |
| 605 | // WARNING: Setting |out| to NULL only gives the maximum size of the |
| 606 | // plaintext. The actual plaintext may be smaller. |
| 607 | // |
| 608 | // See the warning about this operation in |EVP_PKEY_verify_recover_init|. It |
| 609 | // is probably not what you want. |
| 610 | // |
| 611 | // It returns one on success or zero on error. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 612 | OPENSSL_EXPORT int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, uint8_t *out, |
| 613 | size_t *out_len, const uint8_t *sig, |
| 614 | size_t siglen); |
| 615 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 616 | // EVP_PKEY_derive_init initialises an |EVP_PKEY_CTX| for a key derivation |
| 617 | // operation. It should be called before |EVP_PKEY_derive_set_peer| and |
| 618 | // |EVP_PKEY_derive|. |
| 619 | // |
| 620 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 621 | OPENSSL_EXPORT int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); |
| 622 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 623 | // EVP_PKEY_derive_set_peer sets the peer's key to be used for key derivation |
| 624 | // by |ctx| to |peer|. It should be called after |EVP_PKEY_derive_init|. (For |
| 625 | // example, this is used to set the peer's key in (EC)DH.) It returns one on |
| 626 | // success and zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 627 | OPENSSL_EXPORT int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); |
| 628 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 629 | // EVP_PKEY_derive derives a shared key between the two keys configured in |
| 630 | // |ctx|. If |key| is non-NULL then, on entry, |out_key_len| must contain the |
| 631 | // amount of space at |key|. If sufficient then the shared key will be written |
| 632 | // to |key| and |*out_key_len| will be set to the length. If |key| is NULL then |
| 633 | // |out_key_len| will be set to the maximum length. |
| 634 | // |
| 635 | // WARNING: Setting |out| to NULL only gives the maximum size of the key. The |
| 636 | // actual key may be smaller. |
| 637 | // |
| 638 | // It returns one on success and zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 639 | OPENSSL_EXPORT int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, uint8_t *key, |
| 640 | size_t *out_key_len); |
| 641 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 642 | // EVP_PKEY_keygen_init initialises an |EVP_PKEY_CTX| for a key generation |
| 643 | // operation. It should be called before |EVP_PKEY_keygen|. |
| 644 | // |
| 645 | // It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 646 | OPENSSL_EXPORT int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); |
| 647 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 648 | // EVP_PKEY_keygen performs a key generation operation using the values from |
Robert Sloan | 4c22c5f | 2019-03-01 15:53:37 -0800 | [diff] [blame] | 649 | // |ctx|. If |*out_pkey| is non-NULL, it overwrites |*out_pkey| with the |
| 650 | // resulting key. Otherwise, it sets |*out_pkey| to a newly-allocated |EVP_PKEY| |
| 651 | // containing the result. It returns one on success or zero on error. |
| 652 | OPENSSL_EXPORT int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **out_pkey); |
| 653 | |
| 654 | // EVP_PKEY_paramgen_init initialises an |EVP_PKEY_CTX| for a parameter |
| 655 | // generation operation. It should be called before |EVP_PKEY_paramgen|. |
| 656 | // |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 657 | // It returns one on success or zero on error. |
Robert Sloan | 4c22c5f | 2019-03-01 15:53:37 -0800 | [diff] [blame] | 658 | OPENSSL_EXPORT int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); |
| 659 | |
| 660 | // EVP_PKEY_paramgen performs a parameter generation using the values from |
| 661 | // |ctx|. If |*out_pkey| is non-NULL, it overwrites |*out_pkey| with the |
| 662 | // resulting parameters, but no key. Otherwise, it sets |*out_pkey| to a |
| 663 | // newly-allocated |EVP_PKEY| containing the result. It returns one on success |
| 664 | // or zero on error. |
| 665 | OPENSSL_EXPORT int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **out_pkey); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 666 | |
| 667 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 668 | // Generic control functions. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 669 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 670 | // EVP_PKEY_CTX_set_signature_md sets |md| as the digest to be used in a |
| 671 | // signature operation. It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 672 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, |
| 673 | const EVP_MD *md); |
| 674 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 675 | // EVP_PKEY_CTX_get_signature_md sets |*out_md| to the digest to be used in a |
| 676 | // signature operation. It returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 677 | OPENSSL_EXPORT int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, |
| 678 | const EVP_MD **out_md); |
| 679 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 680 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 681 | // RSA specific control functions. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 682 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 683 | // EVP_PKEY_CTX_set_rsa_padding sets the padding type to use. It should be one |
| 684 | // of the |RSA_*_PADDING| values. Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 685 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int padding); |
| 686 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 687 | // EVP_PKEY_CTX_get_rsa_padding sets |*out_padding| to the current padding |
| 688 | // value, which is one of the |RSA_*_PADDING| values. Returns one on success or |
| 689 | // zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 690 | OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, |
| 691 | int *out_padding); |
| 692 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 693 | // EVP_PKEY_CTX_set_rsa_pss_saltlen sets the length of the salt in a PSS-padded |
| 694 | // signature. A value of -1 cause the salt to be the same length as the digest |
| 695 | // in the signature. A value of -2 causes the salt to be the maximum length |
| 696 | // that will fit when signing and recovered from the signature when verifying. |
| 697 | // Otherwise the value gives the size of the salt in bytes. |
| 698 | // |
| 699 | // If unsure, use -1. |
| 700 | // |
| 701 | // Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 702 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, |
| 703 | int salt_len); |
| 704 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 705 | // EVP_PKEY_CTX_get_rsa_pss_saltlen sets |*out_salt_len| to the salt length of |
| 706 | // a PSS-padded signature. See the documentation for |
| 707 | // |EVP_PKEY_CTX_set_rsa_pss_saltlen| for details of the special values that it |
| 708 | // can take. |
| 709 | // |
| 710 | // Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 711 | OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, |
| 712 | int *out_salt_len); |
| 713 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 714 | // EVP_PKEY_CTX_set_rsa_keygen_bits sets the size of the desired RSA modulus, |
| 715 | // in bits, for key generation. Returns one on success or zero on |
| 716 | // error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 717 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, |
| 718 | int bits); |
| 719 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 720 | // EVP_PKEY_CTX_set_rsa_keygen_pubexp sets |e| as the public exponent for key |
| 721 | // generation. Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 722 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, |
| 723 | BIGNUM *e); |
| 724 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 725 | // EVP_PKEY_CTX_set_rsa_oaep_md sets |md| as the digest used in OAEP padding. |
| 726 | // Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 727 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, |
| 728 | const EVP_MD *md); |
| 729 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 730 | // EVP_PKEY_CTX_get_rsa_oaep_md sets |*out_md| to the digest function used in |
| 731 | // OAEP padding. Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 732 | OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, |
| 733 | const EVP_MD **out_md); |
| 734 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 735 | // EVP_PKEY_CTX_set_rsa_mgf1_md sets |md| as the digest used in MGF1. Returns |
| 736 | // one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 737 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, |
| 738 | const EVP_MD *md); |
| 739 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 740 | // EVP_PKEY_CTX_get_rsa_mgf1_md sets |*out_md| to the digest function used in |
| 741 | // MGF1. Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 742 | OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, |
| 743 | const EVP_MD **out_md); |
| 744 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 745 | // EVP_PKEY_CTX_set0_rsa_oaep_label sets |label_len| bytes from |label| as the |
| 746 | // label used in OAEP. DANGER: On success, this call takes ownership of |label| |
| 747 | // and will call |OPENSSL_free| on it when |ctx| is destroyed. |
| 748 | // |
| 749 | // Returns one on success or zero on error. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 750 | OPENSSL_EXPORT int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 751 | uint8_t *label, |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 752 | size_t label_len); |
| 753 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 754 | // EVP_PKEY_CTX_get0_rsa_oaep_label sets |*out_label| to point to the internal |
| 755 | // buffer containing the OAEP label (which may be NULL) and returns the length |
| 756 | // of the label or a negative value on error. |
| 757 | // |
| 758 | // WARNING: the return value differs from the usual return value convention. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 759 | OPENSSL_EXPORT int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, |
| 760 | const uint8_t **out_label); |
| 761 | |
| 762 | |
Robert Sloan | 4c22c5f | 2019-03-01 15:53:37 -0800 | [diff] [blame] | 763 | // EC specific control functions. |
| 764 | |
| 765 | // EVP_PKEY_CTX_set_ec_paramgen_curve_nid sets the curve used for |
| 766 | // |EVP_PKEY_keygen| or |EVP_PKEY_paramgen| operations to |nid|. It returns one |
| 767 | // on success and zero on error. |
| 768 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, |
| 769 | int nid); |
| 770 | |
| 771 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 772 | // Deprecated functions. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 773 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 774 | // EVP_PKEY_DH is defined for compatibility, but it is impossible to create an |
| 775 | // |EVP_PKEY| of that type. |
Adam Langley | 4139edb | 2016-01-13 15:00:54 -0800 | [diff] [blame] | 776 | #define EVP_PKEY_DH NID_dhKeyAgreement |
| 777 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 778 | // EVP_PKEY_RSA2 was historically an alternate form for RSA public keys (OID |
| 779 | // 2.5.8.1.1), but is no longer accepted. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 780 | #define EVP_PKEY_RSA2 NID_rsa |
| 781 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 782 | // OpenSSL_add_all_algorithms does nothing. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 783 | OPENSSL_EXPORT void OpenSSL_add_all_algorithms(void); |
| 784 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 785 | // OPENSSL_add_all_algorithms_conf does nothing. |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 786 | OPENSSL_EXPORT void OPENSSL_add_all_algorithms_conf(void); |
David Benjamin | 6e899c7 | 2016-06-09 18:02:18 -0400 | [diff] [blame] | 787 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 788 | // OpenSSL_add_all_ciphers does nothing. |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 789 | OPENSSL_EXPORT void OpenSSL_add_all_ciphers(void); |
| 790 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 791 | // OpenSSL_add_all_digests does nothing. |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 792 | OPENSSL_EXPORT void OpenSSL_add_all_digests(void); |
| 793 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 794 | // EVP_cleanup does nothing. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 795 | OPENSSL_EXPORT void EVP_cleanup(void); |
| 796 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 797 | OPENSSL_EXPORT void EVP_CIPHER_do_all_sorted( |
| 798 | void (*callback)(const EVP_CIPHER *cipher, const char *name, |
| 799 | const char *unused, void *arg), |
| 800 | void *arg); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 801 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 802 | OPENSSL_EXPORT void EVP_MD_do_all_sorted(void (*callback)(const EVP_MD *cipher, |
| 803 | const char *name, |
| 804 | const char *unused, |
| 805 | void *arg), |
| 806 | void *arg); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 807 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 808 | // i2d_PrivateKey marshals a private key from |key| to an ASN.1, DER |
| 809 | // structure. If |outp| is not NULL then the result is written to |*outp| and |
| 810 | // |*outp| is advanced just past the output. It returns the number of bytes in |
| 811 | // the result, whether written or not, or a negative value on error. |
| 812 | // |
| 813 | // RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 3447) structure. |
| 814 | // EC keys are serialized as a DER-encoded ECPrivateKey (RFC 5915) structure. |
| 815 | // |
Robert Sloan | 309a31e | 2018-01-29 10:22:47 -0800 | [diff] [blame] | 816 | // Use |RSA_marshal_private_key| or |EC_KEY_marshal_private_key| instead. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 817 | OPENSSL_EXPORT int i2d_PrivateKey(const EVP_PKEY *key, uint8_t **outp); |
| 818 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 819 | // i2d_PublicKey marshals a public key from |key| to a type-specific format. |
| 820 | // If |outp| is not NULL then the result is written to |*outp| and |
| 821 | // |*outp| is advanced just past the output. It returns the number of bytes in |
| 822 | // the result, whether written or not, or a negative value on error. |
| 823 | // |
| 824 | // RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 3447) structure. |
| 825 | // EC keys are serialized as an EC point per SEC 1. |
| 826 | // |
| 827 | // Use |RSA_marshal_public_key| or |EC_POINT_point2cbb| instead. |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 828 | OPENSSL_EXPORT int i2d_PublicKey(const EVP_PKEY *key, uint8_t **outp); |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 829 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 830 | // d2i_PrivateKey parses an ASN.1, DER-encoded, private key from |len| bytes at |
| 831 | // |*inp|. If |out| is not NULL then, on exit, a pointer to the result is in |
| 832 | // |*out|. Note that, even if |*out| is already non-NULL on entry, it will not |
| 833 | // be written to. Rather, a fresh |EVP_PKEY| is allocated and the previous one |
| 834 | // is freed. On successful exit, |*inp| is advanced past the DER structure. It |
| 835 | // returns the result or NULL on error. |
| 836 | // |
| 837 | // This function tries to detect one of several formats. Instead, use |
| 838 | // |EVP_parse_private_key| for a PrivateKeyInfo, |RSA_parse_private_key| for an |
| 839 | // RSAPrivateKey, and |EC_parse_private_key| for an ECPrivateKey. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 840 | OPENSSL_EXPORT EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **out, |
| 841 | const uint8_t **inp, long len); |
| 842 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 843 | // d2i_AutoPrivateKey acts the same as |d2i_PrivateKey|, but detects the type |
| 844 | // of the private key. |
| 845 | // |
| 846 | // This function tries to detect one of several formats. Instead, use |
| 847 | // |EVP_parse_private_key| for a PrivateKeyInfo, |RSA_parse_private_key| for an |
| 848 | // RSAPrivateKey, and |EC_parse_private_key| for an ECPrivateKey. |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 849 | OPENSSL_EXPORT EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **out, const uint8_t **inp, |
| 850 | long len); |
| 851 | |
Robert Sloan | 4c22c5f | 2019-03-01 15:53:37 -0800 | [diff] [blame] | 852 | // d2i_PublicKey parse a public key from |len| bytes at |*inp| in a type- |
| 853 | // specific format specified by |type|. If |out| is not NULL then, on exit, a |
| 854 | // pointer to the result is in |*out|. Note that, even if |*out| is already non- |
| 855 | // NULL on entry, it will not be written to. Rather, a fresh |EVP_PKEY| is |
| 856 | // allocated and the previous one is freed. On successful exit, |*inp| is |
| 857 | // advanced past the decoded key. It returns the result or NULL on error. |
| 858 | // |
| 859 | // RSA keys are parsed as a DER-encoded RSAPublicKey (RFC 3447) structure. |
| 860 | // Parsing EC keys is not supported by this function. |
| 861 | // |
| 862 | // Use |RSA_parse_public_key| instead. |
| 863 | OPENSSL_EXPORT EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **out, |
| 864 | const uint8_t **inp, long len); |
| 865 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 866 | // EVP_PKEY_get0_DH returns NULL. |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 867 | OPENSSL_EXPORT DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey); |
David Benjamin | c895d6b | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 868 | |
Adam Vartanian | bfcf3a7 | 2018-08-10 14:55:24 +0100 | [diff] [blame] | 869 | // EVP_PKEY_get1_DH returns NULL. |
Robert Sloan | 1f278ae | 2018-09-04 13:56:45 -0700 | [diff] [blame] | 870 | OPENSSL_EXPORT DH *EVP_PKEY_get1_DH(const EVP_PKEY *pkey); |
Adam Vartanian | bfcf3a7 | 2018-08-10 14:55:24 +0100 | [diff] [blame] | 871 | |
Robert Sloan | 4c22c5f | 2019-03-01 15:53:37 -0800 | [diff] [blame] | 872 | // EVP_PKEY_CTX_set_ec_param_enc returns one if |encoding| is |
| 873 | // |OPENSSL_EC_NAMED_CURVE| or zero with an error otherwise. |
| 874 | OPENSSL_EXPORT int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, |
| 875 | int encoding); |
| 876 | |
Adam Vartanian | bfcf3a7 | 2018-08-10 14:55:24 +0100 | [diff] [blame] | 877 | |
| 878 | // Preprocessor compatibility section (hidden). |
| 879 | // |
| 880 | // Historically, a number of APIs were implemented in OpenSSL as macros and |
| 881 | // constants to 'ctrl' functions. To avoid breaking #ifdefs in consumers, this |
| 882 | // section defines a number of legacy macros. |
| 883 | |
Robert Sloan | 726e9d1 | 2018-09-11 11:45:04 -0700 | [diff] [blame] | 884 | // |BORINGSSL_PREFIX| already makes each of these symbols into macros, so there |
| 885 | // is no need to define conflicting macros. |
| 886 | #if !defined(BORINGSSL_PREFIX) |
Adam Vartanian | bfcf3a7 | 2018-08-10 14:55:24 +0100 | [diff] [blame] | 887 | #define EVP_PKEY_CTX_set_rsa_oaep_md EVP_PKEY_CTX_set_rsa_oaep_md |
| 888 | #define EVP_PKEY_CTX_set0_rsa_oaep_label EVP_PKEY_CTX_set0_rsa_oaep_label |
Robert Sloan | 726e9d1 | 2018-09-11 11:45:04 -0700 | [diff] [blame] | 889 | #endif |
Adam Vartanian | bfcf3a7 | 2018-08-10 14:55:24 +0100 | [diff] [blame] | 890 | |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 891 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 892 | // Private structures. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 893 | |
| 894 | struct evp_pkey_st { |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 895 | CRYPTO_refcount_t references; |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 896 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 897 | // type contains one of the EVP_PKEY_* values or NID_undef and determines |
| 898 | // which element (if any) of the |pkey| union is valid. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 899 | int type; |
| 900 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 901 | union { |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 902 | void *ptr; |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 903 | RSA *rsa; |
| 904 | DSA *dsa; |
| 905 | DH *dh; |
| 906 | EC_KEY *ec; |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 907 | } pkey; |
| 908 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 909 | // ameth contains a pointer to a method table that contains many ASN.1 |
| 910 | // methods for the key type. |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 911 | const EVP_PKEY_ASN1_METHOD *ameth; |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 912 | } /* EVP_PKEY */; |
| 913 | |
| 914 | |
| 915 | #if defined(__cplusplus) |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 916 | } // extern C |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 917 | |
| 918 | extern "C++" { |
Robert Sloan | 726e9d1 | 2018-09-11 11:45:04 -0700 | [diff] [blame] | 919 | BSSL_NAMESPACE_BEGIN |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 920 | |
| 921 | BORINGSSL_MAKE_DELETER(EVP_PKEY, EVP_PKEY_free) |
Adam Vartanian | bfcf3a7 | 2018-08-10 14:55:24 +0100 | [diff] [blame] | 922 | BORINGSSL_MAKE_UP_REF(EVP_PKEY, EVP_PKEY_up_ref) |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 923 | BORINGSSL_MAKE_DELETER(EVP_PKEY_CTX, EVP_PKEY_CTX_free) |
| 924 | |
Robert Sloan | 726e9d1 | 2018-09-11 11:45:04 -0700 | [diff] [blame] | 925 | BSSL_NAMESPACE_END |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 926 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 927 | } // extern C++ |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 928 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 929 | #endif |
| 930 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 931 | #define EVP_R_BUFFER_TOO_SMALL 100 |
| 932 | #define EVP_R_COMMAND_NOT_SUPPORTED 101 |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 933 | #define EVP_R_DECODE_ERROR 102 |
| 934 | #define EVP_R_DIFFERENT_KEY_TYPES 103 |
| 935 | #define EVP_R_DIFFERENT_PARAMETERS 104 |
| 936 | #define EVP_R_ENCODE_ERROR 105 |
| 937 | #define EVP_R_EXPECTING_AN_EC_KEY_KEY 106 |
| 938 | #define EVP_R_EXPECTING_AN_RSA_KEY 107 |
| 939 | #define EVP_R_EXPECTING_A_DSA_KEY 108 |
| 940 | #define EVP_R_ILLEGAL_OR_UNSUPPORTED_PADDING_MODE 109 |
| 941 | #define EVP_R_INVALID_DIGEST_LENGTH 110 |
| 942 | #define EVP_R_INVALID_DIGEST_TYPE 111 |
| 943 | #define EVP_R_INVALID_KEYBITS 112 |
| 944 | #define EVP_R_INVALID_MGF1_MD 113 |
| 945 | #define EVP_R_INVALID_OPERATION 114 |
| 946 | #define EVP_R_INVALID_PADDING_MODE 115 |
| 947 | #define EVP_R_INVALID_PSS_SALTLEN 116 |
| 948 | #define EVP_R_KEYS_NOT_SET 117 |
| 949 | #define EVP_R_MISSING_PARAMETERS 118 |
| 950 | #define EVP_R_NO_DEFAULT_DIGEST 119 |
| 951 | #define EVP_R_NO_KEY_SET 120 |
| 952 | #define EVP_R_NO_MDC2_SUPPORT 121 |
| 953 | #define EVP_R_NO_NID_FOR_CURVE 122 |
| 954 | #define EVP_R_NO_OPERATION_SET 123 |
| 955 | #define EVP_R_NO_PARAMETERS_SET 124 |
| 956 | #define EVP_R_OPERATION_NOT_SUPPORTED_FOR_THIS_KEYTYPE 125 |
| 957 | #define EVP_R_OPERATON_NOT_INITIALIZED 126 |
| 958 | #define EVP_R_UNKNOWN_PUBLIC_KEY_TYPE 127 |
| 959 | #define EVP_R_UNSUPPORTED_ALGORITHM 128 |
| 960 | #define EVP_R_UNSUPPORTED_PUBLIC_KEY_TYPE 129 |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 961 | #define EVP_R_NOT_A_PRIVATE_KEY 130 |
| 962 | #define EVP_R_INVALID_SIGNATURE 131 |
Robert Sloan | 8ff0355 | 2017-06-14 12:40:58 -0700 | [diff] [blame] | 963 | #define EVP_R_MEMORY_LIMIT_EXCEEDED 132 |
| 964 | #define EVP_R_INVALID_PARAMETERS 133 |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 965 | |
Robert Sloan | 8f860b1 | 2017-08-28 07:37:06 -0700 | [diff] [blame] | 966 | #endif // OPENSSL_HEADER_EVP_H |