1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
|
nacl.pwhash
===========
.. module:: nacl.pwhash
The package pwhash provides implementations of modern *memory-hard*
password hashing construction exposing modules with a uniform API.
Functions exposed at top level
------------------------------
The top level module only provides the functions implementing
ascii encoded hashing and verification.
.. function:: str(password, \
opslimit=OPSLIMIT_INTERACTIVE, \
memlimit=MEMLIMIT_INTERACTIVE)
Returns a password verifier hash, generated with the password hasher
choosen as a default by libsodium.
:param password: password used to seed the key derivation procedure;
it length must be between
:py:const:`PASSWD_MIN` and
:py:const:`PASSWD_MAX`
:type password: bytes
:param opslimit: the time component (operation count)
of the key derivation procedure's computational cost;
it must be between
:py:const:`OPSLIMIT_MIN` and
:py:const:`OPSLIMIT_MAX`
:type opslimit: int
:param memlimit: the memory occupation component
of the key derivation procedure's computational cost;
it must be between
:py:const:`MEMLIMIT_MIN` and
:py:const:`MEMLIMIT_MAX`
:type memlimit: int
:returns: the ascii encoded password hash along with a prefix encoding
the used hashing construct, the random generated salt and
the operation and memory limits used to generate the password hash
:rtype: bytes
As of PyNaCl version 1.2 this is :py:func:`nacl.pwhash.argon2id.str`.
.. versionadded:: 1.2
.. function:: verify(password_hash, password)
This function checks if hashing the proposed password, with
the same construction and parameters encoded in the password hash
would generate the same encoded string, thus verifying the
correct password has been proposed in an authentication attempt.
.. versionadded:: 1.2
.. rubric:: Module level constants
The top level module defines the constants related to the :py:func:`str`
hashing construct and its corresponding :py:func:`verify` password
verifier.
.. py:data:: PASSWD_MIN
.. py:data:: PASSWD_MAX
minimum and maximum length of the password to hash
.. py:data:: PWHASH_SIZE
maximum size of the encoded hash
.. py:data:: OPSLIMIT_MIN
.. py:data:: OPSLIMIT_MAX
minimum and maximum operation count for the hashing construct
.. py:data:: MEMLIMIT_MIN
.. py:data:: MEMLIMIT_MAX
minimum and maximum memory occupation for the hashing construct
and the recommended values for the opslimit and memlimit parameters
.. py:data:: MEMLIMIT_INTERACTIVE
.. py:data:: OPSLIMIT_INTERACTIVE
recommended values for the interactive user authentication password
check case, leading to a sub-second hashing time
.. py:data:: MEMLIMIT_SENSITIVE
.. py:data:: OPSLIMIT_SENSITIVE
recommended values for generating a password hash/derived key meant to protect
sensitive data, leading to a multi-second hashing time
.. py:data:: MEMLIMIT_MODERATE
.. py:data:: OPSLIMIT_MODERATE
values leading to a hashing time and memory cost intermediate between the
interactive and the sensitive cases
Per-mechanism password hashing implementation modules
-----------------------------------------------------
Along with the respective :py:func:`str` and :py:func:`verify` functions,
the modules implementing named password hashing constructs expose also
a :py:func:`kdf` function returning a raw pseudo-random bytes sequence
derived from the input parameters
nacl.pwhash.argon2id
""""""""""""""""""""
.. module:: nacl.pwhash.argon2id
.. function:: kdf(size, password, salt, \
opslimit=OPSLIMIT_SENSITIVE, \
memlimit=MEMLIMIT_SENSITIVE, \
encoder=nacl.encoding.RawEncoder)
Derive a ``size`` bytes long key from a caller-supplied
``password`` and ``salt`` pair using the ``argon2id`` partially
data dependent memory-hard construct.
:param size: derived key size, must be between
:py:const:`BYTES_MIN` and
:py:const:`BYTES_MAX`
:type size: int
:param password: password used to seed the key derivation procedure;
it length must be between
:py:const:`PASSWD_MIN` and
:py:const:`PASSWD_MAX`
:type password: bytes
:param salt: **RANDOM** salt used in the key derivation procedure;
its length must be exactly :py:const:`.SALTBYTES`
:type salt: bytes
:param opslimit: the time component (operation count)
of the key derivation procedure's computational cost;
it must be between
:py:const:`OPSLIMIT_MIN` and
:py:const:`OPSLIMIT_MAX`
:type opslimit: int
:param memlimit: the memory occupation component
of the key derivation procedure's computational cost;
it must be between
:py:const:`MEMLIMIT_MIN` and
:py:const:`MEMLIMIT_MAX`
:type memlimit: int
:rtype: bytes
The default settings for opslimit and memlimit are those deemed
correct for generating a key, which can be used to protect
sensitive data for a long time, leading to a multi-second
hashing time.
.. versionadded:: 1.2
.. function:: str(password, \
opslimit=OPSLIMIT_INTERACTIVE, \
memlimit=MEMLIMIT_INTERACTIVE)
Returns a password verifier hash, generated with the ``argon2id``
password hasher.
See: :py:func:`nacl.pwhash.str` for the general API.
.. versionadded:: 1.2
.. function:: verify(password_hash, password)
This function verifies the proposed ``password``, using
``password_hash`` as a password verifier.
See: :py:func:`nacl.pwhash.verify` for the general API.
.. versionadded:: 1.2
.. rubric:: Module level constants
The module defines the constants related to the :py:func:`kdf` raw hashing
construct
.. py:data:: SALTBYTES
the length of the random bytes sequence passed in as a salt to the
:py:func:`kdf`
.. py:data:: BYTES_MIN
.. py:data:: BYTES_MAX
the minimum and maximum allowed values for the ``size`` parameter
of the :py:func:`kdf`
The meaning of each of the constants
.. py:data:: PASSWD_MIN
.. py:data:: PASSWD_MAX
.. py:data:: PWHASH_SIZE
.. py:data:: OPSLIMIT_MIN
.. py:data:: OPSLIMIT_MAX
.. py:data:: MEMLIMIT_MIN
.. py:data:: MEMLIMIT_MAX
.. py:data:: MEMLIMIT_INTERACTIVE
.. py:data:: OPSLIMIT_INTERACTIVE
.. py:data:: MEMLIMIT_SENSITIVE
.. py:data:: OPSLIMIT_SENSITIVE
.. py:data:: MEMLIMIT_MODERATE
.. py:data:: OPSLIMIT_MODERATE
is the same as in :py:mod:`nacl.hash`.
nacl.pwhash.argon2i
"""""""""""""""""""
.. module:: nacl.pwhash.argon2i
.. function:: kdf(size, password, salt, \
opslimit=OPSLIMIT_SENSITIVE, \
memlimit=MEMLIMIT_SENSITIVE, \
encoder=nacl.encoding.RawEncoder)
Derive a ``size`` bytes long key from a caller-supplied
``password`` and ``salt`` pair using the ``argon2i``
data independent memory-hard construct.
See: py:func:`nacl.pwhash.argon2id.kdf` for the general API.
.. versionadded:: 1.2
.. function:: str(password, \
opslimit=OPSLIMIT_INTERACTIVE, \
memlimit=MEMLIMIT_INTERACTIVE)
Returns a password verifier hash, generated with the ``argon2i``
password hasher.
See: :py:func:`nacl.pwhash.str` for the general API.
.. versionadded:: 1.2
.. function:: verify(password_hash, password)
This function verifies the proposed ``password``, using
``password_hash`` as a password verifier.
See: :py:func:`nacl.pwhash.verify` for the general API.
.. versionadded:: 1.2
.. rubric:: Module level constants
The meaning of each of the constants
.. py:data:: PASSWD_MIN
.. py:data:: PASSWD_MAX
.. py:data:: PWHASH_SIZE
.. py:data:: SALTBYTES
.. py:data:: BYTES_MIN
.. py:data:: BYTES_MAX
.. py:data:: OPSLIMIT_MIN
.. py:data:: OPSLIMIT_MAX
.. py:data:: MEMLIMIT_MIN
.. py:data:: MEMLIMIT_MAX
.. py:data:: MEMLIMIT_INTERACTIVE
.. py:data:: OPSLIMIT_INTERACTIVE
.. py:data:: MEMLIMIT_SENSITIVE
.. py:data:: OPSLIMIT_SENSITIVE
.. py:data:: MEMLIMIT_MODERATE
.. py:data:: OPSLIMIT_MODERATE
is the same as in :py:mod:`nacl.pwhash`
and :py:mod:`nacl.pwhash.argon2id`
nacl.pwhash.scrypt
""""""""""""""""""
.. module:: nacl.pwhash.scrypt
.. function:: kdf(size, password, salt, \
opslimit=OPSLIMIT_SENSITIVE, \
memlimit=MEMLIMIT_SENSITIVE, \
encoder=nacl.encoding.RawEncoder)
Derive a ``size`` bytes long key from a caller-supplied
``password`` and ``salt`` pair using the ``scrypt``
data dependent memory-hard construct.
See: :py:func:`nacl.pwhash.argon2id.kdf` for the general API.
.. versionadded:: 1.2
.. function:: str(password, \
opslimit=OPSLIMIT_INTERACTIVE, \
memlimit=MEMLIMIT_INTERACTIVE)
Returns a password verifier hash, generated with the ``scrypt``
password hasher.
See: :py:func:`nacl.pwhash.str` for the general API.
.. versionadded:: 1.2
.. function:: verify(password_hash, password)
This function verifies the proposed ``password``, using
``password_hash`` as a password verifier.
See: py:func:`nacl.pwhash.verify` for the general API.
.. versionadded:: 1.2
.. rubric:: Module level constants
The meaning of each of the constants
.. py:data:: PASSWD_MIN
.. py:data:: PASSWD_MAX
.. py:data:: PWHASH_SIZE
.. py:data:: SALTBYTES
.. py:data:: BYTES_MIN
.. py:data:: BYTES_MAX
.. py:data:: OPSLIMIT_MIN
.. py:data:: OPSLIMIT_MAX
.. py:data:: MEMLIMIT_MIN
.. py:data:: MEMLIMIT_MAX
.. py:data:: MEMLIMIT_INTERACTIVE
.. py:data:: OPSLIMIT_INTERACTIVE
.. py:data:: MEMLIMIT_SENSITIVE
.. py:data:: OPSLIMIT_SENSITIVE
.. py:data:: MEMLIMIT_MODERATE
.. py:data:: OPSLIMIT_MODERATE
is the same as in :py:mod:`nacl.pwhash`
and :py:mod:`nacl.pwhash.argon2id`
|
