-
Notifications
You must be signed in to change notification settings - Fork 85
/
scrypt.1
251 lines (251 loc) · 6.43 KB
/
scrypt.1
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
.\" Copyright 2009 Colin Percival
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.Dd @DATE@
.Dt SCRYPT 1
.Os
.Sh NAME
.Nm scrypt
.Nd encrypt and decrypt files
.Sh SYNOPSIS
.Nm
.Brq Cm enc | Cm dec | Cm info
.Op Fl f
.Op Fl -logN Ar value
.Op Fl M Ar maxmem
.Op Fl m Ar maxmemfrac
.Op Fl P
.Op Fl p Ar value
.Op Fl -passphrase Ar method:arg
.Op Fl r Ar value
.Op Fl t Ar maxtime
.Op Fl v
.Ar infile
.Op Ar outfile
.Nm
.Fl -version
.Sh DESCRIPTION
.Nm Cm enc
encrypts
.Ar infile
and writes the result to
.Ar outfile
if specified, or the standard output otherwise.
The user will be prompted to enter a passphrase (twice) to
be used to generate a derived encryption key.
.Pp
.Nm Cm dec
decrypts
.Ar infile
and writes the result to
.Ar outfile
if specified, or the standard output otherwise.
The user will be prompted to enter the passphrase used at
encryption time to generate the derived encryption key.
.Pp
.Nm Cm info
provides information about the encryption parameters used for
.Ar infile .
.Pp
Unless otherwise specified via
.Fl -passphrase ,
.Nm
reads passphrases from its controlling terminal, or failing that, from stdin.
Prompts are only printed when
.Nm
is reading passphrases from some terminal.
.Sh OPTIONS
.Bl -tag -width "-m maxmemfrac"
.It Fl f
Force the operation to proceed even if it is anticipated to
require an excessive amount of memory or CPU time.
Do not print any warnings about exceeding any memory or CPU time limits.
.It Fl -logN Ar value
Set the work parameter N to
.Pf 2^ Ar value .
If
.Fl -logN
is set,
.Fl r
and
.Fl p
must also be set.
If such explicit parameters are given, the resource limits set by
.Fl M ,
.Fl m ,
and
.Fl t
are not enforced.
.It Fl M Ar maxmem
Use at most
.Ar maxmem
bytes of RAM to compute the derived encryption key.
.It Fl m Ar maxmemfrac
Use at most the fraction
.Ar maxmemfrac
of the available RAM to compute the derived encryption key.
The maximum possible value for
.Ar maxmemfrac
is 0.5.
.It Fl P
Deprecated synonym for
.Fl -passphrase Ar dev:stdin-once .
.It Fl p Ar value
Set the work parameter p to
.Ar value .
If
.Fl p
is set,
.Fl -logN
and
.Fl r
must also be set.
If such explicit parameters are given, the resource limits set by
.Fl M ,
.Fl m ,
and
.Fl t
are not enforced.
.It Fl -passphrase Ar method:arg
Read the passphrase using the specified method.
.Bl -tag -width aa
.It Ar dev:tty-stdin
Attempt to read the passphrase from /dev/tty; if that fails, read it from stdin.
This is the default behaviour.
.It Ar dev:stdin-once
Attempt to read the passphrase from stdin, and do so only once even when
encrypting.
This cannot be used if
.Ar infile
is also stdin (aka '-').
.It Ar dev:tty-once
Attempt to read the passphrase from /dev/tty, and do so only once
even when encrypting.
.It Ar env:VAR
Read the passphrase from the environment variable specified by
.Ar VAR .
.Pp
.Bf Em
Storing a passphrase in an environment variable may be a security risk.
.Ef
Only use this option if you are certain that you know what you are doing.
.It Ar file:FILENAME
Read the passphrase from the file specified by
.Ar FILENAME .
.Pp
.Bf Em
Storing a passphrase in a file may be a security risk.
.Ef
Only use this option if you are certain that you know what you are doing.
.El
.It Fl r Ar value
Set the work parameter r to
.Ar value .
If
.Fl r
is set,
.Fl -logN
and
.Fl p
must also be set.
If such explicit parameters are given, the resource limits set by
.Fl M ,
.Fl m ,
and
.Fl t
are not enforced.
.It Fl t Ar maxtime
Use at most
.Ar maxtime
seconds of CPU time to compute the derived encryption key.
.It Fl v
Print encryption parameters (N, r, p) and memory/cpu limits.
.It Fl -version
Print version of scrypt, and exit.
.El
.Pp
In
.Nm Cm enc ,
the memory and CPU time limits are enforced by picking
appropriate parameters to the
.Nm
key derivation function.
In
.Nm Cm dec ,
the memory and CPU time limits are enforced by exiting with
an error if decrypting the file would require too much memory
or CPU time.
.Sh EXIT STATUS
The
.Nm
utility exits 0 on success, and >0 if an error occurs.
.Pp
Note that if the input encrypted file is corrupted,
.Nm Cm dec
may produce output prior to determining that the input
was corrupt and exiting with a non-zero status; so
users should direct the output to a safe location and
check the exit status of
.Nm
before using the decrypted data.
.Sh ALGORITHM PARAMETERS
The scrypt algorithm has three tuneable work parameters: N, r, p.
When decrypting, scrypt will always use the values specified by
the encryption header.
When encrypting, scrypt will choose appropriate values based on your system's
speed and memory (influenced by
.Fl M ,
.Fl m ,
and/or
.Fl t ) ,
unless you specify explicit parameters via
.Fl -logN ,
.Fl p ,
.Fl r .
.Sh SEE ALSO
.Rs
.%A "Colin Percival"
.%T "Stronger Key Derivation via Sequential Memory-Hard Functions"
.%R "BSDCan'09"
.%D "May 2009"
.Re
.Rs
.%A "Colin Percival"
.%A "Simon Josefsson"
.%T "The scrypt Password-Based Key Derivation Function"
.%R "IETF RFC 7914"
.%D "August 2016"
.Re
.Sh HISTORY
The
.Nm
utility was written in May 2009 by Colin Percival as a
demonstration of the
.Nm
key derivation function.
The
.Nm
key derivation function was invented in March 2009 by Colin
Percival in order to allow key files from the
.Nm Tarsnap
backup system to be passphrase protected.