doc/man7/scrypt.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 scrypt - EVP_PKEY scrypt KDF support
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/kdf.h>
  10
  11  int EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass,
  12                                 int passlen);
  13
  14  int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
  15                                    int saltlen);
  16
  17  int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N);
  18
  19  int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r);
  20
  21  int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p);
  22
  23  int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx, uint64_t maxmem);
  24
  25 =head1 DESCRIPTION
  26
  27 The EVP_PKEY_SCRYPT algorithm implements the scrypt password based key
  28 derivation function, as described in RFC 7914.  It is memory-hard in the sense
  29 that it deliberately requires a significant amount of RAM for efficient
  30 computation. The intention of this is to render brute forcing of passwords on
  31 systems that lack large amounts of main memory (such as GPUs or ASICs)
  32 computationally infeasible.
  33
  34 scrypt provides three work factors that can be customized: N, r and p. N, which
  35 has to be a positive power of two, is the general work factor and scales CPU
  36 time in an approximately linear fashion. r is the block size of the internally
  37 used hash function and p is the parallelization factor. Both r and p need to be
  38 greater than zero. The amount of RAM that scrypt requires for its computation
  39 is roughly (128 * N * r * p) bytes.
  40
  41 In the original paper of Colin Percival ("Stronger Key Derivation via
  42 Sequential Memory-Hard Functions", 2009), the suggested values that give a
  43 computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
  44 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
  45 this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
  46 GHz), this computation takes about 3 seconds. When N, r or p are not specified,
  47 they default to 1048576, 8, and 1, respectively. The default amount of RAM that
  48 may be used by scrypt defaults to 1025 MiB.
  49
  50 EVP_PKEY_CTX_set1_pbe_pass() sets the B<passlen> bytes long password.
  51
  52 EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt value.
  53
  54 EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and
  55 EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p.
  56
  57 EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key derivation may
  58 maximally use, given in bytes. If RAM is exceeded because the load factors are
  59 chosen too high, the key derivation will fail.
  60
  61 =head1 STRING CTRLS
  62
  63 scrypt also supports string based control operations via
  64 L<EVP_PKEY_CTX_ctrl_str(3)>.
  65 The B<password> can be directly specified using the B<type> parameter "pass" or
  66 given in hex encoding using the "hexpass" parameter. Similarly, the B<salt> can
  67 either be specified using the B<type> parameter "salt" or in hex encoding by
  68 using the "hexsalt" parameter. The work factors B<N>, B<r> and B<p> as well as
  69 B<maxmem_bytes> can be set by using the parameters "N", "r", "p" and
  70 "maxmem_bytes", respectively.
  71
  72 =head1 NOTES
  73
  74 All these functions are implemented as macros.
  75
  76 A context for scrypt can be obtained by calling:
  77
  78  EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_SCRYPT, NULL);
  79
  80 The output length of an scrypt key derivation is specified via the length
  81 parameter to the L<EVP_PKEY_derive(3)> function.
  82
  83 =head1 RETURN VALUES
  84
  85 All these functions return 1 for success and 0 or a negative value for failure.
  86 In particular a return value of -2 indicates the operation is not supported by
  87 the public key algorithm.
  88
  89 =head1 EXAMPLE
  90
  91 This example derives a 64-byte long test vector using scrypt using the password
  92 "password", salt "NaCl" and N = 1024, r = 8, p = 16.
  93
  94  EVP_PKEY_CTX *pctx;
  95  unsigned char out[64];
  96
  97  size_t outlen = sizeof(out);
  98  pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
  99
 100  if (EVP_PKEY_derive_init(pctx) <= 0) {
 101      error("EVP_PKEY_derive_init");
 102  }
 103  if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) {
 104      error("EVP_PKEY_CTX_set1_pbe_pass");
 105  }
 106  if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) {
 107      error("EVP_PKEY_CTX_set1_scrypt_salt");
 108  }
 109  if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) {
 110      error("EVP_PKEY_CTX_set_scrypt_N");
 111  }
 112  if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) {
 113      error("EVP_PKEY_CTX_set_scrypt_r");
 114  }
 115  if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) {
 116      error("EVP_PKEY_CTX_set_scrypt_p");
 117  }
 118  if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) {
 119      error("EVP_PKEY_derive");
 120  }
 121
 122  {
 123      const unsigned char expected[sizeof(out)] = {
 124          0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
 125          0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
 126          0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
 127          0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
 128          0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
 129          0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
 130          0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
 131          0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
 132      };
 133
 134      assert(!memcmp(out, expected, sizeof(out)));
 135  }
 136
 137  EVP_PKEY_CTX_free(pctx);
 138
 139 =head1 CONFORMING TO
 140
 141 RFC 7914
 142
 143 =head1 SEE ALSO
 144
 145 L<EVP_PKEY_CTX_new(3)>,
 146 L<EVP_PKEY_CTX_ctrl_str(3)>,
 147 L<EVP_PKEY_derive(3)>
 148
 149 =head1 COPYRIGHT
 150
 151 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
 152
 153 Licensed under the OpenSSL license (the "License").  You may not use
 154 this file except in compliance with the License.  You can obtain a copy
 155 in the file LICENSE in the source distribution or at
 156 L<https://www.openssl.org/source/license.html>.
 157
 158 =cut