aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJung-uk Kim <jkim@FreeBSD.org>2019-05-28 20:08:17 +0000
committerJung-uk Kim <jkim@FreeBSD.org>2019-05-28 20:08:17 +0000
commit375b8e6770f750fb915859470f6f1fe43f35cc48 (patch)
tree5db6744924edfc112439ad2366f52f246baa21d1 /doc
parent851f7386fd78b9787f4f6669ad271886a2a003f1 (diff)
downloadsrc-375b8e6770f750fb915859470f6f1fe43f35cc48.tar.gz
src-375b8e6770f750fb915859470f6f1fe43f35cc48.zip
Import OpenSSL 1.1.1c.vendor/openssl/1.1.1c
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=348333 svn path=/vendor-crypto/openssl/1.1.1c/; revision=348334; tag=vendor/openssl/1.1.1c
Diffstat (limited to 'doc')
-rw-r--r--doc/man1/genpkey.pod10
-rw-r--r--doc/man1/pkeyutl.pod13
-rw-r--r--doc/man1/s_client.pod4
-rw-r--r--doc/man1/s_server.pod2
-rw-r--r--doc/man1/s_time.pod4
-rw-r--r--doc/man1/ts.pod7
-rw-r--r--doc/man3/ASN1_TIME_set.pod66
-rw-r--r--doc/man3/ASN1_generate_nconf.pod16
-rw-r--r--doc/man3/BIO_connect.pod14
-rw-r--r--doc/man3/BIO_push.pod16
-rw-r--r--doc/man3/BIO_s_file.pod38
-rw-r--r--doc/man3/BIO_s_mem.pod18
-rw-r--r--doc/man3/BN_CTX_start.pod3
-rw-r--r--doc/man3/BN_new.pod3
-rw-r--r--doc/man3/BN_rand.pod20
-rw-r--r--doc/man3/BN_security_bits.pod10
-rw-r--r--doc/man3/CMS_verify.pod4
-rw-r--r--doc/man3/CONF_modules_load_file.pod12
-rw-r--r--doc/man3/DES_random_key.pod12
-rw-r--r--doc/man3/ECDSA_SIG_new.pod4
-rw-r--r--doc/man3/EVP_DigestVerifyInit.pod6
-rw-r--r--doc/man3/EVP_EncryptInit.pod10
-rw-r--r--doc/man3/EVP_PKEY_meth_new.pod10
-rw-r--r--doc/man3/EVP_PKEY_set1_RSA.pod21
-rw-r--r--doc/man3/EVP_chacha20.pod12
-rw-r--r--doc/man3/HMAC.pod4
-rw-r--r--doc/man3/OBJ_nid2obj.pod24
-rw-r--r--doc/man3/OCSP_cert_to_id.pod6
-rw-r--r--doc/man3/PEM_read_bio_PrivateKey.pod140
-rw-r--r--doc/man3/RAND_DRBG_generate.pod10
-rw-r--r--doc/man3/RAND_DRBG_get0_master.pod11
-rw-r--r--doc/man3/RAND_DRBG_new.pod10
-rw-r--r--doc/man3/RAND_DRBG_reseed.pod17
-rw-r--r--doc/man3/RAND_DRBG_set_callbacks.pod11
-rw-r--r--doc/man3/RAND_add.pod12
-rw-r--r--doc/man3/RAND_bytes.pod20
-rw-r--r--doc/man3/RAND_cleanup.pod10
-rw-r--r--doc/man3/RSA_padding_add_PKCS1_type_1.pod60
-rw-r--r--doc/man3/RSA_public_encrypt.pod38
-rw-r--r--doc/man3/SSL_CIPHER_get_name.pod17
-rw-r--r--doc/man3/SSL_CONF_cmd.pod34
-rw-r--r--doc/man3/SSL_CTX_load_verify_locations.pod36
-rw-r--r--doc/man3/SSL_CTX_new.pod14
-rw-r--r--doc/man3/SSL_CTX_set1_sigalgs.pod10
-rw-r--r--doc/man3/SSL_CTX_set_client_hello_cb.pod4
-rw-r--r--doc/man3/SSL_CTX_set_default_passwd_cb.pod12
-rw-r--r--doc/man3/SSL_CTX_set_generate_session_id.pod18
-rw-r--r--doc/man3/SSL_CTX_set_min_proto_version.pod10
-rw-r--r--doc/man3/SSL_CTX_set_read_ahead.pod4
-rw-r--r--doc/man3/SSL_CTX_set_split_send_fragment.pod10
-rw-r--r--doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod10
-rw-r--r--doc/man3/SSL_CTX_set_tmp_dh_callback.pod18
-rw-r--r--doc/man3/SSL_get_error.pod2
-rw-r--r--doc/man3/SSL_load_client_CA_file.pod32
-rw-r--r--doc/man3/SSL_read.pod10
-rw-r--r--doc/man3/SSL_session_reused.pod4
-rw-r--r--doc/man3/SSL_shutdown.pod2
-rw-r--r--doc/man3/SSL_write.pod10
-rw-r--r--doc/man3/X509_LOOKUP_meth_new.pod20
-rw-r--r--doc/man3/X509_NAME_add_entry_by_txt.pod20
-rw-r--r--doc/man3/X509_NAME_get_index_by_NID.pod26
-rw-r--r--doc/man3/X509_get_subject_name.pod18
-rw-r--r--doc/man3/d2i_X509.pod28
63 files changed, 583 insertions, 494 deletions
diff --git a/doc/man1/genpkey.pod b/doc/man1/genpkey.pod
index 202e531c7e07..1ba54d486619 100644
--- a/doc/man1/genpkey.pod
+++ b/doc/man1/genpkey.pod
@@ -118,7 +118,7 @@ or ED448 algorithms.
=item B<rsa_keygen_bits:numbits>
-The number of bits in the generated key. If not specified 1024 is used.
+The number of bits in the generated key. If not specified 2048 is used.
=item B<rsa_keygen_primes:numprimes>
@@ -185,12 +185,12 @@ below.
=item B<dsa_paramgen_bits:numbits>
-The number of bits in the generated prime. If not specified 1024 is used.
+The number of bits in the generated prime. If not specified 2048 is used.
=item B<dsa_paramgen_q_bits:numbits>
The number of bits in the q parameter. Must be one of 160, 224 or 256. If not
-specified 160 is used.
+specified 224 is used.
=item B<dsa_paramgen_md:digest>
@@ -209,7 +209,7 @@ or B<sha256> if it is 256.
=item B<dh_paramgen_prime_len:numbits>
-The number of bits in the prime parameter B<p>. The default is 1024.
+The number of bits in the prime parameter B<p>. The default is 2048.
=item B<dh_paramgen_subprime_len:numbits>
@@ -325,7 +325,7 @@ The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-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/pkeyutl.pod b/doc/man1/pkeyutl.pod
index 664dbef3598b..dffc449a4e0e 100644
--- a/doc/man1/pkeyutl.pod
+++ b/doc/man1/pkeyutl.pod
@@ -272,20 +272,19 @@ value less than the minimum restriction.
=head1 DSA ALGORITHM
The DSA algorithm supports signing and verification operations only. Currently
-there are no additional options other than B<digest>. Only the SHA1
-digest can be used and this digest is assumed by default.
+there are no additional B<-pkeyopt> options other than B<digest>. The SHA1
+digest is assumed by default.
=head1 DH ALGORITHM
The DH algorithm only supports the derivation operation and no additional
-options.
+B<-pkeyopt> options.
=head1 EC ALGORITHM
The EC algorithm supports sign, verify and derive operations. The sign and
-verify operations use ECDSA and derive uses ECDH. Currently there are no
-additional options other than B<digest>. Only the SHA1 digest can be used and
-this digest is assumed by default.
+verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for
+the B<-pkeyopt> B<digest> option.
=head1 X25519 and X448 ALGORITHMS
@@ -328,7 +327,7 @@ L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
=head1 COPYRIGHT
-Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-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 81d516ace146..15752b5e1613 100644
--- a/doc/man1/s_client.pod
+++ b/doc/man1/s_client.pod
@@ -201,7 +201,7 @@ Even though SNI should normally be a DNS name and not an IP address, if
B<-servername> is provided then that name will be sent, regardless of whether
it is a DNS name or not.
-This option cannot be used in conjuction with B<-noservername>.
+This option cannot be used in conjunction with B<-noservername>.
=item B<-noservername>
@@ -542,7 +542,7 @@ further information).
=item B<-bugs>
-There are several known bug in SSL and TLS implementations. Adding this
+There are several known bugs in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-comp>
diff --git a/doc/man1/s_server.pod b/doc/man1/s_server.pod
index c4c014fdc18b..768789633e7f 100644
--- a/doc/man1/s_server.pod
+++ b/doc/man1/s_server.pod
@@ -542,7 +542,7 @@ OpenSSL was built.
=item B<-bugs>
-There are several known bug in SSL and TLS implementations. Adding this
+There are several known bugs in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-no_comp>
diff --git a/doc/man1/s_time.pod b/doc/man1/s_time.pod
index c08e44a431be..ac32f36bc789 100644
--- a/doc/man1/s_time.pod
+++ b/doc/man1/s_time.pod
@@ -127,7 +127,7 @@ OpenSSL was built.
=item B<-bugs>
-There are several known bug in SSL and TLS implementations. Adding this
+There are several known bugs in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-cipher cipherlist>
@@ -202,7 +202,7 @@ L<s_client(1)>, L<s_server(1)>, L<ciphers(1)>
=head1 COPYRIGHT
-Copyright 2004-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2004-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/ts.pod b/doc/man1/ts.pod
index eeccaf674c1a..ec57ec7ebbd4 100644
--- a/doc/man1/ts.pod
+++ b/doc/man1/ts.pod
@@ -262,7 +262,7 @@ specified, the argument is given to the engine as a key identifier.
=item B<-I<digest>>
Signing digest to use. Overrides the B<signer_digest> config file
-option. (Optional)
+option. (Mandatory unless specified in the config file)
=item B<-chain> certs_file.pem
@@ -460,7 +460,8 @@ command line option. (Optional)
=item B<signer_digest>
Signing digest to use. The same as the
-B<-I<digest>> command line option. (Optional)
+B<-I<digest>> command line option. (Mandatory unless specified on the command
+line)
=item B<default_policy>
@@ -664,7 +665,7 @@ L<config(5)>
=head1 COPYRIGHT
-Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-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/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod
index a083ebfd1bd4..5ed817517dc6 100644
--- a/doc/man3/ASN1_TIME_set.pod
+++ b/doc/man3/ASN1_TIME_set.pod
@@ -173,38 +173,6 @@ certificates complying with RFC5280 et al use GMT anyway.
Use the ASN1_TIME_normalize() function to normalize the time value before
printing to get GMT results.
-=head1 EXAMPLES
-
-Set a time structure to one hour after the current time and print it out:
-
- #include <time.h>
- #include <openssl/asn1.h>
-
- ASN1_TIME *tm;
- time_t t;
- BIO *b;
-
- t = time(NULL);
- tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
- b = BIO_new_fp(stdout, BIO_NOCLOSE);
- ASN1_TIME_print(b, tm);
- ASN1_STRING_free(tm);
- BIO_free(b);
-
-Determine if one time is later or sooner than the current time:
-
- int day, sec;
-
- if (!ASN1_TIME_diff(&day, &sec, NULL, to))
- /* Invalid time format */
-
- if (day > 0 || sec > 0)
- printf("Later\n");
- else if (day < 0 || sec < 0)
- printf("Sooner\n");
- else
- printf("Same\n");
-
=head1 RETURN VALUES
ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(),
@@ -238,6 +206,38 @@ ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or
ASN1_TIME_to_generalizedtime() returns a pointer to
the appropriate time structure on success or NULL if an error occurred.
+=head1 EXAMPLES
+
+Set a time structure to one hour after the current time and print it out:
+
+ #include <time.h>
+ #include <openssl/asn1.h>
+
+ ASN1_TIME *tm;
+ time_t t;
+ BIO *b;
+
+ t = time(NULL);
+ tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
+ b = BIO_new_fp(stdout, BIO_NOCLOSE);
+ ASN1_TIME_print(b, tm);
+ ASN1_STRING_free(tm);
+ BIO_free(b);
+
+Determine if one time is later or sooner than the current time:
+
+ int day, sec;
+
+ if (!ASN1_TIME_diff(&day, &sec, NULL, to))
+ /* Invalid time format */
+
+ if (day > 0 || sec > 0)
+ printf("Later\n");
+ else if (day < 0 || sec < 0)
+ printf("Sooner\n");
+ else
+ printf("Same\n");
+
=head1 HISTORY
The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1.
@@ -248,7 +248,7 @@ The ASN1_TIME_compare() function was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-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/ASN1_generate_nconf.pod b/doc/man3/ASN1_generate_nconf.pod
index bf29af62f729..422bf7b7ed3d 100644
--- a/doc/man3/ASN1_generate_nconf.pod
+++ b/doc/man3/ASN1_generate_nconf.pod
@@ -162,6 +162,13 @@ bits are zero.
=back
+=head1 RETURN VALUES
+
+ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
+data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
+
+The error codes that can be obtained by L<ERR_get_error(3)>.
+
=head1 EXAMPLES
A simple IA5String:
@@ -247,20 +254,13 @@ structure:
e=INTEGER:0x010001
-=head1 RETURN VALUES
-
-ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
-data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
-
-The error codes that can be obtained by L<ERR_get_error(3)>.
-
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 COPYRIGHT
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-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/BIO_connect.pod b/doc/man3/BIO_connect.pod
index 454832e7e032..2766c3d6c5b7 100644
--- a/doc/man3/BIO_connect.pod
+++ b/doc/man3/BIO_connect.pod
@@ -95,19 +95,19 @@ B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
OpenSSL error stack will hold the error data and errno has the system
error.
-=head1 HISTORY
-
-BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
-BIO_get_accept_socket() and BIO_accept() were deprecated in
-OpenSSL 1.1.0. Use the functions described above instead.
-
=head1 SEE ALSO
L<BIO_ADDR(3)>
+=head1 HISTORY
+
+BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
+BIO_get_accept_socket() and BIO_accept() were deprecated in OpenSSL 1.1.0.
+Use the functions described above instead.
+
=head1 COPYRIGHT
-Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-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/BIO_push.pod b/doc/man3/BIO_push.pod
index ce56db9836ff..93f2cc31fdae 100644
--- a/doc/man3/BIO_push.pod
+++ b/doc/man3/BIO_push.pod
@@ -36,6 +36,13 @@ The process of calling BIO_push() and BIO_pop() on a BIO may have additional
consequences (a control call is made to the affected BIOs) any effects will
be noted in the descriptions of individual BIOs.
+=head1 RETURN VALUES
+
+BIO_push() returns the end of the chain, B<b>.
+
+BIO_pop() returns the next BIO in the chain, or NULL if there is no next
+BIO.
+
=head1 EXAMPLES
For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
@@ -62,13 +69,6 @@ by B<md1> and B<md2>. If the call:
The call will return B<b64> and the new chain will be B<md1-b64-f> data can
be written to B<md1> as before.
-=head1 RETURN VALUES
-
-BIO_push() returns the end of the chain, B<b>.
-
-BIO_pop() returns the next BIO in the chain, or NULL if there is no next
-BIO.
-
=head1 SEE ALSO
L<bio>
@@ -79,7 +79,7 @@ The BIO_set_next() function was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
-Copyright 2000-2016 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/man3/BIO_s_file.pod b/doc/man3/BIO_s_file.pod
index 23cdc9b684a6..2ed0bb3c0f35 100644
--- a/doc/man3/BIO_s_file.pod
+++ b/doc/man3/BIO_s_file.pod
@@ -80,6 +80,24 @@ On Windows BIO_new_files reserves for the filename argument to be
UTF-8 encoded. In other words if you have to make it work in multi-
lingual environment, encode file names in UTF-8.
+=head1 RETURN VALUES
+
+BIO_s_file() returns the file BIO method.
+
+BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
+occurred.
+
+BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
+(although the current implementation never return 0).
+
+BIO_seek() returns the same value as the underlying fseek() function:
+0 for success or -1 for failure.
+
+BIO_tell() returns the current file position.
+
+BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
+BIO_rw_filename() return 1 for success or 0 for failure.
+
=head1 EXAMPLES
File BIO "hello world":
@@ -122,24 +140,6 @@ Alternative technique:
BIO_printf(out, "Hello World\n");
BIO_free(out);
-=head1 RETURN VALUES
-
-BIO_s_file() returns the file BIO method.
-
-BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
-occurred.
-
-BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
-(although the current implementation never return 0).
-
-BIO_seek() returns the same value as the underlying fseek() function:
-0 for success or -1 for failure.
-
-BIO_tell() returns the current file position.
-
-BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
-BIO_rw_filename() return 1 for success or 0 for failure.
-
=head1 BUGS
BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
@@ -158,7 +158,7 @@ L<BIO_set_close(3)>, L<BIO_get_close(3)>
=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/man3/BIO_s_mem.pod b/doc/man3/BIO_s_mem.pod
index 050d7786a6cf..2a5d423648db 100644
--- a/doc/man3/BIO_s_mem.pod
+++ b/doc/man3/BIO_s_mem.pod
@@ -88,6 +88,22 @@ a buffering BIO to the chain will speed up the process.
Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
give undefined results, including perhaps a program crash.
+Switching the memory BIO from read write to read only is not supported and
+can give undefined results including a program crash. There are two notable
+exceptions to the rule. The first one is to assign a static memory buffer
+immediately after BIO creation and set the BIO as read only.
+
+The other supported sequence is to start with read write BIO then temporarily
+switch it to read only and call BIO_reset() on the read only BIO immediately
+before switching it back to read write. Before the BIO is freed it must be
+switched back to the read write mode.
+
+Calling BIO_get_mem_ptr() on read only BIO will return a BUF_MEM that
+contains only the remaining data to be read. If the close status of the
+BIO is set to BIO_NOCLOSE, before freeing the BUF_MEM the data pointer
+in it must be set to NULL as the data pointer does not point to an
+allocated memory.
+
=head1 BUGS
There should be an option to set the maximum size of a memory BIO.
@@ -124,7 +140,7 @@ BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
=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/man3/BN_CTX_start.pod b/doc/man3/BN_CTX_start.pod
index 372da506d9d3..bb039e5539cd 100644
--- a/doc/man3/BN_CTX_start.pod
+++ b/doc/man3/BN_CTX_start.pod
@@ -27,6 +27,7 @@ calls must be made before calling any other functions that use the
B<ctx> as an argument.
Finally, BN_CTX_end() must be called before returning from the function.
+If B<ctx> is NULL, nothing is done.
When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from
BN_CTX_get() become invalid.
@@ -47,7 +48,7 @@ L<BN_CTX_new(3)>
=head1 COPYRIGHT
-Copyright 2000-2016 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/man3/BN_new.pod b/doc/man3/BN_new.pod
index 08aae5e91915..1fab6d26eb19 100644
--- a/doc/man3/BN_new.pod
+++ b/doc/man3/BN_new.pod
@@ -27,6 +27,7 @@ OPENSSL_secure_malloc(3) is used to store the value.
BN_clear() is used to destroy sensitive data such as keys when they
are no longer needed. It erases the memory used by B<a> and sets it
to the value 0.
+If B<a> is NULL, nothing is done.
BN_free() frees the components of the B<BIGNUM>, and if it was created
by BN_new(), also the structure itself. BN_clear_free() additionally
@@ -53,7 +54,7 @@ BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.
=head1 COPYRIGHT
-Copyright 2000-2017 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/man3/BN_rand.pod b/doc/man3/BN_rand.pod
index 90b50ffc311e..d57348e62b8c 100644
--- a/doc/man3/BN_rand.pod
+++ b/doc/man3/BN_rand.pod
@@ -59,6 +59,15 @@ seeded with enough randomness to ensure an unpredictable byte sequence.
The functions return 1 on success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<RAND_add(3)>,
+L<RAND_bytes(3)>,
+L<RAND_priv_bytes(3)>,
+L<RAND(7)>,
+L<RAND_DRBG(7)>
+
=head1 HISTORY
=over 2
@@ -78,18 +87,9 @@ BN_priv_rand() and BN_priv_rand_range() functions were added in OpenSSL 1.1.1.
=back
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<RAND_add(3)>,
-L<RAND_bytes(3)>,
-L<RAND_priv_bytes(3)>,
-L<RAND(7)>,
-L<RAND_DRBG(7)>
-
=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/man3/BN_security_bits.pod b/doc/man3/BN_security_bits.pod
index f6e5857a4eed..acf59027ba24 100644
--- a/doc/man3/BN_security_bits.pod
+++ b/doc/man3/BN_security_bits.pod
@@ -31,17 +31,17 @@ Number of security bits.
ECC (Elliptic Curve Cryptography) is not covered by the BN_security_bits()
function. The symmetric algorithms are not covered neither.
-=head1 HISTORY
-
-The BN_security_bits() function was added in OpenSSL 1.1.0.
-
=head1 SEE ALSO
L<DH_security_bits(3)>, L<DSA_security_bits(3)>, L<RSA_security_bits(3)>
+=head1 HISTORY
+
+The BN_security_bits() function was added in OpenSSL 1.1.0.
+
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/CMS_verify.pod b/doc/man3/CMS_verify.pod
index 7187d9840ab6..be688681cbc6 100644
--- a/doc/man3/CMS_verify.pod
+++ b/doc/man3/CMS_verify.pod
@@ -46,7 +46,7 @@ are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
CRLs are used in addition to attempting to look them up in B<store>. If any
chain verify fails an error code is returned.
-Finally the signed content is read (and written to B<out> is it is not NULL)
+Finally the signed content is read (and written to B<out> if it is not NULL)
and the signature's checked.
If all signature's verify correctly then the function is successful.
@@ -122,7 +122,7 @@ L<ERR_get_error(3)>, L<CMS_sign(3)>
=head1 COPYRIGHT
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-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/CONF_modules_load_file.pod b/doc/man3/CONF_modules_load_file.pod
index 485cf797b12e..04fbd60f40b7 100644
--- a/doc/man3/CONF_modules_load_file.pod
+++ b/doc/man3/CONF_modules_load_file.pod
@@ -67,6 +67,12 @@ Applications can use the CONF_modules_load() function if they wish to load a
configuration file themselves and have finer control over how errors are
treated.
+=head1 RETURN VALUES
+
+These functions return 1 for success and a zero or negative value for
+failure. If module errors are not ignored the return code will reflect the
+return value of the failing module (this will always be zero or negative).
+
=head1 EXAMPLES
Load a configuration file and print out any errors and exit (missing file
@@ -122,12 +128,6 @@ Load and parse configuration file manually, custom error handling:
NCONF_free(cnf);
}
-=head1 RETURN VALUES
-
-These functions return 1 for success and a zero or negative value for
-failure. If module errors are not ignored the return code will reflect the
-return value of the failing module (this will always be zero or negative).
-
=head1 SEE ALSO
L<config(5)>, L<OPENSSL_config(3)>
diff --git a/doc/man3/DES_random_key.pod b/doc/man3/DES_random_key.pod
index 6e0394d637b2..bd4bd9750cd3 100644
--- a/doc/man3/DES_random_key.pod
+++ b/doc/man3/DES_random_key.pod
@@ -296,6 +296,11 @@ last 4 bytes of the checksum of the input.
DES_fcrypt() returns a pointer to the caller-provided buffer and DES_crypt() -
to a static buffer on success; otherwise they return NULL.
+=head1 SEE ALSO
+
+L<des_modes(7)>,
+L<EVP_EncryptInit(3)>
+
=head1 HISTORY
The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
@@ -304,14 +309,9 @@ OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A>
if both character were not present, and could crash when given non-ASCII
on some platforms.
-=head1 SEE ALSO
-
-L<des_modes(7)>,
-L<EVP_EncryptInit(3)>
-
=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/man3/ECDSA_SIG_new.pod b/doc/man3/ECDSA_SIG_new.pod
index 0bf63f8bde80..8d6cda5e7a3c 100644
--- a/doc/man3/ECDSA_SIG_new.pod
+++ b/doc/man3/ECDSA_SIG_new.pod
@@ -200,13 +200,13 @@ ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
=head1 SEE ALSO
-L<DSA_new(3)>,
+L<EC_KEY_new(3)>,
L<EVP_DigestSignInit(3)>,
L<EVP_DigestVerifyInit(3)>
=head1 COPYRIGHT
-Copyright 2004-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2004-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/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod
index 98a0987a3aaa..592a7508dce0 100644
--- a/doc/man3/EVP_DigestVerifyInit.pod
+++ b/doc/man3/EVP_DigestVerifyInit.pod
@@ -28,8 +28,8 @@ EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this
can be used to set alternative verification options. Note that any existing
value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed
directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before
-being passed to EVP_DigestSignInit() (which means the EVP_PKEY_CTX is created
-inside EVP_DigestSignInit() and it will be freed automatically when the
+being passed to EVP_DigestVerifyInit() (which means the EVP_PKEY_CTX is created
+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_DigsetSignInit() if the passed B<ctx>
@@ -102,7 +102,7 @@ were added in OpenSSL 1.0.0.
=head1 COPYRIGHT
-Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-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/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index b43a3e5468ca..6b068617b0ad 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -412,7 +412,9 @@ The following I<ctrl>s are supported in CCM mode.
This call is made to set the expected B<CCM> tag value when decrypting or
the length of the tag (with the C<tag> parameter set to NULL) when encrypting.
The tag length is often referred to as B<M>. If not set a default value is
-used (12 for AES).
+used (12 for AES). When decrypting, the tag needs to be set before passing
+in data to be decrypted, but as in GCM and OCB mode, it can be set after
+passing additional authenticated data (see L<AEAD Interface>).
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
@@ -436,7 +438,9 @@ The following I<ctrl>s are supported for the ChaCha20-Poly1305 AEAD algorithm.
Sets the nonce length. This call can only be made before specifying the nonce.
If not called a default nonce length of 12 (i.e. 96 bits) is used. The maximum
-nonce length is 16 (B<CHACHA_CTR_SIZE>, i.e. 128-bits).
+nonce length is 12 bytes (i.e. 96-bits). If a nonce of less than 12 bytes is set
+then the nonce is automatically padded with leading 0 bytes to make it 12 bytes
+in length.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
@@ -641,7 +645,7 @@ EVP_CIPHER_CTX_reset().
=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/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod
index db803fc2a268..8a167ce0d6ff 100644
--- a/doc/man3/EVP_PKEY_meth_new.pod
+++ b/doc/man3/EVP_PKEY_meth_new.pod
@@ -286,7 +286,7 @@ L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
The signctx_init() and signctx() methods are used to sign a digest present by
a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See
-L<EVP_DigestSignInit(3)> for detail.
+L<EVP_DigestSignInit(3)> for details.
int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen,
@@ -294,7 +294,7 @@ L<EVP_DigestSignInit(3)> for detail.
The verifyctx_init() and verifyctx() methods are used to verify a signature
against the data in a B<EVP_MD_CTX> object. They are called by the various
-EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail.
+EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for details.
int (*encrypt_init) (EVP_PKEY_CTX *ctx);
int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
@@ -321,7 +321,7 @@ L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>.
int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value);
The ctrl() and ctrl_str() methods are used to adjust algorithm-specific
-settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
+settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for details.
int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen,
const unsigned char *tbs, size_t tbslen);
@@ -330,7 +330,7 @@ settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail.
size_t tbslen);
The digestsign() and digestverify() methods are used to generate or verify
-a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
+a signature in a one-shot mode. They could be called by L<EVP_DigestSign(3)>
and L<EVP_DigestVerify(3)>.
int (*check) (EVP_PKEY *pkey);
@@ -414,7 +414,7 @@ arguments.
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod
index d10fc59d8bcc..d571e58d95ba 100644
--- a/doc/man3/EVP_PKEY_set1_RSA.pod
+++ b/doc/man3/EVP_PKEY_set1_RSA.pod
@@ -9,7 +9,7 @@ EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id, EVP_PKEY_set_alias_type,
-EVP_PKEY_set1_engine - EVP_PKEY assignment functions
+EVP_PKEY_set1_engine, EVP_PKEY_get0_engine - EVP_PKEY assignment functions
=head1 SYNOPSIS
@@ -45,6 +45,7 @@ EVP_PKEY_set1_engine - EVP_PKEY assignment functions
int EVP_PKEY_type(int type);
int EVP_PKEY_set_alias_type(EVP_PKEY *pkey, int type);
+ ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
=head1 DESCRIPTION
@@ -81,6 +82,8 @@ often seen in practice.
EVP_PKEY_type() returns the underlying type of the NID B<type>. For example
EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
+EVP_PKEY_get0_engine() returns a reference to the ENGINE handling B<pkey>.
+
EVP_PKEY_set1_engine() sets the ENGINE handling B<pkey> to B<engine>. It
must be called after the key algorithm and components are set up.
If B<engine> does not include an B<EVP_PKEY_METHOD> for B<pkey> an
@@ -111,13 +114,6 @@ is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM
key as part of its routine to load a private key.
-=head1 EXAMPLES
-
-After loading an ECC key, it is possible to convert it to using SM2
-algorithms with EVP_PKEY_set_alias_type:
-
- EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
-
=head1 RETURN VALUES
EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
@@ -138,13 +134,20 @@ EVP_PKEY_set1_engine() returns 1 for success and 0 for failure.
EVP_PKEY_set_alias_type() returns 1 for success and 0 for error.
+=head1 EXAMPLES
+
+After loading an ECC key, it is possible to convert it to using SM2
+algorithms with EVP_PKEY_set_alias_type:
+
+ EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
+
=head1 SEE ALSO
L<EVP_PKEY_new(3)>
=head1 COPYRIGHT
-Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-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/EVP_chacha20.pod b/doc/man3/EVP_chacha20.pod
index 96da825cded4..a21b64859568 100644
--- a/doc/man3/EVP_chacha20.pod
+++ b/doc/man3/EVP_chacha20.pod
@@ -21,7 +21,15 @@ The ChaCha20 stream cipher for EVP.
=item EVP_chacha20()
-The ChaCha20 stream cipher. The key length is 256 bits, the IV is 96 bits long.
+The ChaCha20 stream cipher. The key length is 256 bits, the IV is 128 bits long.
+The first 32 bits consists of a counter in little-endian order followed by a 96
+bit nonce. For example a nonce of:
+
+000000000000000000000002
+
+With an initial counter of 42 (2a in hex) would be expressed as:
+
+2a000000000000000000000000000002
=item EVP_chacha20_poly1305()
@@ -46,7 +54,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/HMAC.pod b/doc/man3/HMAC.pod
index 65386a7baa31..30c0e6bac392 100644
--- a/doc/man3/HMAC.pod
+++ b/doc/man3/HMAC.pod
@@ -63,7 +63,9 @@ If B<md> is NULL, the digest is placed in a static array. The size of
the output is placed in B<md_len>, unless it is B<NULL>. Note: passing a NULL
value for B<md> to use the static array is not thread safe.
-B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
+B<evp_md> is a message digest such as EVP_sha1(), EVP_ripemd160() etc. HMAC does
+not support variable output length digests such as EVP_shake128() and
+EVP_shake256().
HMAC_CTX_new() creates a new HMAC_CTX in heap memory.
diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod
index cbf889f2c711..f84d5b1eb384 100644
--- a/doc/man3/OBJ_nid2obj.pod
+++ b/doc/man3/OBJ_nid2obj.pod
@@ -130,6 +130,17 @@ These functions cannot return B<const> because an B<ASN1_OBJECT> can
represent both an internal, constant, OID and a dynamically-created one.
The latter cannot be constant because it needs to be freed after use.
+=head1 RETURN VALUES
+
+OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
+error occurred.
+
+OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
+on error.
+
+OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
+a NID or B<NID_undef> on error.
+
=head1 EXAMPLES
Create an object for B<commonName>:
@@ -159,17 +170,6 @@ Instead B<buf> must point to a valid buffer and B<buf_len> should
be set to a positive value. A buffer length of 80 should be more
than enough to handle any OID encountered in practice.
-=head1 RETURN VALUES
-
-OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
-error occurred.
-
-OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
-on error.
-
-OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
-a NID or B<NID_undef> on error.
-
=head1 SEE ALSO
L<ERR_get_error(3)>
@@ -181,7 +181,7 @@ and should not be used.
=head1 COPYRIGHT
-Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-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/OCSP_cert_to_id.pod b/doc/man3/OCSP_cert_to_id.pod
index f1a4b1512b64..c8d39c191358 100644
--- a/doc/man3/OCSP_cert_to_id.pod
+++ b/doc/man3/OCSP_cert_to_id.pod
@@ -19,8 +19,8 @@ OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions
void OCSP_CERTID_free(OCSP_CERTID *id);
- int OCSP_id_issuer_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
- int OCSP_id_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
+ int OCSP_id_issuer_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b);
+ int OCSP_id_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b);
int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd,
ASN1_OCTET_STRING **pikeyHash,
@@ -79,7 +79,7 @@ L<OCSP_sendreq_new(3)>
=head1 COPYRIGHT
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-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/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 744a46f81ed9..7c381e85feff 100644
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -298,71 +298,6 @@ arbitrary data to be passed to the callback by the application
B<must> return the number of characters in the passphrase or -1 if
an error occurred.
-=head1 EXAMPLES
-
-Although the PEM routines take several arguments in almost all applications
-most of them are set to 0 or NULL.
-
-Read a certificate in PEM format from a BIO:
-
- X509 *x;
-
- x = PEM_read_bio_X509(bp, NULL, 0, NULL);
- if (x == NULL)
- /* Error */
-
-Alternative method:
-
- X509 *x = NULL;
-
- if (!PEM_read_bio_X509(bp, &x, 0, NULL))
- /* Error */
-
-Write a certificate to a BIO:
-
- if (!PEM_write_bio_X509(bp, x))
- /* Error */
-
-Write a private key (using traditional format) to a BIO using
-triple DES encryption, the pass phrase is prompted for:
-
- if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
- /* Error */
-
-Write a private key (using PKCS#8 format) to a BIO using triple
-DES encryption, using the pass phrase "hello":
-
- if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
- NULL, 0, 0, "hello"))
- /* Error */
-
-Read a private key from a BIO using a pass phrase callback:
-
- key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
- if (key == NULL)
- /* Error */
-
-Skeleton pass phrase callback:
-
- int pass_cb(char *buf, int size, int rwflag, void *u)
- {
-
- /* We'd probably do something else if 'rwflag' is 1 */
- printf("Enter pass phrase for \"%s\"\n", (char *)u);
-
- /* get pass phrase, length 'len' into 'tmp' */
- char *tmp = "hello";
- if (tmp == NULL) /* An error occurred */
- return -1;
-
- size_t len = strlen(tmp);
-
- if (len > size)
- len = size;
- memcpy(buf, tmp, len);
- return len;
- }
-
=head1 NOTES
The old B<PrivateKey> write routines are retained for compatibility.
@@ -460,20 +395,85 @@ if an error occurred.
The write routines return 1 for success or 0 for failure.
-=head1 HISTORY
+=head1 EXAMPLES
-The old Netscape certificate sequences were no longer documented
-in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
-as they will be formally deprecated in a future releases.
+Although the PEM routines take several arguments in almost all applications
+most of them are set to 0 or NULL.
+
+Read a certificate in PEM format from a BIO:
+
+ X509 *x;
+
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+ if (x == NULL)
+ /* Error */
+
+Alternative method:
+
+ X509 *x = NULL;
+
+ if (!PEM_read_bio_X509(bp, &x, 0, NULL))
+ /* Error */
+
+Write a certificate to a BIO:
+
+ if (!PEM_write_bio_X509(bp, x))
+ /* Error */
+
+Write a private key (using traditional format) to a BIO using
+triple DES encryption, the pass phrase is prompted for:
+
+ if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
+ /* Error */
+
+Write a private key (using PKCS#8 format) to a BIO using triple
+DES encryption, using the pass phrase "hello":
+
+ if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
+ NULL, 0, 0, "hello"))
+ /* Error */
+
+Read a private key from a BIO using a pass phrase callback:
+
+ key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
+ if (key == NULL)
+ /* Error */
+
+Skeleton pass phrase callback:
+
+ int pass_cb(char *buf, int size, int rwflag, void *u)
+ {
+
+ /* We'd probably do something else if 'rwflag' is 1 */
+ printf("Enter pass phrase for \"%s\"\n", (char *)u);
+
+ /* get pass phrase, length 'len' into 'tmp' */
+ char *tmp = "hello";
+ if (tmp == NULL) /* An error occurred */
+ return -1;
+
+ size_t len = strlen(tmp);
+
+ if (len > size)
+ len = size;
+ memcpy(buf, tmp, len);
+ return len;
+ }
=head1 SEE ALSO
L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>,
L<passphrase-encoding(7)>
+=head1 HISTORY
+
+The old Netscape certificate sequences were no longer documented
+in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
+as they will be formally deprecated in a future releases.
+
=head1 COPYRIGHT
-Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-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/RAND_DRBG_generate.pod b/doc/man3/RAND_DRBG_generate.pod
index b39ee93f5142..bee2d6c176ef 100644
--- a/doc/man3/RAND_DRBG_generate.pod
+++ b/doc/man3/RAND_DRBG_generate.pod
@@ -65,10 +65,6 @@ Since the default DRBG implementation does not have access to such an approved
entropy source, a request for prediction resistance will always fail.
In other words, prediction resistance is currently not supported yet by the DRBG.
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_bytes(3)>,
@@ -76,9 +72,13 @@ L<RAND_DRBG_set_reseed_interval(3)>,
L<RAND_DRBG_set_reseed_time_interval(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/RAND_DRBG_get0_master.pod b/doc/man3/RAND_DRBG_get0_master.pod
index c958bf20ec0f..55d1eab7c21f 100644
--- a/doc/man3/RAND_DRBG_get0_master.pod
+++ b/doc/man3/RAND_DRBG_get0_master.pod
@@ -53,11 +53,6 @@ During initialization, it is possible to change the reseed interval
and reseed time interval.
It is also possible to exchange the reseeding callbacks entirely.
-
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_DRBG_set_callbacks(3)>,
@@ -68,9 +63,13 @@ L<RAND_DRBG_set_callbacks(3)>,
L<RAND_DRBG_generate(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod
index dcd7a944190f..5da91be9dfab 100644
--- a/doc/man3/RAND_DRBG_new.pod
+++ b/doc/man3/RAND_DRBG_new.pod
@@ -104,10 +104,6 @@ To ensure that they are applied to the global and thread-local DRBG instances
RAND_DRBG_set_defaults() before creating any thread and before calling any
cryptographic routines that obtain random data directly or indirectly.
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<OPENSSL_zalloc(3)>,
@@ -115,9 +111,13 @@ L<OPENSSL_secure_zalloc(3)>,
L<RAND_DRBG_generate(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/RAND_DRBG_reseed.pod b/doc/man3/RAND_DRBG_reseed.pod
index da3a40be4424..3610c1301e09 100644
--- a/doc/man3/RAND_DRBG_reseed.pod
+++ b/doc/man3/RAND_DRBG_reseed.pod
@@ -13,7 +13,8 @@ RAND_DRBG_set_reseed_defaults
#include <openssl/rand_drbg.h>
int RAND_DRBG_reseed(RAND_DRBG *drbg,
- const unsigned char *adin, size_t adinlen);
+ const unsigned char *adin, size_t adinlen,
+ int prediction_resistance);
int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg,
unsigned int interval);
@@ -37,6 +38,10 @@ and mixing in the specified additional data provided in the buffer B<adin>
of length B<adinlen>.
The additional data can be omitted by setting B<adin> to NULL and B<adinlen>
to 0.
+An immediate reseeding from a live entropy source can be requested by setting
+the B<prediction_resistance> flag to 1.
+This feature is not implemented yet, so reseeding with prediction resistance
+requested will always fail.
RAND_DRBG_set_reseed_interval()
sets the reseed interval of the B<drbg>, which is the maximum allowed number
@@ -88,10 +93,6 @@ To ensure that they are applied to the global and thread-local DRBG instances
RAND_DRBG_set_reseed_defaults() before creating any thread and before calling any
cryptographic routines that obtain random data directly or indirectly.
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_DRBG_generate(3)>,
@@ -99,9 +100,13 @@ L<RAND_DRBG_bytes(3)>,
L<RAND_DRBG_set_callbacks(3)>.
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod
index a927d6a7dacc..3da051e696aa 100644
--- a/doc/man3/RAND_DRBG_set_callbacks.pod
+++ b/doc/man3/RAND_DRBG_set_callbacks.pod
@@ -124,20 +124,19 @@ In this case the DRBG will automatically request an extra amount of entropy
utilize for the nonce, following the recommendations of [NIST SP 800-90A Rev. 1],
section 8.6.7.
-
-=head1 HISTORY
-
-The RAND_DRBG functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<RAND_DRBG_new(3)>,
L<RAND_DRBG_reseed(3)>,
L<RAND_DRBG(7)>
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/RAND_add.pod b/doc/man3/RAND_add.pod
index b6753fd2ed0b..4ba6ff977dd1 100644
--- a/doc/man3/RAND_add.pod
+++ b/doc/man3/RAND_add.pod
@@ -80,11 +80,6 @@ RAND_event() returns RAND_status().
The other functions do not return values.
-=head1 HISTORY
-
-RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should
-not be used.
-
=head1 SEE ALSO
L<RAND_bytes(3)>,
@@ -92,9 +87,14 @@ L<RAND_egd(3)>,
L<RAND_load_file(3)>,
L<RAND(7)>
+=head1 HISTORY
+
+RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should
+not be used.
+
=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/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index f257e050065f..e2265d170a61 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -43,6 +43,15 @@ return 1 on success, -1 if not supported by the current
RAND method, or 0 on other failure. The error code can be
obtained by L<ERR_get_error(3)>.
+=head1 SEE ALSO
+
+L<RAND_add(3)>,
+L<RAND_bytes(3)>,
+L<RAND_priv_bytes(3)>,
+L<ERR_get_error(3)>,
+L<RAND(7)>,
+L<RAND_DRBG(7)>
+
=head1 HISTORY
=over 2
@@ -57,18 +66,9 @@ The RAND_priv_bytes() function was added in OpenSSL 1.1.1.
=back
-=head1 SEE ALSO
-
-L<RAND_add(3)>,
-L<RAND_bytes(3)>,
-L<RAND_priv_bytes(3)>,
-L<ERR_get_error(3)>,
-L<RAND(7)>,
-L<RAND_DRBG(7)>
-
=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/man3/RAND_cleanup.pod b/doc/man3/RAND_cleanup.pod
index 3859ce343aa8..e5187532222d 100644
--- a/doc/man3/RAND_cleanup.pod
+++ b/doc/man3/RAND_cleanup.pod
@@ -23,18 +23,18 @@ L<OPENSSL_init_crypto(3)>.
RAND_cleanup() returns no value.
+=head1 SEE ALSO
+
+L<RAND(7)>
+
=head1 HISTORY
RAND_cleanup() was deprecated in OpenSSL 1.1.0; do not use it.
See L<OPENSSL_init_crypto(3)>
-=head1 SEE ALSO
-
-L<RAND(7)>
-
=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/man3/RSA_padding_add_PKCS1_type_1.pod b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
index 9ea2634c0346..20926003d876 100644
--- a/doc/man3/RSA_padding_add_PKCS1_type_1.pod
+++ b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
@@ -5,6 +5,7 @@
RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
+RSA_padding_add_PKCS1_OAEP_mgf1, RSA_padding_check_PKCS1_OAEP_mgf1,
RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
padding
@@ -14,35 +15,46 @@ padding
#include <openssl/rsa.h>
int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
- unsigned char *f, int fl);
+ const unsigned char *f, int fl);
int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
+ const unsigned char *f, int fl, int rsa_len);
int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
- unsigned char *f, int fl);
+ const unsigned char *f, int fl);
int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
+ const unsigned char *f, int fl, int rsa_len);
int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
- unsigned char *f, int fl, unsigned char *p, int pl);
+ const unsigned char *f, int fl,
+ const unsigned char *p, int pl);
int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len,
- unsigned char *p, int pl);
+ const unsigned char *f, int fl, int rsa_len,
+ const unsigned char *p, int pl);
+
+ int RSA_padding_add_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
+ const unsigned char *f, int fl,
+ const unsigned char *p, int pl,
+ const EVP_MD *md, const EVP_MD *mgf1md);
+
+ int RSA_padding_check_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
+ const unsigned char *f, int fl, int rsa_len,
+ const unsigned char *p, int pl,
+ const EVP_MD *md, const EVP_MD *mgf1md);
int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
- unsigned char *f, int fl);
+ const unsigned char *f, int fl);
int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
+ const unsigned char *f, int fl, int rsa_len);
int RSA_padding_add_none(unsigned char *to, int tlen,
- unsigned char *f, int fl);
+ const unsigned char *f, int fl);
int RSA_padding_check_none(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
+ const unsigned char *f, int fl, int rsa_len);
=head1 DESCRIPTION
@@ -98,6 +110,10 @@ at B<to>.
For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
+For RSA_padding_xxx_OAEP_mgf1(), B<md> points to the md hash,
+if B<md> is B<NULL> that means md=sha1, and B<mgf1md> points to
+the mgf1 hash, if B<mgf1md> is B<NULL> that means mgf1md=md.
+
=head1 RETURN VALUES
The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
@@ -107,15 +123,21 @@ L<ERR_get_error(3)>.
=head1 WARNING
-The RSA_padding_check_PKCS1_type_2() padding check leaks timing
+The result of RSA_padding_check_PKCS1_type_2() is a very sensitive
information which can potentially be used to mount a Bleichenbacher
padding oracle attack. This is an inherent weakness in the PKCS #1
-v1.5 padding design. Prefer PKCS1_OAEP padding. Otherwise it can
-be recommended to pass zero-padded B<f>, so that B<fl> equals to
-B<rsa_len>, and if fixed by protocol, B<tlen> being set to the
-expected length. In such case leakage would be minimal, it would
-take attacker's ability to observe memory access pattern with byte
-granilarity as it occurs, post-factum timing analysis won't do.
+v1.5 padding design. Prefer PKCS1_OAEP padding. If that is not
+possible, the result of RSA_padding_check_PKCS1_type_2() should be
+checked in constant time if it matches the expected length of the
+plaintext and additionally some application specific consistency
+checks on the plaintext need to be performed in constant time.
+If the plaintext is rejected it must be kept secret which of the
+checks caused the application to reject the message.
+Do not remove the zero-padding from the decrypted raw RSA data
+which was computed by RSA_private_decrypt() with B<RSA_NO_PADDING>,
+as this would create a small timing side channel which could be
+used to mount a Bleichenbacher attack against any padding mode
+including PKCS1_OAEP.
=head1 SEE ALSO
@@ -125,7 +147,7 @@ L<RSA_sign(3)>, L<RSA_verify(3)>
=head1 COPYRIGHT
-Copyright 2000-2016 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/man3/RSA_public_encrypt.pod b/doc/man3/RSA_public_encrypt.pod
index 91c176e24c52..d91c6884b1d5 100644
--- a/doc/man3/RSA_public_encrypt.pod
+++ b/doc/man3/RSA_public_encrypt.pod
@@ -8,10 +8,10 @@ RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
#include <openssl/rsa.h>
- int RSA_public_encrypt(int flen, unsigned char *from,
+ int RSA_public_encrypt(int flen, const unsigned char *from,
unsigned char *to, RSA *rsa, int padding);
- int RSA_private_decrypt(int flen, unsigned char *from,
+ int RSA_private_decrypt(int flen, const unsigned char *from,
unsigned char *to, RSA *rsa, int padding);
=head1 DESCRIPTION
@@ -27,6 +27,8 @@ B<padding> denotes one of the following modes:
=item RSA_PKCS1_PADDING
PKCS #1 v1.5 padding. This currently is the most widely used mode.
+However, it is highly recommended to use RSA_PKCS1_OAEP_PADDING in
+new applications. SEE WARNING BELOW.
=item RSA_PKCS1_OAEP_PADDING
@@ -46,23 +48,35 @@ Encrypting user data directly with RSA is insecure.
=back
-B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
-based padding modes, less than RSA_size(B<rsa>) - 41 for
+B<flen> must not be more than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
+based padding modes, not more than RSA_size(B<rsa>) - 42 for
RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING.
-The random number generator must be seeded prior to calling
-RSA_public_encrypt().
+When a padding mode other than RSA_NO_PADDING is in use, then
+RSA_public_encrypt() will include some random bytes into the ciphertext
+and therefore the ciphertext will be different each time, even if the
+plaintext and the public key are exactly identical.
+The returned ciphertext in B<to> will always be zero padded to exactly
+RSA_size(B<rsa>) bytes.
+B<to> and B<from> may overlap.
RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the
-private key B<rsa> and stores the plaintext in B<to>. B<to> must point
-to a memory section large enough to hold the decrypted data (which is
-smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that
-was used to encrypt the data.
+private key B<rsa> and stores the plaintext in B<to>. B<flen> should
+be equal to RSA_size(B<rsa>) but may be smaller, when leading zero
+bytes are in the ciphertext. Those are not important and may be removed,
+but RSA_public_encrypt() does not do that. B<to> must point
+to a memory section large enough to hold the maximal possible decrypted
+data (which is equal to RSA_size(B<rsa>) for RSA_NO_PADDING,
+RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 based padding modes and
+RSA_size(B<rsa>) - 42 for RSA_PKCS1_OAEP_PADDING).
+B<padding> is the padding mode that was used to encrypt the data.
+B<to> and B<from> may overlap.
=head1 RETURN VALUES
RSA_public_encrypt() returns the size of the encrypted data (i.e.,
RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the
-recovered plaintext.
+recovered plaintext. A return value of 0 is not an error and
+means only that the plaintext was empty.
On error, -1 is returned; the error codes can be
obtained by L<ERR_get_error(3)>.
@@ -85,7 +99,7 @@ L<RSA_size(3)>
=head1 COPYRIGHT
-Copyright 2000-2016 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/man3/SSL_CIPHER_get_name.pod b/doc/man3/SSL_CIPHER_get_name.pod
index 4c12c5ed20d0..26edae3d80be 100644
--- a/doc/man3/SSL_CIPHER_get_name.pod
+++ b/doc/man3/SSL_CIPHER_get_name.pod
@@ -124,7 +124,10 @@ Textual representation of the cipher name.
=item <protocol version>
-Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
+The minimum protocol version that the ciphersuite supports, such as B<TLSv1.2>.
+Note that this is not always the same as the protocol version in which the
+ciphersuite was first defined because some ciphersuites are backwards compatible
+with earlier protocol versions.
=item Kx=<key exchange>
@@ -177,6 +180,11 @@ SSL_CIPHER_get_id() returns a 4-byte integer representing the OpenSSL-specific I
SSL_CIPHER_get_protocol_id() returns a 2-byte integer representing the TLS
protocol-specific ID.
+=head1 SEE ALSO
+
+L<ssl(7)>, L<SSL_get_current_cipher(3)>,
+L<SSL_get_ciphers(3)>, L<ciphers(1)>
+
=head1 HISTORY
The SSL_CIPHER_get_version() function was updated to always return the
@@ -193,14 +201,9 @@ required to enable this function.
The OPENSSL_cipher_name() function was added in OpenSSL 1.1.1.
-=head1 SEE ALSO
-
-L<ssl(7)>, L<SSL_get_current_cipher(3)>,
-L<SSL_get_ciphers(3)>, L<ciphers(1)>
-
=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/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index a74e7284f9de..7f2449e379b9 100644
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -594,6 +594,23 @@ checking or translation of the command value. For example if the return
value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
pathname to an absolute pathname.
+=head1 RETURN VALUES
+
+SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
+B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
+returns the number of arguments processed. This is useful when processing
+command lines.
+
+A return value of -2 means B<cmd> is not recognised.
+
+A return value of -3 means B<cmd> is recognised and the command requires a
+value but B<value> is NULL.
+
+A return code of 0 indicates that both B<cmd> and B<value> are valid but an
+error occurred attempting to perform the operation: for example due to an
+error in the syntax of B<value> in this case the error queue may provide
+additional information.
+
=head1 EXAMPLES
Set supported signature algorithms:
@@ -640,23 +657,6 @@ Set supported curves to P-256, P-384:
SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
-=head1 RETURN VALUES
-
-SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
-B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
-returns the number of arguments processed. This is useful when processing
-command lines.
-
-A return value of -2 means B<cmd> is not recognised.
-
-A return value of -3 means B<cmd> is recognised and the command requires a
-value but B<value> is NULL.
-
-A return code of 0 indicates that both B<cmd> and B<value> are valid but an
-error occurred attempting to perform the operation: for example due to an
-error in the syntax of B<value> in this case the error queue may provide
-additional information.
-
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)>,
diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod
index a96aafed5f76..b16271bfaa19 100644
--- a/doc/man3/SSL_CTX_load_verify_locations.pod
+++ b/doc/man3/SSL_CTX_load_verify_locations.pod
@@ -100,23 +100,6 @@ with different expiration dates. If a "certificate expired" verification
error occurs, no other certificate will be searched. Make sure to not
have expired certificates mixed with valid ones.
-=head1 EXAMPLES
-
-Generate a CA certificate file with descriptive text from the CA certificates
-ca1.pem ca2.pem ca3.pem:
-
- #!/bin/sh
- rm CAfile.pem
- for i in ca1.pem ca2.pem ca3.pem ; do
- openssl x509 -in $i -text >> CAfile.pem
- done
-
-Prepare the directory /some/where/certs containing several CA certificates
-for use as B<CApath>:
-
- cd /some/where/certs
- c_rehash .
-
=head1 RETURN VALUES
For SSL_CTX_load_verify_locations the following return values can occur:
@@ -139,6 +122,23 @@ SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
missing default location is still treated as a success.
+=head1 EXAMPLES
+
+Generate a CA certificate file with descriptive text from the CA certificates
+ca1.pem ca2.pem ca3.pem:
+
+ #!/bin/sh
+ rm CAfile.pem
+ for i in ca1.pem ca2.pem ca3.pem ; do
+ openssl x509 -in $i -text >> CAfile.pem
+ done
+
+Prepare the directory /some/where/certs containing several CA certificates
+for use as B<CApath>:
+
+ cd /some/where/certs
+ c_rehash .
+
=head1 SEE ALSO
L<ssl(7)>,
@@ -151,7 +151,7 @@ L<SSL_CTX_set_client_CA_list(3)>
=head1 COPYRIGHT
-Copyright 2000-2016 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/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod
index d07834151eb7..df25a6f657fd 100644
--- a/doc/man3/SSL_CTX_new.pod
+++ b/doc/man3/SSL_CTX_new.pod
@@ -190,6 +190,11 @@ SSL_CTX_up_ref() returns 1 for success and 0 for failure.
=back
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
+L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
+
=head1 HISTORY
Support for SSLv2 and the corresponding SSLv2_method(),
@@ -198,18 +203,13 @@ removed in OpenSSL 1.1.0.
SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
were deprecated and the preferred TLS_method(), TLS_server_method()
-and TLS_client_method() functions were introduced in OpenSSL 1.1.0.
+and TLS_client_method() functions were added in OpenSSL 1.1.0.
All version-specific methods were deprecated in OpenSSL 1.1.0.
-=head1 SEE ALSO
-
-L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
-L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
-
=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/man3/SSL_CTX_set1_sigalgs.pod b/doc/man3/SSL_CTX_set1_sigalgs.pod
index 93d5320d965a..1c462a95b6ae 100644
--- a/doc/man3/SSL_CTX_set1_sigalgs.pod
+++ b/doc/man3/SSL_CTX_set1_sigalgs.pod
@@ -83,6 +83,10 @@ be used with the B<_list> forms of the API.
The use of MD5 as a digest is strongly discouraged due to security weaknesses.
+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 for failure.
+
=head1 EXAMPLES
Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
@@ -97,10 +101,6 @@ using a string:
SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256");
-=head1 RETURN VALUES
-
-All these functions return 1 for success and 0 for failure.
-
=head1 SEE ALSO
L<ssl(7)>, L<SSL_get_shared_sigalgs(3)>,
@@ -108,7 +108,7 @@ L<SSL_CONF_CTX_new(3)>
=head1 COPYRIGHT
-Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-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/SSL_CTX_set_client_hello_cb.pod b/doc/man3/SSL_CTX_set_client_hello_cb.pod
index 6824b5b8d1a4..2ec298960a03 100644
--- a/doc/man3/SSL_CTX_set_client_hello_cb.pod
+++ b/doc/man3/SSL_CTX_set_client_hello_cb.pod
@@ -65,6 +65,8 @@ both required, and on success the caller must release the storage allocated for
B<*out> using OPENSSL_free(). The contents of B<*out> is an array of integers
holding the numerical value of the TLS extension types in the order they appear
in the ClientHello. B<*outlen> contains the number of elements in the array.
+In situations when the ClientHello has no extensions, the function will return
+success with B<*out> set to NULL and B<*outlen> set to 0.
=head1 NOTES
@@ -120,7 +122,7 @@ were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-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/SSL_CTX_set_default_passwd_cb.pod b/doc/man3/SSL_CTX_set_default_passwd_cb.pod
index 999a70c8c366..991ce7a5a922 100644
--- a/doc/man3/SSL_CTX_set_default_passwd_cb.pod
+++ b/doc/man3/SSL_CTX_set_default_passwd_cb.pod
@@ -90,20 +90,20 @@ truncated.
return strlen(buf);
}
+=head1 SEE ALSO
+
+L<ssl(7)>,
+L<SSL_CTX_use_certificate(3)>
+
=head1 HISTORY
SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(),
SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were
added in OpenSSL 1.1.0.
-=head1 SEE ALSO
-
-L<ssl(7)>,
-L<SSL_CTX_use_certificate(3)>
-
=head1 COPYRIGHT
-Copyright 2000-2016 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/man3/SSL_CTX_set_generate_session_id.pod b/doc/man3/SSL_CTX_set_generate_session_id.pod
index 2bee351a4dbc..dab563750806 100644
--- a/doc/man3/SSL_CTX_set_generate_session_id.pod
+++ b/doc/man3/SSL_CTX_set_generate_session_id.pod
@@ -82,6 +82,14 @@ and the same race condition applies.
The callback must return 0 if it cannot generate a session id for whatever
reason and return 1 on success.
+=head1 RETURN VALUES
+
+SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
+always return 1.
+
+SSL_has_matching_session_id() returns 1 if another session with the
+same id is already in the cache.
+
=head1 EXAMPLES
The callback function listed will generate a session id with the
@@ -114,21 +122,13 @@ server id given, and will fill the rest with pseudo random bytes:
}
-=head1 RETURN VALUES
-
-SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
-always return 1.
-
-SSL_has_matching_session_id() returns 1 if another session with the
-same id is already in the cache.
-
=head1 SEE ALSO
L<ssl(7)>, L<SSL_get_version(3)>
=head1 COPYRIGHT
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-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/SSL_CTX_set_min_proto_version.pod b/doc/man3/SSL_CTX_set_min_proto_version.pod
index 45866588601a..7dfbfecf079d 100644
--- a/doc/man3/SSL_CTX_set_min_proto_version.pod
+++ b/doc/man3/SSL_CTX_set_min_proto_version.pod
@@ -52,18 +52,18 @@ lowest or highest protocol, respectively.
All these functions are implemented using macros.
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
+
=head1 HISTORY
The setter functions were added in OpenSSL 1.1.0. The getter functions
were added in OpenSSL 1.1.1.
-=head1 SEE ALSO
-
-L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
-
=head1 COPYRIGHT
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-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/SSL_CTX_set_read_ahead.pod b/doc/man3/SSL_CTX_set_read_ahead.pod
index 137e251b9585..ff037d938dcd 100644
--- a/doc/man3/SSL_CTX_set_read_ahead.pod
+++ b/doc/man3/SSL_CTX_set_read_ahead.pod
@@ -46,7 +46,7 @@ records, and SSL_has_pending() can't tell the difference between processed and
unprocessed data, it's recommended that if read ahead is turned on that
B<SSL_MODE_AUTO_RETRY> is not turned off using SSL_CTX_clear_mode().
That will prevent getting B<SSL_ERROR_WANT_READ> when there is still a complete
-record availale that hasn't been processed.
+record available that hasn't been processed.
If the application wants to continue to use the underlying transport (e.g. TCP
connection) after the SSL connection is finished using SSL_shutdown() reading
@@ -64,7 +64,7 @@ L<ssl(7)>, L<SSL_pending(3)>
=head1 COPYRIGHT
-Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-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/SSL_CTX_set_split_send_fragment.pod b/doc/man3/SSL_CTX_set_split_send_fragment.pod
index 877b4aecd949..d63ca4157e09 100644
--- a/doc/man3/SSL_CTX_set_split_send_fragment.pod
+++ b/doc/man3/SSL_CTX_set_split_send_fragment.pod
@@ -162,6 +162,10 @@ SSL_set_default_read_buffer_len(), SSL_CTX_set_tlsext_max_fragment_length(),
SSL_set_tlsext_max_fragment_length() and SSL_SESSION_get_max_fragment_length()
all these functions are implemented using macros.
+=head1 SEE ALSO
+
+L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
+
=head1 HISTORY
The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
@@ -172,13 +176,9 @@ functions were added in OpenSSL 1.1.0.
The SSL_CTX_set_tlsext_max_fragment_length(), SSL_set_tlsext_max_fragment_length()
and SSL_SESSION_get_max_fragment_length() functions were added in OpenSSL 1.1.1.
-=head1 SEE ALSO
-
-L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
-
=head1 COPYRIGHT
-Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-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/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
index 7a4bb3427027..43bddc51e8cf 100644
--- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
@@ -121,6 +121,10 @@ For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key
the overall security is only 128 bits because breaking the ticket key will
enable an attacker to obtain the session keys.
+=head1 RETURN VALUES
+
+returns 0 to indicate the callback function was set.
+
=head1 EXAMPLES
Reference Implementation:
@@ -175,10 +179,6 @@ Reference Implementation:
}
}
-=head1 RETURN VALUES
-
-returns 0 to indicate the callback function was set.
-
=head1 SEE ALSO
L<ssl(7)>, L<SSL_set_session(3)>,
@@ -190,7 +190,7 @@ L<SSL_CTX_set_session_id_context(3)>,
=head1 COPYRIGHT
-Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2014-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/SSL_CTX_set_tmp_dh_callback.pod b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod
index a2ac1c0adbbc..fba649f8f572 100644
--- a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod
+++ b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod
@@ -81,6 +81,14 @@ are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use
the callback but ignore B<keylength> and B<is_export> and simply
supply at least 2048-bit parameters in the callback.
+=head1 RETURN VALUES
+
+SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
+diagnostic output.
+
+SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
+on failure. Check the error queue to find out the reason of failure.
+
=head1 EXAMPLES
Setup DH parameters with a key length of 2048 bits. (Error handling
@@ -109,14 +117,6 @@ Code for setting up parameters during server initialization:
/* Error. */
...
-=head1 RETURN VALUES
-
-SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
-diagnostic output.
-
-SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
-on failure. Check the error queue to find out the reason of failure.
-
=head1 SEE ALSO
L<ssl(7)>, L<SSL_CTX_set_cipher_list(3)>,
@@ -125,7 +125,7 @@ L<ciphers(1)>, L<dhparam(1)>
=head1 COPYRIGHT
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-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/SSL_get_error.pod b/doc/man3/SSL_get_error.pod
index 5a7a4b7058ef..32668a036ddb 100644
--- a/doc/man3/SSL_get_error.pod
+++ b/doc/man3/SSL_get_error.pod
@@ -166,7 +166,7 @@ The SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1.
=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/man3/SSL_load_client_CA_file.pod b/doc/man3/SSL_load_client_CA_file.pod
index 412b1a098ca4..a6cfb308d30c 100644
--- a/doc/man3/SSL_load_client_CA_file.pod
+++ b/doc/man3/SSL_load_client_CA_file.pod
@@ -23,21 +23,6 @@ the specific usage as support function for
L<SSL_CTX_set_client_CA_list(3)>,
it is not limited to CA certificates.
-=head1 EXAMPLES
-
-Load names of CAs from file and use it as a client CA list:
-
- SSL_CTX *ctx;
- STACK_OF(X509_NAME) *cert_names;
-
- ...
- cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
- if (cert_names != NULL)
- SSL_CTX_set_client_CA_list(ctx, cert_names);
- else
- /* error */
- ...
-
=head1 RETURN VALUES
The following return values can occur:
@@ -54,6 +39,21 @@ Pointer to the subject names of the successfully read certificates.
=back
+=head1 EXAMPLES
+
+Load names of CAs from file and use it as a client CA list:
+
+ SSL_CTX *ctx;
+ STACK_OF(X509_NAME) *cert_names;
+
+ ...
+ cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
+ if (cert_names != NULL)
+ SSL_CTX_set_client_CA_list(ctx, cert_names);
+ else
+ /* error */
+ ...
+
=head1 SEE ALSO
L<ssl(7)>,
@@ -61,7 +61,7 @@ L<SSL_CTX_set_client_CA_list(3)>
=head1 COPYRIGHT
-Copyright 2000-2016 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/man3/SSL_read.pod b/doc/man3/SSL_read.pod
index 1410a0228c30..4da7ad1ae1f4 100644
--- a/doc/man3/SSL_read.pod
+++ b/doc/man3/SSL_read.pod
@@ -126,10 +126,6 @@ You should instead call SSL_get_error() to find out if it's retryable.
=back
-=head1 HISTORY
-
-The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_write_ex(3)>,
@@ -140,9 +136,13 @@ L<SSL_pending(3)>,
L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
L<ssl(7)>, L<bio(7)>
+=head1 HISTORY
+
+The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL 1.1.1.
+
=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/man3/SSL_session_reused.pod b/doc/man3/SSL_session_reused.pod
index 1a3d567bd844..82c59435901a 100644
--- a/doc/man3/SSL_session_reused.pod
+++ b/doc/man3/SSL_session_reused.pod
@@ -8,7 +8,7 @@ SSL_session_reused - query whether a reused session was negotiated during handsh
#include <openssl/ssl.h>
- int SSL_session_reused(SSL *ssl);
+ int SSL_session_reused(const SSL *ssl);
=head1 DESCRIPTION
@@ -44,7 +44,7 @@ L<SSL_CTX_set_session_cache_mode(3)>
=head1 COPYRIGHT
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-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/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod
index 551fff6308b6..732e5ada04ae 100644
--- a/doc/man3/SSL_shutdown.pod
+++ b/doc/man3/SSL_shutdown.pod
@@ -157,7 +157,7 @@ L<ssl(7)>, L<bio(7)>
=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/man3/SSL_write.pod b/doc/man3/SSL_write.pod
index 3956f1def387..84eb948cc6eb 100644
--- a/doc/man3/SSL_write.pod
+++ b/doc/man3/SSL_write.pod
@@ -104,10 +104,6 @@ You should instead call SSL_get_error() to find out if it's retryable.
=back
-=head1 HISTORY
-
-The SSL_write_ex() function was added in OpenSSL 1.1.1.
-
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>
@@ -116,9 +112,13 @@ L<SSL_connect(3)>, L<SSL_accept(3)>
L<SSL_set_connect_state(3)>,
L<ssl(7)>, L<bio(7)>
+=head1 HISTORY
+
+The SSL_write_ex() function was added in OpenSSL 1.1.1.
+
=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/man3/X509_LOOKUP_meth_new.pod b/doc/man3/X509_LOOKUP_meth_new.pod
index fb165fd6ad9d..e5f0a098b3fa 100644
--- a/doc/man3/X509_LOOKUP_meth_new.pod
+++ b/doc/man3/X509_LOOKUP_meth_new.pod
@@ -150,10 +150,20 @@ the X509_LOOKUP context, the type of the X509_OBJECT being requested, parameters
related to the lookup, and an X509_OBJECT that will receive the requested
object.
-Implementations should use either X509_OBJECT_set1_X509() or
-X509_OBJECT_set1_X509_CRL() to set the result. 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
+Implementations must add objects they find to the B<X509_STORE> object
+using X509_STORE_add_cert() or X509_STORE_add_crl(). This increments
+its reference count. However, the X509_STORE_CTX_get_by_subject()
+function also increases the reference count which leads to one too
+many references being held. Therefore applications should
+additionally call X509_free() or X509_CRL_free() to decrement the
+reference count again.
+
+Implementations should also use either X509_OBJECT_set1_X509() or
+X509_OBJECT_set1_X509_CRL() to set the result. Note that this also
+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.
@@ -179,7 +189,7 @@ The functions described here were added in OpenSSL 1.1.0i.
=head1 COPYRIGHT
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2018-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/X509_NAME_add_entry_by_txt.pod b/doc/man3/X509_NAME_add_entry_by_txt.pod
index b48f0908e813..0459cf4a4655 100644
--- a/doc/man3/X509_NAME_add_entry_by_txt.pod
+++ b/doc/man3/X509_NAME_add_entry_by_txt.pod
@@ -74,6 +74,15 @@ structure respectively. This will then be a multivalued RDN:
since multivalues RDNs are very seldom used B<set> is almost
always set to zero.
+=head1 RETURN VALUES
+
+X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
+X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
+success of 0 if an error occurred.
+
+X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
+structure of B<NULL> if an error occurred.
+
=head1 EXAMPLES
Create an B<X509_NAME> structure:
@@ -95,15 +104,6 @@ Create an B<X509_NAME> structure:
"Joe Bloggs", -1, -1, 0))
/* Error */
-=head1 RETURN VALUES
-
-X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
-X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
-success of 0 if an error occurred.
-
-X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
-structure of B<NULL> if an error occurred.
-
=head1 BUGS
B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a
@@ -117,7 +117,7 @@ L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
=head1 COPYRIGHT
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-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/X509_NAME_get_index_by_NID.pod b/doc/man3/X509_NAME_get_index_by_NID.pod
index 5621806bb530..420ace134874 100644
--- a/doc/man3/X509_NAME_get_index_by_NID.pod
+++ b/doc/man3/X509_NAME_get_index_by_NID.pod
@@ -69,6 +69,18 @@ Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
should check for the return value of -2. Alternatively the NID validity
can be determined first by checking OBJ_nid2obj(nid) is not NULL.
+=head1 RETURN VALUES
+
+X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
+return the index of the next matching entry or -1 if not found.
+X509_NAME_get_index_by_NID() can also return -2 if the supplied
+NID is invalid.
+
+X509_NAME_entry_count() returns the total number of entries.
+
+X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
+requested entry or B<NULL> if the index is invalid.
+
=head1 EXAMPLES
Process all entries:
@@ -94,25 +106,13 @@ Process all commonName entries:
/* Do something with e */
}
-=head1 RETURN VALUES
-
-X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
-return the index of the next matching entry or -1 if not found.
-X509_NAME_get_index_by_NID() can also return -2 if the supplied
-NID is invalid.
-
-X509_NAME_entry_count() returns the total number of entries.
-
-X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
-requested entry or B<NULL> if the index is invalid.
-
=head1 SEE ALSO
L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
=head1 COPYRIGHT
-Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-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/X509_get_subject_name.pod b/doc/man3/X509_get_subject_name.pod
index 7c4a499225ec..807f9d3d9b19 100644
--- a/doc/man3/X509_get_subject_name.pod
+++ b/doc/man3/X509_get_subject_name.pod
@@ -48,14 +48,6 @@ and X509_CRL_get_issuer() return an B<X509_NAME> pointer.
X509_set_subject_name(), X509_set_issuer_name(), X509_REQ_set_subject_name()
and X509_CRL_set_issuer_name() return 1 for success and 0 for failure.
-=head1 HISTORY
-
-X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in
-earlier versions.
-
-X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was previously
-added in OpenSSL 1.0.0 as a macro.
-
=head1 SEE ALSO
L<d2i_X509(3)>,
@@ -74,9 +66,17 @@ L<X509_sign(3)>,
L<X509V3_get_d2i(3)>,
L<X509_verify_cert(3)>
+=head1 HISTORY
+
+X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in
+earlier versions.
+
+X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was previously
+added in OpenSSL 1.0.0 as a macro.
+
=head1 COPYRIGHT
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-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/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 71985a44edf4..3d50f5d9081a 100644
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -496,6 +496,19 @@ Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
=back
+=head1 RETURN VALUES
+
+d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
+or B<NULL> if an error occurs. If the "reuse" capability has been used with
+a valid structure being passed in via B<a>, then the object is not freed in
+the event of error but may be in a potentially invalid or inconsistent state.
+
+i2d_TYPE() returns the number of bytes successfully encoded or a negative
+value if an error occurs.
+
+i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
+occurs.
+
=head1 EXAMPLES
Allocate and encode the DER encoding of an X509 structure:
@@ -586,22 +599,9 @@ structure has been modified after deserialization or previous
serialization. This is because some objects cache the encoding for
efficiency reasons.
-=head1 RETURN VALUES
-
-d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
-or B<NULL> if an error occurs. If the "reuse" capability has been used with
-a valid structure being passed in via B<a>, then the object is not freed in
-the event of error but may be in a potentially invalid or inconsistent state.
-
-i2d_TYPE() returns the number of bytes successfully encoded or a negative
-value if an error occurs.
-
-i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
-occurs.
-
=head1 COPYRIGHT
-Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 1998-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