openssl: Adjust manual pages for 1.0.1l.
[dragonfly.git] / secure / lib / libcipher / cipher.3
1 .\" FreeSec: libcrypt for NetBSD
2 .\"
3 .\" Copyright (c) 1994 David Burren
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\" 4. Neither the name of the author nor the names of other contributors
15 .\"    may be used to endorse or promote products derived from this software
16 .\"    without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" $FreeBSD: src/secure/lib/libcipher/cipher.3,v 1.6.2.3 2001/12/14 15:21:13 ru Exp $
31 .\" $DragonFly: src/secure/lib/libcipher/cipher.3,v 1.2 2003/06/17 04:27:48 dillon Exp $
32 .\"
33 .\" Manual page, using -mandoc macros
34 .\"
35 .Dd March 9, 1994
36 .Dt CIPHER 3
37 .Os
38 .Sh NAME
39 .Nm setkey ,
40 .Nm encrypt ,
41 .Nm des_setkey ,
42 .Nm des_cipher
43 .Nd DES encryption
44 .Sh LIBRARY
45 .Lb libcipher
46 .Sh SYNOPSIS
47 .In unistd.h
48 .Ft int
49 .Fn setkey "const char *key"
50 .Ft int
51 .Fn encrypt "char *block" "int flag"
52 .Ft int
53 .Fn des_setkey "const char *key"
54 .Ft int
55 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
56 .Sh DESCRIPTION
57 The functions,
58 .Fn encrypt ,
59 .Fn setkey ,
60 .Fn des_setkey
61 and
62 .Fn des_cipher
63 provide access to the
64 .Tn DES
65 algorithm.
66 .Fn setkey
67 is passed a 64-byte array of binary values (numeric 0 or 1).
68 A 56-bit key is extracted from this array by dividing the
69 array into groups of 8, and ignoring the last bit in each group.
70 That bit is reserved for a byte parity check by DES, but is ignored
71 by these functions.
72 .Pp
73 The
74 .Fa block
75 argument to
76 .Fn encrypt
77 is also a 64-byte array of binary values.
78 If the value of
79 .Fa flag
80 is 0,
81 .Fa block
82 is encrypted otherwise it is decrypted.
83 The result is returned in the original array
84 .Fa block
85 after using the key specified by
86 .Fn setkey
87 to process it.
88 .Pp
89 The argument to
90 .Fn des_setkey
91 is a character array of length 8.
92 The least significant bit (the parity bit) in each character is ignored,
93 and the remaining bits are concatenated to form a 56-bit key.
94 The function
95 .Fn des_cipher
96 encrypts (or decrypts if
97 .Fa count
98 is negative) the 64-bits stored in the 8 characters at
99 .Fa in
100 using
101 .Xr abs 3
102 of
103 .Fa count
104 iterations of
105 .Tn DES
106 and stores the 64-bit result in the 8 characters at
107 .Fa out
108 (which may be the same as
109 .Fa in ) .
110 The
111 .Fa salt
112 introduces disorder in the
113 .Tn DES
114 algorithm in one of 16777216 or 4096 possible ways
115 (ie. with 24 or 12 bits: if bit
116 .Em i
117 of the
118 .Ar salt
119 is set, then bits
120 .Em i
121 and
122 .Em i+24
123 are swapped in the
124 .Tn DES
125 E-box output).
126 .Pp
127 The functions
128 .Fn setkey ,
129 .Fn encrypt ,
130 .Fn des_setkey ,
131 and
132 .Fn des_cipher
133 return 0 on success and 1 on failure.
134 .Pp
135 The
136 .Fn setkey
137 and
138 .Fn des_setkey
139 functions manipulate the same key space.
140 .Sh SEE ALSO
141 .Xr login 1 ,
142 .Xr passwd 1 ,
143 .Xr crypt 3 ,
144 .Xr getpass 3 ,
145 .Xr passwd 5
146 .Sh HISTORY
147 This library (FreeSec 1.0) was developed outside the United States of America
148 as an unencumbered replacement for the U.S.-only
149 .Nx
150 libcrypt encryption
151 library.
152 Users should be aware that this code (and programs staticly linked with it)
153 may not be exported from the U.S., although it apparently can be imported.
154 .Sh AUTHORS
155 .An David Burren Aq davidb@werj.com.au