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> 61#include <openssl/stack.h> 62 63/* OpenSSL included digest and cipher functions in this header so we include 64 * them for users that still expect that. 65 * 66 * TODO(fork): clean up callers so that they include what they use. */ 67#include <openssl/aead.h> 68#include <openssl/cipher.h> 69#include <openssl/digest.h> 70#include <openssl/mem.h> 71#include <openssl/obj.h> 72#include <openssl/thread.h> 73 74#if defined(__cplusplus) 75extern "C" { 76#endif 77 78 79/* EVP abstracts over public/private key algorithms. */ 80 81 82/* Public key objects. */ 83 84/* EVP_PKEY_new creates a new, empty public-key object and returns it or NULL 85 * on allocation failure. */ 86OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new(void); 87 88/* EVP_PKEY_free frees all data referenced by |pkey| and then frees |pkey| 89 * itself. */ 90OPENSSL_EXPORT void EVP_PKEY_free(EVP_PKEY *pkey); 91 92/* EVP_PKEY_is_opaque returns one if |pkey| is opaque. Opaque keys are backed by 93 * custom implementations which do not expose key material and parameters. It is 94 * an error to attempt to duplicate, export, or compare an opaque key. */ 95OPENSSL_EXPORT int EVP_PKEY_is_opaque(const EVP_PKEY *pkey); 96 97/* EVP_PKEY_cmp compares |a| and |b| and returns one if they are equal, zero if 98 * not and a negative number on error. 99 * 100 * WARNING: this differs from the traditional return value of a "cmp" 101 * function. */ 102OPENSSL_EXPORT int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); 103 104/* EVP_PKEY_dup adds one to the reference count of |pkey| and returns 105 * |pkey|. */ 106OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *pkey); 107 108/* EVP_PKEY_copy_parameters sets the parameters of |to| to equal the parameters 109 * of |from|. It returns one on success and zero on error. */ 110OPENSSL_EXPORT int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); 111 112/* EVP_PKEY_missing_parameters returns one if |pkey| is missing needed 113 * parameters or zero if not, or if the algorithm doesn't take parameters. */ 114OPENSSL_EXPORT int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); 115 116/* EVP_PKEY_size returns the "size", in bytes, of |pkey|. For example, for an 117 * RSA key this returns the number of bytes needed to represent the modulus. */ 118OPENSSL_EXPORT int EVP_PKEY_size(const EVP_PKEY *pkey); 119 120/* EVP_PKEY_bits returns the "size", in bits, of |pkey|. For example, for an 121 * RSA key, this returns the bit length of the modulus. */ 122OPENSSL_EXPORT int EVP_PKEY_bits(EVP_PKEY *pkey); 123 124/* EVP_PKEY_id returns the type of |pkey|, which is one of the |EVP_PKEY_*| 125 * values. */ 126OPENSSL_EXPORT int EVP_PKEY_id(const EVP_PKEY *pkey); 127 128/* EVP_PKEY_type returns a canonicalised form of |NID|. For example, 129 * |EVP_PKEY_RSA2| will be turned into |EVP_PKEY_RSA|. */ 130OPENSSL_EXPORT int EVP_PKEY_type(int nid); 131 132/* EVP_PKEY_new_mac_key allocates a fresh |EVP_PKEY| of the given type (e.g. 133 * |EVP_PKEY_HMAC|), sets |mac_key| as the MAC key and "generates" a new key, 134 * suitable for signing. It returns the fresh |EVP_PKEY|, or NULL on error. */ 135OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *engine, 136 const uint8_t *mac_key, 137 size_t mac_key_len); 138 139 140/* Getting and setting concrete public key types. 141 * 142 * The following functions get and set the underlying public key in an 143 * |EVP_PKEY| object. The |set1| functions take an additional reference to the 144 * underlying key and return one on success or zero on error. The |assign| 145 * functions adopt the caller's reference. The getters return a fresh reference 146 * to the underlying object. */ 147 148OPENSSL_EXPORT int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); 149OPENSSL_EXPORT int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); 150OPENSSL_EXPORT RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); 151 152OPENSSL_EXPORT int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, struct dsa_st *key); 153OPENSSL_EXPORT int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); 154OPENSSL_EXPORT struct dsa_st *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); 155 156OPENSSL_EXPORT int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, struct ec_key_st *key); 157OPENSSL_EXPORT int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); 158OPENSSL_EXPORT struct ec_key_st *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); 159 160OPENSSL_EXPORT int EVP_PKEY_set1_DH(EVP_PKEY *pkey, struct dh_st *key); 161OPENSSL_EXPORT int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key); 162OPENSSL_EXPORT struct dh_st *EVP_PKEY_get1_DH(EVP_PKEY *pkey); 163 164#define EVP_PKEY_NONE NID_undef 165#define EVP_PKEY_RSA NID_rsaEncryption 166#define EVP_PKEY_RSA2 NID_rsa 167#define EVP_PKEY_DSA NID_dsa 168#define EVP_PKEY_DH NID_dhKeyAgreement 169#define EVP_PKEY_DHX NID_dhpublicnumber 170#define EVP_PKEY_EC NID_X9_62_id_ecPublicKey 171#define EVP_PKEY_HMAC NID_hmac 172 173/* EVP_PKEY_assign sets the underlying key of |pkey| to |key|, which must be of 174 * the given type. The |type| argument should be one of the |EVP_PKEY_*| 175 * values. */ 176OPENSSL_EXPORT int EVP_PKEY_assign(EVP_PKEY *pkey, int type, void *key); 177 178/* EVP_PKEY_set_type sets the type of |pkey| to |type|, which should be one of 179 * the |EVP_PKEY_*| values. It returns one if sucessful or zero otherwise. If 180 * |pkey| is NULL, it simply reports whether the type is known. */ 181OPENSSL_EXPORT int EVP_PKEY_set_type(EVP_PKEY *pkey, int type); 182 183/* EVP_PKEY_cmp_parameters compares the parameters of |a| and |b|. It returns 184 * one if they match, zero if not, or a negative number of on error. 185 * 186 * WARNING: the return value differs from the usual return value convention. */ 187OPENSSL_EXPORT int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, 188 const EVP_PKEY *b); 189 190 191/* ASN.1 functions */ 192 193/* d2i_PrivateKey parses an ASN.1, DER-encoded, private key from |len| bytes at 194 * |*inp|. If |out| is not NULL then, on exit, a pointer to the result is in 195 * |*out|. If |*out| is already non-NULL on entry then the result is written 196 * directly into |*out|, otherwise a fresh |EVP_PKEY| is allocated. On 197 * successful exit, |*inp| is advanced past the DER structure. It returns the 198 * result or NULL on error. */ 199OPENSSL_EXPORT EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **out, 200 const uint8_t **inp, long len); 201 202/* d2i_AutoPrivateKey acts the same as |d2i_PrivateKey|, but detects the type 203 * of the private key. */ 204OPENSSL_EXPORT EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **out, const uint8_t **inp, 205 long len); 206 207/* i2d_PrivateKey marshals a private key from |key| to an ASN.1, DER 208 * structure. If |outp| is not NULL then the result is written to |*outp| and 209 * |*outp| is advanced just past the output. It returns the number of bytes in 210 * the result, whether written or not, or a negative value on error. */ 211OPENSSL_EXPORT int i2d_PrivateKey(const EVP_PKEY *key, uint8_t **outp); 212 213/* i2d_PublicKey marshals a public key from |key| to an ASN.1, DER 214 * structure. If |outp| is not NULL then the result is written to |*outp| and 215 * |*outp| is advanced just past the output. It returns the number of bytes in 216 * the result, whether written or not, or a negative value on error. */ 217OPENSSL_EXPORT int i2d_PublicKey(EVP_PKEY *key, uint8_t **outp); 218 219 220/* Signing */ 221 222/* EVP_DigestSignInit sets up |ctx| for a signing operation with |type| and 223 * |pkey|. The |ctx| argument must have been initialised with 224 * |EVP_MD_CTX_init|. If |pctx| is not NULL, the |EVP_PKEY_CTX| of the signing 225 * operation will be written to |*pctx|; this can be used to set alternative 226 * signing options. 227 * 228 * It returns one on success, or zero on error. */ 229OPENSSL_EXPORT int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, 230 const EVP_MD *type, ENGINE *e, 231 EVP_PKEY *pkey); 232 233/* EVP_DigestSignUpdate appends |len| bytes from |data| to the data which will 234 * be signed in |EVP_DigestSignFinal|. It returns one on success and zero 235 * otherwise. */ 236OPENSSL_EXPORT int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *data, 237 size_t len); 238 239/* EVP_DigestSignFinal signs the data that has been included by one or more 240 * calls to |EVP_DigestSignUpdate|. If |out_sig| is NULL then |*out_sig_len| is 241 * set to the maximum number of output bytes. Otherwise, on entry, 242 * |*out_sig_len| must contain the length of the |out_sig| buffer. If the call 243 * is successful, the signature is written to |out_sig| and |*out_sig_len| is 244 * set to its length. 245 * 246 * It returns one on success, or zero on error. */ 247OPENSSL_EXPORT int EVP_DigestSignFinal(EVP_MD_CTX *ctx, uint8_t *out_sig, 248 size_t *out_sig_len); 249 250 251/* Verifying */ 252 253/* EVP_DigestVerifyInit sets up |ctx| for a signature verification operation 254 * with |type| and |pkey|. The |ctx| argument must have been initialised with 255 * |EVP_MD_CTX_init|. If |pctx| is not NULL, the |EVP_PKEY_CTX| of the signing 256 * operation will be written to |*pctx|; this can be used to set alternative 257 * signing options. 258 * 259 * It returns one on success, or zero on error. */ 260OPENSSL_EXPORT int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, 261 const EVP_MD *type, ENGINE *e, 262 EVP_PKEY *pkey); 263 264/* EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which 265 * will be verified by |EVP_DigestVerifyFinal|. It returns one on success and 266 * zero otherwise. */ 267OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data, 268 size_t len); 269 270/* EVP_DigestVerifyFinal verifies that |sig_len| bytes of |sig| are a valid 271 * signature for the data that has been included by one or more calls to 272 * |EVP_DigestVerifyUpdate|. 273 * 274 * It returns one on success and <= 0 on error. WARNING: this differs from the 275 * usual return value convention. */ 276OPENSSL_EXPORT int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const uint8_t *sig, 277 size_t sig_len); 278 279 280/* Signing (old functions) */ 281 282/* EVP_SignInit_ex configures |ctx|, which must already have been initialised, 283 * for a fresh signing operation using the hash function |type|. It returns one 284 * on success and zero otherwise. 285 * 286 * (In order to initialise |ctx|, either obtain it initialised with 287 * |EVP_MD_CTX_create|, or use |EVP_MD_CTX_init|.) */ 288OPENSSL_EXPORT int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, 289 ENGINE *impl); 290 291/* EVP_SignInit is a deprecated version of |EVP_SignInit_ex|. 292 * 293 * TODO(fork): remove. */ 294OPENSSL_EXPORT int EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); 295 296/* EVP_SignUpdate appends |len| bytes from |data| to the data which will be 297 * signed in |EVP_SignFinal|. */ 298OPENSSL_EXPORT int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *data, 299 size_t len); 300 301/* EVP_SignFinal signs the data that has been included by one or more calls to 302 * |EVP_SignUpdate|, using the key |pkey|, and writes it to |sig|. On entry, 303 * |sig| must point to at least |EVP_PKEY_size(pkey)| bytes of space. The 304 * actual size of the signature is written to |*out_sig_len|. 305 * 306 * It returns one on success and zero otherwise. 307 * 308 * It does not modify |ctx|, thus it's possible to continue to use |ctx| in 309 * order to sign a longer message. */ 310OPENSSL_EXPORT int EVP_SignFinal(const EVP_MD_CTX *ctx, uint8_t *sig, 311 unsigned int *out_sig_len, EVP_PKEY *pkey); 312 313 314/* Verifying (old functions) */ 315 316/* EVP_VerifyInit_ex configures |ctx|, which must already have been 317 * initialised, for a fresh signature verification operation using the hash 318 * function |type|. It returns one on success and zero otherwise. 319 * 320 * (In order to initialise |ctx|, either obtain it initialised with 321 * |EVP_MD_CTX_create|, or use |EVP_MD_CTX_init|.) */ 322OPENSSL_EXPORT int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, 323 ENGINE *impl); 324 325/* EVP_VerifyInit is a deprecated version of |EVP_VerifyInit_ex|. 326 * 327 * TODO(fork): remove. */ 328OPENSSL_EXPORT int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); 329 330/* EVP_VerifyUpdate appends |len| bytes from |data| to the data which will be 331 * signed in |EVP_VerifyFinal|. */ 332OPENSSL_EXPORT int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *data, 333 size_t len); 334 335/* EVP_VerifyFinal verifies that |sig_len| bytes of |sig| are a valid 336 * signature, by |pkey|, for the data that has been included by one or more 337 * calls to |EVP_VerifyUpdate|. 338 * 339 * It returns one on success and zero otherwise. 340 * 341 * It does not modify |ctx|, thus it's possible to continue to use |ctx| in 342 * order to sign a longer message. */ 343OPENSSL_EXPORT int EVP_VerifyFinal(EVP_MD_CTX *ctx, const uint8_t *sig, 344 size_t sig_len, EVP_PKEY *pkey); 345 346 347/* Printing */ 348 349/* EVP_PKEY_print_public prints a textual representation of the public key in 350 * |pkey| to |out|. Returns one on success or zero otherwise. */ 351OPENSSL_EXPORT int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, 352 int indent, ASN1_PCTX *pctx); 353 354/* EVP_PKEY_print_public prints a textual representation of the private key in 355 * |pkey| to |out|. Returns one on success or zero otherwise. */ 356OPENSSL_EXPORT int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, 357 int indent, ASN1_PCTX *pctx); 358 359/* EVP_PKEY_print_public prints a textual representation of the parameters in 360 * |pkey| to |out|. Returns one on success or zero otherwise. */ 361OPENSSL_EXPORT int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, 362 int indent, ASN1_PCTX *pctx); 363 364 365/* Password stretching. 366 * 367 * Password stretching functions take a low-entropy password and apply a slow 368 * function that results in a key suitable for use in symmetric 369 * cryptography. */ 370 371/* PKCS5_PBKDF2_HMAC computes |iterations| iterations of PBKDF2 of |password| 372 * and |salt|, using |digest|, and outputs |key_len| bytes to |out_key|. It 373 * returns one on success and zero on error. */ 374OPENSSL_EXPORT int PKCS5_PBKDF2_HMAC(const char *password, int password_len, 375 const uint8_t *salt, size_t salt_len, 376 unsigned iterations, const EVP_MD *digest, 377 size_t key_len, uint8_t *out_key); 378 379/* PKCS5_PBKDF2_HMAC_SHA1 is the same as PKCS5_PBKDF2_HMAC, but with |digest| 380 * fixed to |EVP_sha1|. */ 381OPENSSL_EXPORT int PKCS5_PBKDF2_HMAC_SHA1(const char *password, 382 int password_len, const uint8_t *salt, 383 size_t salt_len, unsigned iterations, 384 size_t key_len, uint8_t *out_key); 385 386 387/* Public key contexts. 388 * 389 * |EVP_PKEY_CTX| objects hold the context of an operation (e.g. signing or 390 * encrypting) that uses a public key. */ 391 392/* EVP_PKEY_CTX_new allocates a fresh |EVP_PKEY_CTX| for use with |pkey|. It 393 * returns the context or NULL on error. */ 394OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); 395 396/* EVP_PKEY_CTX_new allocates a fresh |EVP_PKEY_CTX| for a key of type |id| 397 * (e.g. |EVP_PKEY_HMAC|). This can be used for key generation where 398 * |EVP_PKEY_CTX_new| can't be used because there isn't an |EVP_PKEY| to pass 399 * it. It returns the context or NULL on error. */ 400OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); 401 402/* EVP_KEY_CTX_free frees |ctx| and the data it owns. */ 403OPENSSL_EXPORT void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); 404 405/* EVP_PKEY_CTX_dup allocates a fresh |EVP_PKEY_CTX| and sets it equal to the 406 * state of |ctx|. It returns the fresh |EVP_PKEY_CTX| or NULL on error. */ 407OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); 408 409/* EVP_PKEY_CTX_get0_pkey returns the |EVP_PKEY| associated with |ctx|. */ 410OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_CTX_get0_pkey(EVP_PKEY_CTX *ctx); 411 412/* EVP_PKEY_CTX_set_app_data sets an opaque pointer on |ctx|. */ 413OPENSSL_EXPORT void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); 414 415/* EVP_PKEY_CTX_get_app_data returns the opaque pointer from |ctx| that was 416 * previously set with |EVP_PKEY_CTX_set_app_data|, or NULL if none has been 417 * set. */ 418OPENSSL_EXPORT void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); 419 420/* EVP_PKEY_CTX_ctrl performs |cmd| on |ctx|. The |keytype| and |optype| 421 * arguments can be -1 to specify that any type and operation are acceptable, 422 * otherwise |keytype| must match the type of |ctx| and the bits of |optype| 423 * must intersect the operation flags set on |ctx|. 424 * 425 * The |p1| and |p2| arguments depend on the value of |cmd|. 426 * 427 * It returns -2 if |cmd| is not recognised, -1 on error or a |cmd| specific 428 * value otherwise. */ 429OPENSSL_EXPORT int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, 430 int cmd, int p1, void *p2); 431 432/* EVP_PKEY_sign_init initialises an |EVP_PKEY_CTX| for a signing operation. It 433 * should be called before |EVP_PKEY_sign|. 434 * 435 * It returns one on success or zero on error. */ 436OPENSSL_EXPORT int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); 437 438/* EVP_PKEY_sign signs |data_len| bytes from |data| using |ctx|. If |sig| is 439 * NULL, the maximum size of the signature is written to 440 * |out_sig_len|. Otherwise, |*sig_len| must contain the number of bytes of 441 * space available at |sig|. If sufficient, the signature will be written to 442 * |sig| and |*sig_len| updated with the true length. 443 * 444 * WARNING: Setting |out| to NULL only gives the maximum size of the 445 * plaintext. The actual plaintext may be smaller. 446 * 447 * It returns one on success or zero on error. (Note: this differs from 448 * OpenSSL, which can also return negative values to indicate an error. ) */ 449OPENSSL_EXPORT int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, uint8_t *sig, 450 size_t *sig_len, const uint8_t *data, 451 size_t data_len); 452 453/* EVP_PKEY_verify_init initialises an |EVP_PKEY_CTX| for a signature 454 * verification operation. It should be called before |EVP_PKEY_verify|. 455 * 456 * It returns one on success or zero on error. */ 457OPENSSL_EXPORT int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); 458 459/* EVP_PKEY_verify verifies that |sig_len| bytes from |sig| are a valid signature 460 * for |data|. 461 * 462 * It returns one on success or zero on error. */ 463OPENSSL_EXPORT int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, const uint8_t *sig, 464 size_t sig_len, const uint8_t *data, 465 size_t data_len); 466 467/* EVP_PKEY_encrypt_init initialises an |EVP_PKEY_CTX| for an encryption 468 * operation. It should be called before |EVP_PKEY_encrypt|. 469 * 470 * It returns one on success or zero on error. */ 471OPENSSL_EXPORT int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); 472 473/* EVP_PKEY_encrypt encrypts |in_len| bytes from |in|. If |out| is NULL, the 474 * maximum size of the ciphertext is written to |out_len|. Otherwise, |*out_len| 475 * must contain the number of bytes of space available at |out|. If sufficient, 476 * the ciphertext will be written to |out| and |*out_len| updated with the true 477 * length. 478 * 479 * WARNING: Setting |out| to NULL only gives the maximum size of the 480 * ciphertext. The actual ciphertext may be smaller. 481 * 482 * It returns one on success or zero on error. */ 483OPENSSL_EXPORT int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, uint8_t *out, 484 size_t *out_len, const uint8_t *in, 485 size_t in_len); 486 487/* EVP_PKEY_decrypt_init initialises an |EVP_PKEY_CTX| for a decryption 488 * operation. It should be called before |EVP_PKEY_decrypt|. 489 * 490 * It returns one on success or zero on error. */ 491OPENSSL_EXPORT int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); 492 493/* EVP_PKEY_decrypt decrypts |in_len| bytes from |in|. If |out| is NULL, the 494 * maximum size of the plaintext is written to |out_len|. Otherwise, |*out_len| 495 * must contain the number of bytes of space available at |out|. If sufficient, 496 * the ciphertext will be written to |out| and |*out_len| updated with the true 497 * length. 498 * 499 * WARNING: Setting |out| to NULL only gives the maximum size of the 500 * plaintext. The actual plaintext may be smaller. 501 * 502 * It returns one on success or zero on error. */ 503OPENSSL_EXPORT int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, uint8_t *out, 504 size_t *out_len, const uint8_t *in, 505 size_t in_len); 506 507/* EVP_PKEY_derive_init initialises an |EVP_PKEY_CTX| for a key derivation 508 * operation. It should be called before |EVP_PKEY_derive_set_peer| and 509 * |EVP_PKEY_derive|. 510 * 511 * It returns one on success or zero on error. */ 512OPENSSL_EXPORT int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); 513 514/* EVP_PKEY_derive_set_peer sets the peer's key to be used for key derivation 515 * by |ctx| to |peer|. It should be called after |EVP_PKEY_derive_init|. (For 516 * example, this is used to set the peer's key in (EC)DH.) It returns one on 517 * success and zero on error. */ 518OPENSSL_EXPORT int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); 519 520/* EVP_PKEY_derive derives a shared key between the two keys configured in 521 * |ctx|. If |key| is non-NULL then, on entry, |out_key_len| must contain the 522 * amount of space at |key|. If sufficient then the shared key will be written 523 * to |key| and |*out_key_len| will be set to the length. If |key| is NULL then 524 * |out_key_len| will be set to the maximum length. 525 * 526 * WARNING: Setting |out| to NULL only gives the maximum size of the key. The 527 * actual key may be smaller. 528 * 529 * It returns one on success and zero on error. */ 530OPENSSL_EXPORT int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, uint8_t *key, 531 size_t *out_key_len); 532 533/* EVP_PKEY_keygen_init initialises an |EVP_PKEY_CTX| for a key generation 534 * operation. It should be called before |EVP_PKEY_keygen|. 535 * 536 * It returns one on success or zero on error. */ 537OPENSSL_EXPORT int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); 538 539/* EVP_PKEY_keygen performs a key generation operation using the values from 540 * |ctx| and sets |*ppkey| to a fresh |EVP_PKEY| containing the resulting key. 541 * It returns one on success or zero on error. */ 542OPENSSL_EXPORT int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); 543 544 545/* EVP_PKEY_CTX_ctrl operations. 546 * 547 * These values are passed as the |cmd| argument to 548 * EVP_PKEY_CTX_ctrl */ 549 550/* Generic. */ 551 552/* EVP_PKEY_CTX_set_signature_md sets |md| as the digest to be used in a 553 * signature operation. It returns one on success or otherwise on error. See 554 * the return values of |EVP_PKEY_CTX_ctrl| for details. */ 555OPENSSL_EXPORT int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, 556 const EVP_MD *md); 557 558/* EVP_PKEY_CTX_get_signature_md sets |*out_md| to the digest to be used in a 559 * signature operation. It returns one on success or otherwise on error. See 560 * the return values of |EVP_PKEY_CTX_ctrl| for details. */ 561OPENSSL_EXPORT int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, 562 const EVP_MD **out_md); 563 564/* EVP_PKEY_CTRL_DIGESTINIT is an internal value. It's called by 565 * EVP_DigestInit_ex to signal the |EVP_PKEY| that a digest operation is 566 * starting. */ 567#define EVP_PKEY_CTRL_DIGESTINIT 3 568 569/* EVP_PKEY_CTRL_PEER_KEY is called with different values of |p1|: 570 * 0: Is called from |EVP_PKEY_derive_set_peer| and |p2| contains a peer key. 571 * If the return value is <= 0, the key is rejected. 572 * 1: Is called at the end of |EVP_PKEY_derive_set_peer| and |p2| contains a 573 * peer key. If the return value is <= 0, the key is rejected. 574 * 2: Is called with |p2| == NULL to test whether the peer's key was used. 575 * (EC)DH always return one in this case. 576 * 3: Is called with |p2| == NULL to set whether the peer's key was used. 577 * (EC)DH always return one in this case. This was only used for GOST. */ 578#define EVP_PKEY_CTRL_PEER_KEY 4 579 580/* EVP_PKEY_CTRL_SET_MAC_KEY sets a MAC key. For example, this can be done an 581 * |EVP_PKEY_CTX| prior to calling |EVP_PKEY_keygen| in order to generate an 582 * HMAC |EVP_PKEY| with the given key. It returns one on success and zero on 583 * error. */ 584#define EVP_PKEY_CTRL_SET_MAC_KEY 5 585 586/* EVP_PKEY_ALG_CTRL is the base value from which key-type specific ctrl 587 * commands are numbered. */ 588#define EVP_PKEY_ALG_CTRL 0x1000 589 590 591/* RSA specific control functions. */ 592 593/* EVP_PKEY_CTX_set_rsa_padding sets the padding type to use. It should be one 594 * of the |RSA_*_PADDING| values. Returns one on success or another value on 595 * error. See |EVP_PKEY_CTX_ctrl| for the other return values, which are 596 * non-standard. */ 597OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int padding); 598 599/* EVP_PKEY_CTX_get_rsa_padding sets |*out_padding| to the current padding 600 * value, which is one of the |RSA_*_PADDING| values. Returns one on success or 601 * another value on error. See |EVP_PKEY_CTX_ctrl| for the other return values, 602 * which are non-standard. */ 603OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, 604 int *out_padding); 605 606/* EVP_PKEY_CTX_set_rsa_pss_saltlen sets the length of the salt in a PSS-padded 607 * signature. A value of -1 cause the salt to be the same length as the digest 608 * in the signature. A value of -2 causes the salt to be the maximum length 609 * that will fit. Otherwise the value gives the size of the salt in bytes. 610 * 611 * Returns one on success or another value on error. See |EVP_PKEY_CTX_ctrl| 612 * for the other return values, which are non-standard. */ 613OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, 614 int salt_len); 615 616/* EVP_PKEY_CTX_get_rsa_pss_saltlen sets |*out_salt_len| to the salt length of 617 * a PSS-padded signature. See the documentation for 618 * |EVP_PKEY_CTX_set_rsa_pss_saltlen| for details of the special values that it 619 * can take. 620 * 621 * Returns one on success or another value on error. See |EVP_PKEY_CTX_ctrl| 622 * for the other return values, which are non-standard. */ 623OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, 624 int *out_salt_len); 625 626/* EVP_PKEY_CTX_set_rsa_keygen_bits sets the size of the desired RSA modulus, 627 * in bits, for key generation. Returns one on success or another value on 628 * error. See |EVP_PKEY_CTX_ctrl| for the other return values, which are 629 * non-standard. */ 630OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, 631 int bits); 632 633/* EVP_PKEY_CTX_set_rsa_keygen_pubexp sets |e| as the public exponent for key 634 * generation. Returns one on success or another value on error. See 635 * |EVP_PKEY_CTX_ctrl| for the other return values, which are non-standard. */ 636OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, 637 BIGNUM *e); 638 639/* EVP_PKEY_CTX_set_rsa_oaep_md sets |md| as the digest used in OAEP padding. 640 * Returns one on success or another value on error. See |EVP_PKEY_CTX_ctrl| 641 * for the other return values, which are non-standard. */ 642OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, 643 const EVP_MD *md); 644 645/* EVP_PKEY_CTX_get_rsa_oaep_md sets |*out_md| to the digest function used in 646 * OAEP padding. Returns one on success or another value on error. See 647 * |EVP_PKEY_CTX_ctrl| for the other return values, which are non-standard. */ 648OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, 649 const EVP_MD **out_md); 650 651/* EVP_PKEY_CTX_set_rsa_mgf1_md sets |md| as the digest used in MGF1. Returns 652 * one on success or another value on error. See |EVP_PKEY_CTX_ctrl| for the 653 * other return values, which are non-standard. */ 654OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, 655 const EVP_MD *md); 656 657/* EVP_PKEY_CTX_get_rsa_mgf1_md sets |*out_md| to the digest function used in 658 * MGF1. Returns one on success or another value on error. See 659 * |EVP_PKEY_CTX_ctrl| for the other return values, which are non-standard. */ 660OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, 661 const EVP_MD **out_md); 662 663/* EVP_PKEY_CTX_set0_rsa_oaep_label sets |label_len| bytes from |label| as the 664 * label used in OAEP. DANGER: this call takes ownership of |label| and will 665 * call |free| on it when |ctx| is destroyed. 666 * 667 * Returns one on success or another value on error. See |EVP_PKEY_CTX_ctrl| 668 * for the other return values, which are non-standard. */ 669OPENSSL_EXPORT int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, 670 const uint8_t *label, 671 size_t label_len); 672 673/* EVP_PKEY_CTX_get0_rsa_oaep_label sets |*out_label| to point to the internal 674 * buffer containing the OAEP label (which may be NULL) and returns the length 675 * of the label or a negative value on error. */ 676OPENSSL_EXPORT int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, 677 const uint8_t **out_label); 678 679 680/* EC specific */ 681 682#define EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID (EVP_PKEY_ALG_CTRL + 1) 683#define EVP_PKEY_CTRL_EC_PARAM_ENC (EVP_PKEY_ALG_CTRL + 2) 684#define EVP_PKEY_CTRL_EC_ECDH_COFACTOR (EVP_PKEY_ALG_CTRL + 3) 685#define EVP_PKEY_CTRL_EC_KDF_TYPE (EVP_PKEY_ALG_CTRL + 4) 686#define EVP_PKEY_CTRL_EC_KDF_MD (EVP_PKEY_ALG_CTRL + 5) 687#define EVP_PKEY_CTRL_GET_EC_KDF_MD (EVP_PKEY_ALG_CTRL + 6) 688#define EVP_PKEY_CTRL_EC_KDF_OUTLEN (EVP_PKEY_ALG_CTRL + 7) 689#define EVP_PKEY_CTRL_GET_EC_KDF_OUTLEN (EVP_PKEY_ALG_CTRL + 8) 690#define EVP_PKEY_CTRL_EC_KDF_UKM (EVP_PKEY_ALG_CTRL + 9) 691#define EVP_PKEY_CTRL_GET_EC_KDF_UKM (EVP_PKEY_ALG_CTRL + 10) 692 693#define EVP_PKEY_ECDH_KDF_NONE 1 694#define EVP_PKEY_ECDH_KDF_X9_62 2 695 696 697/* PKEY ctrl commands. 698 * 699 * These values are passed as the |op| argument to 700 * EVP_PKEY_ASN1_METHOD.pkey_ctrl. */ 701 702/* ASN1_PKEY_CTRL_DEFAULT_MD_NID expects |arg2| to be an |int*| and sets the 703 * pointed at int to be the NID of the default hash function used in 704 * signing. */ 705#define ASN1_PKEY_CTRL_DEFAULT_MD_NID 0x3 706 707 708/* Private functions */ 709 710/* OpenSSL_add_all_algorithms does nothing. */ 711OPENSSL_EXPORT void OpenSSL_add_all_algorithms(void); 712 713/* EVP_cleanup does nothing. */ 714OPENSSL_EXPORT void EVP_cleanup(void); 715 716/* EVP_PKEY_asn1_find returns the ASN.1 method table for the given |nid|, which 717 * should be one of the |EVP_PKEY_*| values. It returns NULL if |nid| is 718 * unknown. */ 719OPENSSL_EXPORT const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find(ENGINE **pengine, 720 int nid); 721 722/* TODO(fork): move to PEM? */ 723OPENSSL_EXPORT const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find_str( 724 ENGINE **pengine, const char *name, size_t len); 725 726struct evp_pkey_st { 727 int references; 728 729 /* type contains one of the EVP_PKEY_* values or NID_undef and determines 730 * which element (if any) of the |pkey| union is valid. */ 731 int type; 732 733 /* TODO(fork): document */ 734 int save_type; 735 736 union { 737 char *ptr; 738 struct rsa_st *rsa; /* RSA */ 739 struct dsa_st *dsa; /* DSA */ 740 struct dh_st *dh; /* DH */ 741 struct ec_key_st *ec; /* ECC */ 742 } pkey; 743 744 ENGINE *engine; 745 746 /* TODO(fork): document */ 747 int save_parameters; 748 /* ameth contains a pointer to a method table that contains many ASN.1 749 * methods for the key type. */ 750 const EVP_PKEY_ASN1_METHOD *ameth; 751 752 /* TODO(fork): document; */ 753 STACK_OF(X509_ATTRIBUTE) * attributes; /* [ 0 ] */ 754} /* EVP_PKEY */; 755 756 757#if defined(__cplusplus) 758} /* extern C */ 759#endif 760 761#define EVP_F_rsa_item_verify 100 762#define EVP_F_do_sigver_init 101 763#define EVP_F_eckey_priv_decode 102 764#define EVP_F_pkey_ec_sign 103 765#define EVP_F_EVP_PKEY_sign_init 104 766#define EVP_F_d2i_PrivateKey 105 767#define EVP_F_rsa_priv_encode 106 768#define EVP_F_rsa_mgf1_to_md 107 769#define EVP_F_EVP_PKEY_get1_DH 108 770#define EVP_F_EVP_PKEY_sign 109 771#define EVP_F_old_ec_priv_decode 110 772#define EVP_F_EVP_PKEY_get1_RSA 111 773#define EVP_F_pkey_ec_ctrl 112 774#define EVP_F_evp_pkey_ctx_new 113 775#define EVP_F_EVP_PKEY_verify 114 776#define EVP_F_EVP_PKEY_encrypt 115 777#define EVP_F_EVP_PKEY_keygen 116 778#define EVP_F_eckey_type2param 117 779#define EVP_F_eckey_priv_encode 118 780#define EVP_F_do_EC_KEY_print 119 781#define EVP_F_pkey_ec_keygen 120 782#define EVP_F_EVP_PKEY_encrypt_init 121 783#define EVP_F_pkey_rsa_ctrl 122 784#define EVP_F_rsa_priv_decode 123 785#define EVP_F_rsa_pss_to_ctx 124 786#define EVP_F_EVP_PKEY_get1_EC_KEY 125 787#define EVP_F_EVP_PKEY_verify_init 126 788#define EVP_F_EVP_PKEY_derive_init 127 789#define EVP_F_eckey_param2type 128 790#define EVP_F_eckey_pub_decode 129 791#define EVP_F_d2i_AutoPrivateKey 130 792#define EVP_F_eckey_param_decode 131 793#define EVP_F_EVP_PKEY_new 132 794#define EVP_F_pkey_ec_derive 133 795#define EVP_F_pkey_ec_paramgen 134 796#define EVP_F_EVP_PKEY_CTX_ctrl 135 797#define EVP_F_EVP_PKEY_decrypt_init 136 798#define EVP_F_EVP_PKEY_decrypt 137 799#define EVP_F_EVP_PKEY_copy_parameters 138 800#define EVP_F_EVP_PKEY_set_type 139 801#define EVP_F_EVP_PKEY_derive 140 802#define EVP_F_EVP_PKEY_keygen_init 141 803#define EVP_F_do_rsa_print 142 804#define EVP_F_old_rsa_priv_decode 143 805#define EVP_F_rsa_algor_to_md 144 806#define EVP_F_eckey_pub_encode 145 807#define EVP_F_EVP_PKEY_derive_set_peer 146 808#define EVP_F_pkey_rsa_sign 147 809#define EVP_F_check_padding_md 148 810#define EVP_F_i2d_PublicKey 149 811#define EVP_F_rsa_pub_decode 150 812#define EVP_F_EVP_PKEY_get1_DSA 151 813#define EVP_F_pkey_rsa_encrypt 152 814#define EVP_F_pkey_rsa_decrypt 153 815#define EVP_F_hmac_signctx 154 816#define EVP_R_UNSUPPORTED_PUBLIC_KEY_TYPE 100 817#define EVP_R_UNSUPPORTED_SIGNATURE_TYPE 101 818#define EVP_R_INVALID_DIGEST_TYPE 102 819#define EVP_R_EXPECTING_A_DH_KEY 103 820#define EVP_R_OPERATON_NOT_INITIALIZED 104 821#define EVP_R_MISSING_PARAMETERS 105 822#define EVP_R_NO_DEFAULT_DIGEST 106 823#define EVP_R_UNKNOWN_DIGEST 107 824#define EVP_R_KEYS_NOT_SET 108 825#define EVP_R_X931_UNSUPPORTED 109 826#define EVP_R_DIGEST_DOES_NOT_MATCH 110 827#define EVP_R_DIFFERENT_PARAMETERS 111 828#define EVP_R_OPERATION_NOT_SUPPORTED_FOR_THIS_KEYTYPE 112 829#define EVP_R_DIFFERENT_KEY_TYPES 113 830#define EVP_R_NO_PARAMETERS_SET 114 831#define EVP_R_NO_NID_FOR_CURVE 115 832#define EVP_R_NO_OPERATION_SET 116 833#define EVP_R_UNSUPPORTED_ALGORITHM 117 834#define EVP_R_EXPECTING_AN_DSA_KEY 118 835#define EVP_R_UNKNOWN_MASK_DIGEST 119 836#define EVP_R_INVALID_SALT_LENGTH 120 837#define EVP_R_BUFFER_TOO_SMALL 121 838#define EVP_R_INVALID_PADDING_MODE 122 839#define EVP_R_INVALID_MGF1_MD 123 840#define EVP_R_SHARED_INFO_ERROR 124 841#define EVP_R_INVALID_KEYBITS 125 842#define EVP_R_PEER_KEY_ERROR 126 843#define EVP_R_EXPECTING_A_DSA_KEY 127 844#define EVP_R_UNSUPPORTED_MASK_ALGORITHM 128 845#define EVP_R_EXPECTING_AN_EC_KEY_KEY 129 846#define EVP_R_INVALID_TRAILER 130 847#define EVP_R_INVALID_DIGEST_LENGTH 131 848#define EVP_R_COMMAND_NOT_SUPPORTED 132 849#define EVP_R_EXPLICIT_EC_PARAMETERS_NOT_SUPPORTED 133 850#define EVP_R_ILLEGAL_OR_UNSUPPORTED_PADDING_MODE 134 851#define EVP_R_NO_MDC2_SUPPORT 135 852#define EVP_R_INVALID_CURVE 136 853#define EVP_R_NO_KEY_SET 137 854#define EVP_R_INVALID_PSS_PARAMETERS 138 855#define EVP_R_KDF_PARAMETER_ERROR 139 856#define EVP_R_UNSUPPORTED_MASK_PARAMETER 140 857#define EVP_R_EXPECTING_AN_RSA_KEY 141 858#define EVP_R_INVALID_OPERATION 142 859#define EVP_R_DECODE_ERROR 143 860#define EVP_R_INVALID_PSS_SALTLEN 144 861#define EVP_R_UNKNOWN_PUBLIC_KEY_TYPE 145 862 863#endif /* OPENSSL_HEADER_EVP_H */ 864