1=pod
2
3=head1 NAME
4
5EVP_PKEY_CTX_set1_scrypt_salt,
6EVP_PKEY_CTX_set_scrypt_N,
7EVP_PKEY_CTX_set_scrypt_r,
8EVP_PKEY_CTX_set_scrypt_p,
9EVP_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
30These functions are used to set up the necessary data to use the
31scrypt KDF.
32For more information on scrypt, see L<EVP_KDF-SCRYPT(7)>.
33
34EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt
35value.
36
37EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and
38EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p.
39
40EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key
41derivation may maximally use, given in bytes.
42If RAM is exceeded because the load factors are chosen too high, the
43key derivation will fail.
44
45=head1 STRING CTRLS
46
47scrypt also supports string based control operations via
48L<EVP_PKEY_CTX_ctrl_str(3)>.
49Similarly, the B<salt> can either be specified using the B<type>
50parameter "salt" or in hex encoding by using the "hexsalt" parameter.
51The work factors B<N>, B<r> and B<p> as well as B<maxmem_bytes> can be
52set by using the parameters "N", "r", "p" and "maxmem_bytes",
53respectively.
54
55=head1 NOTES
56
57There is a newer generic API for KDFs, L<EVP_KDF(3)>, which is
58preferred over the EVP_PKEY method.
59
60The scrypt KDF also uses EVP_PKEY_CTX_set1_pbe_pass() as well as
61the value from the string controls "pass" and "hexpass".
62See L<EVP_PKEY_CTX_set1_pbe_pass(3)>.
63
64=head1 RETURN VALUES
65
66All these functions return 1 for success and 0 or a negative value for
67failure.
68In particular a return value of -2 indicates the operation is not
69supported by the public key algorithm.
70
71=head1 SEE ALSO
72
73L<EVP_KDF(3)>
74L<EVP_PKEY_CTX_new(3)>,
75L<EVP_PKEY_CTX_ctrl_str(3)>,
76L<EVP_PKEY_derive(3)>
77
78=head1 HISTORY
79
80All of the functions described here were converted from macros to functions in
81OpenSSL 3.0.
82
83=head1 COPYRIGHT
84
85Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
86
87Licensed under the Apache License 2.0 (the "License").  You may not use
88this file except in compliance with the License.  You can obtain a copy
89in the file LICENSE in the source distribution or at
90L<https://www.openssl.org/source/license.html>.
91
92=cut
93