diff options
Diffstat (limited to 'src/lib/libcrypto/man/EVP_BytesToKey.3')
| -rw-r--r-- | src/lib/libcrypto/man/EVP_BytesToKey.3 | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/EVP_BytesToKey.3 b/src/lib/libcrypto/man/EVP_BytesToKey.3 new file mode 100644 index 0000000000..45a3d9bf33 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_BytesToKey.3 | |||
| @@ -0,0 +1,82 @@ | |||
| 1 | .Dd $Mdocdate: November 3 2016 $ | ||
| 2 | .Dt EVP_BYTESTOKEY 3 | ||
| 3 | .Os | ||
| 4 | .Sh NAME | ||
| 5 | .Nm EVP_BytesToKey | ||
| 6 | .Nd password based encryption routine | ||
| 7 | .Sh SYNOPSIS | ||
| 8 | .In openssl/evp.h | ||
| 9 | .Ft int | ||
| 10 | .Fo EVP_BytesToKey | ||
| 11 | .Fa "const EVP_CIPHER *type" | ||
| 12 | .Fa "const EVP_MD *md" | ||
| 13 | .Fa "const unsigned char *salt" | ||
| 14 | .Fa "const unsigned char *data" | ||
| 15 | .Fa "int datal" | ||
| 16 | .Fa "int count" | ||
| 17 | .Fa "unsigned char *key" | ||
| 18 | .Fa "unsigned char *iv" | ||
| 19 | .Fc | ||
| 20 | .Sh DESCRIPTION | ||
| 21 | .Fn EVP_BytesToKey | ||
| 22 | derives a key and IV from various parameters. | ||
| 23 | .Fa type | ||
| 24 | is the cipher to derive the key and IV for. | ||
| 25 | .Fa md | ||
| 26 | is the message digest to use. | ||
| 27 | The | ||
| 28 | .Fa salt | ||
| 29 | parameter is used as a salt in the derivation: it should point to an 8 | ||
| 30 | byte buffer or | ||
| 31 | .Dv NULL | ||
| 32 | if no salt is used. | ||
| 33 | .Fa data | ||
| 34 | is a buffer containing | ||
| 35 | .Fa datal | ||
| 36 | bytes which is used to derive the keying data. | ||
| 37 | .Fa count | ||
| 38 | is the iteration count to use. | ||
| 39 | The derived key and IV will be written to | ||
| 40 | .Fa key | ||
| 41 | and | ||
| 42 | .Fa iv , | ||
| 43 | respectively. | ||
| 44 | .Pp | ||
| 45 | A typical application of this function is to derive keying material for | ||
| 46 | an encryption algorithm from a password in the | ||
| 47 | .Fa data | ||
| 48 | parameter. | ||
| 49 | .Pp | ||
| 50 | Increasing the | ||
| 51 | .Fa count | ||
| 52 | parameter slows down the algorithm which makes it harder for an attacker | ||
| 53 | to perform a brute force attack using a large number of candidate | ||
| 54 | passwords. | ||
| 55 | .Pp | ||
| 56 | If the total key and IV length is less than the digest length and MD5 | ||
| 57 | is used, then the derivation algorithm is compatible with PKCS#5 v1.5. | ||
| 58 | Otherwise, a non standard extension is used to derive the extra data. | ||
| 59 | .Pp | ||
| 60 | Newer applications should use more standard algorithms such as PBKDF2 as | ||
| 61 | defined in PKCS#5v2.1 for key derivation. | ||
| 62 | .Sh KEY DERIVATION ALGORITHM | ||
| 63 | The key and IV is derived by concatenating D_1, D_2, etc until enough | ||
| 64 | data is available for the key and IV. | ||
| 65 | D_i is defined recursively as: | ||
| 66 | .Pp | ||
| 67 | .Dl D_i = HASH^count(D_(i-1) || data || salt) | ||
| 68 | .Pp | ||
| 69 | where || denotes concatenation, D_0 is empty, HASH is the digest | ||
| 70 | algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) is | ||
| 71 | HASH(HASH(data)) and so on. | ||
| 72 | .Pp | ||
| 73 | The initial bytes are used for the key and the subsequent bytes for the | ||
| 74 | IV. | ||
| 75 | .Sh RETURN VALUES | ||
| 76 | .Fn EVP_BytesToKey | ||
| 77 | returns the size of the derived key in bytes. | ||
| 78 | .Sh SEE ALSO | ||
| 79 | .Xr evp 3 , | ||
| 80 | .Xr EVP_EncryptInit 3 , | ||
| 81 | .Xr PKCS5_PBKDF2_HMAC 3 , | ||
| 82 | .Xr rand 3 | ||