lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3

   1 .\"     $OpenBSD: PKCS5_PBKDF2_HMAC.3,v 1.6 2018/03/23 04:34:23 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Jeffrey Walton <noloader@gmail.com>.
   5 .\" Copyright (c) 2014, 2015 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: March 23 2018 $
  52 .Dt PKCS5_PBKDF2_HMAC 3
  53 .Os
  54 .Sh NAME
  55 .Nm PKCS5_PBKDF2_HMAC ,
  56 .Nm PKCS5_PBKDF2_HMAC_SHA1
  57 .Nd password based derivation routines with salt and iteration count
  58 .Sh SYNOPSIS
  59 .In openssl/evp.h
  60 .Ft int
  61 .Fo PKCS5_PBKDF2_HMAC
  62 .Fa "const char *pass"
  63 .Fa "int passlen"
  64 .Fa "const unsigned char *salt"
  65 .Fa "int saltlen"
  66 .Fa "int iter"
  67 .Fa "const EVP_MD *digest"
  68 .Fa "int keylen"
  69 .Fa "unsigned char *out"
  70 .Fc
  71 .Ft int
  72 .Fo PKCS5_PBKDF2_HMAC_SHA1
  73 .Fa "const char *pass"
  74 .Fa "int passlen"
  75 .Fa "const unsigned char *salt"
  76 .Fa "int saltlen"
  77 .Fa "int iter"
  78 .Fa "int keylen"
  79 .Fa "unsigned char *out"
  80 .Fc
  81 .Sh DESCRIPTION
  82 .Fn PKCS5_PBKDF2_HMAC
  83 derives a key from a password using a salt and iteration count as
  84 specified in RFC 2898.
  85 .Pp
  86 .Fa pass
  87 is the password used in the derivation of length
  88 .Fa passlen .
  89 .Fa pass
  90 is an optional parameter and can be
  91 .Dv NULL .
  92 If
  93 .Fa passlen
  94 is -1, then the function will calculate the length of
  95 .Fa pass
  96 using
  97 .Xr strlen 3 .
  98 .Pp
  99 .Fa salt
 100 is the salt used in the derivation of length
 101 .Fa saltlen .
 102 If the
 103 .Fa salt
 104 is
 105 .Dv NULL ,
 106 then
 107 .Fa saltlen
 108 must be 0.
 109 The function will not attempt to calculate the length of the
 110 .Fa salt
 111 because it is not assumed to be NUL terminated.
 112 .Pp
 113 .Fa iter
 114 is the iteration count and its value should be greater than or equal to 1.
 115 RFC 2898 suggests an iteration count of at least 1000.
 116 Any
 117 .Fa iter
 118 less than 1 is treated as a single iteration.
 119 .Pp
 120 .Fa digest
 121 is the message digest function used in the derivation.
 122 Values include any of the EVP_* message digests.
 123 .Fn PKCS5_PBKDF2_HMAC_SHA1
 124 calls
 125 .Fn PKCS5_PBKDF2_HMAC
 126 with
 127 .Xr EVP_sha1 3 .
 128 .Pp
 129 The derived key will be written to
 130 .Fa out .
 131 The size of the
 132 .Fa out
 133 buffer is specified via
 134 .Fa keylen .
 135 .Pp
 136 A typical application of this function is to derive keying material for
 137 an encryption algorithm from a password in the
 138 .Fa pass ,
 139 a salt in
 140 .Fa salt ,
 141 and an iteration count.
 142 .Pp
 143 Increasing the
 144 .Fa iter
 145 parameter slows down the algorithm which makes it harder for an attacker
 146 to perform a brute force attack using a large number of candidate
 147 passwords.
 148 .Sh RETURN VALUES
 149 .Fn PKCS5_PBKDF2_HMAC
 150 and
 151 .Fn PBKCS5_PBKDF2_HMAC_SHA1
 152 return 1 on success or 0 on error.
 153 .Sh SEE ALSO
 154 .Xr evp 3 ,
 155 .Xr EVP_BytesToKey 3 ,
 156 .Xr RAND_bytes 3
 157 .Sh HISTORY
 158 .Fn PKCS5_PBKDF2_HMAC_SHA1
 159 first appeared in OpenSSL 0.9.4 and has been available since
 160 .Ox 2.6 .
 161 .Pp
 162 .Fn PKCS5_PBKDF2_HMAC
 163 first appeared in OpenSSL 1.0.0 and has been available since
 164 .Ox 4.9 .