[authen-passphrase-scrypt.git] / scrypt-1.2.1 / scrypt.1

.\" 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 February 10, 2017
.Dt SCRYPT 1
.Os
.Sh NAME
.Nm scrypt
.Nd encrypt and decrypt files.
.Sh SYNOPSIS
.Nm
.Brq Cm enc | Cm dec
.Op Fl f
.Op Fl M Ar maxmem
.Op Fl m Ar maxmemfrac
.Op Fl t Ar maxtime
.Op Fl P
.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
If
.Fl P
is not given,
.Nm
reads passphrases from its controlling terminal, or failing that,
from stdin.  Prompts are only printed when
.Nm
is reading passphrases from some terminal.  If
.Fl P
is given, then
.Nm
does not print any prompts, and reads a passphrase from stdin.
.Sh OPTIONS
.Bl -tag -width "-m maxmemfrac"
.It Fl f
Force the decryption to proceed even if it is anticipated to
require an excessive amount of memory or CPU time.
.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.
.It Fl t Ar maxtime
Use at most
.Ar maxtime
seconds of CPU time to compute the derived encryption key.
.It Fl P
Always read passphrase from stdin, and do so only once even
when encrypting.
.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 SEE ALSO
.Rs
.%A "Colin Percival"
.%T "Stronger Key Derivation via Sequential Memory-Hard Functions"
.%O "Presented at BSDCan'09"
.%D "May 2009"
.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.
Commit	Line	Data
0c1f3509 MG	1	.\" Copyright 2009 Colin Percival
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.Dd February 10, 2017
	25	.Dt SCRYPT 1
	26	.Os
	27	.Sh NAME
	28	.Nm scrypt
	29	.Nd encrypt and decrypt files.
	30	.Sh SYNOPSIS
	31	.Nm
	32	.Brq Cm enc \| Cm dec
	33	.Op Fl f
	34	.Op Fl M Ar maxmem
	35	.Op Fl m Ar maxmemfrac
	36	.Op Fl t Ar maxtime
	37	.Op Fl P
	38	.Ar infile
	39	.Op Ar outfile
	40	.Nm
	41	.Fl -version
	42	.Sh DESCRIPTION
	43	.Nm Cm enc
	44	encrypts
	45	.Ar infile
	46	and writes the result to
	47	.Ar outfile
	48	if specified, or the standard output otherwise.
	49	The user will be prompted to enter a passphrase (twice) to
	50	be used to generate a derived encryption key.
	51	.Pp
	52	.Nm Cm dec
	53	decrypts
	54	.Ar infile
	55	and writes the result to
	56	.Ar outfile
	57	if specified, or the standard output otherwise.
	58	The user will be prompted to enter the passphrase used at
	59	encryption time to generate the derived encryption key.
	60	.Pp
	61	If
	62	.Fl P
	63	is not given,
	64	.Nm
65	reads passphrases from its controlling terminal, or failing that,
66	from stdin. Prompts are only printed when
67	.Nm
68	is reading passphrases from some terminal. If
69	.Fl P
70	is given, then
71	.Nm
72	does not print any prompts, and reads a passphrase from stdin.
73	.Sh OPTIONS
74	.Bl -tag -width "-m maxmemfrac"
75	.It Fl f
76	Force the decryption to proceed even if it is anticipated to
77	require an excessive amount of memory or CPU time.
78	.It Fl M Ar maxmem
79	Use at most
80	.Ar maxmem
81	bytes of RAM to compute the derived encryption key.
82	.It Fl m Ar maxmemfrac
83	Use at most the fraction
84	.Ar maxmemfrac
85	of the available RAM to compute the derived encryption key.
86	.It Fl t Ar maxtime
87	Use at most
88	.Ar maxtime
89	seconds of CPU time to compute the derived encryption key.
90	.It Fl P
91	Always read passphrase from stdin, and do so only once even
92	when encrypting.
93	.It Fl -version
94	Print version of scrypt, and exit.
95	.El
96	.Pp
97	In
98	.Nm Cm enc ,
99	the memory and CPU time limits are enforced by picking
100	appropriate parameters to the
101	.Nm
102	key derivation function.
103	In
104	.Nm Cm dec ,
105	the memory and CPU time limits are enforced by exiting with
106	an error if decrypting the file would require too much memory
107	or CPU time.
108	.Sh EXIT STATUS
109	The
110	.Nm
111	utility exits 0 on success, and >0 if an error occurs.
112	.Pp
113	Note that if the input encrypted file is corrupted,
114	.Nm Cm dec
115	may produce output prior to determining that the input
116	was corrupt and exiting with a non-zero status; so
117	users should direct the output to a safe location and
118	check the exit status of
119	.Nm
120	before using the decrypted data.
121	.Sh SEE ALSO
122	.Rs
123	.%A "Colin Percival"
124	.%T "Stronger Key Derivation via Sequential Memory-Hard Functions"
125	.%O "Presented at BSDCan'09"
126	.%D "May 2009"
127	.Re
128	.Sh HISTORY
129	The
130	.Nm
131	utility was written in May 2009 by Colin Percival as a
132	demonstration of the
133	.Nm
134	key derivation function.
135	The
136	.Nm
137	key derivation function was invented in March 2009 by Colin
138	Percival in order to allow key files from the
139	.Nm tarsnap
140	backup system to be passphrase protected.