Generally modernize the language.

Refer to TLS instead of SSL/TLS, and try to have more consistent
usage of commas and that/which.

Reword some descriptions to avoid implying that a list of potential
reasons for behavior is an exhaustive list.

Clarify how get_session_cb() is only called on servers (i.e., in general,
and that it's given the session ID proposed by the client).

Clarify the semantics of the get_cb()'s "copy" argument.
The behavior seems to have changed in commit
8876bc05, though the behavior prior
to that commit was not to leave the reference-count unchanged if
*copy was not written to -- instead, libssl seemed to assume that the
callback already had incremented the reference count.
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10943)

(cherry picked from commit 06f876837a8ec76b28c42953731a156c0c3700e2)

CLA: trivial
Signed-off-by: NJakub Jelen <jjelen@redhat.com>
Reviewed-by: NKurt Roeckx <kurt@roeckx.be>
Reviewed-by: NRichard Levitte <levitte@openssl.org>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11299)

(cherry picked from commit c08dea30d4d127412097b39d9974ba6090041a7c)

(cherry picked from commit 88398d2a358f)

Additionally, remove an outdated paragraph mentioning the .rnd
file, which is obsolete in 1.1.1 since the RANDFILE entry was
removed from openssl.cnf in commit 1fd6afb5.

Also borrow some text from 'openssl(1)/Random State Options'
on master (commit a397aca43598) to emphasize that it is not
necessary anymore to restore and save the RNG state using the
'-rand' and '-writerand' options.
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11251)

CLA: trivial
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: NPaul Yang <kaishen.yy@antfin.com>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11253)

(cherry picked from commit 9f44e96e245993c8e7aaa9fadf1d6713c9c60915)

Reviewed-by: NNicola Tuveri <nic.tuv@gmail.com>

(cherry picked from commit 03d65ca2095777cf6314ad813eb7de5779c9b93d)
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/11232)

We change the description to be about the key rather than the
signature.  How the key size is related to the signature is explained
in the description of EVP_SignFinal() anyway.
Reviewed-by: NNicola Tuveri <nic.tuv@gmail.com>

(cherry picked from commit 6942a0d6feb8d3dcbbc6a1ec6be9de7ab2df1530)
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/11232)

OpenSSL 1.1.0 has extended option checking, and rejects passing a PKCS#11
engine URL to "-signkey" option. The actual code is ready to take it.

Change the option parsing to allow an engine URL to be passed and modify
the manpage accordingly.

CLA: trivial

(cherry picked from commit 16d560439d8b1be5082228a87576a8f79b3525ac)
Reviewed-by: NShane Lontis <shane.lontis@oracle.com>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11173)

EVP_PKEY_get_raw_private_key() and EVP_PKEY_get_raw_public_key() expect
the size of the key buffer to be populated in the |*len| parameter on
entry - but the docs made no mention of this.

Fixes #11245
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11254)

(cherry picked from commit f529fc7d53bf4228fae61cb1efe73d97fe3eb35f)

Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11120)

Most of all, the base X509_LOOKUP functionality is now documented.
Furthermore, the names X509_LOOKUP_METHOD and X509_STORE are added for
reference.

Some functions were moved from X509_LOOKUP_meth_new.pod
Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11120)

CAkeyform may be set to PEM, DER or ENGINE, but the current options
are not using the proper optionformat 'E' (OPT_FMT_PDE) for this.

Set the valtype for CAkeyform to 'E' and use OPT_FMT_PDE when extracting
the option value.

This amends bf4006a6 ("Fix regression on x509 keyform argument") which
did the same thing for keyform and changed the manpage synopsis entries
for both keyform and CAkeyform but did not change the option section.
Hence, change the option section.

CLA: trivial
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11172)

The BIO_f_buffer() documentation tells in enough detail how it affects
BIO_gets(), but not how it affects BIO_read_ex().  This change
remedies that.

Fixes #10859
Reviewed-by: NTim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10890)

(cherry picked from commit 9a4fd80ee0ad1833879b6a55c9c4673eeb8446a3)

Fixes #10998
Reviewed-by: NShane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11000)

CLA: trivial
Signed-off-by: NJakub Jelen <jjelen@redhat.com>
Reviewed-by: NRichard Levitte <levitte@openssl.org>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: NMatt Caswell <matt@openssl.org>
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10841)

(cherry picked from commit 099a398268a298557be784528ac1d94f0f44c97c)

CLA: trivial
Reviewed-by: NPaul Yang <kaishen.yy@antfin.com>
Reviewed-by: NMatt Caswell <matt@openssl.org>
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10810)

(cherry picked from commit 924d041fe0c650a79449217f81880a6384ff06b2)

The behaviour of SSL_get_servername() is quite complicated and depends on
numerous factors such as whether it is called on the client or the server,
whether it is called before or after the handshake, what protocol version
was negotiated, and whether a resumption was attempted or was successful.

We attempt to document the behavior more clearly.
Reviewed-by: NBen Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/10018)

(cherry picked from commit 0dc7c8e8314f27ac093b2d7bc8f13d0dfd302bdb)

Reviewed-by: NMatt Caswell <matt@openssl.org>
Reviewed-by: NShane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10933)

