1=pod 2 3=head1 NAME 4 5EVP_KDF-ARGON2 - The Argon2 EVP KDF implementation 6 7=head1 DESCRIPTION 8 9Support for computing the B<argon2> password-based KDF through the B<EVP_KDF> 10API. 11 12The EVP_KDF-ARGON2 algorithm implements the Argon2 password-based key 13derivation function, as described in IETF RFC 9106. It is memory-hard in 14the sense that it deliberately requires a significant amount of RAM for efficient 15computation. The intention of this is to render brute forcing of passwords on 16systems that lack large amounts of main memory (such as GPUs or ASICs) 17computationally infeasible. 18 19Argon2d (Argon2i) uses data-dependent (data-independent) memory access and 20primary seek to address trade-off (side-channel) attacks. 21 22Argon2id is a hybrid construction which, in the first two slices of the first 23pass, generates reference addresses data-independently as in Argon2i, whereas 24in later slices and next passes it generates them data-dependently as in 25Argon2d. 26 27Sbox-hardened version Argon2ds is not supported. 28 29For more information, please refer to RFC 9106. 30 31=head2 Supported parameters 32 33The supported parameters are: 34 35=over 4 36 37=item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> 38 39=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> 40 41=item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string> 42 43=item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> 44 45=item "size" (B<OSSL_KDF_PARAM_SIZE>) <unsigned integer> 46 47These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 48 49Note that RFC 9106 recommends 128 bits salt for most applications, or 64 bits 50salt in the case of space constraints. At least 128 bits output length is 51recommended. 52 53Note that secret (or pepper) is an optional secret data used along the 54password. 55 56=item "threads" (B<OSSL_KDF_PARAM_THREADS>) <unsigned integer> 57 58The number of threads, bounded above by the number of lanes. 59 60This can only be used with built-in thread support. Threading must be 61explicitly enabled. See EXAMPLES section for more information. 62 63=item "ad" (B<OSSL_KDF_PARAM_ARGON2_AD>) <octet string> 64 65Optional associated data, may be used to "tag" a group of keys, or tie them 66to a particular public key, without having to modify salt. 67 68=item "lanes" (B<OSSL_KDF_PARAM_ARGON2_LANES>) <unsigned integer> 69 70Argon2 splits the requested memory size into lanes, each of which is designed 71to be processed in parallel. For example, on a system with p cores, it's 72recommended to use p lanes. 73 74The number of lanes is used to derive the key. It is possible to specify 75more lanes than the number of available computational threads. This is 76especially encouraged if multi-threading is disabled. 77 78=item "memcost" (B<OSSL_KDF_PARAM_ARGON2_MEMCOST>) <unsigned integer> 79 80Memory cost parameter (the number of 1k memory blocks used). 81 82=item "version" (B<OSSL_KDF_PARAM_ARGON2_VERSION>) <unsigned integer> 83 84Argon2 version. Supported values: 0x10, 0x13 (default). 85 86=item "early_clean" (B<OSSL_KDF_PARAM_EARLY_CLEAN>) <unsigned integer> 87 88If set (nonzero), password and secret stored in Argon2 context are zeroed 89early during initial hash computation, as soon as they are not needed. 90Otherwise, they are zeroed along the rest of Argon2 context data on clear, 91free, reset. 92 93This can be useful if, for example, multiple keys with different ad value 94are to be generated from a single password and secret. 95 96=back 97 98=head1 EXAMPLES 99 100This example uses Argon2d with password "1234567890", salt "saltsalt", 101using 2 lanes, 2 threads, and memory cost of 65536: 102 103 #include <string.h> /* strlen */ 104 #include <openssl/core_names.h> /* OSSL_KDF_* */ 105 #include <openssl/params.h> /* OSSL_PARAM_* */ 106 #include <openssl/thread.h> /* OSSL_set_max_threads */ 107 #include <openssl/kdf.h> /* EVP_KDF_* */ 108 109 int main(void) 110 { 111 int retval = 1; 112 113 EVP_KDF *kdf = NULL; 114 EVP_KDF_CTX *kctx = NULL; 115 OSSL_PARAM params[6], *p = params; 116 117 /* argon2 params, please refer to RFC9106 for recommended defaults */ 118 uint32_t lanes = 2, threads = 2, memcost = 65536; 119 char pwd[] = "1234567890", salt[] = "saltsalt"; 120 121 /* derive result */ 122 size_t outlen = 128; 123 unsigned char result[outlen]; 124 125 /* required if threads > 1 */ 126 if (OSSL_set_max_threads(NULL, threads) != 1) 127 goto fail; 128 129 p = params; 130 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_THREADS, &threads); 131 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES, 132 &lanes); 133 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST, 134 &memcost); 135 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 136 salt, 137 strlen((const char *)salt)); 138 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, 139 pwd, 140 strlen((const char *)pwd)); 141 *p++ = OSSL_PARAM_construct_end(); 142 143 if ((kdf = EVP_KDF_fetch(NULL, "ARGON2D", NULL)) == NULL) 144 goto fail; 145 if ((kctx = EVP_KDF_CTX_new(kdf)) == NULL) 146 goto fail; 147 if (EVP_KDF_derive(kctx, &result[0], outlen, params) != 1) 148 goto fail; 149 150 printf("Output = %s\n", OPENSSL_buf2hexstr(result, outlen)); 151 retval = 0; 152 153 fail: 154 EVP_KDF_free(kdf); 155 EVP_KDF_CTX_free(kctx); 156 OSSL_set_max_threads(NULL, 0); 157 158 return retval; 159 } 160 161=head1 NOTES 162 163"ARGON2I", "ARGON2D", and "ARGON2ID" are the names for this implementation; it 164can be used with the EVP_KDF_fetch() function. 165 166=head1 CONFORMING TO 167 168RFC 9106 Argon2, see L<https://www.rfc-editor.org/rfc/rfc9106.txt>. 169 170=head1 SEE ALSO 171 172L<EVP_KDF(3)>, 173L<EVP_KDF_CTX_new(3)>, 174L<EVP_KDF_CTX_free(3)>, 175L<EVP_KDF_CTX_set_params(3)>, 176L<EVP_KDF_derive(3)>, 177L<EVP_KDF(3)/PARAMETERS> 178 179=head1 HISTORY 180 181This functionality was added to OpenSSL 3.2. 182 183=head1 COPYRIGHT 184 185Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved. 186 187Licensed under the Apache License 2.0 (the "License"). You may not use 188this file except in compliance with the License. You can obtain a copy 189in the file LICENSE in the source distribution or at 190L<https://www.openssl.org/source/license.html>. 191 192=cut 193
