aboutsummaryrefslogtreecommitdiff
path: root/doc/man7
diff options
context:
space:
mode:
authorJung-uk Kim <jkim@FreeBSD.org>2018-09-13 19:18:07 +0000
committerJung-uk Kim <jkim@FreeBSD.org>2018-09-13 19:18:07 +0000
commita43ce912fc025d11e1395506111f75fc194d7ba5 (patch)
tree9794cf7720d75938ed0ea4f499c0dcd4b6eacdda /doc/man7
parent02be298e504b8554caca6dc85af450e1ea44d19d (diff)
downloadsrc-a43ce912fc025d11e1395506111f75fc194d7ba5.tar.gz
src-a43ce912fc025d11e1395506111f75fc194d7ba5.zip
Import OpenSSL 1.1.1.vendor/openssl/1.1.1
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=338658 svn path=/vendor-crypto/openssl/1.1.1/; revision=338659; tag=vendor/openssl/1.1.1
Diffstat (limited to 'doc/man7')
-rw-r--r--doc/man7/Ed25519.pod87
-rw-r--r--doc/man7/RAND.pod81
-rw-r--r--doc/man7/RAND_DRBG.pod301
-rw-r--r--doc/man7/RSA-PSS.pod61
-rw-r--r--doc/man7/SM2.pod79
-rw-r--r--doc/man7/X25519.pod74
-rw-r--r--doc/man7/bio.pod87
-rw-r--r--doc/man7/crypto.pod60
-rw-r--r--doc/man7/ct.pod53
-rw-r--r--doc/man7/des_modes.pod258
-rw-r--r--doc/man7/evp.pod114
-rw-r--r--doc/man7/ossl_store-file.pod71
-rw-r--r--doc/man7/ossl_store.pod87
-rw-r--r--doc/man7/passphrase-encoding.pod180
-rw-r--r--doc/man7/scrypt.pod115
-rw-r--r--doc/man7/ssl.pod843
-rw-r--r--doc/man7/x509.pod73
17 files changed, 2624 insertions, 0 deletions
diff --git a/doc/man7/Ed25519.pod b/doc/man7/Ed25519.pod
new file mode 100644
index 000000000000..3f54217918a7
--- /dev/null
+++ b/doc/man7/Ed25519.pod
@@ -0,0 +1,87 @@
+=pod
+
+=head1 NAME
+
+Ed25519,
+Ed448
+- EVP_PKEY Ed25519 and Ed448 support
+
+=head1 DESCRIPTION
+
+The B<Ed25519> and B<Ed448> EVP_PKEY implementation supports key generation,
+one-shot digest sign and digest verify using PureEdDSA and B<Ed25519> or B<Ed448>
+(see RFC8032). It has associated private and public key formats compatible with
+draft-ietf-curdle-pkix-04.
+
+No additional parameters can be set during key generation, one-shot signing or
+verification. In particular, because PureEdDSA is used, a digest must B<NOT> be
+specified when signing or verifying.
+
+=head1 NOTES
+
+The PureEdDSA algorithm does not support the streaming mechanism
+of other signature algorithms using, for example, EVP_DigestUpdate().
+The message to sign or verify must be passed using the one-shot
+EVP_DigestSign() and EVP_DigestVerify() functions.
+
+When calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the
+digest B<type> parameter B<MUST> be set to B<NULL>.
+
+Applications wishing to sign certificates (or other structures such as
+CRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign()
+or X509_sign_ctx() in the usual way.
+
+A context for the B<Ed25519> algorithm can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
+
+For the B<Ed448> algorithm a context can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL);
+
+Ed25519 or Ed448 private keys can be set directly using
+L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
+using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
+can also be generated (see the example below). Setting a private key also sets
+the associated public key.
+
+Ed25519 or Ed448 public keys can be set directly using
+L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
+structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
+
+Ed25519 and Ed448 can be tested within L<speed(1)> application since version 1.1.1.
+Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is
+specified, then both Ed25519 and Ed448 are benchmarked.
+
+=head1 EXAMPLE
+
+This example generates an B<ED25519> private key and writes it to standard
+output in PEM format:
+
+ #include <openssl/evp.h>
+ #include <openssl/pem.h>
+ ...
+ EVP_PKEY *pkey = NULL;
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
+ EVP_PKEY_keygen_init(pctx);
+ EVP_PKEY_keygen(pctx, &pkey);
+ EVP_PKEY_CTX_free(pctx);
+ PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_keygen(3)>,
+L<EVP_DigestSignInit(3)>,
+L<EVP_DigestVerifyInit(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod
new file mode 100644
index 000000000000..971b3cdb1612
--- /dev/null
+++ b/doc/man7/RAND.pod
@@ -0,0 +1,81 @@
+=pod
+
+=head1 NAME
+
+RAND
+- the OpenSSL random generator
+
+=head1 DESCRIPTION
+
+Random numbers are a vital part of cryptography, they are needed to provide
+unpredictability for tasks like key generation, creating salts, and many more.
+Software-based generators must be seeded with external randomness before they
+can be used as a cryptographically-secure pseudo-random number generator
+(CSPRNG).
+The availability of common hardware with special instructions and
+modern operating systems, which may use items such as interrupt jitter
+and network packet timings, can be reasonable sources of seeding material.
+
+OpenSSL comes with a default implementation of the RAND API which is based on
+the deterministic random bit generator (DRBG) model as described in
+[NIST SP 800-90A Rev. 1]. The default random generator will initialize
+automatically on first use and will be fully functional without having
+to be initialized ('seeded') explicitly.
+It seeds and reseeds itself automatically using trusted random sources
+provided by the operating system.
+
+As a normal application developer, you do not have to worry about any details,
+just use L<RAND_bytes(3)> to obtain random data.
+Having said that, there is one important rule to obey: Always check the error
+return value of L<RAND_bytes(3)> and do not take randomness for granted.
+
+For values that should remain secret, you can use L<RAND_priv_bytes(3)>
+instead.
+This method does not provide 'better' randomness, it uses the same type of CSPRNG.
+The intention behind using a dedicated CSPRNG exclusively for private
+values is that none of its output should be visible to an attacker (e.g.,
+used as salt value), in order to reveal as little information as
+possible about its internal state, and that a compromise of the "public"
+CSPRNG instance will not affect the secrecy of these private values.
+
+In the rare case where the default implementation does not satisfy your special
+requirements, there are two options:
+
+=over 2
+
+=item *
+
+Replace the default RAND method by your own RAND method using
+L<RAND_set_rand_method(3)>.
+
+=item *
+
+Modify the default settings of the OpenSSL RAND method by modifying the security
+parameters of the underlying DRBG, which is described in detail in L<RAND_DRBG(7)>.
+
+=back
+
+Changing the default random generator or its default parameters should be necessary
+only in exceptional cases and is not recommended, unless you have a profound knowledge
+of cryptographic principles and understand the implications of your changes.
+
+=head1 SEE ALSO
+
+L<RAND_add(3)>,
+L<RAND_bytes(3)>,
+L<RAND_priv_bytes(3)>,
+L<RAND_get_rand_method(3)>,
+L<RAND_set_rand_method(3)>,
+L<RAND_OpenSSL(3)>,
+L<RAND_DRBG(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/RAND_DRBG.pod b/doc/man7/RAND_DRBG.pod
new file mode 100644
index 000000000000..b89c30d43edd
--- /dev/null
+++ b/doc/man7/RAND_DRBG.pod
@@ -0,0 +1,301 @@
+=pod
+
+=head1 NAME
+
+RAND_DRBG - the deterministic random bit generator
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand_drbg.h>
+
+=head1 DESCRIPTION
+
+The default OpenSSL RAND method is based on the RAND_DRBG class,
+which implements a deterministic random bit generator (DRBG).
+A DRBG is a certain type of cryptographically-secure pseudo-random
+number generator (CSPRNG), which is described in
+[NIST SP 800-90A Rev. 1].
+
+While the RAND API is the 'frontend' which is intended to be used by
+application developers for obtaining random bytes, the RAND_DRBG API
+serves as the 'backend', connecting the former with the operating
+systems's entropy sources and providing access to the DRBG's
+configuration parameters.
+
+=head2 Disclaimer
+
+Unless you have very specific requirements for your random generator,
+it is in general not necessary to utilize the RAND_DRBG API directly.
+The usual way to obtain random bytes is to use L<RAND_bytes(3)> or
+L<RAND_priv_bytes(3)>, see also L<RAND(7)>.
+
+=head2 Typical Use Cases
+
+Typical examples for such special use cases are the following:
+
+=over 2
+
+=item *
+
+You want to use your own private DRBG instances.
+Multiple DRBG instances which are accessed only by a single thread provide
+additional security (because their internal states are independent) and
+better scalability in multithreaded applications (because they don't need
+to be locked).
+
+=item *
+
+You need to integrate a previously unsupported entropy source.
+
+=item *
+
+You need to change the default settings of the standard OpenSSL RAND
+implementation to meet specific requirements.
+
+=back
+
+
+=head1 CHAINING
+
+A DRBG instance can be used as the entropy source of another DRBG instance,
+provided it has itself access to a valid entropy source.
+The DRBG instance which acts as entropy source is called the I<parent> DRBG,
+the other instance the I<child> DRBG.
+
+This is called chaining. A chained DRBG instance is created by passing
+a pointer to the parent DRBG as argument to the RAND_DRBG_new() call.
+It is possible to create chains of more than two DRBG in a row.
+
+=head1 THE THREE SHARED DRBG INSTANCES
+
+Currently, there are three shared DRBG instances,
+the <master>, <public>, and <private> DRBG.
+While the <master> DRBG is a single global instance, the <public> and <private>
+DRBG are created per thread and accessed through thread-local storage.
+
+By default, the functions L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> use
+the thread-local <public> and <private> DRBG instance, respectively.
+
+=head2 The <master> DRBG instance
+
+The <master> DRBG is not used directly by the application, only for reseeding
+the two other two DRBG instances. It reseeds itself by obtaining randomness
+either from os entropy sources or by consuming randomness which was added
+previously by L<RAND_add(3)>.
+
+=head2 The <public> DRBG instance
+
+This instance is used per default by L<RAND_bytes(3)>.
+
+=head2 The <private> DRBG instance
+
+This instance is used per default by L<RAND_priv_bytes(3)>
+
+
+=head1 LOCKING
+
+The <master> DRBG is intended to be accessed concurrently for reseeding
+by its child DRBG instances. The necessary locking is done internally.
+It is I<not> thread-safe to access the <master> DRBG directly via the
+RAND_DRBG interface.
+The <public> and <private> DRBG are thread-local, i.e. there is an
+instance of each per thread. So they can safely be accessed without
+locking via the RAND_DRBG interface.
+
+Pointers to these DRBG instances can be obtained using
+RAND_DRBG_get0_master(),
+RAND_DRBG_get0_public(), and
+RAND_DRBG_get0_private(), respectively.
+Note that it is not allowed to store a pointer to one of the thread-local
+DRBG instances in a variable or other memory location where it will be
+accessed and used by multiple threads.
+
+All other DRBG instances created by an application don't support locking,
+because they are intended to be used by a single thread.
+Instead of accessing a single DRBG instance concurrently from different
+threads, it is recommended to instantiate a separate DRBG instance per
+thread. Using the <master> DRBG as entropy source for multiple DRBG
+instances on different threads is thread-safe, because the DRBG instance
+will lock the <master> DRBG automatically for obtaining random input.
+
+=head1 THE OVERALL PICTURE
+
+The following picture gives an overview over how the DRBG instances work
+together and are being used.
+
+ +--------------------+
+ | os entropy sources |
+ +--------------------+
+ |
+ v +-----------------------------+
+ RAND_add() ==> <master> <-| shared DRBG (with locking) |
+ / \ +-----------------------------+
+ / \ +---------------------------+
+ <public> <private> <- | per-thread DRBG instances |
+ | | +---------------------------+
+ v v
+ RAND_bytes() RAND_priv_bytes()
+ | ^
+ | |
+ +------------------+ +------------------------------------+
+ | general purpose | | used for secrets like session keys |
+ | random generator | | and private keys for certificates |
+ +------------------+ +------------------------------------+
+
+
+The usual way to obtain random bytes is to call RAND_bytes(...) or
+RAND_priv_bytes(...). These calls are roughly equivalent to calling
+RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
+respectively. The method L<RAND_DRBG_bytes(3)> is a convenience method
+wrapping the L<RAND_DRBG_generate(3)> function, which serves the actual
+request for random data.
+
+=head1 RESEEDING
+
+A DRBG instance seeds itself automatically, pulling random input from
+its entropy source. The entropy source can be either a trusted operating
+system entropy source, or another DRBG with access to such a source.
+
+Automatic reseeding occurs after a predefined number of generate requests.
+The selection of the trusted entropy sources is configured at build
+time using the --with-rand-seed option. The following sections explain
+the reseeding process in more detail.
+
+=head2 Automatic Reseeding
+
+Before satisfying a generate request (L<RAND_DRBG_generate(3)>), the DRBG
+reseeds itself automatically, if one of the following conditions holds:
+
+- the DRBG was not instantiated (=seeded) yet or has been uninstantiated.
+
+- the number of generate requests since the last reseeding exceeds a
+certain threshold, the so called I<reseed_interval>.
+This behaviour can be disabled by setting the I<reseed_interval> to 0.
+
+- the time elapsed since the last reseeding exceeds a certain time
+interval, the so called I<reseed_time_interval>.
+This can be disabled by setting the I<reseed_time_interval> to 0.
+
+- the DRBG is in an error state.
+
+B<Note>: An error state is entered if the entropy source fails while
+the DRBG is seeding or reseeding.
+The last case ensures that the DRBG automatically recovers
+from the error as soon as the entropy source is available again.
+
+=head2 Manual Reseeding
+
+In addition to automatic reseeding, the caller can request an immediate
+reseeding of the DRBG with fresh entropy by setting the
+I<prediction resistance> parameter to 1 when calling L<RAND_DRBG_generate(3)>.
+
+The dcoument [NIST SP 800-90C] describes prediction resistance requests
+in detail and imposes strict conditions on the entropy sources that are
+approved for providing prediction resistance.
+Since the default DRBG implementation does not have access to such an approved
+entropy source, a request for prediction resistance will currently always fail.
+In other words, prediction resistance is currently not supported yet by the DRBG.
+
+
+For the three shared DRBGs (and only for these) there is another way to
+reseed them manually:
+If L<RAND_add(3)> is called with a positive I<randomness> argument
+(or L<RAND_seed(3)>), then this will immediately reseed the <master> DRBG.
+The <public> and <private> DRBG will detect this on their next generate
+call and reseed, pulling randomness from <master>.
+
+The last feature has been added to support the common practice used with
+previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
+
+
+=head2 Entropy Input vs. Additional Data
+
+The DRBG distinguishes two different types of random input: I<entropy>,
+which comes from a trusted source, and I<additional input>',
+which can optionally be added by the user and is considered untrusted.
+It is possible to add I<additional input> not only during reseeding,
+but also for every generate request.
+This is in fact done automatically by L<RAND_DRBG_bytes(3)>.
+
+
+=head2 Configuring the Random Seed Source
+
+In most cases OpenSSL will automatically choose a suitable seed source
+for automatically seeding and reseeding its <master> DRBG. In some cases
+however, it will be necessary to explicitly specify a seed source during
+configuration, using the --with-rand-seed option. For more information,
+see the INSTALL instructions. There are also operating systems where no
+seed source is available and automatic reseeding is disabled by default.
+
+The following two sections describe the reseeding process of the master
+DRBG, depending on whether automatic reseeding is available or not.
+
+
+=head2 Reseeding the master DRBG with automatic seeding enabled
+
+Calling RAND_poll() or RAND_add() is not necessary, because the DRBG
+pulls the necessary entropy from its source automatically.
+However, both calls are permitted, and do reseed the RNG.
+
+RAND_add() can be used to add both kinds of random input, depending on the
+value of the B<randomness> argument:
+
+=over 4
+
+=item randomness == 0:
+
+The random bytes are mixed as additional input into the current state of
+the DRBG.
+Mixing in additional input is not considered a full reseeding, hence the
+reseed counter is not reset.
+
+
+=item randomness > 0:
+
+The random bytes are used as entropy input for a full reseeding
+(resp. reinstantiation) if the DRBG is instantiated
+(resp. uninstantiated or in an error state).
+The number of random bits required for reseeding is determined by the
+security strength of the DRBG. Currently it defaults to 256 bits (32 bytes).
+It is possible to provide less randomness than required.
+In this case the missing randomness will be obtained by pulling random input
+from the trusted entropy sources.
+
+=back
+
+=head2 Reseeding the master DRBG with automatic seeding disabled
+
+Calling RAND_poll() will always fail.
+
+RAND_add() needs to be called for initial seeding and periodic reseeding.
+At least 48 bytes (384 bits) of randomness have to be provided, otherwise
+the (re-)seeding of the DRBG will fail. This corresponds to one and a half
+times the security strength of the DRBG. The extra half is used for the
+nonce during instantiation.
+
+More precisely, the number of bytes needed for seeding depend on the
+I<security strength> of the DRBG, which is set to 256 by default.
+
+=head1 SEE ALSO
+
+L<RAND_DRBG_bytes(3)>,
+L<RAND_DRBG_generate(3)>,
+L<RAND_DRBG_reseed(3)>,
+L<RAND_DRBG_get0_master(3)>,
+L<RAND_DRBG_get0_public(3)>,
+L<RAND_DRBG_get0_private(3)>,
+L<RAND_DRBG_set_reseed_interval(3)>,
+L<RAND_DRBG_set_reseed_time_interval(3)>,
+L<RAND_DRBG_set_reseed_defaults(3)>,
+L<RAND(7)>,
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/RSA-PSS.pod b/doc/man7/RSA-PSS.pod
new file mode 100644
index 000000000000..29775d862103
--- /dev/null
+++ b/doc/man7/RSA-PSS.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+RSA-PSS - EVP_PKEY RSA-PSS algorithm support
+
+=head1 DESCRIPTION
+
+The B<RSA-PSS> EVP_PKEY implementation is a restricted version of the RSA
+algorithm which only supports signing, verification and key generation
+using PSS padding modes with optional parameter restrictions.
+
+It has associated private key and public key formats.
+
+This algorithm shares several control operations with the B<RSA> algorithm
+but with some restrictions described below.
+
+=head2 Signing and Verification
+
+Signing and verification is similar to the B<RSA> algorithm except the
+padding mode is always PSS. If the key in use has parameter restrictions then
+the corresponding signature parameters are set to the restrictions:
+for example, if the key can only be used with digest SHA256, MGF1 SHA256
+and minimum salt length 32 then the digest, MGF1 digest and salt length
+will be set to SHA256, SHA256 and 32 respectively.
+
+=head2 Key Generation
+
+By default no parameter restrictions are placed on the generated key.
+
+=head1 NOTES
+
+The public key format is documented in RFC4055.
+
+The PKCS#8 private key format used for RSA-PSS keys is similar to the RSA
+format except it uses the B<id-RSASSA-PSS> OID and the parameters field, if
+present, restricts the key parameters in the same way as the public key.
+
+=head1 CONFORMING TO
+
+RFC 4055
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_set_rsa_pss_keygen_md(3)>,
+L<EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(3)>,
+L<EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(3)>,
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/SM2.pod b/doc/man7/SM2.pod
new file mode 100644
index 000000000000..029dc736cbd5
--- /dev/null
+++ b/doc/man7/SM2.pod
@@ -0,0 +1,79 @@
+=pod
+
+=head1 NAME
+
+SM2 - Chinese SM2 signature and encryption algorithm support
+
+=head1 DESCRIPTION
+
+The B<SM2> algorithm was first defined by the Chinese national standard GM/T
+0003-2012 and was later standardized by ISO as ISO/IEC 14888. B<SM2> is actually
+an elliptic curve based algorithm. The current implementation in OpenSSL supports
+both signature and encryption schemes via the EVP interface.
+
+When doing the B<SM2> signature algorithm, it requires a distinguishing identifier
+to form the message prefix which is hashed before the real message is hashed.
+
+=head1 NOTES
+
+B<SM2> signatures can be generated by using the 'DigestSign' series of APIs, for
+instance, EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal().
+Ditto for the verification process by calling the 'DigestVerify' series of APIs.
+
+There are several special steps that need to be done before computing an B<SM2>
+signature.
+
+The B<EVP_PKEY> structure will default to using ECDSA for signatures when it is
+created. It should be set to B<EVP_PKEY_SM2> by calling:
+
+ EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
+
+Then an ID should be set by calling:
+
+ EVP_PKEY_CTX_set1_id(pctx, id, id_len);
+
+When calling the EVP_DigestSignInit() or EVP_DigestVerifyInit() functions, a
+pre-allocated B<EVP_PKEY_CTX> should be assigned to the B<EVP_MD_CTX>. This is
+done by calling:
+
+ EVP_MD_CTX_set_pkey_ctx(mctx, pctx);
+
+And normally there is no need to pass a B<pctx> parameter to EVP_DigestSignInit()
+or EVP_DigestVerifyInit() in such a scenario.
+
+=head1 EXAMPLE
+
+This example demonstrates the calling sequence for using an B<EVP_PKEY> to verify
+a message with the SM2 signature algorithm and the SM3 hash algorithm:
+
+ #include <openssl/evp.h>
+
+ /* obtain an EVP_PKEY using whatever methods... */
+ EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
+ mctx = EVP_MD_CTX_new();
+ pctx = EVP_PKEY_CTX_new(pkey, NULL);
+ EVP_PKEY_CTX_set1_id(pctx, id, id_len);
+ EVP_MD_CTX_set_pkey_ctx(mctx, pctx);;
+ EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey);
+ EVP_DigestVerifyUpdate(mctx, msg, msg_len);
+ EVP_DigestVerifyFinal(mctx, sig, sig_len)
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_set_alias_type(3)>,
+L<EVP_DigestSignInit(3)>,
+L<EVP_DigestVerifyInit(3)>,
+L<EVP_PKEY_CTX_set1_id(3)>,
+L<EVP_MD_CTX_set_pkey_ctx(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/X25519.pod b/doc/man7/X25519.pod
new file mode 100644
index 000000000000..7cb6ff6b3bed
--- /dev/null
+++ b/doc/man7/X25519.pod
@@ -0,0 +1,74 @@
+=pod
+
+=head1 NAME
+
+X25519,
+X448
+- EVP_PKEY X25519 and X448 support
+
+=head1 DESCRIPTION
+
+The B<X25519> and B<X448> EVP_PKEY implementation supports key generation and
+key derivation using B<X25519> and B<X448>. It has associated private and public
+key formats compatible with draft-ietf-curdle-pkix-03.
+
+No additional parameters can be set during key generation.
+
+The peer public key must be set using EVP_PKEY_derive_set_peer() when
+performing key derivation.
+
+=head1 NOTES
+
+A context for the B<X25519> algorithm can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
+
+For the B<X448> algorithm a context can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X448, NULL);
+
+X25519 or X448 private keys can be set directly using
+L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
+using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
+can also be generated (see the example below). Setting a private key also sets
+the associated public key.
+
+X25519 or X448 public keys can be set directly using
+L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
+structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
+
+=head1 EXAMPLE
+
+This example generates an B<X25519> private key and writes it to standard
+output in PEM format:
+
+ #include <openssl/evp.h>
+ #include <openssl/pem.h>
+ ...
+ EVP_PKEY *pkey = NULL;
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
+ EVP_PKEY_keygen_init(pctx);
+ EVP_PKEY_keygen(pctx, &pkey);
+ EVP_PKEY_CTX_free(pctx);
+ PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
+
+The key derivation example in L<EVP_PKEY_derive(3)> can be used with
+B<X25519> and B<X448>.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_keygen(3)>,
+L<EVP_PKEY_derive(3)>,
+L<EVP_PKEY_derive_set_peer(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod
new file mode 100644
index 000000000000..45ef2f77041d
--- /dev/null
+++ b/doc/man7/bio.pod
@@ -0,0 +1,87 @@
+=pod
+
+=head1 NAME
+
+bio - Basic I/O abstraction
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+ #include <openssl/bio.h>
+
+=head1 DESCRIPTION
+
+A BIO is an I/O abstraction, it hides many of the underlying I/O
+details from an application. If an application uses a BIO for its
+I/O it can transparently handle SSL connections, unencrypted network
+connections and file I/O.
+
+There are two type of BIO, a source/sink BIO and a filter BIO.
+
+As its name implies a source/sink BIO is a source and/or sink of data,
+examples include a socket BIO and a file BIO.
+
+A filter BIO takes data from one BIO and passes it through to
+another, or the application. The data may be left unmodified (for
+example a message digest BIO) or translated (for example an
+encryption BIO). The effect of a filter BIO may change according
+to the I/O operation it is performing: for example an encryption
+BIO will encrypt data if it is being written to and decrypt data
+if it is being read from.
+
+BIOs can be joined together to form a chain (a single BIO is a chain
+with one component). A chain normally consist of one source/sink
+BIO and one or more filter BIOs. Data read from or written to the
+first BIO then traverses the chain to the end (normally a source/sink
+BIO).
+
+
+Some BIOs (such as memory BIOs) can be used immediately after calling
+BIO_new(). Others (such as file BIOs) need some additional initialization,
+and frequently a utility function exists to create and initialize such BIOs.
+
+If BIO_free() is called on a BIO chain it will only free one BIO resulting
+in a memory leak.
+
+Calling BIO_free_all() on a single BIO has the same effect as calling
+BIO_free() on it other than the discarded return value.
+
+Normally the B<type> argument is supplied by a function which returns a
+pointer to a BIO_METHOD. There is a naming convention for such functions:
+a source/sink BIO is normally called BIO_s_*() and a filter BIO
+BIO_f_*();
+
+=head1 EXAMPLE
+
+Create a memory BIO:
+
+ BIO *mem = BIO_new(BIO_s_mem());
+
+=head1 SEE ALSO
+
+L<BIO_ctrl(3)>,
+L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>,
+L<BIO_f_cipher(3)>, L<BIO_f_md(3)>,
+L<BIO_f_null(3)>, L<BIO_f_ssl(3)>,
+L<BIO_find_type(3)>, L<BIO_new(3)>,
+L<BIO_new_bio_pair(3)>,
+L<BIO_push(3)>, L<BIO_read_ex(3)>,
+L<BIO_s_accept(3)>, L<BIO_s_bio(3)>,
+L<BIO_s_connect(3)>, L<BIO_s_fd(3)>,
+L<BIO_s_file(3)>, L<BIO_s_mem(3)>,
+L<BIO_s_null(3)>, L<BIO_s_socket(3)>,
+L<BIO_set_callback(3)>,
+L<BIO_should_retry(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
+
diff --git a/doc/man7/crypto.pod b/doc/man7/crypto.pod
new file mode 100644
index 000000000000..e08c5c8aec13
--- /dev/null
+++ b/doc/man7/crypto.pod
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+crypto - OpenSSL cryptographic library
+
+=head1 SYNOPSIS
+
+See the individual manual pages for details.
+
+=head1 DESCRIPTION
+
+The OpenSSL B<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 implement SSH, OpenPGP, and
+other cryptographic standards.
+
+B<libcrypto> consists of a number of sub-libraries that implement the
+individual algorithms.
+
+The functionality includes symmetric encryption, public key
+cryptography and key agreement, certificate handling, cryptographic
+hash functions, cryptographic pseudo-random number generator, and
+various utilities.
+
+=head1 NOTES
+
+Some of the newer functions follow a naming convention using the numbers
+B<0> and B<1>. For example the functions:
+
+ int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
+ int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
+
+The B<0> version uses the supplied structure pointer directly
+in the parent and it will be freed up when the parent is freed.
+In the above example B<crl> would be freed but B<rev> would not.
+
+The B<1> function uses a copy of the supplied structure pointer
+(or in some cases increases its link count) in the parent and
+so both (B<x> and B<obj> above) should be freed up.
+
+=head1 RETURN VALUES
+
+See the individual manual pages for details.
+
+=head1 SEE ALSO
+
+L<openssl(1)>, L<ssl(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/ct.pod b/doc/man7/ct.pod
new file mode 100644
index 000000000000..355204d2a632
--- /dev/null
+++ b/doc/man7/ct.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+ct - Certificate Transparency
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+=head1 DESCRIPTION
+
+This library implements Certificate Transparency (CT) verification for TLS
+clients, as defined in RFC 6962. This verification can provide some confidence
+that a certificate has been publicly logged in a set of CT logs.
+
+By default, these checks are disabled. They can be enabled using
+SSL_CTX_ct_enable() or SSL_ct_enable().
+
+This library can also be used to parse and examine CT data structures, such as
+Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are
+functions for:
+- decoding and encoding SCTs in DER and TLS wire format.
+- printing SCTs.
+- verifying the authenticity of SCTs.
+- loading a CT log list from a CONF file.
+
+=head1 SEE ALSO
+
+L<d2i_SCT_LIST(3)>,
+L<CTLOG_STORE_new(3)>,
+L<CTLOG_STORE_get0_log_by_id(3)>,
+L<SCT_new(3)>,
+L<SCT_print(3)>,
+L<SCT_validate(3)>,
+L<SCT_validate(3)>,
+L<CT_POLICY_EVAL_CTX_new(3)>,
+L<SSL_CTX_set_ct_validation_callback(3)>
+
+=head1 HISTORY
+
+This library was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/des_modes.pod b/doc/man7/des_modes.pod
new file mode 100644
index 000000000000..f7415d77f485
--- /dev/null
+++ b/doc/man7/des_modes.pod
@@ -0,0 +1,258 @@
+=pod
+
+=head1 NAME
+
+des_modes - the variants of DES and other crypto algorithms of OpenSSL
+
+=head1 DESCRIPTION
+
+Several crypto algorithms for OpenSSL can be used in a number of modes. Those
+are used for using block ciphers in a way similar to stream ciphers, among
+other things.
+
+=head1 OVERVIEW
+
+=head2 Electronic Codebook Mode (ECB)
+
+Normally, this is found as the function I<algorithm>_ecb_encrypt().
+
+=over 2
+
+=item *
+
+64 bits are enciphered at a time.
+
+=item *
+
+The order of the blocks can be rearranged without detection.
+
+=item *
+
+The same plaintext block always produces the same ciphertext block
+(for the same key) making it vulnerable to a 'dictionary attack'.
+
+=item *
+
+An error will only affect one ciphertext block.
+
+=back
+
+=head2 Cipher Block Chaining Mode (CBC)
+
+Normally, this is found as the function I<algorithm>_cbc_encrypt().
+Be aware that des_cbc_encrypt() is not really DES CBC (it does
+not update the IV); use des_ncbc_encrypt() instead.
+
+=over 2
+
+=item *
+
+a multiple of 64 bits are enciphered at a time.
+
+=item *
+
+The CBC mode produces the same ciphertext whenever the same
+plaintext is encrypted using the same key and starting variable.
+
+=item *
+
+The chaining operation makes the ciphertext blocks dependent on the
+current and all preceding plaintext blocks and therefore blocks can not
+be rearranged.
+
+=item *
+
+The use of different starting variables prevents the same plaintext
+enciphering to the same ciphertext.
+
+=item *
+
+An error will affect the current and the following ciphertext blocks.
+
+=back
+
+=head2 Cipher Feedback Mode (CFB)
+
+Normally, this is found as the function I<algorithm>_cfb_encrypt().
+
+=over 2
+
+=item *
+
+a number of bits (j) <= 64 are enciphered at a time.
+
+=item *
+
+The CFB mode produces the same ciphertext whenever the same
+plaintext is encrypted using the same key and starting variable.
+
+=item *
+
+The chaining operation makes the ciphertext variables dependent on the
+current and all preceding variables and therefore j-bit variables are
+chained together and can not be rearranged.
+
+=item *
+
+The use of different starting variables prevents the same plaintext
+enciphering to the same ciphertext.
+
+=item *
+
+The strength of the CFB mode depends on the size of k (maximal if
+j == k). In my implementation this is always the case.
+
+=item *
+
+Selection of a small value for j will require more cycles through
+the encipherment algorithm per unit of plaintext and thus cause
+greater processing overheads.
+
+=item *
+
+Only multiples of j bits can be enciphered.
+
+=item *
+
+An error will affect the current and the following ciphertext variables.
+
+=back
+
+=head2 Output Feedback Mode (OFB)
+
+Normally, this is found as the function I<algorithm>_ofb_encrypt().
+
+=over 2
+
+=item *
+
+a number of bits (j) <= 64 are enciphered at a time.
+
+=item *
+
+The OFB mode produces the same ciphertext whenever the same
+plaintext enciphered using the same key and starting variable. More
+over, in the OFB mode the same key stream is produced when the same
+key and start variable are used. Consequently, for security reasons
+a specific start variable should be used only once for a given key.
+
+=item *
+
+The absence of chaining makes the OFB more vulnerable to specific attacks.
+
+=item *
+
+The use of different start variables values prevents the same
+plaintext enciphering to the same ciphertext, by producing different
+key streams.
+
+=item *
+
+Selection of a small value for j will require more cycles through
+the encipherment algorithm per unit of plaintext and thus cause
+greater processing overheads.
+
+=item *
+
+Only multiples of j bits can be enciphered.
+
+=item *
+
+OFB mode of operation does not extend ciphertext errors in the
+resultant plaintext output. Every bit error in the ciphertext causes
+only one bit to be in error in the deciphered plaintext.
+
+=item *
+
+OFB mode is not self-synchronizing. If the two operation of
+encipherment and decipherment get out of synchronism, the system needs
+to be re-initialized.
+
+=item *
+
+Each re-initialization should use a value of the start variable
+different from the start variable values used before with the same
+key. The reason for this is that an identical bit stream would be
+produced each time from the same parameters. This would be
+susceptible to a 'known plaintext' attack.
+
+=back
+
+=head2 Triple ECB Mode
+
+Normally, this is found as the function I<algorithm>_ecb3_encrypt().
+
+=over 2
+
+=item *
+
+Encrypt with key1, decrypt with key2 and encrypt with key3 again.
+
+=item *
+
+As for ECB encryption but increases the key length to 168 bits.
+There are theoretic attacks that can be used that make the effective
+key length 112 bits, but this attack also requires 2^56 blocks of
+memory, not very likely, even for the NSA.
+
+=item *
+
+If both keys are the same it is equivalent to encrypting once with
+just one key.
+
+=item *
+
+If the first and last key are the same, the key length is 112 bits.
+There are attacks that could reduce the effective key strength
+to only slightly more than 56 bits, but these require a lot of memory.
+
+=item *
+
+If all 3 keys are the same, this is effectively the same as normal
+ecb mode.
+
+=back
+
+=head2 Triple CBC Mode
+
+Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt().
+
+=over 2
+
+=item *
+
+Encrypt with key1, decrypt with key2 and then encrypt with key3.
+
+=item *
+
+As for CBC encryption but increases the key length to 168 bits with
+the same restrictions as for triple ecb mode.
+
+=back
+
+=head1 NOTES
+
+This text was been written in large parts by Eric Young in his original
+documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed
+it to:
+
+ AS 2805.5.2
+ Australian Standard
+ Electronic funds transfer - Requirements for interfaces,
+ Part 5.2: Modes of operation for an n-bit block cipher algorithm
+ Appendix A
+
+=head1 SEE ALSO
+
+L<BF_encrypt(3)>, L<DES_crypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/evp.pod b/doc/man7/evp.pod
new file mode 100644
index 000000000000..e493dacd2313
--- /dev/null
+++ b/doc/man7/evp.pod
@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+evp - high-level cryptographic functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+=head1 DESCRIPTION
+
+The EVP library provides a high-level interface to cryptographic
+functions.
+
+The L<B<EVP_Seal>I<XXX>|EVP_SealInit(3)> and L<B<EVP_Open>I<XXX>|EVP_OpenInit(3)>
+functions provide public key encryption and decryption to implement digital "envelopes".
+
+The L<B<EVP_DigestSign>I<XXX>|EVP_DigestSignInit(3)> and
+L<B<EVP_DigestVerify>I<XXX>|EVP_DigestVerifyInit(3)> functions implement
+digital signatures and Message Authentication Codes (MACs). Also see the older
+L<B<EVP_Sign>I<XXX>|EVP_SignInit(3)> and L<B<EVP_Verify>I<XXX>|EVP_VerifyInit(3)>
+functions.
+
+Symmetric encryption is available with the L<B<EVP_Encrypt>I<XXX>|EVP_EncryptInit(3)>
+functions. The L<B<EVP_Digest>I<XXX>|EVP_DigestInit(3)> functions provide message digests.
+
+The B<EVP_PKEY>I<XXX> functions provide a high level interface to
+asymmetric algorithms. To create a new EVP_PKEY see
+L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated
+with a private key of a particular algorithm by using the functions
+described on the L<EVP_PKEY_set1_RSA(3)> page, or
+new keys can be generated using L<EVP_PKEY_keygen(3)>.
+EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using
+L<EVP_PKEY_print_private(3)>.
+
+The EVP_PKEY functions support the full range of asymmetric algorithm operations:
+
+=over 4
+
+=item For key agreement see L<EVP_PKEY_derive(3)>
+
+=item For signing and verifying see L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>.
+However, note that
+these functions do not perform a digest of the data to be signed. Therefore
+normally you would use the L<EVP_DigestSignInit(3)>
+functions for this purpose.
+
+=item For encryption and decryption see L<EVP_PKEY_encrypt(3)>
+and L<EVP_PKEY_decrypt(3)> respectively. However, note that
+these functions perform encryption and decryption only. As public key
+encryption is an expensive operation, normally you would wrap
+an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and
+L<EVP_OpenInit(3)> functions.
+
+=back
+
+The L<EVP_BytesToKey(3)> function provides some limited support for password
+based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible
+implementation. However, new applications should not typically use this (preferring, for example,
+PBKDF2 from PCKS#5).
+
+The L<B<EVP_Encode>I<XXX>|EVP_EncodeInit(3)> and
+L<B<EVP_Decode>I<XXX>|EVP_EncodeInit(3)> functions implement base 64 encoding
+and decoding.
+
+All the symmetric algorithms (ciphers), digests and asymmetric algorithms
+(public key algorithms) can be replaced by ENGINE modules providing alternative
+implementations. If ENGINE implementations of ciphers or digests are registered
+as defaults, then the various EVP functions will automatically use those
+implementations automatically in preference to built in software
+implementations. For more information, consult the engine(3) man page.
+
+Although low level algorithm specific functions exist for many algorithms
+their use is discouraged. They cannot be used with an ENGINE and ENGINE
+versions of new algorithms cannot be accessed using the low level functions.
+Also makes code harder to adapt to new algorithms and some options are not
+cleanly supported at the low level and some operations are more efficient
+using the high level interface.
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>,
+L<EVP_EncryptInit(3)>,
+L<EVP_OpenInit(3)>,
+L<EVP_SealInit(3)>,
+L<EVP_DigestSignInit(3)>,
+L<EVP_SignInit(3)>,
+L<EVP_VerifyInit(3)>,
+L<EVP_EncodeInit(3)>,
+L<EVP_PKEY_new(3)>,
+L<EVP_PKEY_set1_RSA(3)>,
+L<EVP_PKEY_keygen(3)>,
+L<EVP_PKEY_print_private(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>,
+L<EVP_BytesToKey(3)>,
+L<ENGINE_by_id(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/ossl_store-file.pod b/doc/man7/ossl_store-file.pod
new file mode 100644
index 000000000000..996043b0fb85
--- /dev/null
+++ b/doc/man7/ossl_store-file.pod
@@ -0,0 +1,71 @@
+=pod
+
+=begin comment
+
+This is a recommended way to describe OSSL_STORE loaders,
+"ossl_store-{name}", where {name} is replaced with the name of the
+scheme it implements, in man section 7.
+
+=end comment
+
+=head1 NAME
+
+ossl_store-file - The store 'file' scheme loader
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+#include <openssl/store.h>
+
+=head1 DESCRIPTION
+
+Support for the 'file' scheme is built into C<libcrypto>.
+Since files come in all kinds of formats and content types, the 'file'
+scheme has its own layer of functionality called "file handlers",
+which are used to try to decode diverse types of file contents.
+
+In case a file is formatted as PEM, each called file handler receives
+the PEM name (everything following any 'C<-----BEGIN >') as well as
+possible PEM headers, together with the decoded PEM body. Since PEM
+formatted files can contain more than one object, the file handlers
+are called upon for each such object.
+
+If the file isn't determined to be formatted as PEM, the content is
+loaded in raw form in its entirety and passed to the available file
+handlers as is, with no PEM name or headers.
+
+Each file handler is expected to handle PEM and non-PEM content as
+appropriate. Some may refuse non-PEM content for the sake of
+determinism (for example, there are keys out in the wild that are
+represented as an ASN.1 OCTET STRING. In raw form, it's not easily
+possible to distinguish those from any other data coming as an ASN.1
+OCTET STRING, so such keys would naturally be accepted as PEM files
+only).
+
+=head1 NOTES
+
+When needed, the 'file' scheme loader will require a pass phrase by
+using the C<UI_METHOD> that was passed via OSSL_STORE_open().
+This pass phrase is expected to be UTF-8 encoded, anything else will
+give an undefined result.
+The files made accessible through this loader are expected to be
+standard compliant with regards to pass phrase encoding.
+Files that aren't should be re-generated with a correctly encoded pass
+phrase.
+See L<passphrase-encoding(7)> for more information.
+
+=head1 SEE ALSO
+
+L<ossl_store(7)>, L<passphrase-encoding(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
new file mode 100644
index 000000000000..6e75abd314b7
--- /dev/null
+++ b/doc/man7/ossl_store.pod
@@ -0,0 +1,87 @@
+=pod
+
+=head1 NAME
+
+ossl_store - Store retrieval functions
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+#include <openssl/store.h>
+
+=head1 DESCRIPTION
+
+=head2 General
+
+A STORE is a layer of functionality to retrieve a number of supported
+objects from a repository of any kind, addressable as a file name or
+as a URI.
+
+The functionality supports the pattern "open a channel to the
+repository", "loop and retrieve one object at a time", and "finish up
+by closing the channel".
+
+The retrieved objects are returned as a wrapper type B<OSSL_STORE_INFO>,
+from which an OpenSSL type can be retrieved.
+
+=head2 URI schemes and loaders
+
+Support for a URI scheme is called a STORE "loader", and can be added
+dynamically from the calling application or from a loadable engine.
+
+Support for the 'file' scheme is built into C<libcrypto>.
+See L<ossl_store-file(7)> for more information.
+
+=head2 UI_METHOD and pass phrases
+
+The B<OSS_STORE> API does nothing to enforce any specific format or
+encoding on the pass phrase that the B<UI_METHOD> provides. However,
+the pass phrase is expected to be UTF-8 encoded. The result of any
+other encoding is undefined.
+
+=head1 EXAMPLES
+
+=head2 A generic call
+
+ OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem");
+
+ /*
+ * OSSL_STORE_eof() simulates file semantics for any repository to signal
+ * that no more data can be expected
+ */
+ while (!OSSL_STORE_eof(ctx)) {
+ OSSL_STORE_INFO *info = OSSL_STORE_load(ctx);
+
+ /*
+ * Do whatever is necessary with the OSSL_STORE_INFO,
+ * here just one example
+ */
+ switch (OSSL_STORE_INFO_get_type(info)) {
+ case OSSL_STORE_INFO_X509:
+ /* Print the X.509 certificate text */
+ X509_print_fp(stdout, OSSL_STORE_INFO_get0_CERT(info));
+ /* Print the X.509 certificate PEM output */
+ PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info));
+ break;
+ }
+ }
+
+ OSSL_STORE_close(ctx);
+
+=head1 SEE ALSO
+
+L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>,
+L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>,
+L<OSSL_STORE_SEARCH(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/passphrase-encoding.pod b/doc/man7/passphrase-encoding.pod
new file mode 100644
index 000000000000..68108445269b
--- /dev/null
+++ b/doc/man7/passphrase-encoding.pod
@@ -0,0 +1,180 @@
+=pod
+
+=encoding utf8
+
+=head1 NAME
+
+passphrase-encoding
+- How diverse parts of OpenSSL treat pass phrases character encoding
+
+=head1 DESCRIPTION
+
+In a modern world with all sorts of character encodings, the treatment of pass
+phrases has become increasingly complex.
+This manual page attempts to give an overview over how this problem is
+currently addressed in different parts of the OpenSSL library.
+
+=head2 The general case
+
+The OpenSSL library doesn't treat pass phrases in any special way as a general
+rule, and trusts the application or user to choose a suitable character set
+and stick to that throughout the lifetime of affected objects.
+This means that for an object that was encrypted using a pass phrase encoded in
+ISO-8859-1, that object needs to be decrypted using a pass phrase encoded in
+ISO-8859-1.
+Using the wrong encoding is expected to cause a decryption failure.
+
+=head2 PKCS#12
+
+PKCS#12 is a bit different regarding pass phrase encoding.
+The standard stipulates that the pass phrase shall be encoded as an ASN.1
+BMPString, which consists of the code points of the basic multilingual plane,
+encoded in big endian (UCS-2 BE).
+
+OpenSSL tries to adapt to this requirements in one of the following manners:
+
+=over 4
+
+=item 1.
+
+Treats the received pass phrase as UTF-8 encoded and tries to re-encode it to
+UTF-16 (which is the same as UCS-2 for characters U+0000 to U+D7FF and U+E000
+to U+FFFF, but becomes an expansion for any other character), or failing that,
+proceeds with step 2.
+
+=item 2.
+
+Assumes that the pass phrase is encoded in ASCII or ISO-8859-1 and
+opportunistically prepends each byte with a zero byte to obtain the UCS-2
+encoding of the characters, which it stores as a BMPString.
+
+Note that since there is no check of your locale, this may produce UCS-2 /
+UTF-16 characters that do not correspond to the original pass phrase characters
+for other character sets, such as any ISO-8859-X encoding other than
+ISO-8859-1 (or for Windows, CP 1252 with exception for the extra "graphical"
+characters in the 0x80-0x9F range).
+
+=back
+
+OpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why
+OpenSSL still does this, to be able to read files produced with older versions.
+
+It should be noted that this approach isn't entirely fault free.
+
+A pass phrase encoded in ISO-8859-2 could very well have a sequence such as
+0xC3 0xAF (which is the two characters "LATIN CAPITAL LETTER A WITH BREVE"
+and "LATIN CAPITAL LETTER Z WITH DOT ABOVE" in ISO-8859-2 encoding), but would
+be misinterpreted as the perfectly valid UTF-8 encoded code point U+00EF (LATIN
+SMALL LETTER I WITH DIARESIS) I<if the pass phrase doesn't contain anything that
+would be invalid UTF-8>.
+A pass phrase that contains this kind of byte sequence will give a different
+outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0.
+
+ 0x00 0xC3 0x00 0xAF # OpenSSL older than 1.1.0
+ 0x00 0xEF # OpenSSL 1.1.0 and newer
+
+On the same accord, anything encoded in UTF-8 that was given to OpenSSL older
+than 1.1.0 was misinterpreted as ISO-8859-1 sequences.
+
+=head2 OSSL_STORE
+
+L<ossl_store(7)> acts as a general interface to access all kinds of objects,
+potentially protected with a pass phrase, a PIN or something else.
+This API stipulates that pass phrases should be UTF-8 encoded, and that any
+other pass phrase encoding may give undefined results.
+This API relies on the application to ensure UTF-8 encoding, and doesn't check
+that this is the case, so what it gets, it will also pass to the underlying
+loader.
+
+=head1 RECOMMENDATIONS
+
+This section assumes that you know what pass phrase was used for encryption,
+but that it may have been encoded in a different character encoding than the
+one used by your current input method.
+For example, the pass phrase may have been used at a time when your default
+encoding was ISO-8859-1 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61
+0xEF 0x76 0x65), and you're now in an environment where your default encoding
+is UTF-8 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76
+0x65).
+Whenever it's mentioned that you should use a certain character encoding, it
+should be understood that you either change the input method to use the
+mentioned encoding when you type in your pass phrase, or use some suitable tool
+to convert your pass phrase from your default encoding to the target encoding.
+
+Also note that the sub-sections below discuss human readable pass phrases.
+This is particularly relevant for PKCS#12 objects, where human readable pass
+phrases are assumed.
+For other objects, it's as legitimate to use any byte sequence (such as a
+sequence of bytes from `/dev/urandom` that's been saved away), which makes any
+character encoding discussion irrelevant; in such cases, simply use the same
+byte sequence as it is.
+
+=head2 Creating new objects
+
+For creating new pass phrase protected objects, make sure the pass phrase is
+encoded using UTF-8.
+This is default on most modern Unixes, but may involve an effort on other
+platforms.
+Specifically for Windows, setting the environment variable
+C<OPENSSL_WIN32_UTF8> will have anything entered on [Windows] console prompt
+converted to UTF-8 (command line and separately prompted pass phrases alike).
+
+=head2 Opening existing objects
+
+For opening pass phrase protected objects where you know what character
+encoding was used for the encryption pass phrase, make sure to use the same
+encoding again.
+
+For opening pass phrase protected objects where the character encoding that was
+used is unknown, or where the producing application is unknown, try one of the
+following:
+
+=over 4
+
+=item 1.
+
+Try the pass phrase that you have as it is in the character encoding of your
+environment.
+It's possible that its byte sequence is exactly right.
+
+=item 2.
+
+Convert the pass phrase to UTF-8 and try with the result.
+Specifically with PKCS#12, this should open up any object that was created
+according to the specification.
+
+=item 3.
+
+Do a naïve (i.e. purely mathematical) ISO-8859-1 to UTF-8 conversion and try
+with the result.
+This differs from the previous attempt because ISO-8859-1 maps directly to
+U+0000 to U+00FF, which other non-UTF-8 character sets do not.
+
+This also takes care of the case when a UTF-8 encoded string was used with
+OpenSSL older than 1.1.0.
+(for example, C<ï>, which is 0xC3 0xAF when encoded in UTF-8, would become 0xC3
+0x83 0xC2 0xAF when re-encoded in the naïve manner.
+The conversion to BMPString would then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the
+erroneous/non-compliant encoding used by OpenSSL older than 1.1.0)
+
+=back
+
+=head1 SEE ALSO
+
+L<evp(7)>,
+L<ossl_store(7)>,
+L<EVP_BytesToKey(3)>, L<EVP_DecryptInit(3)>,
+L<PEM_do_header(3)>,
+L<PKCS12_parse(3)>, L<PKCS12_newpass(3)>,
+L<d2i_PKCS8PrivateKey_bio(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/scrypt.pod b/doc/man7/scrypt.pod
new file mode 100644
index 000000000000..94ff3ab53fce
--- /dev/null
+++ b/doc/man7/scrypt.pod
@@ -0,0 +1,115 @@
+=pod
+
+=head1 NAME
+
+scrypt - EVP_PKEY scrypt KDF support
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_SCRYPT algorithm implements the scrypt password based key
+derivation function, as described in RFC 7914. It is memory-hard in the sense
+that it deliberately requires a significant amount of RAM for efficient
+computation. The intention of this is to render brute forcing of passwords on
+systems that lack large amounts of main memory (such as GPUs or ASICs)
+computationally infeasible.
+
+scrypt provides three work factors that can be customized: N, r and p. N, which
+has to be a positive power of two, is the general work factor and scales CPU
+time in an approximately linear fashion. r is the block size of the internally
+used hash function and p is the parallelization factor. Both r and p need to be
+greater than zero. The amount of RAM that scrypt requires for its computation
+is roughly (128 * N * r * p) bytes.
+
+In the original paper of Colin Percival ("Stronger Key Derivation via
+Sequential Memory-Hard Functions", 2009), the suggested values that give a
+computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
+2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
+this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
+GHz), this computation takes about 3 seconds. When N, r or p are not specified,
+they default to 1048576, 8, and 1, respectively. The default amount of RAM that
+may be used by scrypt defaults to 1025 MiB.
+
+=head1 NOTES
+
+A context for scrypt can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
+
+The output length of an scrypt key derivation is specified via the
+length parameter to the L<EVP_PKEY_derive(3)> function.
+
+=head1 EXAMPLE
+
+This example derives a 64-byte long test vector using scrypt using the password
+"password", salt "NaCl" and N = 1024, r = 8, p = 16.
+
+ EVP_PKEY_CTX *pctx;
+ unsigned char out[64];
+
+ size_t outlen = sizeof(out);
+ pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
+
+ if (EVP_PKEY_derive_init(pctx) <= 0) {
+ error("EVP_PKEY_derive_init");
+ }
+ if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) {
+ error("EVP_PKEY_CTX_set1_pbe_pass");
+ }
+ if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) {
+ error("EVP_PKEY_CTX_set1_scrypt_salt");
+ }
+ if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) {
+ error("EVP_PKEY_CTX_set_scrypt_N");
+ }
+ if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) {
+ error("EVP_PKEY_CTX_set_scrypt_r");
+ }
+ if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) {
+ error("EVP_PKEY_CTX_set_scrypt_p");
+ }
+ if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) {
+ error("EVP_PKEY_derive");
+ }
+
+ {
+ const unsigned char expected[sizeof(out)] = {
+ 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
+ 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
+ 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
+ 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
+ 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
+ 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
+ 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
+ 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
+ };
+
+ assert(!memcmp(out, expected, sizeof(out)));
+ }
+
+ EVP_PKEY_CTX_free(pctx);
+
+=head1 CONFORMING TO
+
+RFC 7914
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_set1_scrypt_salt(3)>,
+L<EVP_PKEY_CTX_set_scrypt_N(3)>,
+L<EVP_PKEY_CTX_set_scrypt_r(3)>,
+L<EVP_PKEY_CTX_set_scrypt_p(3)>,
+L<EVP_PKEY_CTX_set_scrypt_maxmem_bytes(3)>,
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/ssl.pod b/doc/man7/ssl.pod
new file mode 100644
index 000000000000..d439860b5b5b
--- /dev/null
+++ b/doc/man7/ssl.pod
@@ -0,0 +1,843 @@
+=pod
+
+=head1 NAME
+
+ssl - OpenSSL SSL/TLS library
+
+=head1 SYNOPSIS
+
+See the individual manual pages for details.
+
+=head1 DESCRIPTION
+
+The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
+Transport Layer Security (TLS v1) protocols. It provides a rich API which is
+documented here.
+
+An B<SSL_CTX> object is created as a framework to establish
+TLS/SSL enabled connections (see L<SSL_CTX_new(3)>).
+Various options regarding certificates, algorithms etc. can be set
+in this object.
+
+When a network connection has been created, it can be assigned to an
+B<SSL> object. After the B<SSL> object has been created using
+L<SSL_new(3)>, L<SSL_set_fd(3)> or
+L<SSL_set_bio(3)> can be used to associate the network
+connection with the object.
+
+When the TLS/SSL handshake is performed using
+L<SSL_accept(3)> or L<SSL_connect(3)>
+respectively.
+L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> and L<SSL_write(3)> are
+used to read and write data on the TLS/SSL connection.
+L<SSL_shutdown(3)> can be used to shut down the
+TLS/SSL connection.
+
+=head1 DATA STRUCTURES
+
+Currently the OpenSSL B<ssl> library functions deals with the following data
+structures:
+
+=over 4
+
+=item B<SSL_METHOD> (SSL Method)
+
+This is a dispatch structure describing the internal B<ssl> library
+methods/functions which implement the various protocol versions (SSLv3
+TLSv1, ...). It's needed to create an B<SSL_CTX>.
+
+=item B<SSL_CIPHER> (SSL Cipher)
+
+This structure holds the algorithm information for a particular cipher which
+are a core part of the SSL/TLS protocol. The available ciphers are configured
+on a B<SSL_CTX> basis and the actual ones used are then part of the
+B<SSL_SESSION>.
+
+=item B<SSL_CTX> (SSL Context)
+
+This is the global context structure which is created by a server or client
+once per program life-time and which holds mainly default values for the
+B<SSL> structures which are later created for the connections.
+
+=item B<SSL_SESSION> (SSL Session)
+
+This is a structure containing the current TLS/SSL session details for a
+connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
+
+=item B<SSL> (SSL Connection)
+
+This is the main SSL/TLS structure which is created by a server or client per
+established connection. This actually is the core structure in the SSL API.
+At run-time the application usually deals with this structure which has
+links to mostly all other structures.
+
+=back
+
+
+=head1 HEADER FILES
+
+Currently the OpenSSL B<ssl> library provides the following C header files
+containing the prototypes for the data structures and functions:
+
+=over 4
+
+=item B<ssl.h>
+
+This is the common header file for the SSL/TLS API. Include it into your
+program to make the API of the B<ssl> library available. It internally
+includes both more private SSL headers and headers from the B<crypto> library.
+Whenever you need hard-core details on the internals of the SSL API, look
+inside this header file.
+
+=item B<ssl2.h>
+
+Unused. Present for backwards compatibility only.
+
+=item B<ssl3.h>
+
+This is the sub header file dealing with the SSLv3 protocol only.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=item B<tls1.h>
+
+This is the sub header file dealing with the TLSv1 protocol only.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=back
+
+=head1 API FUNCTIONS
+
+Currently the OpenSSL B<ssl> library exports 214 API functions.
+They are documented in the following:
+
+=head2 Dealing with Protocol Methods
+
+Here we document the various API functions which deal with the SSL/TLS
+protocol methods defined in B<SSL_METHOD> structures.
+
+=over 4
+
+=item const SSL_METHOD *B<TLS_method>(void);
+
+Constructor for the I<version-flexible> SSL_METHOD structure for clients,
+servers or both.
+See L<SSL_CTX_new(3)> for details.
+
+=item const SSL_METHOD *B<TLS_client_method>(void);
+
+Constructor for the I<version-flexible> SSL_METHOD structure for clients.
+Must be used to support the TLSv1.3 protocol.
+
+=item const SSL_METHOD *B<TLS_server_method>(void);
+
+Constructor for the I<version-flexible> SSL_METHOD structure for servers.
+Must be used to support the TLSv1.3 protocol.
+
+=item const SSL_METHOD *B<TLSv1_2_method>(void);
+
+Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<TLSv1_2_client_method>(void);
+
+Constructor for the TLSv1.2 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<TLSv1_2_server_method>(void);
+
+Constructor for the TLSv1.2 SSL_METHOD structure for servers.
+
+=item const SSL_METHOD *B<TLSv1_1_method>(void);
+
+Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<TLSv1_1_client_method>(void);
+
+Constructor for the TLSv1.1 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<TLSv1_1_server_method>(void);
+
+Constructor for the TLSv1.1 SSL_METHOD structure for servers.
+
+=item const SSL_METHOD *B<TLSv1_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<TLSv1_client_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<TLSv1_server_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for servers.
+
+=item const SSL_METHOD *B<SSLv3_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<SSLv3_client_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<SSLv3_server_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for servers.
+
+=back
+
+=head2 Dealing with Ciphers
+
+Here we document the various API functions which deal with the SSL/TLS
+ciphers defined in B<SSL_CIPHER> structures.
+
+=over 4
+
+=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len);
+
+Write a string to I<buf> (with a maximum size of I<len>) containing a human
+readable description of I<cipher>. Returns I<buf>.
+
+=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits);
+
+Determine the number of bits in I<cipher>. Because of export crippled ciphers
+there are two bits: The bits the algorithm supports in general (stored to
+I<alg_bits>) and the bits which are actually used (the return value).
+
+=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher);
+
+Return the internal name of I<cipher> as a string. These are the various
+strings defined by the I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx>
+definitions in the header files.
+
+=item const char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher);
+
+Returns a string like "C<SSLv3>" or "C<TLSv1.2>" which indicates the
+SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined
+in the specification the first time).
+
+=back
+
+=head2 Dealing with Protocol Contexts
+
+Here we document the various API functions which deal with the SSL/TLS
+protocol context defined in the B<SSL_CTX> structure.
+
+=over 4
+
+=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x);
+
+=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509);
+
+=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c);
+
+=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx);
+
+=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg);
+
+=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t);
+
+=item void B<SSL_CTX_free>(SSL_CTX *a);
+
+=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx);
+
+=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx);
+
+=item STACK *B<SSL_CTX_get_ciphers>(const SSL_CTX *ctx);
+
+=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx);
+
+=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+
+=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx);
+
+=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx);
+
+=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);
+
+=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx);
+
+=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx);
+
+=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx);
+
+=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);
+
+=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, const char *CAfile, const char *CApath);
+
+=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth);
+
+=item int SSL_CTX_up_ref(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c);
+
+=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx);
+
+=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);
+
+=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);
+
+=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);
+
+=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx);
+
+=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx, t);
+
+=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));
+
+=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));
+
+=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));
+
+=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx);
+
+=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg);
+
+=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
+
+=item void B<SSL_CTX_set1_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
+
+=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg)
+
+=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str);
+
+=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list);
+
+=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
+
+=item int B<SSL_CTX_set_ct_validation_callback>(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg);
+
+=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void))
+
+=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m);
+
+=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx);
+
+Use the default paths to locate trusted CA certificates. There is one default
+directory path and one default file path. Both are set via this call.
+
+=item int B<SSL_CTX_set_default_verify_dir>(SSL_CTX *ctx)
+
+Use the default directory path to locate trusted CA certificates.
+
+=item int B<SSL_CTX_set_default_verify_file>(SSL_CTX *ctx)
+
+Use the file path to locate trusted CA certificates.
+
+=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg);
+
+=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));
+
+=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+
+=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg);
+
+=item unsigned long B<SSL_CTX_clear_options>(SSL_CTX *ctx, unsigned long op);
+
+=item unsigned long B<SSL_CTX_get_options>(SSL_CTX *ctx);
+
+=item unsigned long B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op);
+
+=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode);
+
+=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m);
+
+=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode);
+
+=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth);
+
+=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t);
+
+=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh);
+
+=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void));
+
+=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void))
+
+=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey);
+
+=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len);
+
+=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
+
+=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa);
+
+=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len);
+
+=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
+
+=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x);
+
+=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d);
+
+=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, const char *file, int type);
+
+=item int B<SSL_CTX_use_cert_and_key>(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+
+=item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx);
+
+=item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx);
+
+=item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
+
+=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint);
+
+=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
+
+
+=back
+
+=head2 Dealing with Sessions
+
+Here we document the various API functions which deal with the SSL/TLS
+sessions defined in the B<SSL_SESSION> structures.
+
+=over 4
+
+=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b);
+
+=item void B<SSL_SESSION_free>(SSL_SESSION *ss);
+
+=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s);
+
+=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx);
+
+=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s);
+
+=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s);
+
+=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a);
+
+=item SSL_SESSION *B<SSL_SESSION_new>(void);
+
+=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x);
+
+=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x);
+
+=item int B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a);
+
+=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg);
+
+=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t);
+
+=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t);
+
+=back
+
+=head2 Dealing with Connections
+
+Here we document the various API functions which deal with the SSL/TLS
+connection defined in the B<SSL> structure.
+
+=over 4
+
+=item int B<SSL_accept>(SSL *ssl);
+
+=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir);
+
+=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file);
+
+=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x);
+
+=item char *B<SSL_alert_desc_string>(int value);
+
+=item char *B<SSL_alert_desc_string_long>(int value);
+
+=item char *B<SSL_alert_type_string>(int value);
+
+=item char *B<SSL_alert_type_string_long>(int value);
+
+=item int B<SSL_check_private_key>(const SSL *ssl);
+
+=item void B<SSL_clear>(SSL *ssl);
+
+=item long B<SSL_clear_num_renegotiations>(SSL *ssl);
+
+=item int B<SSL_connect>(SSL *ssl);
+
+=item int B<SSL_copy_session_id>(SSL *t, const SSL *f);
+
+Sets the session details for B<t> to be the same as in B<f>. Returns 1 on
+success or 0 on failure.
+
+=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg);
+
+=item int B<SSL_do_handshake>(SSL *ssl);
+
+=item SSL *B<SSL_dup>(SSL *ssl);
+
+SSL_dup() allows applications to configure an SSL handle for use
+in multiple SSL connections, and then duplicate it prior to initiating
+each connection with the duplicated handle.
+Use of SSL_dup() avoids the need to repeat the configuration of the
+handles for each connection.
+
+For SSL_dup() to work, the connection MUST be in its initial state
+and MUST NOT have not yet have started the SSL handshake.
+For connections that are not in their initial state SSL_dup() just
+increments an internal reference count and returns the I<same>
+handle.
+It may be possible to use L<SSL_clear(3)> to recycle an SSL handle
+that is not in its initial state for re-use, but this is best
+avoided.
+Instead, save and restore the session, if desired, and construct a
+fresh handle for each connection.
+
+=item STACK *B<SSL_dup_CA_list>(STACK *sk);
+
+=item void B<SSL_free>(SSL *ssl);
+
+=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl);
+
+=item char *B<SSL_get_app_data>(SSL *ssl);
+
+=item X509 *B<SSL_get_certificate>(const SSL *ssl);
+
+=item const char *B<SSL_get_cipher>(const SSL *ssl);
+
+=item int B<SSL_is_dtls>(const SSL *ssl);
+
+=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits);
+
+=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n);
+
+=item char *B<SSL_get_cipher_name>(const SSL *ssl);
+
+=item char *B<SSL_get_cipher_version>(const SSL *ssl);
+
+=item STACK *B<SSL_get_ciphers>(const SSL *ssl);
+
+=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl);
+
+=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl);
+
+=item long B<SSL_get_default_timeout>(const SSL *ssl);
+
+=item int B<SSL_get_error>(const SSL *ssl, int i);
+
+=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx);
+
+=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void);
+
+=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item int B<SSL_get_fd>(const SSL *ssl);
+
+=item void (*B<SSL_get_info_callback>(const SSL *ssl);)()
+
+=item int B<SSL_get_key_update_type>(SSL *s);
+
+=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl);
+
+=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl);
+
+=item const STACK_OF(SCT) *B<SSL_get0_peer_scts>(SSL *s);
+
+=item EVP_PKEY *B<SSL_get_privatekey>(const SSL *ssl);
+
+=item int B<SSL_get_quiet_shutdown>(const SSL *ssl);
+
+=item BIO *B<SSL_get_rbio>(const SSL *ssl);
+
+=item int B<SSL_get_read_ahead>(const SSL *ssl);
+
+=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl);
+
+=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int size);
+
+=item int B<SSL_get_shutdown>(const SSL *ssl);
+
+=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl);
+
+=item int B<SSL_get_state>(const SSL *ssl);
+
+=item long B<SSL_get_time>(const SSL *ssl);
+
+=item long B<SSL_get_timeout>(const SSL *ssl);
+
+=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int, X509_STORE_CTX *)
+
+=item int B<SSL_get_verify_mode>(const SSL *ssl);
+
+=item long B<SSL_get_verify_result>(const SSL *ssl);
+
+=item char *B<SSL_get_version>(const SSL *ssl);
+
+=item BIO *B<SSL_get_wbio>(const SSL *ssl);
+
+=item int B<SSL_in_accept_init>(SSL *ssl);
+
+=item int B<SSL_in_before>(SSL *ssl);
+
+=item int B<SSL_in_connect_init>(SSL *ssl);
+
+=item int B<SSL_in_init>(SSL *ssl);
+
+=item int B<SSL_is_init_finished>(SSL *ssl);
+
+=item int B<SSL_key_update>(SSL *s, int updatetype);
+
+=item STACK *B<SSL_load_client_CA_file>(const char *file);
+
+=item SSL *B<SSL_new>(SSL_CTX *ctx);
+
+=item int SSL_up_ref(SSL *s);
+
+=item long B<SSL_num_renegotiations>(SSL *ssl);
+
+=item int B<SSL_peek>(SSL *ssl, void *buf, int num);
+
+=item int B<SSL_pending>(const SSL *ssl);
+
+=item int B<SSL_read>(SSL *ssl, void *buf, int num);
+
+=item int B<SSL_renegotiate>(SSL *ssl);
+
+=item char *B<SSL_rstate_string>(SSL *ssl);
+
+=item char *B<SSL_rstate_string_long>(SSL *ssl);
+
+=item long B<SSL_session_reused>(SSL *ssl);
+
+=item void B<SSL_set_accept_state>(SSL *ssl);
+
+=item void B<SSL_set_app_data>(SSL *ssl, char *arg);
+
+=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio);
+
+=item int B<SSL_set_cipher_list>(SSL *ssl, char *str);
+
+=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list);
+
+=item void B<SSL_set_connect_state>(SSL *ssl);
+
+=item int B<SSL_set_ct_validation_callback>(SSL *ssl, ssl_ct_validation_cb callback, void *arg);
+
+=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg);
+
+=item int B<SSL_set_fd>(SSL *ssl, int fd);
+
+=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void))
+
+=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+
+=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg);
+
+=item unsigned long B<SSL_clear_options>(SSL *ssl, unsigned long op);
+
+=item unsigned long B<SSL_get_options>(SSL *ssl);
+
+=item unsigned long B<SSL_set_options>(SSL *ssl, unsigned long op);
+
+=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode);
+
+=item void B<SSL_set_read_ahead>(SSL *ssl, int yes);
+
+=item int B<SSL_set_rfd>(SSL *ssl, int fd);
+
+=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session);
+
+=item void B<SSL_set_shutdown>(SSL *ssl, int mode);
+
+=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth);
+
+=item void B<SSL_set_time>(SSL *ssl, long t);
+
+=item void B<SSL_set_timeout>(SSL *ssl, long t);
+
+=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void))
+
+=item void B<SSL_set_verify_result>(SSL *ssl, long arg);
+
+=item int B<SSL_set_wfd>(SSL *ssl, int fd);
+
+=item int B<SSL_shutdown>(SSL *ssl);
+
+=item OSSL_HANDSHAKE_STATE B<SSL_get_state>(const SSL *ssl);
+
+Returns the current handshake state.
+
+=item char *B<SSL_state_string>(const SSL *ssl);
+
+=item char *B<SSL_state_string_long>(const SSL *ssl);
+
+=item long B<SSL_total_renegotiations>(SSL *ssl);
+
+=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey);
+
+=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len);
+
+=item int B<SSL_use_PrivateKey_file>(SSL *ssl, const char *file, int type);
+
+=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa);
+
+=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len);
+
+=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, const char *file, int type);
+
+=item int B<SSL_use_certificate>(SSL *ssl, X509 *x);
+
+=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d);
+
+=item int B<SSL_use_certificate_file>(SSL *ssl, const char *file, int type);
+
+=item int B<SSL_use_cert_and_key>(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+
+=item int B<SSL_version>(const SSL *ssl);
+
+=item int B<SSL_want>(const SSL *ssl);
+
+=item int B<SSL_want_nothing>(const SSL *ssl);
+
+=item int B<SSL_want_read>(const SSL *ssl);
+
+=item int B<SSL_want_write>(const SSL *ssl);
+
+=item int B<SSL_want_x509_lookup>(const SSL *ssl);
+
+=item int B<SSL_write>(SSL *ssl, const void *buf, int num);
+
+=item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
+
+=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint);
+
+=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
+
+=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl);
+
+=item const char *B<SSL_get_psk_identity>(SSL *ssl);
+
+=back
+
+=head1 RETURN VALUES
+
+See the individual manual pages for details.
+
+=head1 SEE ALSO
+
+L<openssl(1)>, L<crypto(7)>,
+L<CRYPTO_get_ex_new_index(3)>,
+L<SSL_accept(3)>, L<SSL_clear(3)>,
+L<SSL_connect(3)>,
+L<SSL_CIPHER_get_name(3)>,
+L<SSL_COMP_add_compression_method(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_add_session(3)>,
+L<SSL_CTX_ctrl(3)>,
+L<SSL_CTX_flush_sessions(3)>,
+L<SSL_CTX_get_verify_mode(3)>,
+L<SSL_CTX_load_verify_locations(3)>
+L<SSL_CTX_new(3)>,
+L<SSL_CTX_sess_number(3)>,
+L<SSL_CTX_sess_set_cache_size(3)>,
+L<SSL_CTX_sess_set_get_cb(3)>,
+L<SSL_CTX_sessions(3)>,
+L<SSL_CTX_set_cert_store(3)>,
+L<SSL_CTX_set_cert_verify_callback(3)>,
+L<SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_client_cert_cb(3)>,
+L<SSL_CTX_set_default_passwd_cb(3)>,
+L<SSL_CTX_set_generate_session_id(3)>,
+L<SSL_CTX_set_info_callback(3)>,
+L<SSL_CTX_set_max_cert_list(3)>,
+L<SSL_CTX_set_mode(3)>,
+L<SSL_CTX_set_msg_callback(3)>,
+L<SSL_CTX_set_options(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_CTX_set_read_ahead(3)>,
+L<SSL_CTX_set_security_level(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_set_session_id_context(3)>,
+L<SSL_CTX_set_ssl_version(3)>,
+L<SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)>,
+L<SSL_CTX_set_verify(3)>,
+L<SSL_CTX_use_certificate(3)>,
+L<SSL_alert_type_string(3)>,
+L<SSL_do_handshake(3)>,
+L<SSL_enable_ct(3)>,
+L<SSL_get_SSL_CTX(3)>,
+L<SSL_get_ciphers(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_get_default_timeout(3)>,
+L<SSL_get_error(3)>,
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
+L<SSL_get_fd(3)>,
+L<SSL_get_peer_cert_chain(3)>,
+L<SSL_get_rbio(3)>,
+L<SSL_get_session(3)>,
+L<SSL_get_verify_result(3)>,
+L<SSL_get_version(3)>,
+L<SSL_load_client_CA_file(3)>,
+L<SSL_new(3)>,
+L<SSL_pending(3)>,
+L<SSL_read_ex(3)>,
+L<SSL_read(3)>,
+L<SSL_rstate_string(3)>,
+L<SSL_session_reused(3)>,
+L<SSL_set_bio(3)>,
+L<SSL_set_connect_state(3)>,
+L<SSL_set_fd(3)>,
+L<SSL_set_session(3)>,
+L<SSL_set_shutdown(3)>,
+L<SSL_shutdown(3)>,
+L<SSL_state_string(3)>,
+L<SSL_want(3)>,
+L<SSL_write_ex(3)>,
+L<SSL_write(3)>,
+L<SSL_SESSION_free(3)>,
+L<SSL_SESSION_get_time(3)>,
+L<d2i_SSL_SESSION(3)>,
+L<SSL_CTX_set_psk_client_callback(3)>,
+L<SSL_CTX_use_psk_identity_hint(3)>,
+L<SSL_get_psk_identity(3)>,
+L<DTLSv1_listen(3)>
+
+=head1 HISTORY
+
+B<SSLv2_client_method>, B<SSLv2_server_method> and B<SSLv2_method> were removed
+in OpenSSL 1.1.0.
+
+The return type of B<SSL_copy_session_id> was changed from void to int in
+OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/x509.pod b/doc/man7/x509.pod
new file mode 100644
index 000000000000..065dcb14fbeb
--- /dev/null
+++ b/doc/man7/x509.pod
@@ -0,0 +1,73 @@
+=pod
+
+=head1 NAME
+
+x509 - X.509 certificate handling
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+=head1 DESCRIPTION
+
+An X.509 certificate is a structured grouping of information about
+an individual, a device, or anything one can imagine. A X.509 CRL
+(certificate revocation list) is a tool to help determine if a
+certificate is still valid. The exact definition of those can be
+found in the X.509 document from ITU-T, or in RFC3280 from PKIX.
+In OpenSSL, the type X509 is used to express such a certificate, and
+the type X509_CRL is used to express a CRL.
+
+A related structure is a certificate request, defined in PKCS#10 from
+RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type
+X509_REQ is used to express such a certificate request.
+
+To handle some complex parts of a certificate, there are the types
+X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express
+a certificate attributes), X509_EXTENSION (to express a certificate
+extension) and a few more.
+
+Finally, there's the supertype X509_INFO, which can contain a CRL, a
+certificate and a corresponding private key.
+
+B<X509_>I<XXX>, B<d2i_X509_>I<XXX>, and B<i2d_X509_>I<XXX> functions
+handle X.509 certificates, with some exceptions, shown below.
+
+B<X509_CRL_>I<XXX>, B<d2i_X509_CRL_>I<XXX>, and B<i2d_X509_CRL_>I<XXX>
+functions handle X.509 CRLs.
+
+B<X509_REQ_>I<XXX>, B<d2i_X509_REQ_>I<XXX>, and B<i2d_X509_REQ_>I<XXX>
+functions handle PKCS#10 certificate requests.
+
+B<X509_NAME_>I<XXX> functions handle certificate names.
+
+B<X509_ATTRIBUTE_>I<XXX> functions handle certificate attributes.
+
+B<X509_EXTENSION_>I<XXX> functions handle certificate extensions.
+
+=head1 SEE ALSO
+
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_add_entry_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_NAME_new(3)>,
+L<d2i_X509(3)>,
+L<d2i_X509_ALGOR(3)>,
+L<d2i_X509_CRL(3)>,
+L<d2i_X509_NAME(3)>,
+L<d2i_X509_REQ(3)>,
+L<d2i_X509_SIG(3)>,
+L<X509v3(3)>,
+L<crypto(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2003-2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut