From: schwarze <schwarze@openbsd.org>
Date: Tue, 13 Feb 2018 20:54:10 +0000 (+0000)
Subject: Add the missing RETURN VALUES section, mostly from Paul Yang
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=f4cb687abfa527e28073a2dd496eaa3f5e2d42c2;p=openbsd

Add the missing RETURN VALUES section, mostly from Paul Yang
via OpenSSL commit 1f13ad31 Dec 25 17:50:39 2017 +0800,
but fixing two bugs in his description.

This commit also includes a few minor improvements to the description
of DES_fcrypt(3), also from OpenSSL, tweaked by me.
---

diff --git a/lib/libcrypto/man/DES_set_key.3 b/lib/libcrypto/man/DES_set_key.3
index 0a9e7381bce..9e0236c698d 100644
--- a/lib/libcrypto/man/DES_set_key.3
+++ b/lib/libcrypto/man/DES_set_key.3
@@ -1,12 +1,13 @@
-.\"	$OpenBSD: DES_set_key.3,v 1.7 2017/02/09 03:43:05 dtucker Exp $
-.\"	OpenSSL c7497f34 Aug 14 10:50:26 2014 -0400
+.\" $OpenBSD: DES_set_key.3,v 1.8 2018/02/13 20:54:10 schwarze Exp $
+.\" full merge up to:
+.\" OpenSSL man3/DES_random_key 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
 .\" --------------------------------------------------------------------------
 .\" Major patches to this file were contributed by
 .\" Ulf Moeller <ulf@openssl.org>, Ben Laurie <ben@openssl.org>,
 .\" and Richard Levitte <levitte@openssl.org>.
 .\" --------------------------------------------------------------------------
-.\" Copyright (c) 2000, 2001 The OpenSSL Project.  All rights reserved.
+.\" Copyright (c) 2000, 2001, 2017 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -114,7 +115,7 @@
 .\" copied and put under another distribution licence
 .\" [including the GNU Public Licence.]
 .\"
-.Dd $Mdocdate: February 9 2017 $
+.Dd $Mdocdate: February 13 2018 $
 .Dt DES_SET_KEY 3
 .Os
 .Sh NAME
@@ -456,9 +457,6 @@ sets the parity of the passed
 .Fa key
 to odd.
 .Pp
-.Fn DES_is_weak_key
-returns 1 if the passed key is a weak key or 0 if it is ok.
-.Pp
 The following routines mostly operate on an input and output stream of
 .Vt DES_cblock Ns s .
 .Pp
@@ -666,12 +664,16 @@ The following are DES-based transformations:
 is a fast version of the Unix
 .Xr crypt 3
 function.
+The
+.Fa salt
+must be two ASCII characters.
+This version is different from the normal crypt in that the third
+parameter is the buffer that the return value is written into.
+It needs to be at least 14 bytes long.
+The fourteenth byte is set to NUL.
 This version takes only a small amount of space relative to other
 fast crypt implementations.
-This is different to the normal crypt in that the third parameter is the
-buffer that the return value is written into.
-It needs to be at least 14 bytes long.
-This function is thread safe, unlike the normal crypt.
+It is thread safe, unlike the normal crypt.
 .Pp
 .Fn DES_crypt
 is a faster replacement for the normal system
@@ -746,6 +748,31 @@ If set to
 If set to
 .Dv DES_CBC_MODE
 DES_cbc_encrypt is used.
+.Sh RETURN VALUES
+.Fn DES_set_key ,
+.Fn DES_key_sched ,
+and
+.Fn DES_set_key_checked
+return 0 on success or a negative value on error.
+.Pp
+.Fn DES_is_weak_key
+returns 1 if the passed key is a weak key or 0 if it is ok.
+.Pp
+.Fn DES_cbc_cksum
+and
+.Fn DES_quad_cksum
+return a 4-byte integer representing the last 4 bytes of the checksum
+of the input.
+.Pp
+.Fn DES_fcrypt
+returns a pointer to the caller-provided buffer
+.Fa ret ,
+and
+.Fn DES_crypt
+returns a pointer to a static buffer.
+Both are allowed to return
+.Dv NULL
+to indicate failure, but currently, they cannot fail.
 .Sh SEE ALSO
 .Xr crypt 3 ,
 .Xr RAND_bytes 3