(cherry picked from commit 68229aebce159ecea7b887d6a0edd47d881a659b)

Provide a "simple" example for affecting the systemwide default behavior
of libssl.  The large number of mandatory nested sections makes this
less simple than the main description might suggest.
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10937)

(cherry picked from commit 3472082b4b6d73e0803a7c47f03e96ec0a69f77b)

The existing documentation for the new-session callback was unclear
about the requirements on the callback with respect to reference-handling
of the session object being created.  Be more explicit about the
(non-)requirements on the callback code for "success" (1) and "ignore"
(0) return values.
Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10848)

(cherry picked from commit 188d4ec82a9b0085ac5841cce3eda95efb94f2b4)

They never returned the negative values that the documentation stated.
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10847)

Reviewed-by: NRichard Levitte <levitte@openssl.org>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10713)

In OpenSSL pre 1.1.0, 'openssl x509 -keyform engine' was possible
and supported.  In 1.1.0, type of keyform argument is OPT_FMT_PEMDER
which doesn't support engine. This changes type of keyform argument
to OPT_FMT_PDE which means PEM, DER or engine and updates the manpage
including keyform and CAkeyform.

This restores the pre 1.1.0 behavior.

This issue is very similar than https://github.com/openssl/openssl/issues/4366

CLA: trivial
Reviewed-by: NDmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: NMatt Caswell <matt@openssl.org>
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10609)

(cherry picked from commit 0ab6fc79a9a63370be1a615729dc2a6ed0d6c89b)

Make a note of when this function was first introduced
Reviewed-by: NRichard Levitte <levitte@openssl.org>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10568)

This is a missing accessor in order to obtain PSS parameters from an
RSA key, which should also be available in 1.1.1.
Reviewed-by: NRichard Levitte <levitte@openssl.org>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10568)

Fixes #9300
Reviewed-by: NMatt Caswell <matt@openssl.org>
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10523)

(cherry picked from commit 20c09f00346aec3a20ceacc9c9d44c5f050e13dd)

Reported-by: misspell-fixer <https://github.com/vlajos/misspell-fixer>

CLA: trivial
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10544)

(cherry picked from commit 79c44b4e3044aee9dc9618850d4f1ce067757b4b)

Fixes #10455
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10550)

Reviewed-by: NMatt Caswell <matt@openssl.org>
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10420)

This replaces doc/HOWTO/proxy_certificates.txt
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10507)

(cherry picked from commit 2a03823606b2d7e73e5dc890c3202e186511151f)

Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10388)

(cherry picked from commit 2555285fa5e4248ad4a5a0bc14ae4606443856c2)

Add more explicit documentation about the relation between
EC_POINT_point2oct(), EC_POINT_point2hex(), EC_POINT_point2bn() and
their reverse.

In particular highlight that EC_POINT_point2oct() and
EC_POINT_oct2point() conform to, respectively, Sec. 2.3.3 and Sec. 2.3.4
of the SECG SEC 1 standard (which is the normative reference for the
already mentioned RFC 5480), highlighting with a note how this affect
the encoding/decoding of the point at infinity (which in contrast with
any other valid generic point of a curve is assigned an exceptional
fixed octet string encoding, i.e., 0x00).
Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10329)

(cherry picked from commit 3cc26f2eba8a8c16ac559e68c05c094d7ea6bd8b)

This also removes the incorrect documentation comments by those
functions.
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10403)

Reviewed-by: NRichard Levitte <levitte@openssl.org>
Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9823)

(cherry picked from commit 2aa28a1abc893fb16b99ba77e2fecb1cbc8769c7)

The introductory paragraph for the TLSv1.3 server side PSK documentation
is a copy & paste of the client side documentation which has not been
updated with the server side equivalent information.
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10245)

(cherry picked from commit c549cb46e0d3cb4e611acafae5f919b4a8df4007)

(cherry picked from commit eb2ff0408ac6e934e05db7ed4006855c018584f1)
Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10235)

- Use `()` to qualify function names, consistently
- Limit line width to 80 chars
Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10235)

Fixes #9893
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10219)

for the following functions.

EC_GROUP_get_order
EC_GROUP_get_cofactor
EC_GROUP_get_curve_name
EC_GROUP_get_asn1_flag
EC_GROUP_get_point_conversion_form
EC_GROUP_get_degree

(cherry picked from commit df3d1e84b3802acffeec11d6224e8a0e33d0aa83)
Reviewed-by: NNicola Tuveri <nic.tuv@gmail.com>
Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9664)

find-doc-nits complains if a symbol is documented in more than one
location.
Reviewed-by: NRichard Levitte <levitte@openssl.org>

(cherry picked from commit 4ff4e53f816855b07fc02dc931dd57b2ae324aa1)
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10094)

The output format now matches coreutils *dgst tools.

[ edited to remove trailing white space ]
Reviewed-by: NRichard Levitte <levitte@openssl.org>
Reviewed-by: NPaul Dale <paul.dale@oracle.com>

(cherry picked from commit f3448f5481a8d1f6fbf5fd05caaca229af0b87f7)
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: NMatt Caswell <matt@openssl.org>
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10094)