Add Copyright and license.

Mention AES, Chacha20, ECDSA, OCSP, OPENSSL_config.
Improve many cross references.
Convert the table into some real text and polish some wording.

Stop talking about SSL.
Drop vague references to undocumented internals (objects, stack, txt_db).
Delete verbiage that says nothing or is duplicate.

Ultimately, the content of this page should be merged into
OPENSSL_init_crypto(3), but we don't have that function yet,
so the merge has to wait.

1 files changed, 107 insertions, 41 deletions

diff --git a/lib/libcrypto/man/crypto.3 b/lib/libcrypto/man/crypto.3
index a60b682a631..ea98bce36e6 100644
--- a/lib/libcrypto/man/crypto.3
+++ b/lib/libcrypto/man/crypto.3
@@ -1,4 +1,53 @@
-.\"	$OpenBSD: crypto.3,v 1.7 2016/12/06 12:24:33 schwarze Exp $
+.\"	$OpenBSD: crypto.3,v 1.8 2016/12/06 14:29:51 schwarze Exp $
+.\"	OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100
+.\"
+.\" This file was written by Ulf Moeller <ulf@openssl.org> and
+.\" Dr. Stephen Henson <steve@openssl.org>.
+.\" Copyright (c) 2000, 2002 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
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
 .Dd $Mdocdate: December 6 2016 $
 .Dt CRYPTO 3
@@ -10,65 +59,82 @@
 The OpenSSL crypto library implements a wide range of cryptographic
 algorithms used in various Internet standards.
 The services provided by this library are used by the OpenSSL
-implementations of SSL, TLS and S/MIME, and they have also been used to
+implementations of TLS and S/MIME, and they have also been used to
 implement SSH, OpenPGP, and other cryptographic standards.
 .Pp
-.Sy libcrypto
-consists of a number of sub-libraries that implement the individual
-algorithms.
+.Sy Symmetric ciphers
+including AES, Blowfish, CAST, Chacha20, IDEA, DES, RC2, RC4, and
+RC5 are provided by the generic interface
+.Xr EVP_EncryptInit 3 .
+Low-level stand-alone interfaces include
+.Xr BF_set_key 3 ,
+.Xr DES_set_key 3 ,
+and
+.Xr RC4 3 .
 .Pp
-The functionality includes symmetric encryption, public key cryptography
-and key agreement, certificate handling, cryptographic hash functions
-and a cryptographic pseudo-random number generator.
-.Bl -tag -width Ds -offset indent
-.It SYMMETRIC CIPHERS
-.Xr blowfish 3 ,
-CAST, DES, IDEA, RC2,
-.Xr RC4 3 ,
-RC5, see
-.Xr EVP_EncryptInit 3
-.It PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT
-.Xr dsa 3 ,
+.Sy Public key cryptography and key agreement
+are provided by
 .Xr dh 3 ,
-.Xr rsa 3
-.It CERTIFICATES
-.Xr x509 3 ,
-x509v3
-.It AUTHENTICATION CODES, HASH FUNCTIONS
+.Xr dsa 3 ,
+.Xr ECDSA_SIG_new 3 ,
+and
+.Xr rsa 3 .
+.Pp
+.Sy Certificates
+are handled by
+.Xr x509 3
+and
+.Xr X509v3_add_ext 3 .
+.Pp
+.Sy Authentication codes and hash functions
+offered inlude
 .Xr HMAC 3 ,
 .Xr MD2 3 ,
 .Xr MD4 3 ,
 .Xr MD5 3 ,
 .Xr RIPEMD160 3 ,
-.Xr sha1 3 ,
-.Xr sha2 3
-.It AUXILIARY FUNCTIONS
-.Xr ERR 3 ,
-.Xr threads 3 ,
-.Xr RAND_bytes 3 ,
-.Xr OPENSSL_VERSION_NUMBER 3
-.It INPUT/OUTPUT, DATA ENCODING
-asn1,
+.Xr SHA1 3 ,
+and
+.Xr SHA256 3 .
+.Pp
+.Sy Input, output, and data encoding
+facilities include ASN.1,
 .Xr BIO_new 3 ,
 .Xr evp 3 ,
-PEM,
-pkcs7,
-pkcs12
-.It INTERNAL FUNCTIONS
+.Xr PEM_read 3 ,
+.Xr PKCS7_encrypt 3 ,
+.Xr PKCS7_sign 3 ,
+.Xr PKCS12_create 3 ,
+and
+.Xr SMIME_write_PKCS7 3 .
+.Pp
+.Sy Auxiliary features include:
+.Bl -dash -compact
+.It
+configuration file handling, see
+.Xr OPENSSL_config 3
+.It
+error reporting, see
+.Xr ERR 3
+.It
+thread support, see
+.Xr CRYPTO_set_locking_callback 3
+.It
+.Xr OCSP_REQUEST_new 3
+.El
+.Pp
+.Sy Internal utilities
+include
 .Xr bn 3 ,
 .Xr BIO_f_buffer 3 ,
 .Xr ec 3 ,
-.Xr lh_new 3 ,
-objects,
-stack,
-txt_db
-.El
+.Xr lh_new 3 .
 .Pp
 Some of the newer functions follow a naming convention using the numbers
 .Sq 0
 and
 .Sq 1 .
-For example the functions:
+For example consider the names of these functions:
 .Pp
 .Ft int
 .Fo X509_CRL_add0_revoked