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