projects / thirdparty / openssl.git / blame
| Commit | Line | Data |
|---|---|---|
| a8ca496d RL |
1 | =pod |
| 2 | ||
| 3 | =head1 NAME | |
| 4 | ||
| 5 | EVP_PKEY_CTX_set1_scrypt_salt, | |
| 6 | EVP_PKEY_CTX_set_scrypt_N, | |
| 7 | EVP_PKEY_CTX_set_scrypt_r, | |
| 8 | EVP_PKEY_CTX_set_scrypt_p, | |
| 9 | EVP_PKEY_CTX_set_scrypt_maxmem_bytes | |
| 10 | - EVP_PKEY scrypt KDF support functions | |
| 11 | ||
| 12 | =head1 SYNOPSIS | |
| 13 | ||
| 14 | #include <openssl/kdf.h> | |
| 15 | ||
| 16 | int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt, | |
| 17 | int saltlen); | |
| 18 | ||
| 19 | int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N); | |
| 20 | ||
| 21 | int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r); | |
| 22 | ||
| 23 | int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p); | |
| 24 | ||
| 25 | int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx, | |
| 26 | uint64_t maxmem); | |
| 27 | ||
| 28 | =head1 DESCRIPTION | |
| 29 | ||
| 30 | These functions are used to set up the necessary data to use the | |
| 31 | scrypt KDF. | |
| fadb57e5 | 32 | For more information on scrypt, see L<EVP_KDF-SCRYPT(7)>. |
| a8ca496d RL |
33 | |
| 34 | EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt | |
| 35 | value. | |
| 36 | ||
| 37 | EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and | |
| 38 | EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p. | |
| 39 | ||
| 40 | EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key | |
| 41 | derivation may maximally use, given in bytes. | |
| 42 | If RAM is exceeded because the load factors are chosen too high, the | |
| 43 | key derivation will fail. | |
| 44 | ||
| 45 | =head1 STRING CTRLS | |
| 46 | ||
| 47 | scrypt also supports string based control operations via | |
| 48 | L<EVP_PKEY_CTX_ctrl_str(3)>. | |
| 49 | Similarly, the B<salt> can either be specified using the B<type> | |
| 50 | parameter "salt" or in hex encoding by using the "hexsalt" parameter. | |
| 51 | The work factors B<N>, B<r> and B<p> as well as B<maxmem_bytes> can be | |
| 52 | set by using the parameters "N", "r", "p" and "maxmem_bytes", | |
| 53 | respectively. | |
| 54 | ||
| 55 | =head1 NOTES | |
| 56 | ||
| 3cb45a55 RL |
57 | There is a newer generic API for KDFs, L<EVP_KDF(3)>, which is |
| 58 | preferred over the EVP_PKEY method. | |
| 59 | ||
| a8ca496d RL |
60 | The scrypt KDF also uses EVP_PKEY_CTX_set1_pbe_pass() as well as |
| 61 | the value from the string controls "pass" and "hexpass". | |
| 62 | See L<EVP_PKEY_CTX_set1_pbe_pass(3)>. | |
| 63 | ||
| 64 | All the functions described here are implemented as macros. | |
| 65 | ||
| 66 | =head1 RETURN VALUES | |
| 67 | ||
| 68 | All these functions return 1 for success and 0 or a negative value for | |
| 69 | failure. | |
| 70 | In particular a return value of -2 indicates the operation is not | |
| 71 | supported by the public key algorithm. | |
| 72 | ||
| 73 | =head1 SEE ALSO | |
| 74 | ||
| 3cb45a55 | 75 | L<EVP_KDF(3)> |
| a8ca496d RL |
76 | L<EVP_PKEY_CTX_new(3)>, |
| 77 | L<EVP_PKEY_CTX_ctrl_str(3)>, | |
| 78 | L<EVP_PKEY_derive(3)> | |
| 79 | ||
| 80 | =head1 COPYRIGHT | |
| 81 | ||
| 82 | Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. | |
| 83 | ||
| 4746f25a | 84 | Licensed under the Apache License 2.0 (the "License"). You may not use |
| a8ca496d RL |
85 | this file except in compliance with the License. You can obtain a copy |
| 86 | in the file LICENSE in the source distribution or at | |
| 87 | L<https://www.openssl.org/source/license.html>. | |
| 88 | ||
| 89 | =cut |