diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 6 | ||||
| -rw-r--r-- | doc/internal/man3/bn_mul_words.pod | 231 | ||||
| -rw-r--r-- | doc/man1/openssl-s_client.pod.in | 6 | ||||
| -rw-r--r-- | doc/man3/CMS_sign.pod | 4 | ||||
| -rw-r--r-- | doc/man3/DTLS_set_timer_cb.pod | 13 | ||||
| -rw-r--r-- | doc/man3/EVP_PKEY_CTX_new.pod | 9 | ||||
| -rw-r--r-- | doc/man3/EVP_RAND.pod | 11 | ||||
| -rw-r--r-- | doc/man3/OSSL_PARAM.pod | 4 | ||||
| -rw-r--r-- | doc/man3/OSSL_PARAM_int.pod | 25 | ||||
| -rw-r--r-- | doc/man3/PKCS7_sign.pod | 4 | ||||
| -rw-r--r-- | doc/man3/SSL_CONF_cmd.pod | 4 | ||||
| -rw-r--r-- | doc/man3/SSL_CTX_set_min_proto_version.pod | 7 | ||||
| -rw-r--r-- | doc/man3/SSL_CTX_set_options.pod | 4 | ||||
| -rw-r--r-- | doc/man3/SSL_SESSION_get0_hostname.pod | 8 | ||||
| -rw-r--r-- | doc/man3/SSL_key_update.pod | 6 | ||||
| -rw-r--r-- | doc/man3/X509_VERIFY_PARAM_set_flags.pod | 6 | ||||
| -rw-r--r-- | doc/man7/OSSL_PROVIDER-FIPS.pod | 15 | ||||
| -rw-r--r-- | doc/man7/migration_guide.pod | 6 | ||||
| -rw-r--r-- | doc/man7/provider-cipher.pod | 6 | ||||
| -rw-r--r-- | doc/man7/provider-decoder.pod | 6 | ||||
| -rw-r--r-- | doc/man7/provider-encoder.pod | 6 | ||||
| -rw-r--r-- | doc/man7/provider-keymgmt.pod | 4 | ||||
| -rw-r--r-- | doc/man7/provider-signature.pod | 20 |
23 files changed, 348 insertions, 63 deletions
diff --git a/doc/README.md b/doc/README.md index 12bb37ddb8fc..d999b0262b76 100644 --- a/doc/README.md +++ b/doc/README.md @@ -6,10 +6,6 @@ README.md This file [fingerprints.txt](fingerprints.txt) PGP fingerprints of authorised release signers -standards.txt -standards.txt - Moved to the web, <https://www.openssl.org/docs/standards.html> - [HOWTO/](HOWTO/) A few how-to documents; not necessarily up-to-date @@ -27,4 +23,4 @@ standards.txt Algorithm specific EVP_PKEY documentation. Formatted versions of the manpages (apps,ssl,crypto) can be found at - <https://www.openssl.org/docs/manpages.html> + <https://docs.openssl.org/master/> diff --git a/doc/internal/man3/bn_mul_words.pod b/doc/internal/man3/bn_mul_words.pod new file mode 100644 index 000000000000..d2d8e3397a14 --- /dev/null +++ b/doc/internal/man3/bn_mul_words.pod @@ -0,0 +1,231 @@ +=pod + +=head1 NAME + +bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, +bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, +bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, +bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, +bn_mul_low_recursive, bn_sqr_normal, bn_sqr_recursive, +bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, +mul, mul_add, sqr - BIGNUM +library internal functions + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); + BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, + BN_ULONG w); + void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); + BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); + BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, + int num); + BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, + int num); + + void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); + void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); + void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); + void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); + + int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); + + void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, + int nb); + void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); + void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, + int dna, int dnb, BN_ULONG *tmp); + void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, + int n, int tna, int tnb, BN_ULONG *tmp); + void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, + int n2, BN_ULONG *tmp); + + void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); + void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); + + BIGNUM *bn_expand(BIGNUM *a, int bits); + BIGNUM *bn_wexpand(BIGNUM *a, int n); + BIGNUM *bn_expand2(BIGNUM *a, int n); + void bn_fix_top(BIGNUM *a); + +The following are macros: + + void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); + void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); + void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); + + void bn_check_top(BIGNUM *a); + +=head1 DESCRIPTION + +This page documents the internal functions used by the OpenSSL +B<BIGNUM> implementation. They are described here to facilitate +debugging and extending the library. They are I<not> to be used by +applications. + +=head2 The BIGNUM structure + + typedef struct bignum_st BIGNUM; + + struct bignum_st + { + BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ + int top; /* Index of last used d +1. */ + /* The next are internal book keeping for bn_expand. */ + int dmax; /* Size of the d array. */ + int neg; /* one if the number is negative */ + int flags; + }; + + +The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>), +least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits +in size, depending on the 'number of bits' (B<BITS2>) specified in +C<openssl/bn.h>. + +B<dmax> is the size of the B<d> array that has been allocated. B<top> +is the number of words being used, so for a value of 4, bn.d[0]=4 and +bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is +B<0>, the B<d> field can be B<NULL> and B<top> == B<0>. + +B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The +flags begin with B<BN_FLG_>. The macros BN_set_flags(b, n) and +BN_get_flags(b, n) exist to enable or fetch flag(s) B<n> from B<BIGNUM> +structure B<b>. + +Various routines in this library require the use of temporary +B<BIGNUM> variables during their execution. Since dynamic memory +allocation to create B<BIGNUM>s is rather expensive when used in +conjunction with repeated subroutine calls, the B<BN_CTX> structure is +used. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see +L<BN_CTX_start(3)>. + +=head2 Low-level arithmetic operations + +These functions are implemented in C and for several platforms in +assembly language: + +bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word +arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result +in B<rp>, and returns the high word (carry). + +bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> +word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places +the result in B<rp>, and returns the high word (carry). + +bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array +B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap> +word-wise, and places the low and high bytes of the result in B<rp>. + +bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>, B<l>) +by B<d> and returns the result. + +bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word +arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the +result in B<rp>, and returns the high word (carry). + +bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word +arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the +result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0 +otherwise). + +bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and +B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the +result in B<r>. + +bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and +B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the +result in B<r>. + +bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and +B<b> and the 8 word array B<r>. + +bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and +B<b> and the 16 word array B<r>. + +The following functions are implemented in C: + +bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a> +and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and +less than B<b>. + +bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na> +word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word +array B<r>. It computes B<a>*B<b> and places the result in B<r>. + +bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word +arrays B<r>, B<a> and B<b>. It computes the B<n> low words of +B<a>*B<b> and places the result in B<r>. + +bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates +on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb> +(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2> +word arrays B<r> and B<t>. B<n2> must be a power of 2. It computes +B<a>*B<b> and places the result in B<r>. + +bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>) +operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and +B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>. + +bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the +B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a> +and B<b>. + +BN_mul() calls bn_mul_normal(), or an optimized implementation if the +factors have the same size: bn_mul_comba8() is used if they are 8 +words long, bn_mul_recursive() if they are larger than +B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word +size, and bn_mul_part_recursive() for others that are larger than +B<BN_MULL_SIZE_NORMAL>. + +bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array +B<a> and the 2*B<n> word arrays B<tmp> and B<r>. + +The implementations use the following macros which, depending on the +architecture, may use "long long" C operations or inline assembler. +They are defined in C<bn_local.h>. + +mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the +low word of the result in B<r> and the high word in B<c>. + +mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and +places the low word of the result in B<r> and the high word in B<c>. + +sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word +of the result in B<r0> and the high word in B<r1>. + +=head2 Size changes + +bn_expand() ensures that B<b> has enough space for a B<bits> bit +number. bn_wexpand() ensures that B<b> has enough space for an +B<n> word number. If the number has to be expanded, both macros +call bn_expand2(), which allocates a new B<d> array and copies the +data. They return B<NULL> on error, B<b> otherwise. + +The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most +significant nonzero word plus one when B<a> has shrunk. + +=head2 Debugging + +bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top +E<lt>= (a)-E<gt>dmax)>. A violation will cause the program to abort. + +If B<BN_DEBUG> is not defined, bn_check_top() is +defined as an empty macro. + +=head1 RETURN VALUES + +Described above. + +=head1 COPYRIGHT + +Copyright 2000-2025 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/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index caebe10bffb8..29025ef1161b 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -499,12 +499,12 @@ by some servers. =item B<-ign_eof> Inhibit shutting down the connection when end of file is reached in the -input. +input. This implicitly turns on B<-nocommands> as well. =item B<-quiet> Inhibit printing of session and certificate information. This implicitly -turns on B<-ign_eof> as well. +turns on B<-ign_eof> and B<-nocommands> as well. =item B<-no_ign_eof> @@ -971,7 +971,7 @@ The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2025 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 diff --git a/doc/man3/CMS_sign.pod b/doc/man3/CMS_sign.pod index 03bfc6fce16a..9e28d6b7d3b5 100644 --- a/doc/man3/CMS_sign.pod +++ b/doc/man3/CMS_sign.pod @@ -96,7 +96,7 @@ can be performed by obtaining the streaming ASN1 B<BIO> directly using BIO_new_CMS(). If a signer is specified it will use the default digest for the signing -algorithm. This is B<SHA1> for both RSA and DSA keys. +algorithm. This is B<SHA256> for both RSA and DSA keys. If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is output. @@ -132,7 +132,7 @@ The CMS_sign_ex() method was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2008-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2008-2025 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 diff --git a/doc/man3/DTLS_set_timer_cb.pod b/doc/man3/DTLS_set_timer_cb.pod index 5014e77d0fc8..618fd1f6ff0e 100644 --- a/doc/man3/DTLS_set_timer_cb.pod +++ b/doc/man3/DTLS_set_timer_cb.pod @@ -20,6 +20,17 @@ This function sets an optional callback function for controlling the timeout interval on the DTLS protocol. The callback function will be called by DTLS for every new DTLS packet that is sent. +The callback should return the timeout interval in micro seconds. + +The I<timer_us> parameter of the callback is the last set timeout +interval returned. On the first invocation of the callback, +this value will be 0. + +At the beginning of the connection, if no timeout callback has been +set via DTLS_set_timer_cb(), the default timeout value is 1 second. +For all subsequent timeouts, the default behavior is to double the +duration up to a maximum of 1 minute. + =head1 RETURN VALUES Returns void. @@ -30,7 +41,7 @@ The DTLS_set_timer_cb() function was added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2025 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 diff --git a/doc/man3/EVP_PKEY_CTX_new.pod b/doc/man3/EVP_PKEY_CTX_new.pod index d7ac221f7c19..a15abc2c3e17 100644 --- a/doc/man3/EVP_PKEY_CTX_new.pod +++ b/doc/man3/EVP_PKEY_CTX_new.pod @@ -49,8 +49,11 @@ used when no B<EVP_PKEY> structure is associated with the operations, for example during parameter generation or key generation for some algorithms. -EVP_PKEY_CTX_dup() duplicates the context I<ctx>. It is not supported for a -keygen operation. +EVP_PKEY_CTX_dup() duplicates the context I<ctx>. +It is not supported for a keygen operation. +It is however possible to duplicate a context freshly created via any of the +above C<new> functions, provided L<EVP_PKEY_keygen_init(3)> has not yet been +called on the source context, and then use the copy for key generation. EVP_PKEY_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing is done. @@ -122,7 +125,7 @@ added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2006-2025 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 diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod index e5f75010499c..667599273cdc 100644 --- a/doc/man3/EVP_RAND.pod +++ b/doc/man3/EVP_RAND.pod @@ -151,11 +151,8 @@ operating system. If I<prediction_resistance> is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. -EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen> -bytes from the RAND I<ctx>. The function returns the length of the generated -nonce. If I<out> is NULL, the length is still returned but no generation -takes place. This allows a caller to dynamically allocate a buffer of the -appropriate size. +EVP_RAND_nonce() creates a nonce in I<out> of length I<outlen> +bytes from the RAND I<ctx>. EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of its parents. After this I<ctx> will operate in a thread safe manner, albeit @@ -376,7 +373,7 @@ B<EVP_RAND_CTX> structure or NULL if an error occurred. EVP_RAND_CTX_free() does not return a value. -EVP_RAND_nonce() returns the length of the nonce. +EVP_RAND_nonce() returns 1 on success, 0 on error. EVP_RAND_get_strength() returns the strength of the random number generator in bits. @@ -406,7 +403,7 @@ This functionality was added to OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2025 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 diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod index 22fd0f0d7dd7..8a50db2b94d4 100644 --- a/doc/man3/OSSL_PARAM.pod +++ b/doc/man3/OSSL_PARAM.pod @@ -356,7 +356,7 @@ could fill in the parameters like this: =head1 SEE ALSO -L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)> +L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)>, L<OSSL_PARAM_construct_utf8_string(3)> =head1 HISTORY @@ -364,7 +364,7 @@ B<OSSL_PARAM> was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod index 105fe3241f87..aaecd0a87ce9 100644 --- a/doc/man3/OSSL_PARAM_int.pod +++ b/doc/man3/OSSL_PARAM_int.pod @@ -393,6 +393,29 @@ could fill in the parameters like this: if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL) OSSL_PARAM_set_utf8_ptr(p, "cookie value"); +=head2 Example 3 + +This example shows a special case where +I<-Wincompatible-pointer-types-discards-qualifiers> may be set during +compilation. The value for I<buf> cannot be a I<const char *> type string. An +alternative in this case would be to use B<OSSL_PARAM> macro abbreviated calls +rather than the specific callers which allows you to define the sha1 argument +as a standard character array (I<char[]>). + +For example, this code: + + OSSL_PARAM params[2]; + params[0] = OSSL_PARAM_construct_utf8_string("digest", "SHA1", 0); + params[1] = OSSL_PARAM_construct_end(); + +Can be made compatible with the following version: + + char sha1[] = "SHA1"; /* sha1 is defined as char[] in this case */ + OSSL_PARAM params[2]; + + params[0] = OSSL_PARAM_construct_utf8_string("digest", sha1, 0); + params[1] = OSSL_PARAM_construct_end(); + =head1 SEE ALSO L<openssl-core.h(7)>, L<OSSL_PARAM(3)> @@ -403,7 +426,7 @@ These APIs were introduced in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 diff --git a/doc/man3/PKCS7_sign.pod b/doc/man3/PKCS7_sign.pod index 1d997045fe14..5c55aa191def 100644 --- a/doc/man3/PKCS7_sign.pod +++ b/doc/man3/PKCS7_sign.pod @@ -80,7 +80,7 @@ can be performed by obtaining the streaming ASN1 B<BIO> directly using BIO_new_PKCS7(). If a signer is specified it will use the default digest for the signing -algorithm. This is B<SHA1> for both RSA and DSA keys. +algorithm. This is B<SHA256> for both RSA and DSA keys. The I<certs>, I<signcert> and I<pkey> parameters can all be NULL if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added @@ -122,7 +122,7 @@ The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0. =head1 COPYRIGHT -Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2002-2025 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 diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod index ae6ca432829e..0645c75d9878 100644 --- a/doc/man3/SSL_CONF_cmd.pod +++ b/doc/man3/SSL_CONF_cmd.pod @@ -71,7 +71,7 @@ B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>. =item B<-no_renegotiation> -Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +Disables all attempts at renegotiation in (D)TLSv1.2 and earlier, same as setting B<SSL_OP_NO_RENEGOTIATION>. =item B<-no_resumption_on_reneg> @@ -735,7 +735,7 @@ OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2012-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2012-2025 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 diff --git a/doc/man3/SSL_CTX_set_min_proto_version.pod b/doc/man3/SSL_CTX_set_min_proto_version.pod index 2adf9acce00a..a4a49d8549e6 100644 --- a/doc/man3/SSL_CTX_set_min_proto_version.pod +++ b/doc/man3/SSL_CTX_set_min_proto_version.pod @@ -31,9 +31,10 @@ L<SSL_CTX_set_options(3)> that also make it possible to disable specific protocol versions. Use these functions instead of disabling specific protocol versions. -Setting the minimum or maximum version to 0, will enable protocol +Setting the minimum or maximum version to 0 (default), will enable protocol versions down to the lowest version, or up to the highest version -supported by the library, respectively. +supported by the library, respectively. The supported versions might be +controlled by system configuration. Getters return 0 in case B<ctx> or B<ssl> have been configured to automatically use the lowest or highest version supported by the library. @@ -64,7 +65,7 @@ were added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2025 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 diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod index 176f8d25fc31..93e7198166f7 100644 --- a/doc/man3/SSL_CTX_set_options.pod +++ b/doc/man3/SSL_CTX_set_options.pod @@ -241,7 +241,7 @@ Do not query the MTU. Only affects DTLS connections. =item SSL_OP_NO_RENEGOTIATION -Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest +Disable all renegotiation in (D)TLSv1.2 and earlier. Do not send HelloRequest messages, and ignore renegotiation requests via ClientHello. =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION @@ -456,7 +456,7 @@ whether these macros are defined or not. =head1 COPYRIGHT -Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2025 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 diff --git a/doc/man3/SSL_SESSION_get0_hostname.pod b/doc/man3/SSL_SESSION_get0_hostname.pod index f560e7751d84..f7add16d7bdd 100644 --- a/doc/man3/SSL_SESSION_get0_hostname.pod +++ b/doc/man3/SSL_SESSION_get0_hostname.pod @@ -24,10 +24,8 @@ 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 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. +client when the session was created if it was accepted by the server. Otherwise +NULL is returned. The value returned is a pointer to memory maintained within B<s> and should not be free'd. @@ -67,7 +65,7 @@ SSL_SESSION_set1_alpn_selected() functions were added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2025 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 diff --git a/doc/man3/SSL_key_update.pod b/doc/man3/SSL_key_update.pod index 6d5b42e0b166..5ce47b337387 100644 --- a/doc/man3/SSL_key_update.pod +++ b/doc/man3/SSL_key_update.pod @@ -53,7 +53,9 @@ such as SSL_read_ex() or SSL_write_ex() takes place on the connection a check will be performed to confirm that it is a suitable time to start a renegotiation. If so, then it will be initiated immediately. OpenSSL will not attempt to resume any session associated with the connection in the new -handshake. +handshake. Note that some servers will respond to reneogitation attempts with +a "no_renegotiation" alert. An OpenSSL will immediately fail the connection in +this case. When called from the client side, SSL_renegotiate_abbreviated() works in the same was as SSL_renegotiate() except that OpenSSL will attempt to resume the @@ -101,7 +103,7 @@ OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2025 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 diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod index 4627206174a5..b06bedc2e7bc 100644 --- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod +++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod @@ -248,8 +248,8 @@ ored together. B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf certificate. An error occurs if a suitable CRL cannot be found. -B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate -chain. +B<X509_V_FLAG_CRL_CHECK_ALL> expands CRL checking to the entire certificate +chain if B<X509_V_FLAG_CRL_CHECK> has also been enabled, and is otherwise ignored. B<X509_V_FLAG_IGNORE_CRITICAL> disables critical extension checking. By default any unhandled critical extensions in certificates or (if checked) CRLs result @@ -407,7 +407,7 @@ The documentation was changed to align with the implementation. =head1 COPYRIGHT -Copyright 2009-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2009-2025 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 diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod index 66165bdb0cc3..eb34a34a152c 100644 --- a/doc/man7/OSSL_PROVIDER-FIPS.pod +++ b/doc/man7/OSSL_PROVIDER-FIPS.pod @@ -421,6 +421,19 @@ validated versions alongside F<libcrypto> and F<libssl> compiled from any release within the same major release series. This flexibility enables you to address bug fixes and CVEs that fall outside the FIPS boundary. +You can load the FIPS provider into multiple library contexts as any other +provider. However the following restriction applies. The FIPS provider cannot +be used by multiple copies of OpenSSL libcrypto in a single process. + +As the provider saves core callbacks to the libcrypto obtained in the +OSSL_provider_init() call to global data it will fail if subsequent +invocations of its OSSL_provider_init() function yield different addresses +of these callbacks than in the initial call. This happens when different +copies of libcrypto are present in the memory of the process and both try +to load the same FIPS provider. A workaround is to have a different copy +of the FIPS provider loaded for each of the libcrypto instances in the +process. + =head1 SEE ALSO L<openssl-fipsinstall(1)>, @@ -439,7 +452,7 @@ This functionality was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod index e5ab29b95370..b223f856d17d 100644 --- a/doc/man7/migration_guide.pod +++ b/doc/man7/migration_guide.pod @@ -596,13 +596,13 @@ The code needs to be amended to look like this: Support for TLSv1.3 has been added. This has a number of implications for SSL/TLS applications. See the -L<TLS1.3 page|https://wiki.openssl.org/index.php/TLS1.3> for further details. +L<TLS1.3 page|https://github.com/openssl/openssl/wiki/TLS1.3> for further details. =back More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 can be found on the -L<OpenSSL 1.1.0 Changes page|https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes>. +L<OpenSSL 1.1.0 Changes page|https://github.com/openssl/openssl/wiki/OpenSSL_1.1.0_Changes>. =head3 Upgrading from the OpenSSL 2.0 FIPS Object Module @@ -2484,7 +2484,7 @@ The migration guide was created for OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2021-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021-2025 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 diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index eaad3cf2ff02..c5d40a223acf 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -103,8 +103,8 @@ A cipher algorithm implementation may not implement all of these functions. In order to be a consistent set of functions there must at least be a complete set of "encrypt" functions, or a complete set of "decrypt" functions, or a single "cipher" function. -In all cases both the OSSL_FUNC_cipher_newctx and OSSL_FUNC_cipher_freectx functions must be -present. +In all cases the OSSL_FUNC_cipher_get_params and both OSSL_FUNC_cipher_newctx +and OSSL_FUNC_cipher_freectx functions must be present. All other functions are optional. =head2 Context Management Functions @@ -241,7 +241,7 @@ The provider CIPHER interface was introduced in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 diff --git a/doc/man7/provider-decoder.pod b/doc/man7/provider-decoder.pod index e968e661f7cf..d19deec4af5b 100644 --- a/doc/man7/provider-decoder.pod +++ b/doc/man7/provider-decoder.pod @@ -110,7 +110,9 @@ it decodes. For example, an implementation that decodes an RSA key should be named "RSA". Likewise, an implementation that decodes DER data from PEM input should be named "DER". -Properties can be used to further specify details about an implementation: +Properties, as defined in the L<OSSL_ALGORITHM(3)> array element of each +decoder implementation, can be used to further specify details about an +implementation: =over 4 @@ -302,7 +304,7 @@ The DECODER interface was introduced in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 diff --git a/doc/man7/provider-encoder.pod b/doc/man7/provider-encoder.pod index f3e9ce5b1632..dadd33f9b0f6 100644 --- a/doc/man7/provider-encoder.pod +++ b/doc/man7/provider-encoder.pod @@ -127,7 +127,9 @@ The name of an implementation should match the type of object it handles. For example, an implementation that encodes an RSA key should be named "RSA". Likewise, an implementation that further encodes DER should be named "DER". -Properties can be used to further specify details about an implementation: +Properties, as defined in the L<OSSL_ALGORITHM(3)> array element of each +decoder implementation, can be used to further specify details about an +implementation: =over 4 @@ -321,7 +323,7 @@ The ENCODER interface was introduced in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 498ad9c4e107..8596b696c69f 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -29,7 +29,7 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx); /* Key loading by object reference, also a constructor */ - void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz); + void *OSSL_FUNC_keymgmt_load(const void *reference, size_t reference_sz); /* Key object information */ int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]); @@ -442,7 +442,7 @@ The KEYMGMT interface was introduced in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 1a9859eac367..05040ee39914 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -284,7 +284,7 @@ should be written to I<*siglen>. If I<sig> is NULL then the maximum length of the signature should be written to I<*siglen>. OSSL_FUNC_signature_digest_sign() implements a "one shot" digest sign operation -previously started through OSSL_FUNC_signature_digeset_sign_init(). A previously +previously started through OSSL_FUNC_signature_digest_sign_init(). A previously initialised signature context is passed in the I<ctx> parameter. The data to be signed is in I<tbs> which should be I<tbslen> bytes long. Unless I<sig> is NULL, the signature should be written to the location pointed to by the I<sig> @@ -294,7 +294,7 @@ length of the signature should be written to I<*siglen>. =head2 Digest Verify Functions -OSSL_FUNC_signature_digeset_verify_init() initialises a context for verifying given a +OSSL_FUNC_signature_digest_verify_init() initialises a context for verifying given a provider side verification context in the I<ctx> parameter, and a pointer to a provider key object in the I<provkey> parameter. The I<params>, if not NULL, should be set on the context in a manner similar to @@ -318,7 +318,7 @@ verification context is passed in the I<ctx> parameter. The signature to be verified is in I<sig> which is I<siglen> bytes long. OSSL_FUNC_signature_digest_verify() implements a "one shot" digest verify operation -previously started through OSSL_FUNC_signature_digeset_verify_init(). A previously +previously started through OSSL_FUNC_signature_digest_verify_init(). A previously initialised verification context is passed in the I<ctx> parameter. The data to be verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be verified is in I<sig> which is I<siglen> bytes long. @@ -360,8 +360,13 @@ The length of the "digest-size" parameter should not exceed that of a B<size_t>. =item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string> -Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of -signature algorithm and digest algorithm for the signature operation. +Gets the DER-encoded AlgorithmIdentifier for the signature operation. +This typically corresponds to the combination of a digest algorithm +with a purely asymmetric signature algorithm, such as SHA256WithECDSA. + +The L<ASN1_item_sign_ctx(3)> relies on this operation and is used by +many other functions signing ASN.1 structures such as X.509 certificates, +certificate requests, and CRLs, as well as OCSP, CMP, and CMS messages. =item "kat" (B<OSSL_SIGNATURE_PARAM_KAT>) <unsigned integer> @@ -421,7 +426,8 @@ All other functions should return 1 for success or 0 on error. =head1 SEE ALSO -L<provider(7)> +L<provider(7)>, +L<ASN1_item_sign_ctx(3)> =head1 HISTORY @@ -429,7 +435,7 @@ The provider SIGNATURE interface was introduced in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2025 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 |
