1 .\" $OpenBSD: DES_set_key.3,v 1.11 2018/03/22 21:08:22 schwarze Exp $
3 .\" OpenSSL man3/DES_random_key 61f805c1 Jan 16 01:01:46 2018 +0800
5 .\" --------------------------------------------------------------------------
6 .\" Major patches to this file were contributed by
7 .\" Ulf Moeller <ulf@openssl.org>, Ben Laurie <ben@openssl.org>,
8 .\" and Richard Levitte <levitte@openssl.org>.
9 .\" --------------------------------------------------------------------------
10 .\" Copyright (c) 2000, 2001, 2017 The OpenSSL Project. All rights reserved.
12 .\" Redistribution and use in source and binary forms, with or without
13 .\" modification, are permitted provided that the following conditions
16 .\" 1. Redistributions of source code must retain the above copyright
17 .\" notice, this list of conditions and the following disclaimer.
19 .\" 2. Redistributions in binary form must reproduce the above copyright
20 .\" notice, this list of conditions and the following disclaimer in
21 .\" the documentation and/or other materials provided with the
24 .\" 3. All advertising materials mentioning features or use of this
25 .\" software must display the following acknowledgment:
26 .\" "This product includes software developed by the OpenSSL Project
27 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
29 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
30 .\" endorse or promote products derived from this software without
31 .\" prior written permission. For written permission, please contact
32 .\" openssl-core@openssl.org.
34 .\" 5. Products derived from this software may not be called "OpenSSL"
35 .\" nor may "OpenSSL" appear in their names without prior written
36 .\" permission of the OpenSSL Project.
38 .\" 6. Redistributions of any form whatsoever must retain the following
40 .\" "This product includes software developed by the OpenSSL Project
41 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
43 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
44 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
45 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
46 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
47 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
48 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
49 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
50 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
51 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
52 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
53 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
54 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
56 .\" --------------------------------------------------------------------------
57 .\" Parts of this file are derived from SSLeay documentation,
58 .\" which is covered by the following Copyright and license:
59 .\" --------------------------------------------------------------------------
61 .\" Copyright (C) 1995-1998 Tim Hudson (tjh@cryptsoft.com)
62 .\" All rights reserved.
64 .\" This package is an SSL implementation written
65 .\" by Eric Young (eay@cryptsoft.com).
66 .\" The implementation was written so as to conform with Netscapes SSL.
68 .\" This library is free for commercial and non-commercial use as long as
69 .\" the following conditions are aheared to. The following conditions
70 .\" apply to all code found in this distribution, be it the RC4, RSA,
71 .\" lhash, DES, etc., code; not just the SSL code. The SSL documentation
72 .\" included with this distribution is covered by the same copyright terms
73 .\" except that the holder is Tim Hudson (tjh@cryptsoft.com).
75 .\" Copyright remains Eric Young's, and as such any Copyright notices in
76 .\" the code are not to be removed.
77 .\" If this package is used in a product, Eric Young should be given
78 .\" attribution as the author of the parts of the library used.
79 .\" This can be in the form of a textual message at program startup or
80 .\" in documentation (online or textual) provided with the package.
82 .\" Redistribution and use in source and binary forms, with or without
83 .\" modification, are permitted provided that the following conditions
85 .\" 1. Redistributions of source code must retain the copyright
86 .\" notice, this list of conditions and the following disclaimer.
87 .\" 2. Redistributions in binary form must reproduce the above copyright
88 .\" notice, this list of conditions and the following disclaimer in the
89 .\" documentation and/or other materials provided with the distribution.
90 .\" 3. All advertising materials mentioning features or use of this software
91 .\" must display the following acknowledgement:
92 .\" "This product includes cryptographic software written by
93 .\" Eric Young (eay@cryptsoft.com)"
94 .\" The word 'cryptographic' can be left out if the rouines from the
95 .\" library being used are not cryptographic related :-).
96 .\" 4. If you include any Windows specific code (or a derivative thereof)
97 .\" from the apps directory (application code) you must include an
98 .\" acknowledgement: "This product includes software written by
99 .\" Tim Hudson (tjh@cryptsoft.com)"
101 .\" THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
102 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
103 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
104 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
105 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
106 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
107 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
108 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
109 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
110 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
113 .\" The licence and distribution terms for any publically available version or
114 .\" derivative of this code cannot be changed. i.e. this code cannot simply be
115 .\" copied and put under another distribution licence
116 .\" [including the GNU Public Licence.]
118 .Dd $Mdocdate: March 22 2018 $
125 .Nm DES_set_key_checked ,
126 .Nm DES_set_key_unchecked ,
127 .Nm DES_set_odd_parity ,
128 .Nm DES_is_weak_key ,
129 .Nm DES_ecb_encrypt ,
130 .Nm DES_ecb2_encrypt ,
131 .Nm DES_ecb3_encrypt ,
132 .Nm DES_ncbc_encrypt ,
133 .Nm DES_cfb_encrypt ,
134 .Nm DES_ofb_encrypt ,
135 .Nm DES_pcbc_encrypt ,
136 .Nm DES_cfb64_encrypt ,
137 .Nm DES_ofb64_encrypt ,
138 .Nm DES_xcbc_encrypt ,
139 .Nm DES_ede2_cbc_encrypt ,
140 .Nm DES_ede2_cfb64_encrypt ,
141 .Nm DES_ede2_ofb64_encrypt ,
142 .Nm DES_ede3_cbc_encrypt ,
143 .Nm DES_ede3_cbcm_encrypt ,
144 .Nm DES_ede3_cfb64_encrypt ,
145 .Nm DES_ede3_ofb64_encrypt ,
148 .Nm DES_string_to_key ,
149 .Nm DES_string_to_2keys ,
159 .Fa "DES_cblock *ret"
163 .Fa "const_DES_cblock *key"
164 .Fa "DES_key_schedule *schedule"
168 .Fa "const_DES_cblock *key"
169 .Fa "DES_key_schedule *schedule"
172 .Fo DES_set_key_checked
173 .Fa "const_DES_cblock *key"
174 .Fa "DES_key_schedule *schedule"
177 .Fo DES_set_key_unchecked
178 .Fa "const_DES_cblock *key"
179 .Fa "DES_key_schedule *schedule"
182 .Fo DES_set_odd_parity
183 .Fa "DES_cblock *key"
187 .Fa "const_DES_cblock *key"
191 .Fa "const_DES_cblock *input"
192 .Fa "DES_cblock *output"
193 .Fa "DES_key_schedule *ks"
198 .Fa "const_DES_cblock *input"
199 .Fa "DES_cblock *output"
200 .Fa "DES_key_schedule *ks1"
201 .Fa "DES_key_schedule *ks2"
206 .Fa "const_DES_cblock *input"
207 .Fa "DES_cblock *output"
208 .Fa "DES_key_schedule *ks1"
209 .Fa "DES_key_schedule *ks2"
210 .Fa "DES_key_schedule *ks3"
215 .Fa "const unsigned char *input"
216 .Fa "unsigned char *output"
218 .Fa "DES_key_schedule *schedule"
219 .Fa "DES_cblock *ivec"
224 .Fa "const unsigned char *in"
225 .Fa "unsigned char *out"
228 .Fa "DES_key_schedule *schedule"
229 .Fa "DES_cblock *ivec"
234 .Fa "const unsigned char *in"
235 .Fa "unsigned char *out"
238 .Fa "DES_key_schedule *schedule"
239 .Fa "DES_cblock *ivec"
243 .Fa "const unsigned char *input"
244 .Fa "unsigned char *output"
246 .Fa "DES_key_schedule *schedule"
247 .Fa "DES_cblock *ivec"
251 .Fo DES_cfb64_encrypt
252 .Fa "const unsigned char *in"
253 .Fa "unsigned char *out"
255 .Fa "DES_key_schedule *schedule"
256 .Fa "DES_cblock *ivec"
261 .Fo DES_ofb64_encrypt
262 .Fa "const unsigned char *in"
263 .Fa "unsigned char *out"
265 .Fa "DES_key_schedule *schedule"
266 .Fa "DES_cblock *ivec"
271 .Fa "const unsigned char *input"
272 .Fa "unsigned char *output"
274 .Fa "DES_key_schedule *schedule"
275 .Fa "DES_cblock *ivec"
276 .Fa "const_DES_cblock *inw"
277 .Fa "const_DES_cblock *outw"
281 .Fo DES_ede2_cbc_encrypt
282 .Fa "const unsigned char *input"
283 .Fa "unsigned char *output"
285 .Fa "DES_key_schedule *ks1"
286 .Fa "DES_key_schedule *ks2"
287 .Fa "DES_cblock *ivec"
291 .Fo DES_ede2_cfb64_encrypt
292 .Fa "const unsigned char *in"
293 .Fa "unsigned char *out"
295 .Fa "DES_key_schedule *ks1"
296 .Fa "DES_key_schedule *ks2"
297 .Fa "DES_cblock *ivec"
302 .Fo DES_ede2_ofb64_encrypt
303 .Fa "const unsigned char *in"
304 .Fa "unsigned char *out"
306 .Fa "DES_key_schedule *ks1"
307 .Fa "DES_key_schedule *ks2"
308 .Fa "DES_cblock *ivec"
312 .Fo DES_ede3_cbc_encrypt
313 .Fa "const unsigned char *input"
314 .Fa "unsigned char *output"
316 .Fa "DES_key_schedule *ks1"
317 .Fa "DES_key_schedule *ks2"
318 .Fa "DES_key_schedule *ks3"
319 .Fa "DES_cblock *ivec"
323 .Fo DES_ede3_cbcm_encrypt
324 .Fa "const unsigned char *in"
325 .Fa "unsigned char *out"
327 .Fa "DES_key_schedule *ks1"
328 .Fa "DES_key_schedule *ks2"
329 .Fa "DES_key_schedule *ks3"
330 .Fa "DES_cblock *ivec1"
331 .Fa "DES_cblock *ivec2"
335 .Fo DES_ede3_cfb64_encrypt
336 .Fa "const unsigned char *in"
337 .Fa "unsigned char *out"
339 .Fa "DES_key_schedule *ks1"
340 .Fa "DES_key_schedule *ks2"
341 .Fa "DES_key_schedule *ks3"
342 .Fa "DES_cblock *ivec"
347 .Fo DES_ede3_ofb64_encrypt
348 .Fa "const unsigned char *in"
349 .Fa "unsigned char *out"
351 .Fa "DES_key_schedule *ks1"
352 .Fa "DES_key_schedule *ks2"
353 .Fa "DES_key_schedule *ks3"
354 .Fa "DES_cblock *ivec"
359 .Fa "const unsigned char *input"
360 .Fa "DES_cblock *output"
362 .Fa "DES_key_schedule *schedule"
363 .Fa "const_DES_cblock *ivec"
367 .Fa "const unsigned char *input"
368 .Fa "DES_cblock output[]"
371 .Fa "DES_cblock *seed"
374 .Fo DES_string_to_key
375 .Fa "const char *str"
376 .Fa "DES_cblock *key"
379 .Fo DES_string_to_2keys
380 .Fa "const char *str"
381 .Fa "DES_cblock *key1"
382 .Fa "DES_cblock *key2"
386 .Fa "const char *buf"
387 .Fa "const char *salt"
392 .Fa "const char *buf"
393 .Fa "const char *salt"
400 .Fa "DES_key_schedule *sched"
406 .Fa "const void *buf"
408 .Fa "DES_key_schedule *sched"
412 This library contains a fast implementation of the DES encryption
415 There are two phases to the use of DES encryption.
416 The first is the generation of a
418 from a key, and the second is the actual encryption.
421 This type consists of 8 bytes with odd parity.
422 The least significant bit in each byte is the parity bit.
423 The key schedule is an expanded form of the key; it is used to speed the
427 generates a random key in odd parity.
429 Before a DES key can be used, it must be converted into the architecture
433 .Fn DES_set_key_checked
435 .Fn DES_set_key_unchecked
438 .Fn DES_set_key_checked
439 will check that the key passed is of odd parity and is not a weak or
441 If the parity is wrong, then -1 is returned.
442 If the key is a weak key, then -2 is returned.
443 If an error is returned, the key schedule is not generated.
447 .Fn DES_set_key_checked
450 flag is non-zero, otherwise like
451 .Fn DES_set_key_unchecked .
452 These functions are available for compatibility; it is recommended to
453 use a function that does not depend on a global variable.
455 .Fn DES_set_odd_parity
456 sets the parity of the passed
460 The following routines mostly operate on an input and output stream of
461 .Vt DES_cblock Ns s .
464 is the basic DES encryption routine that encrypts or decrypts a single
467 in electronic code book (ECB) mode.
468 It always transforms the input data, pointed to by
470 into the output data, pointed to by the
479 (cleartext) is encrypted into the
481 (ciphertext) using the key_schedule specified by the
483 argument, previously set via
491 (now ciphertext) is decrypted into the
494 Input and output may overlap.
496 does not return a value.
499 encrypts/decrypts the
501 block by using three-key Triple-DES encryption in ECB mode.
502 This involves encrypting the input with
504 decrypting with the key schedule
506 and then encrypting with
508 This routine greatly reduces the chances of brute force breaking of DES
509 and has the advantage of if
514 are the same, it is equivalent to just encryption using ECB mode and
520 is provided to perform two-key Triple-DES encryption by using
522 for the final encryption.
525 encrypts/decrypts using the cipher-block-chaining (CBC) mode of DES.
528 argument is non-zero, the routine cipher-block-chain encrypts the
529 cleartext data pointed to by the
531 argument into the ciphertext pointed to by the
533 argument, using the key schedule provided by the
535 argument, and initialization vector provided by the
540 argument is not an integral multiple of eight bytes, the last block is
541 copied to a temporary area and zero filled.
542 The output is always an integral multiple of eight bytes.
545 is RSA's DESX mode of DES.
550 to "whiten" the encryption.
554 are secret (unlike the iv) and are as such, part of the key.
555 So the key is sort of 24 bytes.
556 This is much better than CBC DES.
558 .Fn DES_ede3_cbc_encrypt
559 implements outer triple CBC DES encryption with three keys.
560 This means that each DES operation inside the CBC mode is really an
561 .Qq Li C=E(ks3,D(ks2,E(ks1,M))) .
562 This mode is used by SSL.
565 .Fn DES_ede2_cbc_encrypt
566 macro implements two-key Triple-DES by reusing
568 for the final encryption.
569 .Qq Li C=E(ks1,D(ks2,E(ks1,M))) .
570 This form of Triple-DES is used by the RSAREF library.
573 encrypt/decrypts using the propagating cipher block chaining mode used
575 Its parameters are the same as
576 .Fn DES_ncbc_encrypt .
579 encrypt/decrypts using cipher feedback mode.
580 This method takes an array of characters as input and outputs an array
582 It does not require any padding to 8 character groups.
585 variable is changed and the new changed value needs to be passed to the
586 next call to this function.
587 Since this function runs a complete DES ECB encryption per
589 this function is only suggested for use when sending small numbers of
592 .Fn DES_cfb64_encrypt
593 implements CFB mode of DES with 64bit feedback.
594 Why is this useful you ask?
595 Because this routine will allow you to encrypt an arbitrary number of
596 bytes, no 8 byte padding.
597 Each call to this routine will encrypt the input bytes to output and
598 then update ivec and num.
599 num contains "how far" we are though ivec.
600 If this does not make much sense, read more about cfb mode of DES :-).
602 .Fn DES_ede3_cfb64_encrypt
604 .Fn DES_ede2_cfb64_encrypt
606 .Fn DES_cfb64_encrypt
607 except that Triple-DES is used.
610 encrypts using output feedback mode.
611 This method takes an array of characters as input and outputs an array
613 It does not require any padding to 8 character groups.
616 variable is changed and the new changed value needs to be passed to the
617 next call to this function.
618 Since this function runs a complete DES ECB encryption per numbits, this
619 function is only suggested for use when sending small numbers of
622 .Fn DES_ofb64_encrypt
624 .Fn DES_cfb64_encrypt
625 using Output Feed Back mode.
627 .Fn DES_ede3_ofb64_encrypt
629 .Fn DES_ede2_ofb64_encrypt
631 .Fn DES_ofb64_encrypt ,
634 The following functions are included in the DES library for
635 compatibility with the MIT Kerberos library.
638 produces an 8-byte checksum based on the input stream (via CBC
640 The last 4 bytes of the checksum are returned and the complete 8 bytes
643 This function is used by Kerberos v4.
644 Other applications should use
649 is a Kerberos v4 function.
650 It returns a 4-byte checksum from the input bytes.
651 The algorithm can be iterated over the input, depending on
658 the 8 bytes generated by each pass are written into
661 The following are DES-based transformations:
664 is a fast version of the Unix
669 must be two ASCII characters.
670 This version is different from the normal crypt in that the third
671 parameter is the buffer that the return value is written into.
672 It needs to be at least 14 bytes long.
673 The fourteenth byte is set to NUL.
674 This version takes only a small amount of space relative to other
675 fast crypt implementations.
676 It is thread safe, unlike the normal crypt.
679 is a faster replacement for the normal system
683 with a static array passed as the third parameter.
684 This emulates the normal non-thread safe semantics of
690 bytes to file descriptor
694 The data is encrypted via
700 as a starting vector.
701 The actual data send down
703 consists of 4 bytes (in network byte order) containing the length of the
704 following encrypted data.
705 The encrypted data then follows, padded with random data out to a
711 bytes from file descriptor
715 The data being read from
717 is assumed to have come from
719 and is decrypted using
721 for the key schedule and
723 for the initial vector.
726 The data format used by
730 has a cryptographic weakness: when asked to write more than
734 will split the data into several chunks that are all encrypted using the
736 So don't use these functions unless you are sure you know what
737 you do (in which case you might not want to use them anyway).
738 They cannot handle non-blocking sockets.
740 uses an internal state and thus cannot be used on multiple files.
743 is used to specify the encryption mode to use with
747 (the default), DES_pcbc_encrypt is used.
750 DES_cbc_encrypt is used.
755 .Fn DES_set_key_checked
756 return 0 on success or a negative value on error.
759 returns 1 if the passed key is a weak key or 0 if it is ok.
764 return a 4-byte integer representing the last 4 bytes of the checksum
768 returns a pointer to the caller-provided buffer
772 returns a pointer to a static buffer.
773 Both are allowed to return
775 to indicate failure, but currently, they cannot fail.
782 library provides higher-level encryption functions.
786 The DES library was initially written to be source code compatible
787 with the MIT Kerberos library.
793 .Fn DES_set_odd_parity ,
794 .Fn DES_is_weak_key ,
795 .Fn DES_ecb_encrypt ,
796 .Fn DES_ecb2_encrypt ,
797 .Fn DES_ecb3_encrypt ,
798 .Fn DES_ncbc_encrypt ,
799 .Fn DES_cfb_encrypt ,
800 .Fn DES_ofb_encrypt ,
801 .Fn DES_pcbc_encrypt ,
802 .Fn DES_cfb64_encrypt ,
803 .Fn DES_ofb64_encrypt ,
804 .Fn DES_xcbc_encrypt ,
805 .Fn DES_ede2_cbc_encrypt ,
806 .Fn DES_ede2_cfb64_encrypt ,
807 .Fn DES_ede2_ofb64_encrypt ,
808 .Fn DES_ede3_cbc_encrypt ,
809 .Fn DES_ede3_cfb64_encrypt ,
810 .Fn DES_ede3_ofb64_encrypt ,
813 .Fn DES_string_to_key ,
814 .Fn DES_string_to_2keys ,
820 with lower case names starting with
822 appeared in SSLeay 0.8.1b or earlier and have been available since
826 .Fn DES_set_key_checked
828 .Fn DES_set_key_unchecked
829 with lower case names starting with
831 first appeared in OpenSSL 0.9.5 and have been available since
838 functions were renamed to
840 to avoid clashes with older versions of libdes.
842 .An Eric Young Aq Mt eay@cryptsoft.com
844 Single-key DES is insecure due to its short key size.
845 ECB mode is not suitable for most applications.
847 DES_cbc_encrypt does not modify
856 operates on input of 8 bits.
857 What this means is that if you set numbits to 12, and length to 2, the
858 first 12 bits will come from the 1st input byte and the low half of the
860 The second 12 bits will have the low 8 bits taken from the 3rd input
861 byte and the top 4 bits taken from the 4th input byte.
862 The same holds for output.
863 This function has been implemented this way because most people will be
864 using a multiple of 8 and because once you get into pulling input
865 bytes apart things get ugly!
867 .Fn DES_string_to_key
868 is available for backward compatibility with the MIT library.
869 New applications should use a cryptographic hash function.
871 .Fn DES_string_to_2key .