xref: /dragonfly/lib/libc/rpc/des_crypt.3 (revision 333227be) 
1.\" @(#)des_crypt.3	2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI;
2.\" $FreeBSD: src/lib/libc/rpc/des_crypt.3,v 1.4.2.3 2001/12/14 18:33:56 ru Exp $
3.\" $DragonFly: src/lib/libc/rpc/des_crypt.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
4.\"
5.Dd October 6, 1987
6.Dt DES_CRYPT 3
7.Os
8.Sh NAME
9.Nm des_crypt , ecb_crypt , cbc_crypt , des_setparity
10.Nd "fast DES encryption"
11.Sh LIBRARY
12.Lb libc
13.Sh SYNOPSIS
14.In rpc/des_crypt.h
15.Ft int
16.Fn ecb_crypt "char *key" "char *data" "unsigned datalen" "unsigned mode"
17.Ft int
18.Fn cbc_crypt "char *key" "char *data" "unsigned datalen" "unsigned mode" "char *ivec"
19.Ft void
20.Fn des_setparity "char *key"
21.Sh DESCRIPTION
22.Fn ecb_crypt
23and
24.Fn cbc_crypt
25implement the
26.Tn NBS
27.Tn DES
28(Data Encryption Standard).
29These routines are faster and more general purpose than
30.Xr crypt 3 .
31They also are able to utilize
32.Tn DES
33hardware if it is available.
34.Fn ecb_crypt
35encrypts in
36.Tn ECB
37(Electronic Code Book)
38mode, which encrypts blocks of data independently.
39.Fn cbc_crypt
40encrypts in
41.Tn CBC
42(Cipher Block Chaining)
43mode, which chains together
44successive blocks.
45.Tn CBC
46mode protects against insertions, deletions and
47substitutions of blocks.
48Also, regularities in the clear text will
49not appear in the cipher text.
50.Pp
51Here is how to use these routines.
52The first parameter,
53.Fa key ,
54is the 8-byte encryption key with parity.
55To set the key's parity, which for
56.Tn DES
57is in the low bit of each byte, use
58.Fn des_setparity .
59The second parameter,
60.Fa data ,
61contains the data to be encrypted or decrypted.
62The
63third parameter,
64.Fa datalen ,
65is the length in bytes of
66.Fa data ,
67which must be a multiple of 8.
68The fourth parameter,
69.Fa mode ,
70is formed by
71.Em OR Ns 'ing
72together some things.
73For the encryption direction
74.Em OR
75in either
76.Dv DES_ENCRYPT
77or
78.Dv DES_DECRYPT .
79For software versus hardware
80encryption,
81.Em OR
82in either
83.Dv DES_HW
84or
85.Dv DES_SW .
86If
87.Dv DES_HW
88is specified, and there is no hardware, then the encryption is performed
89in software and the routine returns
90.Er DESERR_NOHWDEVICE .
91For
92.Fn cbc_crypt ,
93the parameter
94.Fa ivec
95is the 8-byte initialization
96vector for the chaining.
97It is updated to the next initialization
98vector upon return.
99.Sh ERRORS
100.Bl -tag -width [DESERR_NOHWDEVICE] -compact
101.It Bq Er DESERR_NONE
102No error.
103.It Bq Er DESERR_NOHWDEVICE
104Encryption succeeded, but done in software instead of the requested hardware.
105.It Bq Er DESERR_HWERR
106An error occurred in the hardware or driver.
107.It Bq Er DESERR_BADPARAM
108Bad parameter to routine.
109.El
110.Pp
111Given a result status
112.Va stat ,
113the macro
114.Fn DES_FAILED stat
115is false only for the first two statuses.
116.Sh SEE ALSO
117.\" .Xr des 1 ,
118.Xr crypt 3
119.Sh RESTRICTIONS
120These routines are not available in RPCSRC 4.0.
121This information is provided to describe the
122.Tn DES
123interface expected by
124Secure RPC.
125