aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/HOWTO/proxy_certificates.txt319
-rw-r--r--doc/man1/ca.pod6
-rw-r--r--doc/man1/dgst.pod9
-rw-r--r--doc/man1/enc.pod9
-rw-r--r--doc/man1/rand.pod35
-rw-r--r--doc/man1/req.pod8
-rw-r--r--doc/man1/s_client.pod4
-rw-r--r--doc/man1/sess_id.pod4
-rw-r--r--doc/man1/x509.pod19
-rw-r--r--doc/man3/ASN1_INTEGER_get_int64.pod4
-rw-r--r--doc/man3/ASN1_TYPE_get.pod4
-rw-r--r--doc/man3/BIO_f_buffer.pod20
-rw-r--r--doc/man3/BIO_get_ex_new_index.pod6
-rw-r--r--doc/man3/DTLSv1_listen.pod12
-rw-r--r--doc/man3/EC_GROUP_copy.pod90
-rw-r--r--doc/man3/EC_GROUP_new.pod102
-rw-r--r--doc/man3/EC_POINT_new.pod20
-rw-r--r--doc/man3/EVP_DigestInit.pod96
-rw-r--r--doc/man3/EVP_DigestSignInit.pod10
-rw-r--r--doc/man3/EVP_DigestVerifyInit.pod2
-rw-r--r--doc/man3/EVP_EncryptInit.pod9
-rw-r--r--doc/man3/EVP_MD_meth_new.pod21
-rw-r--r--doc/man3/EVP_PKEY_CTX_ctrl.pod16
-rw-r--r--doc/man3/EVP_PKEY_meth_new.pod32
-rw-r--r--doc/man3/EVP_PKEY_new.pod31
-rw-r--r--doc/man3/EVP_PKEY_size.pod80
-rw-r--r--doc/man3/EVP_SignInit.pod44
-rw-r--r--doc/man3/OCSP_request_add1_nonce.pod4
-rw-r--r--doc/man3/OCSP_response_status.pod4
-rw-r--r--doc/man3/OCSP_sendreq_new.pod9
-rw-r--r--doc/man3/OPENSSL_malloc.pod4
-rw-r--r--doc/man3/OPENSSL_secure_malloc.pod4
-rw-r--r--doc/man3/PEM_bytes_read_bio.pod4
-rw-r--r--doc/man3/PEM_read_bio_PrivateKey.pod12
-rw-r--r--doc/man3/PEM_read_bio_ex.pod2
-rw-r--r--doc/man3/RAND_bytes.pod26
-rw-r--r--doc/man3/RAND_set_rand_method.pod2
-rw-r--r--doc/man3/RSA_get0_key.pod7
-rw-r--r--doc/man3/SSL_CTX_sess_set_get_cb.pod57
-rw-r--r--doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod69
-rw-r--r--doc/man3/SSL_CTX_set_tlsext_servername_callback.pod122
-rw-r--r--doc/man3/SSL_CTX_use_psk_identity_hint.pod6
-rw-r--r--doc/man3/SSL_SESSION_get0_hostname.pod7
-rw-r--r--doc/man3/SSL_accept.pod4
-rw-r--r--doc/man3/SSL_connect.pod4
-rw-r--r--doc/man3/SSL_do_handshake.pod4
-rw-r--r--doc/man3/SSL_load_client_CA_file.pod19
-rw-r--r--doc/man3/X509_LOOKUP.pod212
-rw-r--r--doc/man3/X509_LOOKUP_meth_new.pod23
-rw-r--r--doc/man3/X509_STORE_CTX_new.pod2
-rw-r--r--doc/man3/X509_STORE_add_cert.pod17
-rw-r--r--doc/man3/d2i_X509.pod5
-rw-r--r--doc/man5/config.pod18
-rw-r--r--doc/man7/Ed25519.pod4
-rw-r--r--doc/man7/X25519.pod4
-rw-r--r--doc/man7/passphrase-encoding.pod4
-rw-r--r--doc/man7/proxy-certificates.pod363
57 files changed, 1410 insertions, 624 deletions
diff --git a/doc/HOWTO/proxy_certificates.txt b/doc/HOWTO/proxy_certificates.txt
deleted file mode 100644
index 3c4234926111..000000000000
--- a/doc/HOWTO/proxy_certificates.txt
+++ /dev/null
@@ -1,319 +0,0 @@
- HOWTO proxy certificates
-
-0. WARNING
-
-NONE OF THE CODE PRESENTED HERE HAS BEEN CHECKED! The code is just examples to
-show you how things could be done. There might be typos or type conflicts, and
-you will have to resolve them.
-
-1. Introduction
-
-Proxy certificates are defined in RFC 3820. They are really usual certificates
-with the mandatory extension proxyCertInfo.
-
-Proxy certificates are issued by an End Entity (typically a user), either
-directly with the EE certificate as issuing certificate, or by extension through
-an already issued proxy certificate. Proxy certificates are used to extend
-rights to some other entity (a computer process, typically, or sometimes to the
-user itself). This allows the entity to perform operations on behalf of the
-owner of the EE certificate.
-
-See https://www.ietf.org/rfc/rfc3820.txt for more information.
-
-
-2. A warning about proxy certificates
-
-No one seems to have tested proxy certificates with security in mind. To this
-date, it seems that proxy certificates have only been used in a context highly
-aware of them.
-
-Existing applications might misbehave when trying to validate a chain of
-certificates which use a proxy certificate. They might incorrectly consider the
-leaf to be the certificate to check for authorisation data, which is controlled
-by the EE certificate owner.
-
-subjectAltName and issuerAltName are forbidden in proxy certificates, and this
-is enforced in OpenSSL. The subject must be the same as the issuer, with one
-commonName added on.
-
-Possible threats we can think of at this time include:
-
- - impersonation through commonName (think server certificates).
- - use of additional extensions, possibly non-standard ones used in certain
- environments, that would grant extra or different authorisation rights.
-
-For these reasons, OpenSSL requires that the use of proxy certificates be
-explicitly allowed. Currently, this can be done using the following methods:
-
- - if the application directly calls X509_verify_cert(), it can first call:
-
- X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
-
- Where ctx is the pointer which then gets passed to X509_verify_cert().
-
- - proxy certificate validation can be enabled before starting the application
- by setting the environment variable OPENSSL_ALLOW_PROXY_CERTS.
-
-In the future, it might be possible to enable proxy certificates by editing
-openssl.cnf.
-
-
-3. How to create proxy certificates
-
-Creating proxy certificates is quite easy, by taking advantage of a lack of
-checks in the 'openssl x509' application (*ahem*). You must first create a
-configuration section that contains a definition of the proxyCertInfo extension,
-for example:
-
- [ v3_proxy ]
- # A proxy certificate MUST NEVER be a CA certificate.
- basicConstraints=CA:FALSE
-
- # Usual authority key ID
- authorityKeyIdentifier=keyid,issuer:always
-
- # The extension which marks this certificate as a proxy
- proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB
-
-It's also possible to specify the proxy extension in a separate section:
-
- proxyCertInfo=critical,@proxy_ext
-
- [ proxy_ext ]
- language=id-ppl-anyLanguage
- pathlen=0
- policy=text:BC
-
-The policy value has a specific syntax, {syntag}:{string}, where the syntag
-determines what will be done with the string. The following syntags are
-recognised:
-
- text indicates that the string is simply bytes, without any encoding:
-
- policy=text:räksmörgås
-
- Previous versions of this design had a specific tag for UTF-8 text.
- However, since the bytes are copied as-is anyway, there is no need for
- such a specific tag.
-
- hex indicates the string is encoded in hex, with colons between each byte
- (every second hex digit):
-
- policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73
-
- Previous versions of this design had a tag to insert a complete DER
- blob. However, the only legal use for this would be to surround the
- bytes that would go with the hex: tag with whatever is needed to
- construct a correct OCTET STRING. The DER tag therefore felt
- superfluous, and was removed.
-
- file indicates that the text of the policy should really be taken from a
- file. The string is then really a file name. This is useful for
- policies that are large (more than a few lines, e.g. XML documents).
-
-The 'policy' setting can be split up in multiple lines like this:
-
- 0.policy=This is
- 1.policy= a multi-
- 2.policy=line policy.
-
-NOTE: the proxy policy value is the part which determines the rights granted to
-the process using the proxy certificate. The value is completely dependent on
-the application reading and interpreting it!
-
-Now that you have created an extension section for your proxy certificate, you
-can easily create a proxy certificate by doing:
-
- openssl req -new -config openssl.cnf -out proxy.req -keyout proxy.key
- openssl x509 -req -CAcreateserial -in proxy.req -days 7 -out proxy.crt \
- -CA user.crt -CAkey user.key -extfile openssl.cnf -extensions v3_proxy
-
-You can also create a proxy certificate using another proxy certificate as
-issuer (note: I'm using a different configuration section for it):
-
- openssl req -new -config openssl.cnf -out proxy2.req -keyout proxy2.key
- openssl x509 -req -CAcreateserial -in proxy2.req -days 7 -out proxy2.crt \
- -CA proxy.crt -CAkey proxy.key -extfile openssl.cnf -extensions v3_proxy2
-
-
-4. How to have your application interpret the policy?
-
-The basic way to interpret proxy policies is to start with some default rights,
-then compute the resulting rights by checking the proxy certificate against
-the chain of proxy certificates, user certificate and CA certificates. You then
-use the final computed rights. Sounds easy, huh? It almost is.
-
-The slightly complicated part is figuring out how to pass data between your
-application and the certificate validation procedure.
-
-You need the following ingredients:
-
- - a callback function that will be called for every certificate being
- validated. The callback be called several times for each certificate,
- so you must be careful to do the proxy policy interpretation at the right
- time. You also need to fill in the defaults when the EE certificate is
- checked.
-
- - a data structure that is shared between your application code and the
- callback.
-
- - a wrapper function that sets it all up.
-
- - an ex_data index function that creates an index into the generic ex_data
- store that is attached to an X509 validation context.
-
-Here is some skeleton code you can fill in:
-
- #include <string.h>
- #include <netdb.h>
- #include <openssl/x509.h>
- #include <openssl/x509v3.h>
-
- #define total_rights 25
-
- /*
- * In this example, I will use a view of granted rights as a bit
- * array, one bit for each possible right.
- */
- typedef struct your_rights {
- unsigned char rights[(total_rights + 7) / 8];
- } YOUR_RIGHTS;
-
- /*
- * The following procedure will create an index for the ex_data
- * store in the X509 validation context the first time it's called.
- * Subsequent calls will return the same index. */
- static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx)
- {
- static volatile int idx = -1;
- if (idx < 0) {
- X509_STORE_lock(X509_STORE_CTX_get0_store(ctx));
- if (idx < 0) {
- idx = X509_STORE_CTX_get_ex_new_index(0,
- "for verify callback",
- NULL,NULL,NULL);
- }
- X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx));
- }
- return idx;
- }
-
- /* Callback to be given to the X509 validation procedure. */
- static int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
- if (ok == 1) {
- /*
- * It's REALLY important you keep the proxy policy
- * check within this section. It's important to know
- * that when ok is 1, the certificates are checked
- * from top to bottom. You get the CA root first,
- * followed by the possible chain of intermediate
- * CAs, followed by the EE certificate, followed by
- * the possible proxy certificates.
- */
- X509 *xs = X509_STORE_CTX_get_current_cert(ctx);
-
- if (X509_get_extension_flags(xs) & EXFLAG_PROXY) {
- YOUR_RIGHTS *rights =
- (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
- get_proxy_auth_ex_data_idx(ctx));
- PROXY_CERT_INFO_EXTENSION *pci =
- X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
-
- switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) {
- case NID_Independent:
- /*
- * Do whatever you need to grant explicit rights to
- * this particular proxy certificate, usually by
- * pulling them from some database. If there are none
- * to be found, clear all rights (making this and any
- * subsequent proxy certificate void of any rights).
- */
- memset(rights->rights, 0, sizeof(rights->rights));
- break;
- case NID_id_ppl_inheritAll:
- /*
- * This is basically a NOP, we simply let the current
- * rights stand as they are.
- */
- break;
- default:
- /* This is usually the most complex section of code.
- * You really do whatever you want as long as you
- * follow RFC 3820. In the example we use here, the
- * simplest thing to do is to build another, temporary
- * bit array and fill it with the rights granted by
- * the current proxy certificate, then use it as a
- * mask on the accumulated rights bit array, and
- * voilà, you now have a new accumulated rights bit
- * array.
- */
- {
- int i;
- YOUR_RIGHTS tmp_rights;
- memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights));
-
- /*
- * process_rights() is supposed to be a procedure
- * that takes a string and its length, interprets
- * it and sets the bits in the YOUR_RIGHTS pointed
- * at by the third argument.
- */
- process_rights((char *) pci->proxyPolicy->policy->data,
- pci->proxyPolicy->policy->length,
- &tmp_rights);
-
- for(i = 0; i < total_rights / 8; i++)
- rights->rights[i] &= tmp_rights.rights[i];
- }
- break;
- }
- PROXY_CERT_INFO_EXTENSION_free(pci);
- } else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) {
- /* We have an EE certificate, let's use it to set default! */
- YOUR_RIGHTS *rights =
- (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
- get_proxy_auth_ex_data_idx(ctx));
-
- /* The following procedure finds out what rights the owner
- * of the current certificate has, and sets them in the
- * YOUR_RIGHTS structure pointed at by the second
- * argument.
- */
- set_default_rights(xs, rights);
- }
- }
- return ok;
- }
-
- static int my_X509_verify_cert(X509_STORE_CTX *ctx,
- YOUR_RIGHTS *needed_rights)
- {
- int ok;
- int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) =
- X509_STORE_CTX_get_verify_cb(ctx);
- YOUR_RIGHTS rights;
-
- X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
- X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx), &rights);
- X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
- ok = X509_verify_cert(ctx);
-
- if (ok == 1) {
- ok = check_needed_rights(rights, needed_rights);
- }
-
- X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
-
- return ok;
- }
-
-
-If you use SSL or TLS, you can easily set up a callback to have the
-certificates checked properly, using the code above:
-
- SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert, &needed_rights);
-
-
---
-Richard Levitte
diff --git a/doc/man1/ca.pod b/doc/man1/ca.pod
index 7385a00941ea..27bb31493a7f 100644
--- a/doc/man1/ca.pod
+++ b/doc/man1/ca.pod
@@ -51,6 +51,7 @@ B<openssl> B<ca>
[B<-engine id>]
[B<-subj arg>]
[B<-utf8>]
+[B<-sigopt nm:v>]
[B<-create_serial>]
[B<-rand_serial>]
[B<-multivalue-rdn>]
@@ -134,6 +135,11 @@ The private key to sign requests with.
The format of the data in the private key file.
The default is PEM.
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
=item B<-key password>
The password used to encrypt the private key. Since on some
diff --git a/doc/man1/dgst.pod b/doc/man1/dgst.pod
index 66a6697eb10e..ea2c4e3e1598 100644
--- a/doc/man1/dgst.pod
+++ b/doc/man1/dgst.pod
@@ -12,6 +12,7 @@ B<openssl dgst>
[B<-help>]
[B<-c>]
[B<-d>]
+[B<-list>]
[B<-hex>]
[B<-binary>]
[B<-r>]
@@ -22,6 +23,7 @@ B<openssl dgst>
[B<-verify filename>]
[B<-prverify filename>]
[B<-signature filename>]
+[B<-sigopt nm:v>]
[B<-hmac key>]
[B<-fips-fingerprint>]
[B<-rand file...>]
@@ -66,6 +68,10 @@ B<hex> format output is used.
Print out BIO debugging information.
+=item B<-list>
+
+Prints out a list of supported message digests.
+
=item B<-hex>
Digest is to be output as a hex dump. This is the default case for a "normal"
@@ -78,7 +84,8 @@ Output the digest or signature in binary form.
=item B<-r>
-Output the digest in the "coreutils" format used by programs like B<sha1sum>.
+Output the digest in the "coreutils" format, including newlines.
+Used by programs like B<sha1sum>.
=item B<-out filename>
diff --git a/doc/man1/enc.pod b/doc/man1/enc.pod
index a3e0b03b2000..6f20ac1fc7d5 100644
--- a/doc/man1/enc.pod
+++ b/doc/man1/enc.pod
@@ -9,6 +9,7 @@ enc - symmetric cipher routines
B<openssl enc -I<cipher>>
[B<-help>]
+[B<-list>]
[B<-ciphers>]
[B<-in filename>]
[B<-out filename>]
@@ -56,10 +57,14 @@ either by itself or in addition to the encryption or decryption.
Print out a usage message.
-=item B<-ciphers>
+=item B<-list>
List all supported ciphers.
+=item B<-ciphers>
+
+Alias of -list to display all supported ciphers.
+
=item B<-in filename>
The input filename, standard input by default.
@@ -419,6 +424,8 @@ certain parameters. So if, for example, you want to use RC2 with a
The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0.
+The B<-list> option was added in OpenSSL 1.1.1e.
+
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man1/rand.pod b/doc/man1/rand.pod
index 5dd9e8e0a56a..b5d45ab51cf0 100644
--- a/doc/man1/rand.pod
+++ b/doc/man1/rand.pod
@@ -18,12 +18,14 @@ I<num>
=head1 DESCRIPTION
-The B<rand> command outputs I<num> pseudo-random bytes after seeding
-the random number generator once. As in other B<openssl> command
-line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd>
-in addition to the files given in the B<-rand> option. A new
-I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough
-seeding was obtained from these sources.
+This command generates I<num> random bytes using a cryptographically
+secure pseudo random number generator (CSPRNG).
+
+The random bytes are generated using the L<RAND_bytes(3)> function,
+which provides a security level of 256 bits, provided it managed to
+seed itself successfully from a trusted operating system entropy source.
+Otherwise, the command will fail with a nonzero error code.
+For more details, see L<RAND_bytes(3)>, L<RAND(7)>, and L<RAND_DRBG(7)>.
=head1 OPTIONS
@@ -44,6 +46,8 @@ generator.
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
+Explicitly specifying a seed file is in general not necessary, see the
+L</NOTES> section for more information.
=item [B<-writerand file>]
@@ -60,13 +64,28 @@ Show the output as a hex string.
=back
+=head1 NOTES
+
+Prior to OpenSSL 1.1.1, it was common for applications to store information
+about the state of the random-number generator in a file that was loaded
+at startup and rewritten upon exit. On modern operating systems, this is
+generally no longer necessary as OpenSSL will seed itself from a trusted
+entropy source provided by the operating system. The B<-rand> and
+B<-writerand> flags are still supported for special platforms or
+circumstances that might require them.
+
+It is generally an error to use the same seed file more than once and
+every use of B<-rand> should be paired with B<-writerand>.
+
=head1 SEE ALSO
-L<RAND_bytes(3)>
+L<RAND_bytes(3)>,
+L<RAND(7)>,
+L<RAND_DRBG(7)>
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man1/req.pod b/doc/man1/req.pod
index a9b5b1690a5c..730c59079d67 100644
--- a/doc/man1/req.pod
+++ b/doc/man1/req.pod
@@ -46,6 +46,7 @@ B<openssl> B<req>
[B<-reqopt>]
[B<-subject>]
[B<-subj arg>]
+[B<-sigopt nm:v>]
[B<-batch>]
[B<-verbose>]
[B<-engine id>]
@@ -82,6 +83,11 @@ This specifies the input filename to read a request from or standard input
if this option is not specified. A request is only read if the creation
options (B<-new> and B<-newkey>) are not specified.
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
=item B<-passin arg>
The input file password source. For more information about the format of B<arg>
@@ -689,7 +695,7 @@ L<x509v3_config(5)>
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 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
diff --git a/doc/man1/s_client.pod b/doc/man1/s_client.pod
index e2475ea0678f..68a152a272bd 100644
--- a/doc/man1/s_client.pod
+++ b/doc/man1/s_client.pod
@@ -335,7 +335,7 @@ at a positive depth or else "matched EE certificate" at depth 0.
Use one or more times to specify the RRDATA fields of the DANE TLSA
RRset associated with the target service. The B<rrdata> value is
-specied in "presentation form", that is four whitespace separated
+specified in "presentation form", that is four whitespace separated
fields that specify the usage, selector, matching type and associated
data, with the last of these encoded in hexadecimal. Optional
whitespace is ignored in the associated data field. For example:
@@ -828,7 +828,7 @@ The B<-name> option was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man1/sess_id.pod b/doc/man1/sess_id.pod
index 1f7a1e8670cf..6c54ed988bbe 100644
--- a/doc/man1/sess_id.pod
+++ b/doc/man1/sess_id.pod
@@ -93,7 +93,7 @@ Typical output:
Timeout : 300 (sec)
Verify return code 0 (ok)
-Theses are described below in more detail.
+These are described below in more detail.
=over 4
@@ -156,7 +156,7 @@ L<ciphers(1)>, L<s_server(1)>
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man1/x509.pod b/doc/man1/x509.pod
index 7878753414da..65cec9dbda67 100644
--- a/doc/man1/x509.pod
+++ b/doc/man1/x509.pod
@@ -11,7 +11,7 @@ B<openssl> B<x509>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
-[B<-keyform DER|PEM>]
+[B<-keyform DER|PEM|ENGINE>]
[B<-CAform DER|PEM>]
[B<-CAkeyform DER|PEM>]
[B<-in filename>]
@@ -44,7 +44,7 @@ B<openssl> B<x509>
[B<-setalias arg>]
[B<-days arg>]
[B<-set_serial n>]
-[B<-signkey filename>]
+[B<-signkey arg>]
[B<-passin arg>]
[B<-x509toreq>]
[B<-req>]
@@ -61,6 +61,7 @@ B<openssl> B<x509>
[B<-clrext>]
[B<-extfile filename>]
[B<-extensions section>]
+[B<-sigopt nm:v>]
[B<-rand file...>]
[B<-writerand file>]
[B<-engine id>]
@@ -349,10 +350,11 @@ can thus behave like a "mini CA".
=over 4
-=item B<-signkey filename>
+=item B<-signkey arg>
This option causes the input file to be self signed using the supplied
-private key.
+private key or engine. The private key's format is specified with the
+B<-keyform> option.
If the input file is a certificate it sets the issuer name to the
subject name (i.e. makes it self signed) changes the public key to the
@@ -366,6 +368,11 @@ If the input is a certificate request then a self signed certificate
is created using the supplied private key using the subject name in
the request.
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
=item B<-passin arg>
The key password source. For more information about the format of B<arg>
@@ -378,7 +385,7 @@ certificate is being created from another certificate (for example with
the B<-signkey> or the B<-CA> options). Normally all extensions are
retained.
-=item B<-keyform PEM|DER>
+=item B<-keyform PEM|DER|ENGINE>
Specifies the format (DER or PEM) of the private key file used in the
B<-signkey> option.
@@ -925,7 +932,7 @@ the old form must have their links rebuilt using B<c_rehash> or similar.
=head1 COPYRIGHT
-Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man3/ASN1_INTEGER_get_int64.pod b/doc/man3/ASN1_INTEGER_get_int64.pod
index 9b73290742d4..ac6a5799df9d 100644
--- a/doc/man3/ASN1_INTEGER_get_int64.pod
+++ b/doc/man3/ASN1_INTEGER_get_int64.pod
@@ -22,10 +22,10 @@ ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_s
ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
- int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
+ int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a);
long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
- int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
+ int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r);
int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
diff --git a/doc/man3/ASN1_TYPE_get.pod b/doc/man3/ASN1_TYPE_get.pod
index 70c56878b8e6..fb797220a47f 100644
--- a/doc/man3/ASN1_TYPE_get.pod
+++ b/doc/man3/ASN1_TYPE_get.pod
@@ -69,7 +69,7 @@ If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
return value is non-zero. Technically if both parameters are NULL the two
types could be absent OPTIONAL fields and so should match, however passing
NULL values could also indicate a programming error (for example an
-unparseable type which returns NULL) for types which do B<not> match. So
+unparsable type which returns NULL) for types which do B<not> match. So
applications should handle the case of two absent values separately.
=head1 RETURN VALUES
@@ -90,7 +90,7 @@ NULL on failure.
=head1 COPYRIGHT
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2020 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
diff --git a/doc/man3/BIO_f_buffer.pod b/doc/man3/BIO_f_buffer.pod
index 8ceaaa3c0343..047a11d2407c 100644
--- a/doc/man3/BIO_f_buffer.pod
+++ b/doc/man3/BIO_f_buffer.pod
@@ -49,10 +49,20 @@ is expanded.
These functions, other than BIO_f_buffer(), are implemented as macros.
-Buffering BIOs implement BIO_gets() by using BIO_read_ex() operations on the
-next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
-possible to provide BIO_gets() functionality if the following BIOs do not
-support it (for example SSL BIOs).
+Buffering BIOs implement BIO_read_ex() and BIO_gets() by using
+BIO_read_ex() operations on the next BIO in the chain and storing the
+result in an internal buffer, from which bytes are given back to the
+caller as appropriate for the call; a BIO_gets() is guaranteed to give
+the caller a whole line, and BIO_read_ex() is guaranteed to give the
+caller the number of bytes it asks for, unless there's an error or end
+of communication is reached in the next BIO. By prepending a
+buffering BIO to a chain it is therefore possible to provide
+BIO_gets() or exact size BIO_read_ex() functionality if the following
+BIOs do not support it.
+
+Do not add more than one BIO_f_buffer() to a BIO chain. The result of
+doing so will force a full read of the size of the internal buffer of
+the top BIO_f_buffer(), which is 4 KiB at a minimum.
Data is only written to the next BIO in the chain when the write buffer fills
or when BIO_flush() is called. It is therefore important to call BIO_flush()
@@ -82,7 +92,7 @@ L<BIO_ctrl(3)>.
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod
index e61228f1caea..89008531d381 100644
--- a/doc/man3/BIO_get_ex_new_index.pod
+++ b/doc/man3/BIO_get_ex_new_index.pod
@@ -39,7 +39,7 @@ L<CRYPTO_get_ex_new_index(3)>.
These functions handle application-specific data for OpenSSL data
structures.
-TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
+TYPE_get_ex_new_index() is a macro that calls CRYPTO_get_ex_new_index()
with the correct B<index> value.
TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
@@ -50,7 +50,7 @@ an offset into the opaque exdata part of the TYPE object.
=head1 RETURN VALUES
-TYPE_get_new_ex_index() returns a new index on success or -1 on error.
+TYPE_get_ex_new_index() returns a new index on success or -1 on error.
TYPE_set_ex_data() returns 1 on success or 0 on error.
@@ -62,7 +62,7 @@ L<CRYPTO_get_ex_new_index(3)>.
=head1 COPYRIGHT
-Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2020 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
diff --git a/doc/man3/DTLSv1_listen.pod b/doc/man3/DTLSv1_listen.pod
index 76be40b68f10..98511a475f9f 100644
--- a/doc/man3/DTLSv1_listen.pod
+++ b/doc/man3/DTLSv1_listen.pod
@@ -66,9 +66,9 @@ the peer and continue the handshake in a connected state.
Prior to calling DTLSv1_listen() user code must ensure that cookie generation
and verification callbacks have been set up using
-SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
-respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb()
-and SSL_CTX_set_stateless_cookie_verify_cb() must be used instead.
+L<SSL_CTX_set_cookie_generate_cb(3)> and L<SSL_CTX_set_cookie_verify_cb(3)>
+respectively. For SSL_stateless(), L<SSL_CTX_set_stateless_cookie_generate_cb(3)>
+and L<SSL_CTX_set_stateless_cookie_verify_cb(3)> must be used instead.
Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
ClientHellos it is unable to process fragmented messages (since this would
@@ -112,8 +112,10 @@ errors as non-fatal), whilst return codes >0 indicate success.
=head1 SEE ALSO
-L<SSL_get_error(3)>, L<SSL_accept(3)>,
-L<ssl(7)>, L<bio(7)>
+L<SSL_CTX_set_cookie_generate_cb(3)>, L<SSL_CTX_set_cookie_verify_cb(3)>,
+L<SSL_CTX_set_stateless_cookie_generate_cb(3)>,
+L<SSL_CTX_set_stateless_cookie_verify_cb(3)>, L<SSL_get_error(3)>,
+L<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>
=head1 HISTORY
diff --git a/doc/man3/EC_GROUP_copy.pod b/doc/man3/EC_GROUP_copy.pod
index 7bf350062375..0d50fdc0c74f 100644
--- a/doc/man3/EC_GROUP_copy.pod
+++ b/doc/man3/EC_GROUP_copy.pod
@@ -40,7 +40,7 @@ EC_GROUP_get_pentanomial_basis
int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
- point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *);
+ point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *group);
unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x);
size_t EC_GROUP_get_seed_len(const EC_GROUP *);
@@ -61,34 +61,39 @@ EC_GROUP_get_pentanomial_basis
=head1 DESCRIPTION
-EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
+EC_GROUP_copy() copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
-EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created
+EC_GROUP_dup() creates a new EC_GROUP object and copies the content from B<src> to the newly created
EC_GROUP object.
-EC_GROUP_method_of obtains the EC_METHOD of B<group>.
+EC_GROUP_method_of() obtains the EC_METHOD of B<group>.
-EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These
+EC_GROUP_set_generator() sets curve parameters that must be agreed by all participants using the curve. These
parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve.
-EC_GROUP_get0_generator returns the generator for the identified B<group>.
+EC_GROUP_get0_generator() returns the generator for the identified B<group>.
-The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters
-with the respective order and cofactors for the B<group>.
+EC_GROUP_get_order() retrieves the order of B<group> and copies its value into
+B<order>. It fails in case B<group> is not fully initialized (i.e., its order
+is not set or set to zero).
-The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
+EC_GROUP_get_cofactor() retrieves the cofactor of B<group> and copies its value
+into B<cofactor>. It fails in case B<group> is not fully initialized or if the
+cofactor is not set (or set to zero).
+
+The functions EC_GROUP_set_curve_name() and EC_GROUP_get_curve_name(), set and get the NID for the curve respectively
(see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
-will return 0.
+will return NID_undef.
The asn1_flag value is used to determine whether the curve encoding uses
explicit parameters or a named curve using an ASN1 OID: many applications only
support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the
named curve form is used and the parameters must have a corresponding
named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the
-parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and
-EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve.
+parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag() and
+EC_GROUP_set_asn1_flag() get and set the status of the asn1_flag for the curve.
Note: B<OPENSSL_EC_EXPLICIT_CURVE> was added in OpenSSL 1.1.0, for
previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL
1.1.0 the default form was to use explicit parameters (meaning that
@@ -119,32 +124,32 @@ the two possible solutions for y has been used, followed by the octets for x.
For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
-The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form
+The functions EC_GROUP_set_point_conversion_form() and EC_GROUP_get_point_conversion_form(), set and get the point_conversion_form
for the curve respectively.
ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages
in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it.
If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library
-does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block
-containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the
-builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
-EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
+does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed(). This returns a pointer to a memory block
+containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len(). A number of the
+built-in curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
+EC_GROUP_set_seed() and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
this seed value, although it will be preserved in any ASN1 based communications.
-EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
+EC_GROUP_get_degree() gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
the value m.
-The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid.
+The function EC_GROUP_check_discriminant() calculates the discriminant for the curve and verifies that it is valid.
For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
simply b. In either case for the curve to be valid the discriminant must be non zero.
-The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include
+The function EC_GROUP_check() performs a number of checks on a curve to verify that it is valid. Checks performed include
verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
the correct order.
-EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
+EC_GROUP_cmp() compares B<a> and B<b> to determine whether they represent the same curve or not.
-The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
+The functions EC_GROUP_get_basis_type(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis() should only be called for curves
defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial
function f(x). This function is either a trinomial of the form:
@@ -154,39 +159,48 @@ or a pentanomial of the form:
f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
-The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
-function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
-the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
+The function EC_GROUP_get_basis_type() returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
+function EC_GROUP_get_trinomial_basis() must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
+the function EC_GROUP_get_pentanomial_basis() must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
B<k2> and B<k3> respectively.
=head1 RETURN VALUES
-The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check,
-EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis.
+The following functions return 1 on success or 0 on error: EC_GROUP_copy(), EC_GROUP_set_generator(), EC_GROUP_check(),
+EC_GROUP_check_discriminant(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis().
+
+EC_GROUP_dup() returns a pointer to the duplicated curve, or NULL on error.
+
+EC_GROUP_method_of() returns the EC_METHOD implementation in use for the given curve or NULL on error.
+
+EC_GROUP_get0_generator() returns the generator for the given curve or NULL on error.
+
+EC_GROUP_get_order() returns 0 if the order is not set (or set to zero) for
+B<group> or if copying into B<order> fails, 1 otherwise.
+
+EC_GROUP_get_cofactor() returns 0 if the cofactor is not set (or is set to zero) for B<group> or if copying into B<cofactor> fails, 1 otherwise.
-EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error.
+EC_GROUP_get_curve_name() returns the curve name (NID) for B<group> or will return NID_undef if no curve name is associated.
-EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error.
+EC_GROUP_get_asn1_flag() returns the ASN1 flag for the specified B<group> .
-EC_GROUP_get0_generator returns the generator for the given curve or NULL on error.
+EC_GROUP_get_point_conversion_form() returns the point_conversion_form for B<group>.
-EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form
-and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
-specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
+EC_GROUP_get_degree() returns the degree for B<group> or 0 if the operation is not supported by the underlying group implementation.
EC_GROUP_get0_order() returns an internal pointer to the group order.
EC_GROUP_order_bits() returns the number of bits in the group order.
EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor.
-EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
-specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
+EC_GROUP_get0_seed() returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
+specified. EC_GROUP_get_seed_len() returns the length of the seed or 0 if the seed is not specified.
-EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
+EC_GROUP_set_seed() returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
0, the return value will be 1. On error 0 is returned.
-EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
+EC_GROUP_cmp() returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
-EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
+EC_GROUP_get_basis_type() returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
=head1 SEE ALSO
diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod
index 1eee494927f5..c80b191785c4 100644
--- a/doc/man3/EC_GROUP_new.pod
+++ b/doc/man3/EC_GROUP_new.pod
@@ -57,49 +57,63 @@ objects
=head1 DESCRIPTION
-Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
-prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised
+Within the library there are two forms of elliptic curve that are of interest.
+The first form is those defined over the prime field Fp. The elements of Fp are
+the integers 0 to p-1, where p is a prime number. This gives us a revised
elliptic curve equation as follows:
y^2 mod p = x^3 +ax + b mod p
-The second form is those defined over a binary field F2^m where the elements of the field are integers of length at
-most m bits. For this form the elliptic curve equation is modified to:
+The second form is those defined over a binary field F2^m where the elements of
+the field are integers of length at most m bits. For this form the elliptic
+curve equation is modified to:
y^2 + xy = x^3 + ax^2 + b (where b != 0)
-Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
-use a trinomial or a pentanomial for this parameter.
-
-A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
-L<EC_GFp_simple_method(3)>). It is then necessary to call EC_GROUP_set_curve() to set the curve parameters.
-EC_GROUP_new_from_ecparameters() will create a group from the
-specified B<params> and
-EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>.
-
-EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve over Fp B<b>
-is the prime for the field. For a curve over F2^m B<p> represents the irreducible polynomial - each bit
-represents a term in the polynomial. Therefore there will either be three or five bits set dependent on whether
-the polynomial is a trinomial or a pentanomial.
+Operations in a binary field are performed relative to an B<irreducible
+polynomial>. All such curves with OpenSSL use a trinomial or a pentanomial for
+this parameter.
+
+A new curve can be constructed by calling EC_GROUP_new(), using the
+implementation provided by B<meth> (see L<EC_GFp_simple_method(3)>). It is then
+necessary to call EC_GROUP_set_curve() to set the curve parameters.
+EC_GROUP_new_from_ecparameters() will create a group from the specified
+B<params> and EC_GROUP_new_from_ecpkparameters() will create a group from the
+specific PK B<params>.
+
+EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve
+over Fp B<p> is the prime for the field. For a curve over F2^m B<p> represents
+the irreducible polynomial - each bit represents a term in the polynomial.
+Therefore there will either be three or five bits set dependent on whether the
+polynomial is a trinomial or a pentanomial.
+In either case, B<a> and B<b> represents the coefficients a and b from the
+relevant equation introduced above.
EC_group_get_curve() obtains the previously set curve parameters.
-EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for EC_GROUP_set_curve(). They are defined for
-backwards compatibility only and should not be used.
-
-EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for EC_GROUP_get_curve(). They are defined for
-backwards compatibility only and should not be used.
-
-The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and then the
-EC_GROUP_set_curve function. An appropriate default implementation method will be used.
-
-Whilst the library can be used to create any curve using the functions described above, there are also a number of
-predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
-EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
-will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
-curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
-provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
-not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
+EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for
+EC_GROUP_set_curve(). They are defined for backwards compatibility only and
+should not be used.
+
+EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for
+EC_GROUP_get_curve(). They are defined for backwards compatibility only and
+should not be used.
+
+The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m() are
+shortcuts for calling EC_GROUP_new() and then the EC_GROUP_set_curve() function.
+An appropriate default implementation method will be used.
+
+Whilst the library can be used to create any curve using the functions described
+above, there are also a number of predefined curves that are available. In order
+to obtain a list of all of the predefined curves, call the function
+EC_get_builtin_curves(). The parameter B<r> should be an array of
+EC_builtin_curve structures of size B<nitems>. The function will populate the
+B<r> array with information about the builtin curves. If B<nitems> is less than
+the total number of curves available, then the first B<nitems> curves will be
+returned. Otherwise the total number of curves will be provided. The return
+value is the total number of curves available (whether that number has been
+populated in B<r> or not). Passing a NULL B<r>, or setting B<nitems> to 0 will
+do nothing other than return the total number of curves available.
The EC_builtin_curve structure is defined as follows:
typedef struct {
@@ -107,24 +121,28 @@ The EC_builtin_curve structure is defined as follows:
const char *comment;
} EC_builtin_curve;
-Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
+Each EC_builtin_curve item has a unique integer id (B<nid>), and a human
+readable comment string describing the curve.
-In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to
+In order to construct a builtin curve use the function
+EC_GROUP_new_by_curve_name() and provide the B<nid> of the curve to
be constructed.
-EC_GROUP_free frees the memory associated with the EC_GROUP.
+EC_GROUP_free() frees the memory associated with the EC_GROUP.
If B<group> is NULL nothing is done.
-EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
-If B<group> is NULL nothing is done.
+EC_GROUP_clear_free() destroys any sensitive data held within the EC_GROUP and
+then frees its memory. If B<group> is NULL nothing is done.
=head1 RETURN VALUES
-All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
+All EC_GROUP_new* functions return a pointer to the newly constructed group, or
+NULL on error.
-EC_get_builtin_curves returns the number of builtin curves that are available.
+EC_get_builtin_curves() returns the number of builtin curves that are available.
-EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
+EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
+EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error.
=head1 SEE ALSO
@@ -134,7 +152,7 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
=head1 COPYRIGHT
-Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2013-2019 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
diff --git a/doc/man3/EC_POINT_new.pod b/doc/man3/EC_POINT_new.pod
index 796f6666dd38..8cadaa75f145 100644
--- a/doc/man3/EC_POINT_new.pod
+++ b/doc/man3/EC_POINT_new.pod
@@ -171,6 +171,26 @@ The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(),
EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from
and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively.
+The function EC_POINT_point2oct() encodes the given curve point B<p> as an
+octet string into the buffer B<buf> of size B<len>, using the specified
+conversion form B<form>.
+The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve
+Cryptography") standard.
+Similarly the function EC_POINT_oct2point() decodes a curve point into B<p> from
+the octet string contained in the given buffer B<buf> of size B<len>, conforming
+to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
+
+The functions EC_POINT_point2hex() and EC_POINT_point2bn() convert a point B<p>,
+respectively, to the hexadecimal or BIGNUM representation of the same
+encoding of the function EC_POINT_point2oct().
+Vice versa, similarly to the function EC_POINT_oct2point(), the functions
+EC_POINT_hex2point() and EC_POINT_point2bn() decode the hexadecimal or
+BIGNUM representation into the EC_POINT B<p>.
+
+Notice that, according to the standard, the octet string encoding of the point
+at infinity for a given curve is fixed to a single octet of value zero and that,
+vice versa, a single octet of size zero is decoded as the point at infinity.
+
The function EC_POINT_point2oct() must be supplied with a buffer long enough to
store the octet form. The return value provides the number of octets stored.
Calling the function with a NULL buffer will not perform the conversion but
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 3e3e34229763..434e22030fdd 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -2,17 +2,17 @@
=head1 NAME
-EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,
-EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags,
-EVP_MD_CTX_test_flags, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
+EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
+EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags,
+EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
+EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
-EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size,
-EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
-EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data,
+EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags,
+EVP_MD_CTX_md, EVP_MD_CTX_type, EVP_MD_CTX_size, EVP_MD_CTX_block_size,
+EVP_MD_CTX_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn,
EVP_md_null,
-EVP_get_digestbyname, EVP_get_digestbynid,
-EVP_get_digestbyobj,
-EVP_MD_CTX_set_pkey_ctx - EVP digest routines
+EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj,
+EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
=head1 SYNOPSIS
@@ -26,6 +26,8 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);
int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);
+ int EVP_Digest(const void *data, size_t count, unsigned char *md,
+ unsigned int *size, const EVP_MD *type, ENGINE *impl);
int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
@@ -42,12 +44,18 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
int EVP_MD_pkey_type(const EVP_MD *md);
int EVP_MD_size(const EVP_MD *md);
int EVP_MD_block_size(const EVP_MD *md);
+ unsigned long EVP_MD_flags(const EVP_MD *md);
const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
- int EVP_MD_CTX_size(const EVP_MD *ctx);
- int EVP_MD_CTX_block_size(const EVP_MD *ctx);
- int EVP_MD_CTX_type(const EVP_MD *ctx);
+ int EVP_MD_CTX_size(const EVP_MD_CTX *ctx);
+ int EVP_MD_CTX_block_size(const EVP_MD_CTX *ctx);
+ int EVP_MD_CTX_type(const EVP_MD_CTX *ctx);
void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
+ int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx,
+ const void *data, size_t count);
+ void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx,
+ int (*update)(EVP_MD_CTX *ctx,
+ const void *data, size_t count));
const EVP_MD *EVP_md_null(void);
@@ -55,6 +63,7 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
const EVP_MD *EVP_get_digestbynid(int type);
const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);
+ EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx);
void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);
=head1 DESCRIPTION
@@ -79,12 +88,24 @@ Cleans up digest context B<ctx> and frees up the space allocated to it.
=item EVP_MD_CTX_ctrl()
-Performs digest-specific control actions on context B<ctx>.
+Performs digest-specific control actions on context B<ctx>. The control command
+is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>.
+EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions
+may apply depending on the control type and digest implementation.
+See L</CONTROLS> below for more information.
=item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()
Sets, clears and tests B<ctx> flags. See L</FLAGS> below for more information.
+=item EVP_Digest()
+
+A wrapper around the Digest Init_ex, Update and Final_ex functions.
+Hashes B<count> bytes of data at B<data> using a digest B<type> from ENGINE
+B<impl>. The digest value is placed in B<md> and its length is written at B<size>
+if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written.
+If B<impl> is NULL the default implementation of digest B<type> is used.
+
=item EVP_DigestInit_ex()
Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
@@ -122,7 +143,7 @@ few bytes.
=item EVP_DigestInit()
Behaves in the same way as EVP_DigestInit_ex() except it always uses the
-default digest implementation.
+default digest implementation and calls EVP_MD_CTX_reset().
=item EVP_DigestFinal()
@@ -163,6 +184,21 @@ EVP_MD_meth_set_app_datasize().
Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>.
+=item EVP_MD_CTX_set_update_fn()
+
+Sets the update function for B<ctx> to B<update>.
+This is the function that is called by EVP_DigestUpdate. If not set, the
+update function from the B<EVP_MD> type specified at initialization is used.
+
+=item EVP_MD_CTX_update_fn()
+
+Returns the update function for B<ctx>.
+
+=item EVP_MD_flags()
+
+Returns the B<md> flags. Note that these are different from the B<EVP_MD_CTX>
+ones. See L<EVP_MD_meth_set_flags(3)> for more information.
+
=item EVP_MD_pkey_type()
Returns the NID of the public key signing algorithm associated with this
@@ -182,10 +218,15 @@ EVP_get_digestbyobj()
Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an
B<ASN1_OBJECT> structure respectively.
+=item EVP_MD_CTX_pkey_ctx()
+
+Returns the B<EVP_PKEY_CTX> assigned to B<ctx>. The returned pointer should not
+be freed by the caller.
+
=item EVP_MD_CTX_set_pkey_ctx()
Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide
-a customzied B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or
+a customized B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or
L<EVP_DigestVerifyInit(3)>. The B<pctx> passed to this function should be freed
by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX>
assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
@@ -193,6 +234,27 @@ depends on how the B<EVP_PKEY_CTX> is created.
=back
+=head1 CONTROLS
+
+EVP_MD_CTX_ctrl() can be used to send the following standard controls:
+
+=over 4
+
+=item EVP_MD_CTRL_MICALG
+
+Gets the digest Message Integrity Check algorithm string. This is used when
+creating S/MIME multipart/signed messages, as specified in RFC 3851.
+The string value is written to B<p2>.
+
+=item EVP_MD_CTRL_XOF_LEN
+
+This control sets the digest length for extendable output functions to B<p1>.
+Sending this control directly should not be necessary, the use of
+C<EVP_DigestFinalXOF()> is preferred.
+Currently used by SHAKE.
+
+=back
+
=head1 FLAGS
EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags()
@@ -245,8 +307,7 @@ Returns 1 if successful or 0 for failure.
Returns 1 if successful or 0 for failure.
=item EVP_MD_type(),
-EVP_MD_pkey_type(),
-EVP_MD_type()
+EVP_MD_pkey_type()
Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none
exists.
@@ -350,6 +411,7 @@ digest name passed on the command line.
=head1 SEE ALSO
+L<EVP_MD_meth_new(3)>,
L<dgst(1)>,
L<evp(7)>
diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod
index 0bbc3d0ff8f3..912880a5e1c5 100644
--- a/doc/man3/EVP_DigestSignInit.pod
+++ b/doc/man3/EVP_DigestSignInit.pod
@@ -36,7 +36,7 @@ EVP_MD_CTX is freed).
The digest B<type> may be NULL if the signing algorithm supports it.
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
-has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
+has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>. See also L<SM2(7)>.
Only EVP_PKEY types that support signing can be used with these functions. This
includes MAC algorithms where the MAC generation is considered as a form of
@@ -102,10 +102,8 @@ EVP_DigestSignFinal().
=head1 RETURN VALUES
-EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignaFinal() and
-EVP_DigestSign() return 1 for success and 0 or a negative value for failure. In
-particular, a return value of -2 indicates the operation is not supported by the
-public key algorithm.
+EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignFinal() and
+EVP_DigestSign() return 1 for success and 0 for failure.
The error codes can be obtained from L<ERR_get_error(3)>.
@@ -158,7 +156,7 @@ were added in OpenSSL 1.0.0.
=head1 COPYRIGHT
-Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2020 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
diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod
index 05b99bb913ce..0806cd5d58c4 100644
--- a/doc/man3/EVP_DigestVerifyInit.pod
+++ b/doc/man3/EVP_DigestVerifyInit.pod
@@ -33,7 +33,7 @@ inside EVP_DigestVerifyInit() and it will be freed automatically when the
EVP_MD_CTX is freed).
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
-has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
+has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>. See also L<SM2(7)>.
EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
verification context B<ctx>. This function can be called several times on the
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 6b068617b0ad..aaf9975c4c26 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -492,6 +492,15 @@ EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
existing context without allocating and freeing it up on each call.
+There are some differences between functions EVP_CipherInit() and
+EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills
+the passed context object with zeros. As a consequence, EVP_CipherInit() does
+not allow step-by-step initialization of the ctx when the I<key> and I<iv> are
+passed in separate calls. It also means that the flags set for the CTX are
+removed, and it is especially important for the
+B<EVP_CIPHER_CTX_FLAG_WRAP_ALLOW> flag treated specially in
+EVP_CipherInit_ex().
+
EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.
=head1 BUGS
diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod
index 0265c7d50456..e17a4cd519ab 100644
--- a/doc/man3/EVP_MD_meth_new.pod
+++ b/doc/man3/EVP_MD_meth_new.pod
@@ -84,7 +84,12 @@ together. The available flags are:
=item EVP_MD_FLAG_ONESHOT
-This digest method can only handles one block of input.
+This digest method can only handle one block of input.
+
+=item EVP_MD_FLAG_XOF
+
+This digest method is an extensible-output function (XOF) and supports
+the B<EVP_MD_CTRL_XOF_LEN> control.
=item EVP_MD_FLAG_DIGALGID_NULL
@@ -105,19 +110,24 @@ B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
Currently unused.
+=item EVP_MD_FLAG_FIPS
+
+This digest method is suitable for use in FIPS mode.
+Currently unused.
+
=back
EVP_MD_meth_set_init() sets the digest init function for B<md>.
-The digest init function is called by EVP_DigestInit(),
+The digest init function is called by EVP_Digest(), EVP_DigestInit(),
EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
and EVP_VerifyInit_ex().
EVP_MD_meth_set_update() sets the digest update function for B<md>.
-The digest update function is called by EVP_DigestUpdate(),
+The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and
EVP_SignUpdate().
EVP_MD_meth_set_final() sets the digest final function for B<md>.
-The digest final function is called by EVP_DigestFinal(),
+The digest final function is called by EVP_Digest(), EVP_DigestFinal(),
EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
EVP_MD_meth_set_copy() sets the function for B<md> to do extra
@@ -138,6 +148,7 @@ This cleanup function is called by EVP_MD_CTX_reset() and
EVP_MD_CTX_free().
EVP_MD_meth_set_ctrl() sets the control function for B<md>.
+See L<EVP_MD_CTX_ctrl(3)> for the available controls.
EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
@@ -169,7 +180,7 @@ The B<EVP_MD> structure was openly available in OpenSSL before version
=head1 COPYRIGHT
-Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-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
diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index 75fad0f70ce0..16d8462a4263 100644
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -23,6 +23,8 @@ EVP_PKEY_CTX_get_rsa_oaep_md,
EVP_PKEY_CTX_set0_rsa_oaep_label,
EVP_PKEY_CTX_get0_rsa_oaep_label,
EVP_PKEY_CTX_set_dsa_paramgen_bits,
+EVP_PKEY_CTX_set_dsa_paramgen_q_bits,
+EVP_PKEY_CTX_set_dsa_paramgen_md,
EVP_PKEY_CTX_set_dh_paramgen_prime_len,
EVP_PKEY_CTX_set_dh_paramgen_subprime_len,
EVP_PKEY_CTX_set_dh_paramgen_generator,
@@ -93,6 +95,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
#include <openssl/dsa.h>
int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
+ int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits);
+ int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
#include <openssl/dh.h>
@@ -255,7 +259,17 @@ by the library and should not be freed by the caller.
=head2 DSA parameters
The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used
-for DSA parameter generation to B<bits>. If not specified 1024 is used.
+for DSA parameter generation to B<nbits>. If not specified, 1024 is used.
+
+The EVP_PKEY_CTX_set_dsa_paramgen_q_bits() macro sets the number of bits in the
+subprime parameter B<q> for DSA parameter generation to B<qbits>. If not
+specified, 160 is used. If a digest function is specified below, this parameter
+is ignored and instead, the number of bits in B<q> matches the size of the
+digest.
+
+The EVP_PKEY_CTX_set_dsa_paramgen_md() macro sets the digest function used for
+DSA parameter generation to B<md>. If not specified, one of SHA-1, SHA-224, or
+SHA-256 is selected to match the bit length of B<q> above.
=head2 DH parameters
diff --git a/doc/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod
index 8a167ce0d6ff..106873d9acc1 100644
--- a/doc/man3/EVP_PKEY_meth_new.pod
+++ b/doc/man3/EVP_PKEY_meth_new.pod
@@ -8,14 +8,18 @@ EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup,
EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign,
EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx,
EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt,
-EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, EVP_PKEY_meth_set_check,
+EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl,
+EVP_PKEY_meth_set_digestsign, EVP_PKEY_meth_set_digestverify,
+EVP_PKEY_meth_set_check,
EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check,
EVP_PKEY_meth_set_digest_custom,
EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup,
EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx,
EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
-EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check,
+EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl,
+EVP_PKEY_meth_get_digestsign, EVP_PKEY_meth_get_digestverify,
+EVP_PKEY_meth_get_check,
EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check,
EVP_PKEY_meth_get_digest_custom,
EVP_PKEY_meth_remove
@@ -112,6 +116,18 @@ EVP_PKEY_meth_remove
int (*ctrl_str) (EVP_PKEY_CTX *ctx,
const char *type,
const char *value));
+ void EVP_PKEY_meth_set_digestsign(EVP_PKEY_METHOD *pmeth,
+ int (*digestsign) (EVP_MD_CTX *ctx,
+ unsigned char *sig,
+ size_t *siglen,
+ const unsigned char *tbs,
+ size_t tbslen));
+ void EVP_PKEY_meth_set_digestverify(EVP_PKEY_METHOD *pmeth,
+ int (*digestverify) (EVP_MD_CTX *ctx,
+ const unsigned char *sig,
+ size_t siglen,
+ const unsigned char *tbs,
+ size_t tbslen));
void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
int (*check) (EVP_PKEY *pkey));
void EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth,
@@ -200,6 +216,18 @@ EVP_PKEY_meth_remove
int (**pctrl_str) (EVP_PKEY_CTX *ctx,
const char *type,
const char *value));
+ void EVP_PKEY_meth_get_digestsign(EVP_PKEY_METHOD *pmeth,
+ int (**digestsign) (EVP_MD_CTX *ctx,
+ unsigned char *sig,
+ size_t *siglen,
+ const unsigned char *tbs,
+ size_t tbslen));
+ void EVP_PKEY_meth_get_digestverify(EVP_PKEY_METHOD *pmeth,
+ int (**digestverify) (EVP_MD_CTX *ctx,
+ const unsigned char *sig,
+ size_t siglen,
+ const unsigned char *tbs,
+ size_t tbslen));
void EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth,
int (**pcheck) (EVP_PKEY *pkey));
void EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth,
diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod
index ebe20986dba1..667269cc624e 100644
--- a/doc/man3/EVP_PKEY_new.pod
+++ b/doc/man3/EVP_PKEY_new.pod
@@ -72,21 +72,24 @@ EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key().
New applications should use EVP_PKEY_new_raw_private_key() instead.
EVP_PKEY_get_raw_private_key() fills the buffer provided by B<priv> with raw
-private key data. The number of bytes written is populated in B<*len>. If the
-buffer B<priv> is NULL then B<*len> is populated with the number of bytes
-required to hold the key. The calling application is responsible for ensuring
-that the buffer is large enough to receive the private key data. This function
-only works for algorithms that support raw private keys. Currently this is:
-B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_X25519>,
-B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
+private key data. The size of the B<priv> buffer should be in B<*len> on entry
+to the function, and on exit B<*len> is updated with the number of bytes
+actually written. If the buffer B<priv> is NULL then B<*len> is populated with
+the number of bytes required to hold the key. The calling application is
+responsible for ensuring that the buffer is large enough to receive the private
+key data. This function only works for algorithms that support raw private keys.
+Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>,
+B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
EVP_PKEY_get_raw_public_key() fills the buffer provided by B<pub> with raw
-public key data. The number of bytes written is populated in B<*len>. If the
-buffer B<pub> is NULL then B<*len> is populated with the number of bytes
-required to hold the key. The calling application is responsible for ensuring
-that the buffer is large enough to receive the public key data. This function
-only works for algorithms that support raw public keys. Currently this is:
-B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
+public key data. The size of the B<pub> buffer should be in B<*len> on entry
+to the function, and on exit B<*len> is updated with the number of bytes
+actually written. If the buffer B<pub> is NULL then B<*len> is populated with
+the number of bytes required to hold the key. The calling application is
+responsible for ensuring that the buffer is large enough to receive the public
+key data. This function only works for algorithms that support raw public keys.
+Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or
+B<EVP_PKEY_ED448>.
=head1 NOTES
@@ -126,7 +129,7 @@ EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-2020 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
diff --git a/doc/man3/EVP_PKEY_size.pod b/doc/man3/EVP_PKEY_size.pod
new file mode 100644
index 000000000000..786c5039142c
--- /dev/null
+++ b/doc/man3/EVP_PKEY_size.pod
@@ -0,0 +1,80 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_size, EVP_PKEY_bits, EVP_PKEY_security_bits
+- EVP_PKEY information functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_size(const EVP_PKEY *pkey);
+ int EVP_PKEY_bits(const EVP_PKEY *pkey);
+ int EVP_PKEY_security_bits(const EVP_PKEY *pkey);
+
+=head1 DESCRIPTION
+
+EVP_PKEY_size() returns the maximum suitable size for the output
+buffers for almost all operations that can be done with I<pkey>.
+The primary documented use is with L<EVP_SignFinal(3)> and
+L<EVP_SealInit(3)>, but it isn't limited there. The returned size is
+also large enough for the output buffer of L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)>, L<EVP_PKEY_derive(3)>.
+
+It must be stressed that, unless the documentation for the operation
+that's being performed says otherwise, the size returned by
+EVP_PKEY_size() is only preliminary and not exact, so the final
+contents of the target buffer may be smaller. It is therefore crucial
+to take note of the size given back by the function that performs the
+operation, such as L<EVP_PKEY_sign(3)> (the I<siglen> argument will
+receive that length), to avoid bugs.
+
+EVP_PKEY_bits() returns the cryptographic length of the cryptosystem
+to which the key in I<pkey> belongs, in bits. Note that the definition
+of cryptographic length is specific to the key cryptosystem.
+
+EVP_PKEY_security_bits() returns the number of security bits of the given
+I<pkey>, bits of security is defined in NIST SP800-57.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_size(), EVP_PKEY_bits() and EVP_PKEY_security_bits() return a
+positive number, or 0 if this size isn't available.
+
+=head1 NOTES
+
+Most functions that have an output buffer and are mentioned with
+EVP_PKEY_size() have a functionality where you can pass NULL for the
+buffer and still pass a pointer to an integer and get the exact size
+that this function call delivers in the context that it's called in.
+This allows those functions to be called twice, once to find out the
+exact buffer size, then allocate the buffer in between, and call that
+function again actually output the data. For those functions, it
+isn't strictly necessary to call EVP_PKEY_size() to find out the
+buffer size, but may be useful in cases where it's desirable to know
+the upper limit in advance.
+
+It should also be especially noted that EVP_PKEY_size() shouldn't be
+used to get the output size for EVP_DigestSignFinal(), according to
+L<EVP_DigestSignFinal(3)/NOTES>.
+
+=head1 SEE ALSO
+
+L<EVP_SignFinal(3)>,
+L<EVP_SealInit(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/man3/EVP_SignInit.pod b/doc/man3/EVP_SignInit.pod
index c26b7f7d5d22..22ce747d333f 100644
--- a/doc/man3/EVP_SignInit.pod
+++ b/doc/man3/EVP_SignInit.pod
@@ -2,10 +2,8 @@
=head1 NAME
-EVP_PKEY_size,
-EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal,
-EVP_PKEY_security_bits - EVP signing
-functions
+EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal
+- EVP signing functions
=head1 SYNOPSIS
@@ -17,49 +15,36 @@ functions
void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
- int EVP_PKEY_size(const EVP_PKEY *pkey);
- int EVP_PKEY_security_bits(const EVP_PKEY *pkey);
-
=head1 DESCRIPTION
The EVP signature routines are a high level interface to digital
signatures.
-EVP_SignInit_ex() sets up signing context B<ctx> to use digest
-B<type> from ENGINE B<impl>. B<ctx> must be created with
+EVP_SignInit_ex() sets up signing context I<ctx> to use digest
+I<type> from B<ENGINE> I<impl>. I<ctx> must be created with
EVP_MD_CTX_new() before calling this function.
-EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
-signature context B<ctx>. This function can be called several times on the
-same B<ctx> to include additional data.
+EVP_SignUpdate() hashes I<cnt> bytes of data at I<d> into the
+signature context I<ctx>. This function can be called several times on the
+same I<ctx> to include additional data.
-EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
-places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey)
-bytes in size. B<s> is an OUT parameter, and not used as an IN parameter.
+EVP_SignFinal() signs the data in I<ctx> using the private key I<pkey> and
+places the signature in I<sig>. I<sig> must be at least C<EVP_PKEY_size(pkey)>
+bytes in size. I<s> is an OUT parameter, and not used as an IN parameter.
The number of bytes of data written (i.e. the length of the signature)
-will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
+will be written to the integer at I<s>, at most C<EVP_PKEY_size(pkey)> bytes
will be written.
-EVP_SignInit() initializes a signing context B<ctx> to use the default
-implementation of digest B<type>.
-
-EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
-signature returned by EVP_SignFinal() may be smaller.
-
-EVP_PKEY_security_bits() returns the number of security bits of the given B<pkey>,
-bits of security is defined in NIST SP800-57.
+EVP_SignInit() initializes a signing context I<ctx> to use the default
+implementation of digest I<type>.
=head1 RETURN VALUES
EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
for success and 0 for failure.
-EVP_PKEY_size() returns the maximum size of a signature in bytes.
-
The error codes can be obtained by L<ERR_get_error(3)>.
-EVP_PKEY_security_bits() returns the number of security bits.
-
=head1 NOTES
The B<EVP> interface to digital signatures should almost always be used in
@@ -95,6 +80,7 @@ The previous two bugs are fixed in the newer EVP_SignDigest*() function.
=head1 SEE ALSO
+L<EVP_PKEY_size(3)>, L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)>,
L<EVP_VerifyInit(3)>,
L<EVP_DigestInit(3)>,
L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
@@ -103,7 +89,7 @@ L<SHA1(3)>, L<dgst(1)>
=head1 COPYRIGHT
-Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man3/OCSP_request_add1_nonce.pod b/doc/man3/OCSP_request_add1_nonce.pod
index 66e4c7b8fb78..81bf645108f3 100644
--- a/doc/man3/OCSP_request_add1_nonce.pod
+++ b/doc/man3/OCSP_request_add1_nonce.pod
@@ -24,7 +24,7 @@ it adds a nonce to OCSP basic response B<resp>.
OCSP_check_nonce() compares the nonce value in B<req> and B<resp>.
-OCSP_copy_nonce() copys any nonce value present in B<req> to B<resp>.
+OCSP_copy_nonce() copies any nonce value present in B<req> to B<resp>.
=head1 RETURN VALUES
@@ -74,7 +74,7 @@ L<OCSP_sendreq_new(3)>
=head1 COPYRIGHT
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2020 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
diff --git a/doc/man3/OCSP_response_status.pod b/doc/man3/OCSP_response_status.pod
index 82f95b3af1d1..e7e22e4cb549 100644
--- a/doc/man3/OCSP_response_status.pod
+++ b/doc/man3/OCSP_response_status.pod
@@ -58,7 +58,7 @@ with the X509 certificate B<cert>.
OCSP_basic_sign() signs OCSP response B<brsp> using certificate B<signer>, private key
B<key>, digest B<dgst> and additional certificates B<certs>. If the B<flags> option
-B<OCSP_NOCERTS> is set then no certificates will be included in the request. If the
+B<OCSP_NOCERTS> is set then no certificates will be included in the response. If the
B<flags> option B<OCSP_RESPID_KEY> is set then the responder is identified by key ID
rather than by name. OCSP_basic_sign_ctx() also signs OCSP response B<brsp> but
uses the parameters contained in digest context B<ctx>.
@@ -107,7 +107,7 @@ The OCSP_basic_sign_ctx() function was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2020 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
diff --git a/doc/man3/OCSP_sendreq_new.pod b/doc/man3/OCSP_sendreq_new.pod
index 65ba235c104e..a129a16bf23c 100644
--- a/doc/man3/OCSP_sendreq_new.pod
+++ b/doc/man3/OCSP_sendreq_new.pod
@@ -24,8 +24,7 @@ OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions
int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req);
- OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req,
- int maxline);
+ OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req);
=head1 DESCRIPTION
@@ -54,8 +53,8 @@ OCSP_REQ_CTX_set1_req() sets the OCSP request in B<rctx> to B<req>. This
function should be called after any calls to OCSP_REQ_CTX_add1_header().
OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL
-path B<path>, the OCSP request B<req> and with a response header maximum line
-length of B<maxline>. If B<maxline> is zero a default value of 4k is used.
+path B<path>, and the OCSP request B<req> with a response header maximum line
+length 4k. It waits indefinitely on a response.
=head1 RETURN VALUES
@@ -112,7 +111,7 @@ L<OCSP_response_status(3)>
=head1 COPYRIGHT
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2020 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
diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod
index 2d678c951f0a..c60e038309a1 100644
--- a/doc/man3/OPENSSL_malloc.pod
+++ b/doc/man3/OPENSSL_malloc.pod
@@ -160,7 +160,7 @@ about what is being done.
For example, identifying the field names when parsing a complicated
data structure.
OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push())
-attachs an identifying string to the allocation stack.
+attaches an identifying string to the allocation stack.
This must be a global or other static string; it is not copied.
OPENSSL_mem_debug_pop() removes identifying state from the stack.
@@ -245,7 +245,7 @@ only, say, the malloc() implementation is outright dangerous.>
=head1 COPYRIGHT
-Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2020 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
diff --git a/doc/man3/OPENSSL_secure_malloc.pod b/doc/man3/OPENSSL_secure_malloc.pod
index 6c395383513b..86c2522afe49 100644
--- a/doc/man3/OPENSSL_secure_malloc.pod
+++ b/doc/man3/OPENSSL_secure_malloc.pod
@@ -7,6 +7,7 @@ CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc,
OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free,
CRYPTO_secure_free, OPENSSL_secure_clear_free,
CRYPTO_secure_clear_free, OPENSSL_secure_actual_size,
+CRYPTO_secure_allocated,
CRYPTO_secure_used - secure heap storage
=head1 SYNOPSIS
@@ -33,6 +34,7 @@ CRYPTO_secure_used - secure heap storage
size_t OPENSSL_secure_actual_size(const void *ptr);
+ int CRYPTO_secure_allocated(const void *ptr);
size_t CRYPTO_secure_used();
=head1 DESCRIPTION
@@ -90,6 +92,8 @@ OPENSSL_secure_actual_size() tells the actual size allocated to the
pointer; implementations may allocate more space than initially
requested, in order to "round up" and reduce secure heap fragmentation.
+OPENSSL_secure_allocated() tells if a pointer is allocated in the secure heap.
+
CRYPTO_secure_used() returns the number of bytes allocated in the
secure heap.
diff --git a/doc/man3/PEM_bytes_read_bio.pod b/doc/man3/PEM_bytes_read_bio.pod
index 3a5bfee9969f..eb2fb2059ee7 100644
--- a/doc/man3/PEM_bytes_read_bio.pod
+++ b/doc/man3/PEM_bytes_read_bio.pod
@@ -17,7 +17,8 @@ PEM_bytes_read_bio, PEM_bytes_read_bio_secmem - read a PEM-encoded data structur
=head1 DESCRIPTION
-PEM_bytes_read_bio() reads PEM-formatted (RFC 1421) data from the BIO
+PEM_bytes_read_bio() reads PEM-formatted (IETF RFC 1421 and IETF RFC 7468)
+data from the BIO
I<bp> for the data type given in I<name> (RSA PRIVATE KEY, CERTIFICATE,
etc.). If multiple PEM-encoded data structures are present in the same
stream, PEM_bytes_read_bio() will skip non-matching data types and
@@ -66,7 +67,6 @@ PEM_bytes_read_bio() and PEM_bytes_read_bio_secmem() return 1 for success or
=head1 SEE ALSO
-L<PEM(3)>,
L<PEM_read_bio_ex(3)>,
L<passphrase-encoding(7)>
diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 7c381e85feff..a8306500fb3c 100644
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -15,7 +15,8 @@ PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
-PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
+PEM_write_DSA_PUBKEY, PEM_read_bio_Parameters, PEM_write_bio_Parameters,
+PEM_read_bio_DSAparams, PEM_read_DSAparams,
PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
@@ -110,6 +111,9 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
+ EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x);
+ int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x);
+
DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
@@ -216,6 +220,12 @@ a DSA structure. The public key is encoded using a
SubjectPublicKeyInfo structure and an error occurs if the public
key is not DSA.
+The B<Parameters> functions read or write key parameters in PEM format using
+an EVP_PKEY structure. The encoding depends on the type of key; for DSA key
+parameters, it will be a Dss-Parms structure as defined in RFC2459, and for DH
+key parameters, it will be a PKCS#3 DHparameter structure. I<These functions
+only exist for the B<BIO> type>.
+
The B<DSAparams> functions process DSA parameters using a DSA
structure. The parameters are encoded using a Dss-Parms structure
as defined in RFC2459.
diff --git a/doc/man3/PEM_read_bio_ex.pod b/doc/man3/PEM_read_bio_ex.pod
index a16b0ede5a9c..9748e74e0f77 100644
--- a/doc/man3/PEM_read_bio_ex.pod
+++ b/doc/man3/PEM_read_bio_ex.pod
@@ -52,7 +52,7 @@ PEM_read_bio_ex() returns 1 for success or 0 for failure.
=head1 SEE ALSO
-L<PEM(3)>
+L<PEM_bytes_read_bio(3)>
=head1 HISTORY
diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index e2265d170a61..c44c2f967607 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -19,8 +19,8 @@ Deprecated:
=head1 DESCRIPTION
-RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
-into B<buf>.
+RAND_bytes() generates B<num> random bytes using a cryptographically
+secure pseudo random generator (CSPRNG) and stores them in B<buf>.
RAND_priv_bytes() has the same semantics as RAND_bytes(). It is intended to
be used for generating values that should remain private. If using the
@@ -31,10 +31,22 @@ and L<RAND_DRBG(7)>.
=head1 NOTES
-Always check the error return value of RAND_bytes() and
-RAND_priv_bytes() and do not take randomness for granted: an error occurs
-if the CSPRNG has not been seeded with enough randomness to ensure an
-unpredictable byte sequence.
+By default, the OpenSSL CSPRNG supports a security level of 256 bits, provided it
+was able to seed itself from a trusted entropy source.
+On all major platforms supported by OpenSSL (including the Unix-like platforms
+and Windows), OpenSSL is configured to automatically seed the CSPRNG on first use
+using the operating systems's random generator.
+
+If the entropy source fails or is not available, the CSPRNG will enter an
+error state and refuse to generate random bytes. For that reason, it is important
+to always check the error return value of RAND_bytes() and RAND_priv_bytes() and
+not take randomness for granted.
+
+On other platforms, there might not be a trusted entropy source available
+or OpenSSL might have been explicitly configured to use different entropy sources.
+If you are in doubt about the quality of the entropy source, don't hesitate to ask
+your operating system vendor or post a question on GitHub or the openssl-users
+mailing list.
=head1 RETURN VALUES
@@ -68,7 +80,7 @@ The RAND_priv_bytes() function was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man3/RAND_set_rand_method.pod b/doc/man3/RAND_set_rand_method.pod
index 83a6cac17a51..b120e712e6f3 100644
--- a/doc/man3/RAND_set_rand_method.pod
+++ b/doc/man3/RAND_set_rand_method.pod
@@ -48,7 +48,7 @@ Each pointer may be NULL if the function is not implemented.
=head1 RETURN VALUES
-RAND_set_rand_method() returns 1 on success and 0 on failue.
+RAND_set_rand_method() returns 1 on success and 0 on failure.
RAND_get_rand_method() and RAND_OpenSSL() return pointers to the respective
methods.
diff --git a/doc/man3/RSA_get0_key.pod b/doc/man3/RSA_get0_key.pod
index 358c2de256f9..adcd57c49071 100644
--- a/doc/man3/RSA_get0_key.pod
+++ b/doc/man3/RSA_get0_key.pod
@@ -5,7 +5,7 @@
RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key,
RSA_get0_factors, RSA_get0_crt_params,
RSA_get0_n, RSA_get0_e, RSA_get0_d, RSA_get0_p, RSA_get0_q,
-RSA_get0_dmp1, RSA_get0_dmq1, RSA_get0_iqmp,
+RSA_get0_dmp1, RSA_get0_dmq1, RSA_get0_iqmp, RSA_get0_pss_params,
RSA_clear_flags,
RSA_test_flags, RSA_set_flags, RSA_get0_engine, RSA_get_multi_prime_extra_count,
RSA_get0_multi_prime_factors, RSA_get0_multi_prime_crt_params,
@@ -33,6 +33,7 @@ RSA_set0_multi_prime_params, RSA_get_version
const BIGNUM *RSA_get0_dmp1(const RSA *r);
const BIGNUM *RSA_get0_dmq1(const RSA *r);
const BIGNUM *RSA_get0_iqmp(const RSA *r);
+ const RSA_PSS_PARAMS *RSA_get0_pss_params(const RSA *r);
void RSA_clear_flags(RSA *r, int flags);
int RSA_test_flags(const RSA *r, int flags);
void RSA_set_flags(RSA *r, int flags);
@@ -98,6 +99,8 @@ retrieved separately by the corresponding function
RSA_get0_n(), RSA_get0_e(), RSA_get0_d(), RSA_get0_p(), RSA_get0_q(),
RSA_get0_dmp1(), RSA_get0_dmq1(), and RSA_get0_iqmp(), respectively.
+RSA_get0_pss_params() is used to retrieve the RSA-PSS parameters.
+
RSA_set_flags() sets the flags in the B<flags> parameter on the RSA
object. Multiple flags can be passed in one go (bitwise ORed together).
Any flags that are already set are left set. RSA_test_flags() tests to
@@ -157,6 +160,8 @@ L<RSA_new(3)>, L<RSA_size(3)>
=head1 HISTORY
+The RSA_get0_pss_params() function was added in OpenSSL 1.1.1e.
+
The
RSA_get_multi_prime_extra_count(), RSA_get0_multi_prime_factors(),
RSA_get0_multi_prime_crt_params(), RSA_set0_multi_prime_params(),
diff --git a/doc/man3/SSL_CTX_sess_set_get_cb.pod b/doc/man3/SSL_CTX_sess_set_get_cb.pod
index 774c4b120f6e..d30f84d78a28 100644
--- a/doc/man3/SSL_CTX_sess_set_get_cb.pod
+++ b/doc/man3/SSL_CTX_sess_set_get_cb.pod
@@ -28,19 +28,19 @@ SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SS
=head1 DESCRIPTION
-SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
+SSL_CTX_sess_set_new_cb() sets the callback function that is
called whenever a new session was negotiated.
-SSL_CTX_sess_set_remove_cb() sets the callback function, which is
-automatically called whenever a session is removed by the SSL engine,
-because it is considered faulty or the session has become obsolete because
-of exceeding the timeout value.
+SSL_CTX_sess_set_remove_cb() sets the callback function that is
+called whenever a session is removed by the SSL engine. For example,
+this can occur because a session is considered faulty or has become obsolete
+because of exceeding the timeout value.
-SSL_CTX_sess_set_get_cb() sets the callback function which is called,
-whenever a SSL/TLS client proposed to resume a session but the session
+SSL_CTX_sess_set_get_cb() sets the callback function that is called
+whenever a TLS client proposed to resume a session but the session
could not be found in the internal session cache (see
L<SSL_CTX_set_session_cache_mode(3)>).
-(SSL/TLS server only.)
+(TLS server only.)
SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
SSL_CTX_sess_get_get_cb() retrieve the function pointers set by the
@@ -54,12 +54,19 @@ session cache is realized via callback functions. Inside these callback
functions, session can be saved to disk or put into a database using the
L<d2i_SSL_SESSION(3)> interface.
-The new_session_cb() is called, whenever a new session has been negotiated
-and session caching is enabled (see
-L<SSL_CTX_set_session_cache_mode(3)>).
-The new_session_cb() is passed the B<ssl> connection and the ssl session
-B<sess>. If the callback returns B<0>, the session will be immediately
-removed again. Note that in TLSv1.3, sessions are established after the main
+The new_session_cb() is called whenever a new session has been negotiated and
+session caching is enabled (see L<SSL_CTX_set_session_cache_mode(3)>). The
+new_session_cb() is passed the B<ssl> connection and the nascent
+ssl session B<sess>.
+Since sessions are reference-counted objects, the reference count on the
+session is incremented before the callback, on behalf of the application. If
+the callback returns B<0>, the session will be immediately removed from the
+internal cache and the reference count released. If the callback returns B<1>,
+the application retains the reference (for an entry in the
+application-maintained "external session cache"), and is responsible for
+calling SSL_SESSION_free() when the session reference is no longer in use.
+
+Note that in TLSv1.3, sessions are established after the main
handshake has completed. The server decides when to send the client the session
information and this may occur some time after the end of the handshake (or not
at all). This means that applications should expect the new_session_cb()
@@ -72,21 +79,23 @@ In TLSv1.3 it is recommended that each SSL_SESSION object is only used for
resumption once. One way of enforcing that is for applications to call
L<SSL_CTX_remove_session(3)> after a session has been used.
-The remove_session_cb() is called, whenever the SSL engine removes a session
-from the internal cache. This happens when the session is removed because
+The remove_session_cb() is called whenever the SSL engine removes a session
+from the internal cache. This can happen when the session is removed because
it is expired or when a connection was not shutdown cleanly. It also happens
for all sessions in the internal session cache when
L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed
the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
-The get_session_cb() is only called on SSL/TLS servers with the session id
-proposed by the client. The get_session_cb() is always called, also when
+The get_session_cb() is only called on SSL/TLS servers, and is given
+the session id
+proposed by the client. The get_session_cb() is always called, even when
session caching was disabled. The get_session_cb() is passed the
-B<ssl> connection, the session id of length B<length> at the memory location
-B<data>. With the parameter B<copy> the callback can require the
-SSL engine to increment the reference count of the SSL_SESSION object,
-Normally the reference count is not incremented and therefore the
-session must not be explicitly freed with
+B<ssl> connection and the session id of length B<length> at the memory location
+B<data>. By setting the parameter B<copy> to B<1>, the callback can require the
+SSL engine to increment the reference count of the SSL_SESSION object;
+setting B<copy> to B<0> causes the reference count to remain unchanged.
+If the get_session_cb() does not write to B<copy>, the reference count
+is incremented and the session must be explicitly freed with
L<SSL_SESSION_free(3)>.
=head1 RETURN VALUES
@@ -104,7 +113,7 @@ L<SSL_CTX_free(3)>
=head1 COPYRIGHT
-Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2020 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
diff --git a/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
index f29153ed25d8..aa167f6332ed 100644
--- a/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
+++ b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
@@ -3,7 +3,9 @@
=head1 NAME
SSL_CTX_set_stateless_cookie_generate_cb,
-SSL_CTX_set_stateless_cookie_verify_cb
+SSL_CTX_set_stateless_cookie_verify_cb,
+SSL_CTX_set_cookie_generate_cb,
+SSL_CTX_set_cookie_verify_cb
- Callback functions for stateless TLS1.3 cookies
=head1 SYNOPSIS
@@ -21,22 +23,51 @@ SSL_CTX_set_stateless_cookie_verify_cb
const unsigned char *cookie,
size_t cookie_len));
+ void SSL_CTX_set_cookie_generate_cb(SSL_CTX *ctx,
+ int (*app_gen_cookie_cb) (SSL *ssl,
+ unsigned char
+ *cookie,
+ unsigned int
+ *cookie_len));
+ void SSL_CTX_set_cookie_verify_cb(SSL_CTX *ctx,
+ int (*app_verify_cookie_cb) (SSL *ssl,
+ const unsigned
+ char *cookie,
+ unsigned int
+ cookie_len));
+
=head1 DESCRIPTION
-SSL_CTX_set_cookie_generate_cb() sets the callback used by L<SSL_stateless(3)>
-to generate the application-controlled portion of the cookie provided to clients
-in the HelloRetryRequest transmitted as a response to a ClientHello with a
-missing or invalid cookie. gen_stateless_cookie_cb() must write at most
-SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number of bytes
-written to B<cookie_len>. If a cookie cannot be generated, a zero return value
-can be used to abort the handshake.
-
-SSL_CTX_set_cookie_verify_cb() sets the callback used by L<SSL_stateless(3)> to
-determine whether the application-controlled portion of a ClientHello cookie is
-valid. A nonzero return value from app_verify_cookie_cb() communicates that the
-cookie is valid. The integrity of the entire cookie, including the
-application-controlled portion, is automatically verified by HMAC before
-verify_stateless_cookie_cb() is called.
+SSL_CTX_set_stateless_cookie_generate_cb() sets the callback used by
+L<SSL_stateless(3)> to generate the application-controlled portion of the cookie
+provided to clients in the HelloRetryRequest transmitted as a response to a
+ClientHello with a missing or invalid cookie. gen_stateless_cookie_cb() must
+write at most SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number
+of bytes written to B<cookie_len>. If a cookie cannot be generated, a zero
+return value can be used to abort the handshake.
+
+SSL_CTX_set_stateless_cookie_verify_cb() sets the callback used by
+L<SSL_stateless(3)> to determine whether the application-controlled portion of a
+ClientHello cookie is valid. The cookie data is pointed to by B<cookie> and is of
+length B<cookie_len>. A nonzero return value from verify_stateless_cookie_cb()
+communicates that the cookie is valid. The integrity of the entire cookie,
+including the application-controlled portion, is automatically verified by HMAC
+before verify_stateless_cookie_cb() is called.
+
+SSL_CTX_set_cookie_generate_cb() sets the callback used by L<DTLSv1_listen(3)>
+to generate the cookie provided to clients in the HelloVerifyRequest transmitted
+as a response to a ClientHello with a missing or invalid cookie.
+app_gen_cookie_cb() must write at most DTLS1_COOKIE_LENGTH bytes into
+B<cookie>, and must write the number of bytes written to B<cookie_len>. If a
+cookie cannot be generated, a zero return value can be used to abort the
+handshake.
+
+SSL_CTX_set_cookie_verify_cb() sets the callback used by L<DTLSv1_listen(3)> to
+determine whether the cookie in a ClientHello is valid. The cookie data is
+pointed to by B<cookie> and is of length B<cookie_len>. A nonzero return value
+from app_verify_cookie_cb() communicates that the cookie is valid. The
+integrity of the cookie is not verified by OpenSSL. This is an application
+responsibility.
=head1 RETURN VALUES
@@ -44,7 +75,13 @@ Neither function returns a value.
=head1 SEE ALSO
-L<SSL_stateless(3)>
+L<SSL_stateless(3)>,
+L<DTLSv1_listen(3)>
+
+=head1 HISTORY
+
+SSL_CTX_set_stateless_cookie_generate_cb() and
+SSL_CTX_set_stateless_cookie_verify_cb() were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
diff --git a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
index b1fb5ab7d9fa..e971035734e1 100644
--- a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
@@ -11,7 +11,7 @@ SSL_set_tlsext_host_name - handle server name indication (SNI)
#include <openssl/ssl.h>
long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx,
- int (*cb)(SSL *, int *, void *));
+ int (*cb)(SSL *s, int *al, void *arg));
long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg);
const char *SSL_get_servername(const SSL *s, const int type);
@@ -21,21 +21,106 @@ SSL_set_tlsext_host_name - handle server name indication (SNI)
=head1 DESCRIPTION
-The functionality provided by the servername callback is superseded by the
-ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb().
-The servername callback is retained for historical compatibility.
+The functionality provided by the servername callback is mostly superseded by
+the ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb().
+However, even where the ClientHello callback is used, the servername callback is
+still necessary in order to acknowledge the servername requested by the client.
SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
used by a server to perform any actions or configuration required based on
the servername extension received in the incoming connection. When B<cb>
-is NULL, SNI is not used. The B<arg> value is a pointer which is passed to
-the application callback.
+is NULL, SNI is not used.
+
+The servername callback should return one of the following values:
+
+=over 4
+
+=item SSL_TLSEXT_ERR_OK
+
+This is used to indicate that the servername requested by the client has been
+accepted. Typically a server will call SSL_set_SSL_CTX() in the callback to set
+up a different configuration for the selected servername in this case.
+
+=item SSL_TLSEXT_ERR_ALERT_FATAL
+
+In this case the servername requested by the client is not accepted and the
+handshake will be aborted. The value of the alert to be used should be stored in
+the location pointed to by the B<al> parameter to the callback. By default this
+value is initialised to SSL_AD_UNRECOGNIZED_NAME.
+
+=item SSL_TLSEXT_ERR_ALERT_WARNING
+
+If this value is returned then the servername is not accepted by the server.
+However the handshake will continue and send a warning alert instead. The value
+of the alert should be stored in the location pointed to by the B<al> parameter
+as for SSL_TLSEXT_ERR_ALERT_FATAL above. Note that TLSv1.3 does not support
+warning alerts, so if TLSv1.3 has been negotiated then this return value is
+treated the same way as SSL_TLSEXT_ERR_NOACK.
+
+=item SSL_TLSEXT_ERR_NOACK
+
+This return value indicates that the servername is not accepted by the server.
+No alerts are sent and the server will not acknowledge the requested servername.
+
+=back
SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be
-passed into the callback for this B<SSL_CTX>.
+passed into the callback (via the B<arg> parameter) for this B<SSL_CTX>.
+
+The behaviour of SSL_get_servername() depends on a number of different factors.
+In particular note that in TLSv1.3 the servername is negotiated in every
+handshake. In TLSv1.2 the servername is only negotiated on initial handshakes
+and not on resumption handshakes.
+
+=over 4
+
+=item On the client, before the handshake
+
+If a servername has been set via a call to SSL_set_tlsext_host_name() then it
+will return that servername.
+
+If one has not been set, but a TLSv1.2 resumption is being attempted and the
+session from the original handshake had a servername accepted by the server then
+it will return that servername.
+
+Otherwise it returns NULL.
-SSL_get_servername() returns a servername extension value of the specified
-type if provided in the Client Hello or NULL.
+=item On the client, during or after the handshake and a TLSv1.2 (or below)
+resumption occurred
+
+If the session from the orignal handshake had a servername accepted by the
+server then it will return that servername.
+
+Otherwise it returns the servername set via SSL_set_tlsext_host_name() or NULL
+if it was not called.
+
+=item On the client, during or after the handshake and a TLSv1.2 (or below)
+resumption did not occur
+
+It will return the servername set via SSL_set_tlsext_host_name() or NULL if it
+was not called.
+
+=item On the server, before the handshake
+
+The function will always return NULL before the handshake
+
+=item On the server, after the servername extension has been processed and a
+TLSv1.2 (or below) resumption occurred
+
+If a servername was accepted by the server in the original handshake then it
+will return that servername, or NULL otherwise.
+
+=item On the server, after the servername extension has been processed and a
+TLSv1.2 (or below) resumption did not occur
+
+The function will return the servername requested by the client in this
+handshake or NULL if none was requested.
+
+=back
+
+Note that the ClientHello callback occurs before a servername extension from the
+client is processed. The servername, certificate and ALPN callbacks occur after
+a servername extension from the client is processed.
SSL_get_servername_type() returns the servername type or -1 if no servername
is present. Currently the only supported type (defined in RFC3546) is
@@ -65,9 +150,26 @@ SSL_set_tlsext_host_name() returns 1 on success, 0 in case of error.
L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>,
L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)>
+=head1 HISTORY
+
+SSL_get_servername() historically provided some unexpected results in certain
+corner cases. This has been fixed from OpenSSL 1.1.1e.
+
+Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2
+handshake, the server accepted it, and then the client successfully resumed but
+set a different explict servername in the second handshake then when called by
+the client it returned the servername from the second handshake. This has now
+been changed to return the servername requested in the original handshake.
+
+Also prior to 1.1.1e, if the client sent a servername in the first handshake but
+the server did not accept it, and then a second handshake occured where TLSv1.2
+resumption was successful then when called by the server it returned the
+servername requested in the original handshake. This has now been changed to
+NULL.
+
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2020 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
diff --git a/doc/man3/SSL_CTX_use_psk_identity_hint.pod b/doc/man3/SSL_CTX_use_psk_identity_hint.pod
index c8f7526610a8..0957ade5e106 100644
--- a/doc/man3/SSL_CTX_use_psk_identity_hint.pod
+++ b/doc/man3/SSL_CTX_use_psk_identity_hint.pod
@@ -39,9 +39,9 @@ SSL_set_psk_find_session_callback
=head1 DESCRIPTION
-A client application wishing to use TLSv1.3 PSKs should set a callback
-using either SSL_CTX_set_psk_use_session_callback() or
-SSL_set_psk_use_session_callback() as appropriate.
+A server application wishing to use TLSv1.3 PSKs should set a callback
+using either SSL_CTX_set_psk_find_session_callback() or
+SSL_set_psk_find_session_callback() as appropriate.
The callback function is given a pointer to the SSL connection in B<ssl> and
an identity in B<identity> of length B<identity_len>. The callback function
diff --git a/doc/man3/SSL_SESSION_get0_hostname.pod b/doc/man3/SSL_SESSION_get0_hostname.pod
index 475f700a88c5..6e39cbc656dd 100644
--- a/doc/man3/SSL_SESSION_get0_hostname.pod
+++ b/doc/man3/SSL_SESSION_get0_hostname.pod
@@ -24,7 +24,10 @@ SSL_SESSION_set1_alpn_selected
=head1 DESCRIPTION
SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the
-client when the session was created, or NULL if no value was sent.
+client when the session was created if it was accepted by the server and TLSv1.2
+or below was negotiated. Otherwise NULL is returned. Note that in TLSv1.3 the
+SNI hostname is negotiated with each handshake including resumption handshakes
+and is therefore never associated with the session.
The value returned is a pointer to memory maintained within B<s> and
should not be free'd.
@@ -64,7 +67,7 @@ SSL_SESSION_set1_alpn_selected() functions were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2020 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
diff --git a/doc/man3/SSL_accept.pod b/doc/man3/SSL_accept.pod
index 335655f0c8c8..b1595f7acf34 100644
--- a/doc/man3/SSL_accept.pod
+++ b/doc/man3/SSL_accept.pod
@@ -56,7 +56,7 @@ established.
The TLS/SSL handshake was not successful because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
-not clean. It can also occur of action is need to continue the operation
+not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -72,7 +72,7 @@ L<SSL_CTX_new(3)>
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man3/SSL_connect.pod b/doc/man3/SSL_connect.pod
index 426b8ad757db..f7d9e57db622 100644
--- a/doc/man3/SSL_connect.pod
+++ b/doc/man3/SSL_connect.pod
@@ -71,7 +71,7 @@ established.
The TLS/SSL handshake was not successful, because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
-not clean. It can also occur of action is need to continue the operation
+not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -87,7 +87,7 @@ L<SSL_CTX_new(3)>
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man3/SSL_do_handshake.pod b/doc/man3/SSL_do_handshake.pod
index a1b973f7b80a..8852f9d3e3dc 100644
--- a/doc/man3/SSL_do_handshake.pod
+++ b/doc/man3/SSL_do_handshake.pod
@@ -57,7 +57,7 @@ established.
The TLS/SSL handshake was not successful because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
-not clean. It can also occur of action is need to continue the operation
+not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -71,7 +71,7 @@ L<SSL_set_connect_state(3)>
=head1 COPYRIGHT
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-2020 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
diff --git a/doc/man3/SSL_load_client_CA_file.pod b/doc/man3/SSL_load_client_CA_file.pod
index a6cfb308d30c..f354ef4177dc 100644
--- a/doc/man3/SSL_load_client_CA_file.pod
+++ b/doc/man3/SSL_load_client_CA_file.pod
@@ -2,7 +2,10 @@
=head1 NAME
-SSL_load_client_CA_file - load certificate names from file
+SSL_load_client_CA_file,
+SSL_add_file_cert_subjects_to_stack,
+SSL_add_dir_cert_subjects_to_stack
+- load certificate names
=head1 SYNOPSIS
@@ -10,11 +13,23 @@ SSL_load_client_CA_file - load certificate names from file
STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
+ int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
+ const char *file)
+ int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
+ const char *dir)
+
=head1 DESCRIPTION
-SSL_load_client_CA_file() reads certificates from B<file> and returns
+SSL_load_client_CA_file() reads certificates from I<file> and returns
a STACK_OF(X509_NAME) with the subject names found.
+SSL_add_file_cert_subjects_to_stack() reads certificates from I<file>,
+and adds their subject name to the already existing I<stack>.
+
+SSL_add_dir_cert_subjects_to_stack() reads certificates from every
+file in the directory I<dir>, and adds their subject name to the
+already existing I<stack>.
+
=head1 NOTES
SSL_load_client_CA_file() reads a file of PEM formatted certificates and
diff --git a/doc/man3/X509_LOOKUP.pod b/doc/man3/X509_LOOKUP.pod
new file mode 100644
index 000000000000..3e0bb6ab221c
--- /dev/null
+++ b/doc/man3/X509_LOOKUP.pod
@@ -0,0 +1,212 @@
+=pod
+
+=head1 NAME
+
+X509_LOOKUP, X509_LOOKUP_TYPE,
+X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init,
+X509_LOOKUP_shutdown,
+X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data,
+X509_LOOKUP_ctrl,
+X509_LOOKUP_load_file, X509_LOOKUP_add_dir,
+X509_LOOKUP_get_store, X509_LOOKUP_by_subject,
+X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint,
+X509_LOOKUP_by_alias
+- OpenSSL certificate lookup mechanisms
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ typedef x509_lookup_st X509_LOOKUP;
+
+ typedef enum X509_LOOKUP_TYPE;
+
+ X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method);
+ int X509_LOOKUP_init(X509_LOOKUP *ctx);
+ int X509_LOOKUP_shutdown(X509_LOOKUP *ctx);
+ void X509_LOOKUP_free(X509_LOOKUP *ctx);
+
+ int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
+ void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
+
+ int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc,
+ long argl, char **ret);
+ int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type);
+ int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type);
+
+ X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
+
+ int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
+ X509_NAME *name, X509_OBJECT *ret);
+ int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
+ X509_NAME *name, ASN1_INTEGER *serial,
+ X509_OBJECT *ret);
+ int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
+ const unsigned char *bytes, int len,
+ X509_OBJECT *ret);
+ int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
+ const char *str, int len, X509_OBJECT *ret);
+
+=head1 DESCRIPTION
+
+The B<X509_LOOKUP> structure holds the information needed to look up
+certificates and CRLs according to an associated L<X509_LOOKUP_METHOD(3)>.
+Multiple B<X509_LOOKUP> instances can be added to an L<X509_STORE(3)>
+to enable lookup in that store.
+
+X509_LOOKUP_new() creates a new B<X509_LOOKUP> using the given lookup
+I<method>.
+It can also be created by calling L<X509_STORE_add_lookup(3)>, which
+will associate an B<X509_STORE> with the lookup mechanism.
+
+X509_LOOKUP_init() initializes the internal state and resources as
+needed by the given B<X509_LOOKUP> to do its work.
+
+X509_LOOKUP_shutdown() tears down the internal state and resources of
+the given B<X509_LOOKUP>.
+
+X509_LOOKUP_free() destructs the given B<X509_LOOKUP>.
+
+X509_LOOKUP_set_method_data() associates a pointer to application data
+to the given B<X509_LOOKUP>.
+
+X509_LOOKUP_get_method_data() retrieves a pointer to application data
+from the given B<X509_LOOKUP>.
+
+X509_LOOKUP_ctrl() is used to set or get additional data to or from an
+B<X509_LOOKUP> structure or its associated L<X509_LOOKUP_METHOD(3)>.
+The arguments of the control command are passed via I<argc> and I<argl>,
+its return value via I<*ret>.
+The meaning of the arguments depends on the I<cmd> number of the
+control command. In general, this function is not called directly, but
+wrapped by a macro call, see below.
+The control I<cmd>s known to OpenSSL are discussed in more depth
+in L</Control Commands>.
+
+X509_LOOKUP_load_file() passes a filename to be loaded immediately
+into the associated B<X509_STORE>.
+I<type> indicates what type of object is expected.
+This can only be used with a lookup using the implementation
+L<X509_LOOKUP_file(3)>.
+
+X509_LOOKUP_add_dir() passes a directory specification from which
+certificates and CRLs are loaded on demand into the associated
+B<X509_STORE>.
+I<type> indicates what type of object is expected.
+This can only be used with a lookup using the implementation
+L<X509_LOOKUP_hash_dir(3)>.
+
+X509_LOOKUP_load_file(), X509_LOOKUP_add_dir(),
+X509_LOOKUP_add_store(), and X509_LOOKUP_load_store() are implemented
+as macros that use X509_LOOKUP_ctrl().
+
+X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
+X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() look up
+certificates and CRLs in the L<X509_STORE(3)> associated with the
+B<X509_LOOKUP> using different criteria, where the looked up object is
+stored in I<ret>.
+Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects
+matching the criteria in the associated B<X509_STORE>, which makes it
+possible to handle cases where the criteria have more than one hit.
+
+=head2 File Types
+
+X509_LOOKUP_load_file() and X509_LOOKUP_add_dir() take a I<type>,
+which can be one of the following:
+
+=over 4
+
+=item B<X509_FILETYPE_PEM>
+
+The file or files that are loaded are expected to be in PEM format.
+
+=item B<X509_FILETYPE_ASN1>
+
+The file or files that are loaded are expected to be in raw DER format.
+
+=item B<X509_FILETYPE_DEFAULT>
+
+The default certificate file or directory is used. In this case,
+I<name> is ignored.
+
+=begin comment
+
+TODO
+Document X509_get_default_cert_file_env(3),
+X509_get_default_cert_file(3), X509_get_default_cert_dir_env(3) and
+X509_get_default_cert_dir(3) and link to them here.
+
+=end comment
+
+=back
+
+=head2 Control Commands
+
+The B<X509_LOOKUP_METHOD>s built into OpenSSL recognise the following
+X509_LOOKUP_ctrl() I<cmd>s:
+
+=over 4
+
+=item B<X509_L_FILE_LOAD>
+
+This is the command that X509_LOOKUP_load_file() uses.
+The filename is passed in I<argc>, and the type in I<argl>.
+
+=item B<X509_L_ADD_DIR>
+
+This is the command that X509_LOOKUP_add_dir() uses.
+The directory specification is passed in I<argc>, and the type in
+I<argl>.
+
+=item B<X509_L_ADD_STORE>
+
+This is the command that X509_LOOKUP_add_store() uses.
+The URI is passed in I<argc>.
+
+=item B<X509_L_LOAD_STORE>
+
+This is the command that X509_LOOKUP_load_store() uses.
+The URI is passed in I<argc>.
+
+=back
+
+=head1 RETURN VALUES
+
+X509_LOOKUP_new() returns an B<X509_LOOKUP> pointer when successful,
+or NULL on error.
+
+X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or
+0 on error.
+
+X509_LOOKUP_ctrl() returns -1 if the B<X509_LOOKUP> doesn't have an
+associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD>
+doesn't have a control function.
+Otherwise, it returns what the control function in the
+B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
+error.
+
+X509_LOOKUP_get_store() returns an B<X509_STORE> pointer if there is
+one, otherwise NULL.
+
+X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
+X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() all return 0
+if there is no B<X509_LOOKUP_METHOD> or that method doesn't implement
+the corresponding function.
+Otherwise, it returns what the corresponding function in the
+B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
+error.
+
+=head1 SEE ALSO
+
+L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/man3/X509_LOOKUP_meth_new.pod b/doc/man3/X509_LOOKUP_meth_new.pod
index e5f0a098b3fa..a4e7466395dd 100644
--- a/doc/man3/X509_LOOKUP_meth_new.pod
+++ b/doc/man3/X509_LOOKUP_meth_new.pod
@@ -2,6 +2,7 @@
=head1 NAME
+X509_LOOKUP_METHOD,
X509_LOOKUP_meth_new, X509_LOOKUP_meth_free, X509_LOOKUP_meth_set_new_item,
X509_LOOKUP_meth_get_new_item, X509_LOOKUP_meth_set_free,
X509_LOOKUP_meth_get_free, X509_LOOKUP_meth_set_init,
@@ -16,14 +17,15 @@ X509_LOOKUP_get_by_fingerprint_fn, X509_LOOKUP_meth_set_get_by_fingerprint,
X509_LOOKUP_meth_get_get_by_fingerprint,
X509_LOOKUP_get_by_alias_fn, X509_LOOKUP_meth_set_get_by_alias,
X509_LOOKUP_meth_get_get_by_alias,
-X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data,
-X509_LOOKUP_get_store, X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
+X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
- Routines to build up X509_LOOKUP methods
=head1 SYNOPSIS
#include <openssl/x509_vfy.h>
+ typedef x509_lookup_method_st X509_LOOKUP_METHOD;
+
X509_LOOKUP_METHOD *X509_LOOKUP_meth_new(const char *name);
void X509_LOOKUP_meth_free(X509_LOOKUP_METHOD *method);
@@ -92,11 +94,6 @@ X509_LOOKUP_get_store, X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
X509_LOOKUP_get_by_alias_fn X509_LOOKUP_meth_get_get_by_alias(
const X509_LOOKUP_METHOD *method);
- int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
- void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
-
- X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
-
int X509_OBJECT_set1_X509(X509_OBJECT *a, X509 *obj);
int X509_OBJECT_set1_X509_CRL(X509_OBJECT *a, X509_CRL *obj);
@@ -118,7 +115,7 @@ X509_LOOKUP_get_new_item() and X509_LOOKUP_set_new_item() get and set the
function that is called when an B<X509_LOOKUP> object is created with
X509_LOOKUP_new(). If an X509_LOOKUP_METHOD requires any per-X509_LOOKUP
specific data, the supplied new_item function should allocate this data and
-invoke X509_LOOKUP_set_method_data().
+invoke L<X509_LOOKUP_set_method_data(3)>.
X509_LOOKUP_get_free() and X509_LOOKUP_set_free() get and set the function
that is used to free any method data that was allocated and set from within
@@ -126,7 +123,7 @@ new_item function.
X509_LOOKUP_meth_get_init() and X509_LOOKUP_meth_set_init() get and set the
function that is used to initialize the method data that was set with
-X509_LOOKUP_set_method_data() as part of the new_item routine.
+L<X509_LOOKUP_set_method_data(3)> as part of the new_item routine.
X509_LOOKUP_meth_get_shutdown() and X509_LOOKUP_meth_set_shutdown() get and set
the function that is used to shut down the method data whose state was
@@ -164,9 +161,9 @@ increments the result's reference count.
Any method data that was created as a result of the new_item function
set by X509_LOOKUP_meth_set_new_item() can be accessed with
-X509_LOOKUP_get_method_data(). The B<X509_STORE> object that owns the
-X509_LOOKUP may be accessed with X509_LOOKUP_get_store(). Successful lookups
-should return 1, and unsuccessful lookups should return 0.
+L<X509_LOOKUP_get_method_data(3)>. The B<X509_STORE> object that owns the
+X509_LOOKUP may be accessed with L<X509_LOOKUP_get_store(3)>. Successful
+lookups should return 1, and unsuccessful lookups should return 0.
X509_LOOKUP_get_get_by_subject(), X509_LOOKUP_get_get_by_issuer_serial(),
X509_LOOKUP_get_get_by_fingerprint(), X509_LOOKUP_get_get_by_alias() retrieve
@@ -189,7 +186,7 @@ The functions described here were added in OpenSSL 1.1.0i.
=head1 COPYRIGHT
-Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2018-2020 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
diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod
index 472db508bc4e..c5042858be85 100644
--- a/doc/man3/X509_STORE_CTX_new.pod
+++ b/doc/man3/X509_STORE_CTX_new.pod
@@ -28,7 +28,7 @@ X509_STORE_CTX_verify_fn
void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);
- STACK_OF(X509) *X509_STORE_CTX_get0_chain(X609_STORE_CTX *ctx);
+ STACK_OF(X509) *X509_STORE_CTX_get0_chain(X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod
index 3ea5b8b1272f..d840bd6d69bf 100644
--- a/doc/man3/X509_STORE_add_cert.pod
+++ b/doc/man3/X509_STORE_add_cert.pod
@@ -2,8 +2,10 @@
=head1 NAME
+X509_STORE,
X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth,
X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust,
+X509_STORE_add_lookup,
X509_STORE_load_locations,
X509_STORE_set_default_paths
- X509_STORE manipulation
@@ -12,6 +14,8 @@ X509_STORE_set_default_paths
#include <openssl/x509_vfy.h>
+ typedef x509_store_st X509_STORE;
+
int X509_STORE_add_cert(X509_STORE *ctx, X509 *x);
int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x);
int X509_STORE_set_depth(X509_STORE *store, int depth);
@@ -19,6 +23,9 @@ X509_STORE_set_default_paths
int X509_STORE_set_purpose(X509_STORE *ctx, int purpose);
int X509_STORE_set_trust(X509_STORE *ctx, int trust);
+ X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store,
+ X509_LOOKUP_METHOD *meth);
+
int X509_STORE_load_locations(X509_STORE *ctx,
const char *file, const char *dir);
int X509_STORE_set_default_paths(X509_STORE *ctx);
@@ -65,6 +72,11 @@ for the corresponding values used in certificate chain validation. Their
behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual
pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>.
+X509_STORE_add_lookup() finds or creates a L<X509_LOOKUP(3)> with the
+L<X509_LOOKUP_METHOD(3)> I<meth> and adds it to the B<X509_STORE>
+I<store>. This also associates the B<X509_STORE> with the lookup, so
+B<X509_LOOKUP> functions can look up objects in that store.
+
X509_STORE_load_locations() loads trusted certificate(s) into an
B<X509_STORE> from a given file and/or directory path. It is permitted
to specify just a file, just a directory, or both paths. The certificates
@@ -83,6 +95,9 @@ X509_STORE_set_flags(), X509_STORE_set_purpose(),
X509_STORE_set_trust(), X509_STORE_load_locations(), and
X509_STORE_set_default_paths() return 1 on success or 0 on failure.
+X509_STORE_add_lookup() returns the found or created
+L<X509_LOOKUP(3)>, or NULL on error.
+
=head1 SEE ALSO
L<X509_LOOKUP_hash_dir(3)>.
@@ -92,7 +107,7 @@ L<X509_STORE_get0_param(3)>
=head1 COPYRIGHT
-Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2020 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
diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index e36270f73940..a8319bd4715b 100644
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -307,7 +307,6 @@ i2d_POLICYQUALINFO,
i2d_PROFESSION_INFO,
i2d_PROXY_CERT_INFO_EXTENSION,
i2d_PROXY_POLICY,
-i2d_PublicKey,
i2d_RSAPrivateKey,
i2d_RSAPrivateKey_bio,
i2d_RSAPrivateKey_fp,
@@ -461,7 +460,7 @@ Represents an ASN1 OBJECT IDENTIFIER.
Represents a PKCS#3 DH parameters structure.
-=item B<DHparamx>
+=item B<DHxparams>
Represents an ANSI X9.42 DH parameters structure.
@@ -611,7 +610,7 @@ efficiency reasons.
=head1 COPYRIGHT
-Copyright 1998-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 1998-2020 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
diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index 992fdfccf917..7b50b099198c 100644
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -355,6 +355,22 @@ Simple OpenSSL library configuration example to enter FIPS mode:
Note: in the above example you will get an error in non FIPS capable versions
of OpenSSL.
+Simple OpenSSL library configuration to make TLS 1.3 the system-default
+minimum TLS version:
+
+ # Toplevel section for openssl (including libssl)
+ openssl_conf = default_conf_section
+
+ [default_conf_section]
+ # We only specify configuration for the "ssl module"
+ ssl_conf = ssl_section
+
+ [ssl_section]
+ system_default = system_default_section
+
+ [system_default_section]
+ MinProtocol = TLSv1.3
+
More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
@@ -426,7 +442,7 @@ L<x509(1)>, L<req(1)>, L<ca(1)>
=head1 COPYRIGHT
-Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
diff --git a/doc/man7/Ed25519.pod b/doc/man7/Ed25519.pod
index 6442e0ea4378..8ab4fff76493 100644
--- a/doc/man7/Ed25519.pod
+++ b/doc/man7/Ed25519.pod
@@ -11,7 +11,7 @@ Ed448
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.
+RFC 8410.
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
@@ -77,7 +77,7 @@ L<EVP_DigestVerifyInit(3)>,
=head1 COPYRIGHT
-Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2020 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
diff --git a/doc/man7/X25519.pod b/doc/man7/X25519.pod
index 4851f8a1d9dc..6f153cb4b983 100644
--- a/doc/man7/X25519.pod
+++ b/doc/man7/X25519.pod
@@ -10,7 +10,7 @@ X448
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.
+key formats compatible with RFC 8410.
No additional parameters can be set during key generation.
@@ -64,7 +64,7 @@ L<EVP_PKEY_derive_set_peer(3)>
=head1 COPYRIGHT
-Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2020 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
diff --git a/doc/man7/passphrase-encoding.pod b/doc/man7/passphrase-encoding.pod
index 68108445269b..19dcef9acc36 100644
--- a/doc/man7/passphrase-encoding.pod
+++ b/doc/man7/passphrase-encoding.pod
@@ -65,7 +65,7 @@ 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
+SMALL LETTER I WITH DIAERESIS) 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.
@@ -170,7 +170,7 @@ L<d2i_PKCS8PrivateKey_bio(3)>
=head1 COPYRIGHT
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2018-2020 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
diff --git a/doc/man7/proxy-certificates.pod b/doc/man7/proxy-certificates.pod
new file mode 100644
index 000000000000..df5ee1b4b518
--- /dev/null
+++ b/doc/man7/proxy-certificates.pod
@@ -0,0 +1,363 @@
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+proxy-certificates - Proxy certificates in OpenSSL
+
+=head1 DESCRIPTION
+
+Proxy certificates are defined in RFC 3820. They are used to
+extend rights to some other entity (a computer process, typically, or
+sometimes to the user itself). This allows the entity to perform
+operations on behalf of the owner of the EE (End Entity) certificate.
+
+The requirements for a valid proxy certificate are:
+
+=over 4
+
+=item *
+
+They are issued by an End Entity, either a normal EE certificate, or
+another proxy certificate.
+
+=item *
+
+They must not have the B<subjectAltName> or B<issuerAltName>
+extensions.
+
+=item *
+
+They must have the B<proxyCertInfo> extension.
+
+=item *
+
+They must have the subject of their issuer, with one B<commonName>
+added.
+
+=back
+
+=head2 Enabling proxy certificate verification
+
+OpenSSL expects applications that want to use proxy certificates to be
+specially aware of them, and make that explicit. This is done by
+setting an X509 verification flag:
+
+ X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
+
+or
+
+ X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_ALLOW_PROXY_CERTS);
+
+See L</NOTES> for a discussion on this requirement.
+
+=head2 Creating proxy certificates
+
+Creating proxy certificates can be done using the L<openssl-x509(1)>
+command, with some extra extensions:
+
+ [ v3_proxy ]
+ # A proxy certificate MUST NEVER be a CA certificate.
+ basicConstraints=CA:FALSE
+
+ # Usual authority key ID
+ authorityKeyIdentifier=keyid,issuer:always
+
+ # The extension which marks this certificate as a proxy
+ proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB
+
+It's also possible to specify the proxy extension in a separate section:
+
+ proxyCertInfo=critical,@proxy_ext
+
+ [ proxy_ext ]
+ language=id-ppl-anyLanguage
+ pathlen=0
+ policy=text:BC
+
+The policy value has a specific syntax, I<syntag>:I<string>, where the
+I<syntag> determines what will be done with the string. The following
+I<syntag>s are recognised:
+
+=over 4
+
+=item B<text>
+
+indicates that the string is a byte sequence, without any encoding:
+
+ policy=text:räksmörgås
+
+=item B<hex>
+
+indicates the string is encoded hexadecimal encoded binary data, with
+colons between each byte (every second hex digit):
+
+ policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73
+
+=item B<file>
+
+indicates that the text of the policy should be taken from a file.
+The string is then a filename. This is useful for policies that are
+large (more than a few lines, e.g. XML documents).
+
+=back
+
+I<NOTE: The proxy policy value is what determines the rights granted
+to the process during the proxy certificate. It's up to the
+application to interpret and combine these policies.>
+
+With a proxy extension, creating a proxy certificate is a matter of
+two commands:
+
+ openssl req -new -config proxy.cnf \
+ -out proxy.req -keyout proxy.key \
+ -subj "/DC=org/DC=openssl/DC=users/CN=proxy 1"
+
+ openssl x509 -req -CAcreateserial -in proxy.req -out proxy.crt \
+ -CA user.crt -CAkey user.key -days 7 \
+ -extfile proxy.cnf -extensions v3_proxy1
+
+You can also create a proxy certificate using another proxy
+certificate as issuer (note: using a different configuration
+section for the proxy extensions):
+
+ openssl req -new -config proxy.cnf \
+ -out proxy2.req -keyout proxy2.key \
+ -subj "/DC=org/DC=openssl/DC=users/CN=proxy 1/CN=proxy 2"
+
+ openssl x509 -req -CAcreateserial -in proxy2.req -out proxy2.crt \
+ -CA proxy.crt -CAkey proxy.key -days 7 \
+ -extfile proxy.cnf -extensions v3_proxy2
+
+=head2 Using proxy certs in applications
+
+To interpret proxy policies, the application would normally start with
+some default rights (perhaps none at all), then compute the resulting
+rights by checking the rights against the chain of proxy certificates,
+user certificate and CA certificates.
+
+The complicated part is figuring out how to pass data between your
+application and the certificate validation procedure.
+
+The following ingredients are needed for such processing:
+
+=over 4
+
+=item *
+
+a callback function that will be called for every certificate being
+validated. The callback is called several times for each certificate,
+so you must be careful to do the proxy policy interpretation at the
+right time. You also need to fill in the defaults when the EE
+certificate is checked.
+
+=item *
+
+a data structure that is shared between your application code and the
+callback.
+
+=item *
+
+a wrapper function that sets it all up.
+
+=item *
+
+an ex_data index function that creates an index into the generic
+ex_data store that is attached to an X509 validation context.
+
+=back
+
+The following skeleton code can be used as a starting point:
+
+ #include <string.h>
+ #include <netdb.h>
+ #include <openssl/x509.h>
+ #include <openssl/x509v3.h>
+
+ #define total_rights 25
+
+ /*
+ * In this example, I will use a view of granted rights as a bit
+ * array, one bit for each possible right.
+ */
+ typedef struct your_rights {
+ unsigned char rights[(total_rights + 7) / 8];
+ } YOUR_RIGHTS;
+
+ /*
+ * The following procedure will create an index for the ex_data
+ * store in the X509 validation context the first time it's
+ * called. Subsequent calls will return the same index.
+ */
+ static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx)
+ {
+ static volatile int idx = -1;
+
+ if (idx < 0) {
+ X509_STORE_lock(X509_STORE_CTX_get0_store(ctx));
+ if (idx < 0) {
+ idx = X509_STORE_CTX_get_ex_new_index(0,
+ "for verify callback",
+ NULL,NULL,NULL);
+ }
+ X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx));
+ }
+ return idx;
+ }
+
+ /* Callback to be given to the X509 validation procedure. */
+ static int verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
+ if (ok == 1) {
+ /*
+ * It's REALLY important you keep the proxy policy check
+ * within this section. It's important to know that when
+ * ok is 1, the certificates are checked from top to
+ * bottom. You get the CA root first, followed by the
+ * possible chain of intermediate CAs, followed by the EE
+ * certificate, followed by the possible proxy
+ * certificates.
+ */
+ X509 *xs = X509_STORE_CTX_get_current_cert(ctx);
+
+ if (X509_get_extension_flags(xs) & EXFLAG_PROXY) {
+ YOUR_RIGHTS *rights =
+ (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
+ get_proxy_auth_ex_data_idx(ctx));
+ PROXY_CERT_INFO_EXTENSION *pci =
+ X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
+
+ switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) {
+ case NID_Independent:
+ /*
+ * Do whatever you need to grant explicit rights
+ * to this particular proxy certificate, usually
+ * by pulling them from some database. If there
+ * are none to be found, clear all rights (making
+ * this and any subsequent proxy certificate void
+ * of any rights).
+ */
+ memset(rights->rights, 0, sizeof(rights->rights));
+ break;
+ case NID_id_ppl_inheritAll:
+ /*
+ * This is basically a NOP, we simply let the
+ * current rights stand as they are.
+ */
+ break;
+ default:
+ /*
+ * This is usually the most complex section of
+ * code. You really do whatever you want as long
+ * as you follow RFC 3820. In the example we use
+ * here, the simplest thing to do is to build
+ * another, temporary bit array and fill it with
+ * the rights granted by the current proxy
+ * certificate, then use it as a mask on the
+ * accumulated rights bit array, and voilà, you
+ * now have a new accumulated rights bit array.
+ */
+ {
+ int i;
+ YOUR_RIGHTS tmp_rights;
+ memset(tmp_rights.rights, 0,
+ sizeof(tmp_rights.rights));
+
+ /*
+ * process_rights() is supposed to be a
+ * procedure that takes a string and its
+ * length, interprets it and sets the bits
+ * in the YOUR_RIGHTS pointed at by the
+ * third argument.
+ */
+ process_rights((char *) pci->proxyPolicy->policy->data,
+ pci->proxyPolicy->policy->length,
+ &tmp_rights);
+
+ for(i = 0; i < total_rights / 8; i++)
+ rights->rights[i] &= tmp_rights.rights[i];
+ }
+ break;
+ }
+ PROXY_CERT_INFO_EXTENSION_free(pci);
+ } else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) {
+ /* We have an EE certificate, let's use it to set default! */
+ YOUR_RIGHTS *rights =
+ (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
+ get_proxy_auth_ex_data_idx(ctx));
+
+ /*
+ * The following procedure finds out what rights the
+ * owner of the current certificate has, and sets them
+ * in the YOUR_RIGHTS structure pointed at by the
+ * second argument.
+ */
+ set_default_rights(xs, rights);
+ }
+ }
+ return ok;
+ }
+
+ static int my_X509_verify_cert(X509_STORE_CTX *ctx,
+ YOUR_RIGHTS *needed_rights)
+ {
+ int ok;
+ int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) =
+ X509_STORE_CTX_get_verify_cb(ctx);
+ YOUR_RIGHTS rights;
+
+ X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
+ X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx),
+ &rights);
+ X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
+ ok = X509_verify_cert(ctx);
+
+ if (ok == 1) {
+ ok = check_needed_rights(rights, needed_rights);
+ }
+
+ X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
+
+ return ok;
+ }
+
+If you use SSL or TLS, you can easily set up a callback to have the
+certificates checked properly, using the code above:
+
+ SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert,
+ &needed_rights);
+
+=head1 NOTES
+
+To this date, it seems that proxy certificates have only been used in
+environments that are aware of them, and no one seems to have
+investigated how they can be used or misused outside of such an
+environment.
+
+For that reason, OpenSSL requires that applications aware of proxy
+certificates must also make that explicit.
+
+B<subjectAltName> and B<issuerAltName> are forbidden in proxy
+certificates, and this is enforced in OpenSSL. The subject must be
+the same as the issuer, with one commonName added on.
+
+=head1 SEE ALSO
+
+L<X509_STORE_CTX_set_flags(3)>,
+L<X509_STORE_CTX_set_verify_cb(3)>,
+L<X509_VERIFY_PARAM_set_flags(3)>,
+L<SSL_CTX_set_cert_verify_callback(3)>,
+L<openssl-req(1)>, L<openssl-x509(1)>,
+L<RFC 3820|https://tools.ietf.org/html/rfc3820>
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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