source: project/wiki/eggref/4/pbkdf2 @ 36684

Last change on this file since 36684 was 36684, checked in by Tobias Heilig, 14 months ago
File size: 5.0 KB
Line 
1== PBKDF2
2
3[[toc:]]
4
5=== Description
6
7Password-Based Key Derivation Function as defined in [[https://tools.ietf.org/html/rfc2898#section-5.2|RFC2898]]
8
9Note that PBKDF2 is recommended for new applications while PBKDF1 is recommended only for backwards compatibility with existing applications since the keys it produces may not be large enough for some applications.
10
11=== Author
12
13Tobias Heilig
14
15<off_world at gmx . de>
16
17=== Repository
18
19[[https://github.com/off-world/pbkdf2]]
20
21=== Requirements
22
23* [[/eggref/4/message-digest|message-digest]]
24* [[/eggref/4/hmac|hmac]]
25* [[/eggref/4/sha1|sha2]]
26* [[/eggref/4/sha2|sha1]]
27* [[/eggref/4/md5|md5]]
28
29=== API
30
31==== Common Argument Definitions
32
33===== password
34password as a string
35
36===== salt
37salt as a string
38
39===== count
40iteration count as a positive exact integer
41
42===== dklen
43length in bytes of the derived key as a positive exact integer
44
45===== result-type
46; {{'blob}} : return resulting bytes as a blob
47; {{'hex}} : return resulting bytes as a string of lower-case hexadecimal digits
48; {{'string}} : return resulting bytes as a byte-string
49; {{'u8vector}} : return resulting bytes as a u8vector
50
51==== Procedures
52
53===== {{pbkdf1-md2}}
54<procedure>(pbkdf1-md2 password salt count dklen #!optional (result-type 'blob))</procedure>
55
56Derives a key of {{dklen}} bytes from the given {{password}} and {{salt}} using PBKDF1 with MD2. The maximum length of the derived key is bounded by the length of the hash function output which is 16 bytes for MD2.
57
58===== {{pbkdf1-md5}}
59<procedure>(pbkdf1-md5 password salt count dklen #!optional (result-type 'blob))</procedure>
60
61Derives a key of {{dklen}} bytes from the given {{password}} and {{salt}} using PBKDF1 with MD5. The maximum length of the derived key is bounded by the length of the hash function output which is 16 bytes for MD5.
62
63===== {{pbkdf1-sha1}}
64<procedure>(pbkdf1-sha1 password salt count dklen #!optional (result-type 'blob))</procedure>
65
66Derives a key of {{dklen}} bytes from the given {{password}} and {{salt}} using PBKDF1 with SHA1. The maximum length of the derived key is bounded by the length of the hash function output which is 20 bytes for SHA1.
67
68===== {{pbkdf2-hmac-sha1}}
69<procedure>(pbkdf2-hmac-sha1 password salt count dklen #!optional (result-type 'blob))</procedure>
70
71Derives a key of {{dklen}} bytes from the given {{password}} and {{salt}} using PBKDF2 with HMAC-SHA1. The maximum length of the derived key is 2^32 - 1.
72
73===== {{pbkdf2-hmac-sha256}}
74<procedure>(pbkdf2-hmac-sha256 password salt count dklen #!optional (result-type 'blob))</procedure>
75
76
77Derives a key of {{dklen}} bytes from the given {{password}} and {{salt}} using PBKDF2 with HMAC-SHA256. The maximum length of the derived key is 2^32 - 1.
78
79===== {{pbkdf2-hmac-sha384}}
80<procedure>(pbkdf2-hmac-sha384 password salt count dklen #!optional (result-type 'blob))</procedure>
81
82
83Derives a key of {{dklen}} bytes from the given {{password}} and {{salt}} using PBKDF2 with HMAC-SHA384. The maximum length of the derived key is 2^32 - 1.
84
85===== {{pbkdf2-hmac-sha512}}
86<procedure>(pbkdf2-hmac-sha512 password salt count dklen #!optional (result-type 'blob))</procedure>
87
88
89Derives a key of [[dklen]] bytes from the given [[password]] and [[salt]] using PBKDF2 with HMAC-SHA512. The maximum length of the derived key is 2^32 - 1.
90
91=== Examples
92
93<enscript highlight=scheme>
94(use pbkdf2)
95 
96(pbkdf2-hmac-sha1 "password" "salt" 4096 20)
97;=> #${4b007901b765489abead49d926f721d065a429c1}
98
99(pbkdf2-hmac-sha1 "password" "salt" 4096 20 'hex)
100;=> "4b007901b765489abead49d926f721d065a429c1"
101</enscript>
102
103=== License
104
105 Copyright (c) 2018, Tobias Heilig
106 All rights reserved.
107 
108 Redistribution and use in source and binary forms, with or without
109 modification, are permitted provided that the following conditions
110 are met:
111 
112 1. Redistributions of source code must retain the above copyright
113    notice, this list of conditions and the following disclaimer.
114 2. Redistributions in binary form must reproduce the above copyright
115    notice, this list of conditions and the following disclaimer in the
116    documentation and/or other materials provided with the distribution.
117 3. The name of the authors may not be used to endorse or promote products
118    derived from this software without specific prior written permission.
119 
120 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
121 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
122 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
123 ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
124 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
125 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
126 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
127 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
128 IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
129 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
130 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
131
132=== Version History
133; 1.2 : added MD2 support for PBKDF1
134; 1.1 : added PBKDF1 implementation
135; 1.0 : initial release
Note: See TracBrowser for help on using the repository browser.