diff options
Diffstat (limited to 'doc')
83 files changed, 949 insertions, 386 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-ca.pod.in b/doc/man1/openssl-ca.pod.in index 1d497e848e79..1c07db3c8ef1 100644 --- a/doc/man1/openssl-ca.pod.in +++ b/doc/man1/openssl-ca.pod.in @@ -701,7 +701,7 @@ A sample configuration file with the relevant sections for this command: default_days = 365 # how long to certify for default_crl_days= 30 # how long before next CRL - default_md = md5 # md to use + default_md = sha256 # md to use policy = policy_any # default policy email_in_dn = no # Don't add the email into cert DN diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index 9240916fce40..889a59cd497e 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -453,8 +453,11 @@ Reason numbers defined in RFC 5280 are: =item B<-server> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]> -The DNS hostname or IP address and optionally port +The I<host> domain name or IP address and optionally I<port> of the CMP server to connect to using HTTP(S). +IP address may be for v4 or v6, such as C<127.0.0.1> or C<[::1]> for localhost. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. + This option excludes I<-port> and I<-use_mock_srv>. It is ignored if I<-rspin> is given with enough filename arguments. @@ -468,6 +471,7 @@ If a path is included it provides the default value for the B<-path> option. The HTTP(S) proxy server to use for reaching the CMP server unless B<-no_proxy> applies, see below. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that the optional C<http://> or C<https://> prefix is ignored (note that TLS may be selected by B<-tls_used>), as well as any path, userinfo, and query, and fragment @@ -969,8 +973,9 @@ This excludes the B<-server> and B<-port> options. =item B<-port> I<number> -Act as HTTP-based CMP server mock-up listening on the given port. -This excludes the B<-server> and B<-use_mock_srv> options. +Act as HTTP-based CMP server mock-up listening on the given local port. +The client may address the server via, e.g., C<127.0.0.1> or C<[::1]>. +This option excludes the B<-server> and B<-use_mock_srv> options. The B<-rspin>, B<-rspout>, B<-reqin>, and B<-reqout> options so far are not supported in this mode. diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index 65a61ee97f1d..f4d12312b7cb 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -191,6 +191,10 @@ to the output file. Verify signed data. Expects a signed data on input and outputs the signed data. Both clear text and opaque signing is supported. +By default, validation of signer certificates and their chain +is done w.r.t. the S/MIME signing (C<smimesign>) purpose. +For details see L<openssl-verification-options(1)/Certificate Extensions>. + =item B<-resign> Resign a message: take an existing message and one or more new signers. @@ -374,7 +378,8 @@ See L<openssl-format-options(1)> for details. =item B<-originator> I<file> A certificate of the originator of the encrypted message. Necessary for -decryption when Key Agreement is in use for a shared key. +decryption when Key Agreement is in use for a shared key. Currently, not +allowed for encryption. =item B<-recip> I<file> @@ -902,7 +907,7 @@ The B<-engine> option was deprecated 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/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in index a47e783e2d63..ad2d918c7a1a 100644 --- a/doc/man1/openssl-enc.pod.in +++ b/doc/man1/openssl-enc.pod.in @@ -180,9 +180,12 @@ Print out the key and IV used. Print out the key and IV used then immediately exit: don't do any encryption or decryption. -=item B<-bufsize> I<number> +=item B<-bufsize> I<number>[B<k>] Set the buffer size for I/O. +The maximum size that can be specified is B<2^31-1> (2147483647) bytes. +The B<k> suffix can be specified to indicate that I<number> is provided +in kibibytes (multiples of 1024 bytes). =item B<-nopad> @@ -251,7 +254,7 @@ Some of the ciphers do not have large keys and others have security implications if not used correctly. A beginner is advised to just use a strong block cipher, such as AES, in CBC mode. -All the block ciphers normally use PKCS#5 padding, also known as standard +All the block ciphers normally use PKCS#7 padding, also known as standard block padding. This allows a rudimentary integrity or password check to be performed. However, since the chance of random data passing the test is better than 1 in 256 it isn't a very good test. @@ -458,7 +461,7 @@ The B<-ciphers> and B<-engine> options were 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/man1/openssl-fipsinstall.pod.in b/doc/man1/openssl-fipsinstall.pod.in index 97e2ae910c17..57758597cdae 100644 --- a/doc/man1/openssl-fipsinstall.pod.in +++ b/doc/man1/openssl-fipsinstall.pod.in @@ -239,6 +239,10 @@ L<fips_config(5)>, L<OSSL_PROVIDER-FIPS(7)>, L<EVP_MAC(3)> +=head1 HISTORY + +The B<openssl-fipsinstall> application was added in OpenSSL 3.0. + =head1 COPYRIGHT Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man1/openssl-ocsp.pod.in b/doc/man1/openssl-ocsp.pod.in index fbad5079af67..fd23a44df063 100644 --- a/doc/man1/openssl-ocsp.pod.in +++ b/doc/man1/openssl-ocsp.pod.in @@ -30,8 +30,8 @@ B<openssl> B<ocsp> [B<-respin> I<file>] [B<-url> I<URL>] [B<-host> I<host>:I<port>] -[B<-path>] -[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>] +[B<-path> I<pathname>] +[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>] [B<-no_proxy> I<addresses>] [B<-header>] [B<-timeout> I<seconds>] @@ -160,24 +160,32 @@ with B<-serial>, B<-cert> and B<-host> options). =item B<-url> I<responder_url> -Specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. +Specify the responder host and optionally port and path via a URL. +Both HTTP and HTTPS (SSL/TLS) URLs can be specified. The optional userinfo and fragment components are ignored. Any given query component is handled as part of the path component. +For details, see the B<-host> and B<-path> options described next. -=item B<-host> I<hostname>:I<port>, B<-path> I<pathname> +=item B<-host> I<host>:I<port>, B<-path> I<pathname> If the B<-host> option is present then the OCSP request is sent to the host -I<hostname> on port I<port>. The B<-path> option specifies the HTTP pathname -to use or "/" by default. This is equivalent to specifying B<-url> with scheme -http:// and the given hostname, port, and pathname. +I<host> on port I<port>. +The I<host> may be a domain name or an IP (v4 or v6) address, +such as C<127.0.0.1> or C<[::1]> for localhost. +If it is an IPv6 address, it must be enclosed in C<[> and C<]>. -=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]> +The B<-path> option specifies the HTTP pathname to use or "/" by default. +This is equivalent to specifying B<-url> with scheme +http:// and the given I<host>, I<port>, and optional I<pathname>. + +=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]> The HTTP(S) proxy server to use for reaching the OCSP server unless B<-no_proxy> applies, see below. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that the optional C<http://> or C<https://> prefix is ignored, -as well as any userinfo and path components. +as well as any userinfo, path, query, and fragment components. Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY> in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>. @@ -369,8 +377,8 @@ subject name. =item B<-port> I<portnum> -Port to listen for OCSP requests on. The port may also be specified -using the B<url> option. +Port to listen for OCSP requests on. Both IPv4 and IPv6 are possible. +The port may also be specified using the B<-url> option. A C<0> argument indicates that any available port shall be chosen automatically. =item B<-ignore_err> diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in index cf3427a35c0b..2f6ef0021d14 100644 --- a/doc/man1/openssl-pkeyutl.pod.in +++ b/doc/man1/openssl-pkeyutl.pod.in @@ -44,6 +44,8 @@ B<openssl> B<pkeyutl> This command can be used to perform low-level public key operations using any supported algorithm. +By default the signing operation (see B<-sign> option) is assumed. + =head1 OPTIONS =over 4 @@ -59,20 +61,29 @@ if this option is not specified. =item B<-rawin> -This indicates that the input data is raw data, which is not hashed by any -message digest algorithm. The user can specify a digest algorithm by using -the B<-digest> option. This option can only be used with B<-sign> and -B<-verify> and must be used with the Ed25519 and Ed448 algorithms. +This indicates that the signature or verification input data is raw data, +which is not hashed by any message digest algorithm. +Except with EdDSA, +the user can specify a digest algorithm by using the B<-digest> option. +For signature algorithms like RSA, DSA and ECDSA, +the default digest algorithm is SHA-256. For SM2, it is SM3. + +This option can only be used with B<-sign> and B<-verify>. +For EdDSA (the Ed25519 and Ed448 algorithms) this option is required. =item B<-digest> I<algorithm> -This specifies the digest algorithm which is used to hash the input data before -signing or verifying it with the input key. This option could be omitted if the -signature algorithm does not require one (for instance, EdDSA). If this option -is omitted but the signature algorithm requires one, a default value will be -used. For signature algorithms like RSA, DSA and ECDSA, SHA-256 will be the -default digest algorithm. For SM2, it will be SM3. If this option is present, -then the B<-rawin> option must be also specified. +This option can only be used with B<-sign> and B<-verify>. +It specifies the digest algorithm that is used to hash the input data +before signing or verifying it with the input key. This option could be omitted +if the signature algorithm does not require preprocessing the input through +a pluggable hash function before signing (for instance, EdDSA). If this option +is omitted but the signature algorithm requires one and the B<-rawin> option +is given, a default value will be used (see B<-rawin> for details). +If this option is present, then the B<-rawin> option is required. + +At this time, HashEdDSA (the ph or "prehash" variant of EdDSA) is not supported, +so the B<-digest> option cannot be used with EdDSA. =item B<-out> I<filename> @@ -81,7 +92,7 @@ default. =item B<-sigfile> I<file> -Signature file, required for B<-verify> operations only +Signature file, required and allowed for B<-verify> operations only =item B<-inkey> I<filename>|I<uri> @@ -117,21 +128,42 @@ The input is a certificate containing a public key. =item B<-rev> Reverse the order of the input buffer. This is useful for some libraries -(such as CryptoAPI) which represent the buffer in little endian format. +(such as CryptoAPI) which represent the buffer in little-endian format. +This cannot be used in conjunction with B<-rawin>. =item B<-sign> -Sign the input data (which must be a hash) and output the signed result. This -requires a private key. +Sign the input data and output the signed result. This requires a private key. +Using a message digest operation along with this is recommended, +when applicable, see the B<-rawin> and B<-digest> options for details. +Otherwise, the input data given with the B<-in> option is assumed to already +be a digest, but this may then require an additional B<-pkeyopt> C<digest:>I<md> +in some cases (e.g., RSA with the default PKCS#1 padding mode). +Even for other algorithms like ECDSA, where the additional B<-pkeyopt> option +does not affect signature output, it is recommended, as it enables +checking that the input length is consistent with the intended digest. =item B<-verify> -Verify the input data (which must be a hash) against the signature file and -indicate if the verification succeeded or failed. +Verify the input data against the signature given with the B<-sigfile> option +and indicate if the verification succeeded or failed. +The input data given with the B<-in> option is assumed to be a hash value +unless the B<-rawin> option is specified or implied. +With raw data, when a digest algorithm is applicable, though it may be inferred +from the signature or take a default value, it should also be specified. =item B<-verifyrecover> -Verify the input data (which must be a hash) and output the recovered data. +Verify the given signature and output the recovered data (signature payload). +For example, in case of RSA PKCS#1 the recovered data is the B<EMSA-PKCS-v1_5> +DER encoding of the digest algorithm OID and value as specified in +L<RFC8017 Section 9.2|https://datatracker.ietf.org/doc/html/rfc8017#section-9.2>. + +Note that here the input given with the B<-in> option is not a signature input +(as with the B<-sign> and B<-verify> options) but a signature output value, +typically produced using the B<-sign> option. + +This option is available only for use with RSA keys. =item B<-encrypt> @@ -175,8 +207,9 @@ hex dump the output data. =item B<-asn1parse> -Parse the ASN.1 output data, this is useful when combined with the -B<-verifyrecover> option when an ASN1 structure is signed. +Parse the ASN.1 output data to check its DER encoding and print any errors. +When combined with the B<-verifyrecover> option, this may be useful only in case +an ASN.1 DER-encoded structure had been signed directly (without hashing it). {- $OpenSSL::safe::opt_engine_item -} @@ -200,8 +233,8 @@ engine I<id> for crypto operations. The operations and options supported vary according to the key algorithm and its implementation. The OpenSSL operations and options are indicated below. -Unless otherwise mentioned all algorithms support the B<digest:>I<alg> option -which specifies the digest in use for sign, verify and verifyrecover operations. +Unless otherwise mentioned, all algorithms support the B<digest:>I<alg> option, +which specifies the digest in use for the signing and verification operations. The value I<alg> should represent a digest name as used in the EVP_get_digestbyname() function for example B<sha1>. This value is not used to hash the input data. It is used (by some algorithms) for sanity-checking the diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in index a56f548de8ee..7ba599b54a06 100644 --- a/doc/man1/openssl-req.pod.in +++ b/doc/man1/openssl-req.pod.in @@ -638,7 +638,7 @@ Sample configuration file prompting for field values: attributes = req_attributes req_extensions = v3_ca - dirstring_type = nobmp + dirstring_type = nombstr [ req_distinguished_name ] countryName = Country Name (2 letter code) @@ -778,7 +778,7 @@ The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead. =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/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index bd6171aa265c..29025ef1161b 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -10,11 +10,11 @@ openssl-s_client - SSL/TLS client program B<openssl> B<s_client> [B<-help>] [B<-ssl_config> I<section>] -[B<-connect> I<host:port>] +[B<-connect> I<host>:I<port>] [B<-host> I<hostname>] [B<-port> I<port>] -[B<-bind> I<host:port>] -[B<-proxy> I<host:port>] +[B<-bind> I<host>:I<port>] +[B<-proxy> I<host>:I<port>] [B<-proxy_user> I<userid>] [B<-proxy_pass> I<arg>] [B<-unix> I<path>] @@ -157,6 +157,7 @@ This specifies the host and optional port to connect to. It is possible to select the host and port using the optional target positional argument instead. If neither this nor the target positional argument are specified then an attempt is made to connect to the local host on port 4433. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. =item B<-host> I<hostname> @@ -166,17 +167,19 @@ Host to connect to; use B<-connect> instead. Connect to the specified port; use B<-connect> instead. -=item B<-bind> I<host:port> +=item B<-bind> I<host>:I<port> This specifies the host address and or port to bind as the source for the connection. For Unix-domain sockets the port is ignored and the host is used as the source socket address. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. -=item B<-proxy> I<host:port> +=item B<-proxy> I<host>:I<port> When used with the B<-connect> flag, the program uses the host and port specified with this flag and issues an HTTP CONNECT command to connect to the desired server. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. =item B<-proxy_user> I<userid> @@ -260,7 +263,9 @@ See L<openssl-format-options(1)> for details. =item B<-crl_download> -Download CRL from distribution points in the certificate. +Download CRL from distribution points in the certificate. Note that this option +is ignored if B<-crl_check> option is not provided. Note that the maximum size +of CRL is limited by L<X509_CRL_load_http(3)> function. =item B<-key> I<filename>|I<uri> @@ -282,14 +287,20 @@ see L<openssl-passphrase-options(1)>. The verify depth to use. This specifies the maximum length of the server certificate chain and turns on server certificate verification. -Currently the verify operation continues after errors so all the problems +Unless the B<-verify_return_error> option is given, +the verify operation continues after errors so all the problems with a certificate chain can be seen. As a side effect the connection will never fail due to a server certificate verify failure. +By default, validation of server certificates and their chain +is done w.r.t. the (D)TLS Server (C<sslserver>) purpose. +For details see L<openssl-verification-options(1)/Certificate Extensions>. + =item B<-verify_return_error> -Return verification errors instead of continuing. This will typically -abort the handshake with a fatal error. +Turns on server certificate verification, like with B<-verify>, +but returns verification errors instead of continuing. +This will typically abort the handshake with a fatal error. =item B<-verify_quiet> @@ -488,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> @@ -799,10 +810,11 @@ proceed unless the B<-verify_return_error> option is used. =item I<host>:I<port> -Rather than providing B<-connect>, the target hostname and optional port may +Rather than providing B<-connect>, the target host and optional port may be provided as a single positional argument after all options. If neither this nor B<-connect> are provided, falls back to attempting to connect to I<localhost> on port I<4433>. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. =back @@ -881,6 +893,51 @@ option: any verify errors are then returned aborting the handshake. The B<-bind> option may be useful if the server or a firewall requires connections to come from some particular address and or port. +=head2 Note on Non-Interactive Use + +When B<s_client> is run in a non-interactive environment (e.g., a cron job or +a script without a valid I<stdin>), it may close the connection prematurely, +especially with TLS 1.3. To prevent this, you can use the B<-ign_eof> flag, +which keeps B<s_client> running even after reaching EOF from I<stdin>. + +For example: + + openssl s_client -connect <server address>:443 -tls1_3 + -sess_out /path/to/tls_session_params_file + -ign_eof </dev/null + +However, relying solely on B<-ign_eof> can lead to issues if the server keeps +the connection open, expecting the client to close first. In such cases, the +client may hang indefinitely. This behavior is not uncommon, particularly with +protocols where the server waits for a graceful disconnect from the client. + +For example, when connecting to an SMTP server, the session may pause if the +server expects a QUIT command before closing: + + $ openssl s_client -brief -ign_eof -starttls smtp + -connect <server address>:25 </dev/null + CONNECTION ESTABLISHED + Protocol version: TLSv1.3 + Ciphersuite: TLS_AES_256_GCM_SHA384 + ... + 250 CHUNKING + [long pause] + +To avoid such hangs, it's better to use an application-level command to +initiate a clean disconnect. For SMTP, you can send a QUIT command: + + printf 'QUIT\r\n' | openssl s_client -connect <server address>:25 + -starttls smtp -brief -ign_eof + +Similarly, for HTTP/1.1 connections, including a `Connection: close` header +ensures the server closes the connection after responding: + + printf 'GET / HTTP/1.1\r\nHost: <server address>\r\nConnection: close\r\n\r\n' + | openssl s_client -connect <server address>:443 -brief + +These approaches help manage the connection closure gracefully and prevent +hangs caused by the server waiting for the client to initiate the disconnect. + =head1 BUGS Because this program has a lot of options and also because some of the @@ -914,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/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index 99a252a82254..f0825ad33d1f 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -74,7 +74,7 @@ B<openssl> B<s_server> [B<-status>] [B<-status_verbose>] [B<-status_timeout> I<int>] -[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>] +[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>] [B<-no_proxy> I<addresses>] [B<-status_url> I<val>] [B<-status_file> I<infile>] @@ -202,6 +202,10 @@ must supply a certificate or an error occurs. If the cipher suite cannot request a client certificate (for example an anonymous cipher suite or PSK) this option has no effect. +By default, validation of any supplied client certificate and its chain +is done w.r.t. the (D)TLS Client (C<sslclient>) purpose. +For details see L<openssl-verification-options(1)/Certificate Extensions>. + =item B<-cert> I<infile> The certificate to use, most servers cipher suites require the use of a @@ -504,13 +508,14 @@ a verbose printout of the OCSP response. Sets the timeout for OCSP response to I<int> seconds. -=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]> +=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]> The HTTP(S) proxy server to use for reaching the OCSP server unless B<-no_proxy> applies, see below. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that the optional C<http://> or C<https://> prefix is ignored, -as well as any userinfo and path components. +as well as any userinfo, path, query, and fragment components. Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY> in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>. diff --git a/doc/man1/openssl-s_time.pod.in b/doc/man1/openssl-s_time.pod.in index 2b82cf1e9837..ca41f59362f9 100644 --- a/doc/man1/openssl-s_time.pod.in +++ b/doc/man1/openssl-s_time.pod.in @@ -50,6 +50,7 @@ Print out a usage message. =item B<-connect> I<host>:I<port> This specifies the host and optional port to connect to. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. =item B<-www> I<page> diff --git a/doc/man1/openssl-smime.pod.in b/doc/man1/openssl-smime.pod.in index 0b5dbb5df8f7..ffd09704f834 100644 --- a/doc/man1/openssl-smime.pod.in +++ b/doc/man1/openssl-smime.pod.in @@ -394,9 +394,9 @@ Verify a message and extract the signer's certificate if successful: Send encrypted mail using triple DES: - openssl smime -encrypt -in in.txt -from steve@openssl.org \ + openssl smime -encrypt -in in.txt -out mail.msg -from steve@openssl.org \ -to someone@somewhere -subject "Encrypted message" \ - -des3 user.pem -out mail.msg + -des3 user.pem Sign and encrypt mail: diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in index 5f4895b34d6c..cd6dfd5305f0 100644 --- a/doc/man1/openssl-ts.pod.in +++ b/doc/man1/openssl-ts.pod.in @@ -584,10 +584,12 @@ To verify a timestamp reply that includes the certificate chain: -CAfile cacert.pem To verify a timestamp token against the original data file: + openssl ts -verify -data design2.txt -in design2.tsr \ -CAfile cacert.pem To verify a timestamp token against a message imprint: + openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ -in design2.tsr -CAfile cacert.pem diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod index bf9ed9c1a62e..17fcd4eb79f5 100644 --- a/doc/man1/openssl-verification-options.pod +++ b/doc/man1/openssl-verification-options.pod @@ -24,8 +24,9 @@ The most important of them are detailed in the following sections. In a nutshell, a valid chain of certificates needs to be built up and verified starting from the I<target certificate> that is to be verified and ending in a certificate that due to some policy is trusted. -Verification is done relative to the given I<purpose>, which is the intended use -of the target certificate, such as SSL server, or by default for any purpose. +Certificate validation can be performed in the context of a I<purpose>, which +is a high-level specification of the intended use of the target certificate, +such as C<sslserver> for TLS servers, or (by default) for any purpose. The details of how each OpenSSL command handles errors are documented on the specific command page. @@ -150,16 +151,17 @@ the chain components and their links are checked thoroughly. The first step is to check that each certificate is well-formed. Part of these checks are enabled only if the B<-x509_strict> option is given. -The second step is to check the extensions of every untrusted certificate -for consistency with the supplied purpose. -If the B<-purpose> option is not given then no such checks are done -except for SSL/TLS connection setup, -where by default C<sslserver> or C<sslclient>, are checked. -The target or "leaf" certificate, as well as any other untrusted certificates, -must have extensions compatible with the specified purpose. -All certificates except the target or "leaf" must also be valid CA certificates. -The precise extensions required are described in more detail in -L<openssl-x509(1)/CERTIFICATE EXTENSIONS>. +The second step is to check the X.509v3 extensions of every certificate +for consistency with the intended specific purpose, if any. +If the B<-purpose> option is not given then no such checks are done except for +CMS signature checking, where by default C<smimesign> is checked, and SSL/(D)TLS +connection setup, where by default C<sslserver> or C<sslclient> are checked. +The X.509v3 extensions of the target or "leaf" certificate +must be compatible with the specified purpose. +All other certificates down the chain are checked to be valid CA certificates, +and possibly also further non-standard checks are performed. +The precise extensions required are described in detail +in the L</Certificate Extensions> section below. The third step is to check the trust settings on the last certificate (which typically is a self-signed root CA certificate). @@ -455,13 +457,16 @@ Set policy variable inhibit-policy-mapping (see RFC5280). =item B<-purpose> I<purpose> -The intended use for the certificate. -Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>, +A high-level specification of the intended use of the target certificate. +Currently predefined purposes are C<sslclient>, C<sslserver>, C<nssslserver>, C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>, and C<any>. If peer certificate verification is enabled, by default the TLS implementation -as well as the commands B<s_client> and B<s_server> check for consistency -with TLS server or TLS client use, respectively. +and thus the commands L<openssl-s_client(1)> and L<openssl-s_server(1)> +check for consistency with +TLS server (C<sslserver>) or TLS client use (C<sslclient>), respectively. +By default, CMS signature validation, which can be done via L<openssl-cms(1)>, +checks for consistency with S/MIME signing use (C<smimesign>). While IETF RFC 5280 says that B<id-kp-serverAuth> and B<id-kp-clientAuth> are only for WWW use, in practice they are used for all kinds of TLS clients @@ -491,19 +496,20 @@ the subject certificate. =item B<-verify_name> I<name> -Use default verification policies like trust model and required certificate -policies identified by I<name>. +Use a set of verification parameters, also known as verification method, +identified by I<name>. The currently predefined methods are named C<ssl_client>, +C<ssl_server>, C<smime_sign> with alias C<pkcs7>, and C<default>. +These mimic the combinations of purpose and trust settings used in SSL/(D)TLS, +and CMS/PKCS7 (including S/MIME). + +The verification parameters include the trust model, various flags that can +partly be set also via other command-line options, and the verification purpose, +which in turn implies certificate key usage and extended key usage requirements. + The trust model determines which auxiliary trust or reject OIDs are applicable to verifying the given certificate chain. They can be given using the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>. -Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>, -B<ssl_client>, B<ssl_server>. -These mimics the combinations of purpose and trust settings used in SSL, CMS -and S/MIME. -As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not -specified, so the B<-verify_name> options are functionally equivalent to the -corresponding B<-purpose> settings. =back @@ -548,9 +554,8 @@ This option has no effect and is retained for backward compatibility only. =head2 Certificate Extensions -Options like B<-purpose> lead to checking the certificate extensions, -which determine what the target certificate and intermediate CA certificates -can be used for. +Options like B<-purpose> and B<-verify_name> trigger the processing of specific +certificate extensions, which determine what certificates can be used for. =head3 Basic Constraints @@ -574,87 +579,117 @@ keyCertSign bit set if the keyUsage extension is present. =head3 Extended Key Usage -The extKeyUsage (EKU) extension places additional restrictions on the -certificate uses. If this extension is present (whether critical or not) -the key can only be used for the purposes specified. - -A complete description of each check is given below. The comments about +The extKeyUsage (EKU) extension places additional restrictions on +certificate use. If this extension is present (whether critical or not) +in an end-entity certficiate, the key is allowed only for the uses specified, +while the special EKU B<anyExtendedKeyUsage> allows for all uses. + +Note that according to RFC 5280 section 4.2.1.12, +the Extended Key Usage extension will appear only in end-entity certificates, +and consequently the standard certification path validation described +in its section 6 does not include EKU checks for CA certificates. +The CA/Browser Forum requires for TLS server, S/MIME, and code signing use +the presence of respective EKUs in subordinate CA certificates (while excluding +them for root CA certificates), while taking over from RFC 5280 +the certificate validity concept and certificate path validation. + +For historic reasons, OpenSSL has its own way of interpreting and checking +EKU extensions on CA certificates, which may change in the future. +It does not require the presence of EKU extensions in CA certificates, +but in case the verification purpose is +C<sslclient>, C<nssslserver>, C<sslserver>, C<smimesign>, or C<smimeencrypt>, +it checks that any present EKU extension (that does not contain +B<anyExtendedKeyUsage>) contains the respective EKU as detailed below. +Moreover, it does these checks even for trust anchor certificates. + +=head3 Checks Implied by Specific Predefined Policies + +A specific description of each check is given below. The comments about basicConstraints and keyUsage and X.509v1 certificates above apply to B<all> CA certificates. - =over 4 -=item B<SSL Client> +=item B<(D)TLS Client> (C<sslclient>) -The extended key usage extension must be absent or include the "web client -authentication" OID. The keyUsage extension must be absent or it must have the -digitalSignature bit set. The Netscape certificate type must be absent -or it must have the SSL client bit set. +Any given extended key usage extension must allow for C<clientAuth> +("TLS WWW client authentication"). -=item B<SSL Client CA> +For target certificates, +the key usage must allow for C<digitalSignature> and/or C<keyAgreement>. +The Netscape certificate type must be absent or have the SSL client bit set. -The extended key usage extension must be absent or include the "web client -authentication" OID. -The Netscape certificate type must be absent or it must have the SSL CA bit set. -This is used as a work around if the basicConstraints extension is absent. +For all other certificates the normal CA checks apply. In addition, +the Netscape certificate type must be absent or have the SSL CA bit set. +This is used as a workaround if the basicConstraints extension is absent. -=item B<SSL Server> +=item B<(D)TLS Server> (C<sslserver>) -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. The keyUsage extension must be -absent or it -must have the digitalSignature, the keyEncipherment set or both bits set. -The Netscape certificate type must be absent or have the SSL server bit set. +Any given extended key usage extension must allow for C<serverAuth> +("TLS WWW server authentication") and/or include one of the SGC OIDs. -=item B<SSL Server CA> +For target certificates, the key usage must +allow for C<digitalSignature>, C<keyEncipherment>, and/or C<keyAgreement>. +The Netscape certificate type must be absent or have the SSL server bit set. -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. The Netscape certificate type must -be absent or the SSL CA bit must be set. -This is used as a work around if the basicConstraints extension is absent. +For all other certificates the normal CA checks apply. In addition, +the Netscape certificate type must be absent or have the SSL CA bit set. +This is used as a workaround if the basicConstraints extension is absent. -=item B<Netscape SSL Server> +=item B<Netscape SSL Server> (C<nssslserver>) -For Netscape SSL clients to connect to an SSL server it must have the -keyEncipherment bit set if the keyUsage extension is present. This isn't +In addition to what has been described for B<sslserver>, for a Netscape +SSL client to connect to an SSL server, its EE certficate must have the +B<keyEncipherment> bit set if the keyUsage extension is present. This isn't always valid because some cipher suites use the key for digital signing. Otherwise it is the same as a normal SSL server. -=item B<Common S/MIME Client Tests> +=item B<Common S/MIME Checks> -The extended key usage extension must be absent or include the "email -protection" OID. The Netscape certificate type must be absent or should have the -S/MIME bit set. If the S/MIME bit is not set in the Netscape certificate type +Any given extended key usage extension must allow for C<emailProtection>. + +For target certificates, +the Netscape certificate type must be absent or should have the S/MIME bit set. +If the S/MIME bit is not set in the Netscape certificate type then the SSL client bit is tolerated as an alternative but a warning is shown. This is because some Verisign certificates don't set the S/MIME bit. -=item B<S/MIME Signing> +For all other certificates the normal CA checks apply. In addition, +the Netscape certificate type must be absent or have the S/MIME CA bit set. +This is used as a workaround if the basicConstraints extension is absent. + +=item B<S/MIME Signing> (C<smimesign>) + +In addition to the common S/MIME checks, for target certficiates +the key usage must allow for C<digitalSignature> and/or B<nonRepudiation>. + +=item B<S/MIME Encryption> (C<smimeencrypt>) + +In addition to the common S/MIME checks, for target certficiates +the key usage must allow for C<keyEncipherment>. -In addition to the common S/MIME client tests the digitalSignature bit or -the nonRepudiation bit must be set if the keyUsage extension is present. +=item B<CRL Signing> (C<crlsign>) -=item B<S/MIME Encryption> +For target certificates, the key usage must allow for C<cRLSign>. -In addition to the common S/MIME tests the keyEncipherment bit must be set -if the keyUsage extension is present. +For all other certifcates the normal CA checks apply. +Except in this case the basicConstraints extension must be present. -=item B<S/MIME CA> +=item B<OCSP Helper> (C<ocsphelper>) -The extended key usage extension must be absent or include the "email -protection" OID. The Netscape certificate type must be absent or must have the -S/MIME CA bit set. -This is used as a work around if the basicConstraints extension is absent. +For target certificates, no checks are performed at this stage, +but special checks apply; see L<OCSP_basic_verify(3)>. -=item B<CRL Signing> +For all other certifcates the normal CA checks apply. -The keyUsage extension must be absent or it must have the CRL signing bit -set. +=item B<Timestamp Signing> (C<timestampsign>) -=item B<CRL Signing CA> +For target certificates, if the key usage extension is present, it must include +C<digitalSignature> and/or C<nonRepudiation> and must not include other bits. +The EKU extension must be present and contain C<timeStamping> only. +Moreover, it must be marked as critical. -The normal CA tests apply. Except in this case the basicConstraints extension -must be present. +For all other certifcates the normal CA checks apply. =back @@ -671,6 +706,7 @@ only the first one (in the mentioned order of locations) is recognised. =head1 SEE ALSO L<X509_verify_cert(3)>, +L<OCSP_basic_verify(3)>, L<openssl-verify(1)>, L<openssl-ocsp(1)>, L<openssl-ts(1)>, diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index 201428e87004..4865e5c33e6e 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -653,111 +653,22 @@ See L<property(7)> for a more detailed description. =head1 ENVIRONMENT -The OpenSSL library can be take some configuration parameters from the -environment. Some of these variables are listed below. For information -about specific commands, see L<openssl-engine(1)>, -L<openssl-rehash(1)>, and L<tsget(1)>. - -For information about the use of environment variables in configuration, -see L<config(5)/ENVIRONMENT>. - -For information about querying or specifying CPU architecture flags, see -L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>. +The OpenSSL libraries can take some configuration parameters from the +environment. For information about all environment variables used by the OpenSSL libraries, +such as B<OPENSSL_CONF>, B<OPENSSL_MODULES>, and B<OPENSSL_TRACE>, see L<openssl-env(7)>. -=over 4 - -=item B<OPENSSL_TRACE=>I<name>[,...] - -Enable tracing output of OpenSSL library, by name. -This output will only make sense if you know OpenSSL internals well. -Also, it might not give you any output at all, depending on how -OpenSSL was built. - -The value is a comma separated list of names, with the following -available: - -=over 4 - -=item B<TRACE> - -Traces the OpenSSL trace API itself. - -=item B<INIT> - -Traces OpenSSL library initialization and cleanup. - -=item B<TLS> - -Traces the TLS/SSL protocol. - -=item B<TLS_CIPHER> - -Traces the ciphers used by the TLS/SSL protocol. - -=item B<CONF> - -Show details about provider and engine configuration. - -=item B<ENGINE_TABLE> - -The function that is used by RSA, DSA (etc) code to select registered -ENGINEs, cache defaults and functional references (etc), will generate -debugging summaries. - -=item B<ENGINE_REF_COUNT> - -Reference counts in the ENGINE structure will be monitored with a line -of generated for each change. - -=item B<PKCS5V2> - -Traces PKCS#5 v2 key generation. - -=item B<PKCS12_KEYGEN> - -Traces PKCS#12 key generation. - -=item B<PKCS12_DECRYPT> - -Traces PKCS#12 decryption. - -=item B<X509V3_POLICY> - -Generates the complete policy tree at various points during X.509 v3 -policy evaluation. - -=item B<BN_CTX> - -Traces BIGNUM context operations. - -=item B<CMP> - -Traces CMP client and server activity. - -=item B<STORE> - -Traces STORE operations. - -=item B<DECODER> - -Traces decoder operations. - -=item B<ENCODER> - -Traces encoder operations. - -=item B<REF_COUNT> - -Traces decrementing certain ASN.1 structure references. +For information about the use of environment variables in configuration, +see L<config(5)/ENVIRONMENT>. -=back +For information about specific commands, see L<openssl-engine(1)>, +L<openssl-rehash(1)>, and L<tsget(1)>. -=back +For information about querying or specifying CPU architecture flags, see +L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>. -=head1 SEE ALSO L<openssl-asn1parse(1)>, L<openssl-ca(1)>, diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod index 66d9fefe1af6..bdef3fdbb155 100644 --- a/doc/man3/ASN1_TIME_set.pod +++ b/doc/man3/ASN1_TIME_set.pod @@ -102,8 +102,8 @@ functions check the syntax of the time structure I<s>. The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() functions print the time structure I<s> to BIO I<b> in human readable -format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example -"Feb 3 00:55:52 2015 GMT", which does not include a newline. +format. It will be of the format MMM DD HH:MM:SS[.s*] YYYY GMT, for example +"Feb E<32>3 00:55:52 2015 GMT", which does not include a newline. If the time structure has invalid format it prints out "Bad time value" and returns an error. The output for generalized time may include a fractional part following the second. @@ -179,6 +179,10 @@ starting with B<ASN1_UTCTIME> and B<ASN1_GENERALIZEDTIME> act only on that specific time format. The functions starting with B<ASN1_TIME> will operate on either format. +Users familiar with RFC822 should note that when specifying the flag +B<ASN1_DTFLGS_RFC822> the year will be formatted as documented above, +i.e., using 4 digits, not 2 as specified in RFC822. + =head1 BUGS ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() do @@ -272,7 +276,7 @@ The ASN1_TIME_compare() function was added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-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/ASN1_aux_cb.pod b/doc/man3/ASN1_aux_cb.pod index f87b51d5efac..9963ea135025 100644 --- a/doc/man3/ASN1_aux_cb.pod +++ b/doc/man3/ASN1_aux_cb.pod @@ -87,7 +87,7 @@ found for the purposes of reference counting. =item I<asn1_cb> A callback that will be invoked at various points during the processing of -the the B<ASN1_VALLUE>. See below for further details. +the B<ASN1_VALUE>. See below for further details. =item I<enc_offset> @@ -97,7 +97,7 @@ will be saved if the B<ASN1_AFLG_ENCODING> flag has been set. =item I<asn1_const_cb> A callback that will be invoked at various points during the processing of -the the B<ASN1_VALLUE>. This is used in preference to the I<asn1_cb> callback if +the B<ASN1_VALUE>. This is used in preference to the I<asn1_cb> callback if the B<ASN1_AFLG_CONST_CB> flag is set. See below for further details. =back @@ -274,7 +274,7 @@ B<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2021-2023 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/man3/BIO_s_accept.pod b/doc/man3/BIO_s_accept.pod index 25a752998cae..22b3d35b7374 100644 --- a/doc/man3/BIO_s_accept.pod +++ b/doc/man3/BIO_s_accept.pod @@ -169,16 +169,16 @@ BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros. BIO_do_accept(), BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_set_accept_ip_family(), and BIO_set_bind_mode() -return 1 for success and <=0 for failure. +return 1 for success and <= 0 for failure. BIO_get_accept_name() returns the accept name or NULL on error. BIO_get_peer_name() returns the peer name or NULL on error. BIO_get_accept_port() returns the accept port as a string or NULL on error. BIO_get_peer_port() returns the peer port as a string or NULL on error. -BIO_get_accept_ip_family() returns the IP family or <=0 on error. +BIO_get_accept_ip_family() returns the IP family or <= 0 on error. -BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or <=0 on failure. +BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or <= 0 on failure. BIO_new_accept() returns a BIO or NULL on error. diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod index ab813b32d031..a3c9e6428e47 100644 --- a/doc/man3/BIO_s_connect.pod +++ b/doc/man3/BIO_s_connect.pod @@ -59,7 +59,7 @@ a single call: that is it creates a new connect BIO with hostname B<name>. BIO_set_conn_hostname() uses the string B<name> to set the hostname. The hostname can be an IP address; if the address is an IPv6 one, it -must be enclosed with brackets C<[> and C<]>. +must be enclosed in brackets C<[> and C<]>. The hostname can also include the port in the form hostname:port; see L<BIO_parse_hostserv(3)> and BIO_set_conn_port() for details. diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod index accc8a749f0c..6b8d1de19cd8 100644 --- a/doc/man3/BN_generate_prime.pod +++ b/doc/man3/BN_generate_prime.pod @@ -130,7 +130,7 @@ or all the tests passed. If B<p> passes all these tests, it is considered a probable prime. The test performed on B<p> are trial division by a number of small primes -and rounds of the of the Miller-Rabin probabilistic primality test. +and rounds of the Miller-Rabin probabilistic primality test. The functions do at least 64 rounds of the Miller-Rabin test giving a maximum false positive rate of 2^-128. @@ -148,7 +148,7 @@ and BN_is_prime_fasttest() are deprecated. BN_is_prime_fasttest() and BN_is_prime() behave just like BN_is_prime_fasttest_ex() and BN_is_prime_ex() respectively, but with the old -style call back. +style callback. B<ctx> is a preallocated B<BN_CTX> (to save the overhead of allocating and freeing the structure in a loop), or B<NULL>. @@ -246,7 +246,7 @@ BN_check_prime() was added 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/ECDSA_sign.pod b/doc/man3/ECDSA_sign.pod index 7e5646665335..88e851885a01 100644 --- a/doc/man3/ECDSA_sign.pod +++ b/doc/man3/ECDSA_sign.pod @@ -52,7 +52,7 @@ size use L<EVP_PKEY_sign(3)> with a NULL I<sig> parameter. ECDSA_sign() computes a digital signature of the I<dgstlen> bytes hash value I<dgst> using the private EC key I<eckey>. The DER encoded signatures is -stored in I<sig> and its length is returned in I<sig_len>. Note: I<sig> must +stored in I<sig> and its length is returned in I<siglen>. Note: I<sig> must point to ECDSA_size(eckey) bytes of memory. The parameter I<type> is currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with I<kinv> and I<rp> set to NULL. @@ -82,7 +82,7 @@ used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex(). ECDSA_sign_ex() computes a digital signature of the I<dgstlen> bytes hash value I<dgst> using the private EC key I<eckey> and the optional pre-computed values I<kinv> and I<rp>. The DER encoded signature is stored in I<sig> and its -length is returned in I<sig_len>. Note: I<sig> must point to ECDSA_size(eckey) +length is returned in I<siglen>. Note: I<sig> must point to ECDSA_size(eckey) bytes of memory. The parameter I<type> is ignored. ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index f037d135c9da..497e6cfe26da 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -744,7 +744,7 @@ See also EVP_CIPHER_CTX_get_key_length() and EVP_CIPHER_CTX_set_key_length(). =item "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>) <octet string> Gets or sets the AEAD tag for the associated cipher context I<ctx>. -See L<EVP_EncryptInit(3)/AEAD Interface>. +See L<EVP_EncryptInit(3)/AEAD INTERFACE>. =item "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>) <unsigned integer> @@ -1284,6 +1284,15 @@ indicates whether the operation was successful. If it does not indicate success, the authentication operation has failed and any output data B<MUST NOT> be used as it is corrupted. +Please note that the number of authenticated bytes returned by +EVP_CipherUpdate() depends on the cipher used. Stream ciphers, such as ChaCha20 +or ciphers in GCM mode, can handle 1 byte at a time, resulting in an effective +"block" size of 1. Conversely, ciphers in OCB mode must process data one block +at a time, and the block size is returned. + +Regardless of the returned size, it is safe to pass unpadded data to an +EVP_CipherUpdate() call in a single operation. + =head2 GCM and OCB Modes The following I<ctrl>s are supported in GCM and OCB modes. @@ -1319,10 +1328,9 @@ For GCM, this call is only valid when decrypting data. For OCB, this call is valid when decrypting data to set the expected tag, and when encrypting to set the desired tag length. -In OCB mode, calling this when encrypting with C<tag> set to C<NULL> sets the -tag length. The tag length can only be set before specifying an IV. If this is -not called prior to setting the IV during encryption, then a default tag length -is used. +In OCB mode, calling this with C<tag> set to C<NULL> sets the tag length. +The tag length can only be set before specifying an IV. If this is not called +prior to setting the IV, then a default tag length is used. For OCB AES, the default tag length is 16 (i.e. 128 bits). It is also the maximum tag length for OCB. @@ -1738,7 +1746,7 @@ The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.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/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_PKEY_decapsulate.pod b/doc/man3/EVP_PKEY_decapsulate.pod index 819291627bb8..cd6f5f0221a2 100644 --- a/doc/man3/EVP_PKEY_decapsulate.pod +++ b/doc/man3/EVP_PKEY_decapsulate.pod @@ -25,10 +25,13 @@ specifying the private key to use. The EVP_PKEY_decapsulate() function performs a private key decapsulation operation using I<ctx>. The data to be decapsulated is specified using the I<wrapped> and I<wrappedlen> parameters. -If I<unwrapped> is NULL then the maximum size of the output secret buffer +If I<unwrapped> is NULL then the size of the output secret buffer is written to I<*unwrappedlen>. If I<unwrapped> is not NULL and the call is successful then the decapsulated secret data is written to I<unwrapped> -and the amount of data written to I<*unwrappedlen>. +and the amount of data written to I<*unwrappedlen>. Note that, if I<unwrappedlen> +is not NULL in this call, the value it points to must be initialised to the length of +I<unwrapped>, so that the call can validate it is of sufficient size to hold the +result of the operation. =head1 NOTES @@ -57,7 +60,7 @@ Decapsulate data using RSA: unsigned char *secret = NULL;; ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_priv_key, NULL); - if (ctx = NULL) + if (ctx == NULL) /* Error */ if (EVP_PKEY_decapsulate_init(ctx, NULL) <= 0) /* Error */ diff --git a/doc/man3/EVP_PKEY_encapsulate.pod b/doc/man3/EVP_PKEY_encapsulate.pod index 0ee7d627904d..eb51836d7951 100644 --- a/doc/man3/EVP_PKEY_encapsulate.pod +++ b/doc/man3/EVP_PKEY_encapsulate.pod @@ -35,7 +35,10 @@ unless I<genkeylen> is NULL. If I<wrappedkey> is not NULL and the call is successful then the internally generated key is written to I<genkey> and its size is written to I<*genkeylen>. The encapsulated version of the generated key is written to -I<wrappedkey> and its size is written to I<*wrappedkeylen>. +I<wrappedkey> and its size is written to I<*wrappedkeylen>. Note that if +I<wrappedlen> is not NULL, then the value it points to must initially hold the size of +the I<unwrapped> buffer so that its size can be validated by the call, ensuring +it is large enough to hold the result written to I<wrapped>. =head1 NOTES @@ -63,7 +66,7 @@ Encapsulate an RSASVE key (for RSA keys). unsigned char *out = NULL, *secret = NULL; ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_pub_key, NULL); - if (ctx = NULL) + if (ctx == NULL) /* Error */ if (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0) /* Error */ diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod index 1c75c7571994..1815f56f743e 100644 --- a/doc/man3/EVP_PKEY_new.pod +++ b/doc/man3/EVP_PKEY_new.pod @@ -168,7 +168,19 @@ general private key without reference to any particular algorithm. The structure returned by EVP_PKEY_new() is empty. To add a private or public key to this empty structure use the appropriate functions described in L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or -L<EVP_PKEY_set1_EC_KEY(3)>. +L<EVP_PKEY_set1_EC_KEY(3)> for legacy key types implemented in internal +OpenSSL providers. + +For fully provider-managed key types (see L<provider-keymgmt(7)>), +possibly implemented in external providers, use functions such as +L<EVP_PKEY_set1_encoded_public_key(3)> or L<EVP_PKEY_fromdata(3)> +to populate key data. + +Generally caution is advised for using an B<EVP_PKEY> structure across +different library contexts: In order for an B<EVP_PKEY> to be shared by +multiple library contexts the providers associated with the library contexts +must have key managers that support the key type and implement the +OSSL_FUNC_keymgmt_import() and OSSL_FUNC_keymgmt_export() functions. =head1 RETURN VALUES @@ -210,7 +222,7 @@ previously implied to be disallowed. =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/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/EVP_aes_128_gcm.pod b/doc/man3/EVP_aes_128_gcm.pod index 485705ea7889..9bac62b10b32 100644 --- a/doc/man3/EVP_aes_128_gcm.pod +++ b/doc/man3/EVP_aes_128_gcm.pod @@ -127,7 +127,7 @@ EVP_aes_256_ocb() AES for 128, 192 and 256 bit keys in CBC-MAC Mode (CCM), Galois Counter Mode (GCM) and OCB Mode respectively. These ciphers require additional control -operations to function correctly, see the L<EVP_EncryptInit(3)/AEAD Interface> +operations to function correctly, see the L<EVP_EncryptInit(3)/AEAD INTERFACE> section for details. =item EVP_aes_128_wrap(), @@ -184,7 +184,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017-2023 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_aria_128_gcm.pod b/doc/man3/EVP_aria_128_gcm.pod index 91aa75ec3871..74e21444db8f 100644 --- a/doc/man3/EVP_aria_128_gcm.pod +++ b/doc/man3/EVP_aria_128_gcm.pod @@ -88,7 +88,7 @@ EVP_aria_256_gcm(), ARIA for 128, 192 and 256 bit keys in CBC-MAC Mode (CCM) and Galois Counter Mode (GCM). These ciphers require additional control operations to function -correctly, see the L<EVP_EncryptInit(3)/AEAD Interface> section for details. +correctly, see the L<EVP_EncryptInit(3)/AEAD INTERFACE> section for details. =back @@ -113,7 +113,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017-2023 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_chacha20.pod b/doc/man3/EVP_chacha20.pod index 7e80c8de40c9..0dfce7389b78 100644 --- a/doc/man3/EVP_chacha20.pod +++ b/doc/man3/EVP_chacha20.pod @@ -36,7 +36,7 @@ With an initial counter of 42 (2a in hex) would be expressed as: Authenticated encryption with ChaCha20-Poly1305. Like EVP_chacha20(), the key is 256 bits and the IV is 96 bits. This supports additional authenticated data (AAD) and produces a 128-bit authentication tag. See the -L<EVP_EncryptInit(3)/AEAD Interface> section for more information. +L<EVP_EncryptInit(3)/AEAD INTERFACE> section for more information. =back @@ -64,7 +64,7 @@ L<EVP_CIPHER_meth_new(3)> =head1 COPYRIGHT -Copyright 2017-2023 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/OPENSSL_secure_malloc.pod b/doc/man3/OPENSSL_secure_malloc.pod index 1bddd7737069..dbc7073aac18 100644 --- a/doc/man3/OPENSSL_secure_malloc.pod +++ b/doc/man3/OPENSSL_secure_malloc.pod @@ -45,7 +45,12 @@ the program's dynamic memory area, where keys and other sensitive information might be stored, OpenSSL supports the concept of a "secure heap." The level and type of security guarantees depend on the operating system. It is a good idea to review the code and see if it addresses your -threat model and concerns. +threat model and concerns. It should be noted that the secure heap +uses a single read/write lock, and therefore any operations +that involve allocation or freeing of secure heap memory are serialised, +blocking other threads. With that in mind, highly concurrent applications +should enable the secure heap with caution and be aware of the performance +implications for multi-threaded code. If a secure heap is used, then private key B<BIGNUM> values are stored there. This protects long-term storage of private keys, but will not necessarily @@ -135,7 +140,7 @@ a B<size_t> in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-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_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index cab88ae88c91..f2a38b0adef4 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -355,8 +355,10 @@ If TLS is not used this defaults to the value of the environment variable C<http_proxy> if set, else C<HTTP_PROXY>. Otherwise defaults to the value of C<https_proxy> if set, else C<HTTPS_PROXY>. An empty proxy string specifies not to use a proxy. -Else the format is C<[http[s]://]address[:port][/path]>, -where any path given is ignored. +Otherwise the format is +C<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>, +where any given userinfo, path, query, and fragment is ignored. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. The default port number is 80, or 443 in case C<https:> is given. OSSL_CMP_CTX_set1_no_proxy() sets the list of server hostnames not to use diff --git a/doc/man3/OSSL_CMP_validate_msg.pod b/doc/man3/OSSL_CMP_validate_msg.pod index 555624a40358..c5e68065beff 100644 --- a/doc/man3/OSSL_CMP_validate_msg.pod +++ b/doc/man3/OSSL_CMP_validate_msg.pod @@ -44,7 +44,7 @@ any self-issued certificate from the I<msg> extraCerts field may be used as a trust anchor for the path verification of an 'acceptable' cert if it can be used also to validate the issued certificate returned in the IP message. This is according to TS 33.310 [Network Domain Security (NDS); Authentication Framework -(AF)] document specified by the The 3rd Generation Partnership Project (3GPP). +(AF)] document specified by The 3rd Generation Partnership Project (3GPP). Note that using this option is dangerous as the certificate obtained this way has not been authenticated (at least not at CMP level). Taking it over as a trust anchor implements trust-on-first-use (TOFU). @@ -77,7 +77,7 @@ The OpenSSL CMP support was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2007-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_HTTP_parse_url.pod b/doc/man3/OSSL_HTTP_parse_url.pod index 768f0acdb14c..4379c122d66a 100644 --- a/doc/man3/OSSL_HTTP_parse_url.pod +++ b/doc/man3/OSSL_HTTP_parse_url.pod @@ -42,20 +42,25 @@ take any further default value from the C<HTTP_PROXY> environment variable, or from C<HTTPS_PROXY> if I<use_ssl> is nonzero. If I<no_proxy> is NULL, take any default exclusion value from the C<no_proxy> environment variable, or else from C<NO_PROXY>. -Return the determined proxy hostname unless the exclusion contains I<server>. +Return the determined proxy host unless the exclusion value, +which is a list of proxy hosts separated by C<,> and/or whitespace, +contains I<server>. Otherwise return NULL. +When I<server> is a string delimited by C<[> and C<]>, which are used for IPv6 +addresses, the enclosing C<[> and C<]> are stripped prior to comparison. OSSL_parse_url() parses its input string I<url> as a URL of the form C<[scheme://][userinfo@]host[:port][/path][?query][#fragment]> and splits it up into scheme, userinfo, host, port, path, query, and fragment components. The host (or server) component may be a DNS name or an IP address -where IPv6 addresses should be enclosed in square brackets C<[> and C<]>. +where IPv6 addresses must be enclosed in square brackets C<[> and C<]>. The port component is optional and defaults to C<0>. If given, it must be in decimal form. If the I<pport_num> argument is not NULL the integer value of the port number is assigned to I<*pport_num> on success. The path component is also optional and defaults to C</>. Each non-NULL result pointer argument I<pscheme>, I<puser>, I<phost>, I<pport>, I<ppath>, I<pquery>, and I<pfrag>, is assigned the respective url component. +Any IPv6 address in I<*phost> is enclosed in C<[> and C<]>. On success, they are guaranteed to contain non-NULL string pointers, else NULL. It is the responsibility of the caller to free them using L<OPENSSL_free(3)>. If I<pquery> is NULL, any given query component is handled as part of the path. @@ -70,7 +75,7 @@ and the scheme is C<https>, else 0. The port component is optional and defaults to C<443> if the scheme is C<https>, else C<80>. Note that relative paths must be given with a leading C</>, -otherwise the first path element is interpreted as the hostname. +otherwise the first path element is interpreted as the host. Calling the deprecated function OCSP_parse_url(url, host, port, path, ssl) is equivalent to diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index 716e365ef50d..6da1d91b9f37 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -77,12 +77,14 @@ If TLS is not used this defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY>. If I<use_ssl> != 0 it defaults to C<https_proxy> if set, else C<HTTPS_PROXY>. An empty proxy string C<""> forbids using a proxy. -Else the format is +Otherwise, the format is C<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>, where any userinfo, path, query, and fragment given is ignored. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. The default proxy port number is 80, or 443 in case "https:" is given. The HTTP client functions connect via the given proxy unless the I<server> -is found in the optional list I<no_proxy> of proxy hostnames (if not NULL; +is found in the optional list I<no_proxy> of proxy hostnames or IP addresses +separated by C<,> and/or whitespace (if not NULL; default is the environment variable C<no_proxy> if set, else C<NO_PROXY>). Proxying plain HTTP is supported directly, while using a proxy for HTTPS connections requires a suitable callback function diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod index 1e5bf06cf767..8a50db2b94d4 100644 --- a/doc/man3/OSSL_PARAM.pod +++ b/doc/man3/OSSL_PARAM.pod @@ -11,7 +11,7 @@ OSSL_PARAM - a structure to pass or request object parameters typedef struct ossl_param_st OSSL_PARAM; struct ossl_param_st { const char *key; /* the name of the parameter */ - unsigned char data_type; /* declare what kind of content is in data */ + unsigned int data_type; /* declare what kind of content is in data */ void *data; /* value being passed in or out */ size_t data_size; /* data size */ size_t return_size; /* returned size */ @@ -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/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod index f9c9dffd8c6a..bad5b1515353 100644 --- a/doc/man3/OSSL_trace_enabled.pod +++ b/doc/man3/OSSL_trace_enabled.pod @@ -88,9 +88,10 @@ but rather uses a set of convenience macros, see the L</Macros> section below. OSSL_trace_enabled() can be used to check if tracing for the given I<category> is enabled. -OSSL_trace_begin() is used to starts a tracing section, and get the -channel for the given I<category> in form of a BIO. +OSSL_trace_begin() is used to start a tracing section, +and get the channel for the given I<category> in form of a BIO. This BIO can only be used for output. +The pointer returned is NULL if the category is invalid or not enabled. OSSL_trace_end() is used to end a tracing section. @@ -187,6 +188,9 @@ expands to =head1 NOTES +It is not needed to guard trace output function calls like +I<OSSL_TRACE(category, ...)> by I<OSSL_TRACE_ENABLED(category)>. + If producing the trace output requires carrying out auxiliary calculations, this auxiliary code should be placed inside a conditional block which is executed only if the trace category is enabled. diff --git a/doc/man3/OpenSSL_version.pod b/doc/man3/OpenSSL_version.pod index e1cf16e2a109..2cc6c3dfebb9 100644 --- a/doc/man3/OpenSSL_version.pod +++ b/doc/man3/OpenSSL_version.pod @@ -238,9 +238,16 @@ L<crypto(7)> The macros and functions described here were added in OpenSSL 3.0, except for OPENSSL_VERSION_NUMBER and OpenSSL_version_num(). +=head1 BUGS + +There was a discrepancy between this manual and commentary + code +in F<< <openssl/opensslv.h> >>, where the latter suggested that the +four least significant bits of B<OPENSSL_VERSION_NUMBER> could be +C<0x0f> in released OpenSSL versions. + =head1 COPYRIGHT -Copyright 2018-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018-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/PEM_read_CMS.pod b/doc/man3/PEM_read_CMS.pod index dbccf26cd893..880e31481029 100644 --- a/doc/man3/PEM_read_CMS.pod +++ b/doc/man3/PEM_read_CMS.pod @@ -84,9 +84,9 @@ see L<openssl_user_macros(7)>: =head1 DESCRIPTION -All of the functions described on this page are deprecated. -Applications should use OSSL_ENCODER_to_bio() and OSSL_DECODER_from_bio() -instead. +To replace the deprecated functions listed above, applications should use the +B<EVP_PKEY> type and OSSL_DECODER_from_bio() and OSSL_ENCODER_to_bio() to +read and write PEM data containing key parameters or private and public keys. In the description below, B<I<TYPE>> is used as a placeholder for any of the OpenSSL datatypes, such as B<X509>. @@ -142,7 +142,7 @@ were deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 1998-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 1998-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/RAND_load_file.pod b/doc/man3/RAND_load_file.pod index baca54cb3c89..45570920ca95 100644 --- a/doc/man3/RAND_load_file.pod +++ b/doc/man3/RAND_load_file.pod @@ -19,7 +19,11 @@ RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file RAND_load_file() reads a number of bytes from file B<filename> and adds them to the PRNG. If B<max_bytes> is nonnegative, up to B<max_bytes> are read; -if B<max_bytes> is -1, the complete file is read. +if B<max_bytes> is -1, the complete file is read (unless the file +is not a regular file, in that case a fixed number of bytes, +256 in the current implementation, is attempted to be read). +RAND_load_file() can read less than the complete file or the requested number +of bytes if it doesn't fit in the return value type. Do not load the same file multiple times unless its contents have been updated by RAND_write_file() between reads. Also, note that B<filename> should be adequately protected so that an @@ -77,7 +81,7 @@ L<RAND(7)> =head1 COPYRIGHT -Copyright 2000-2020 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/SSL_CIPHER_get_name.pod b/doc/man3/SSL_CIPHER_get_name.pod index 09b7280bdd58..a10942433aa7 100644 --- a/doc/man3/SSL_CIPHER_get_name.pod +++ b/doc/man3/SSL_CIPHER_get_name.pod @@ -37,7 +37,7 @@ SSL_CIPHER_get_protocol_id int SSL_CIPHER_is_aead(const SSL_CIPHER *c); const SSL_CIPHER *SSL_CIPHER_find(SSL *ssl, const unsigned char *ptr); uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *c); - uint32_t SSL_CIPHER_get_protocol_id(const SSL_CIPHER *c); + uint16_t SSL_CIPHER_get_protocol_id(const SSL_CIPHER *c); =head1 DESCRIPTION @@ -203,7 +203,7 @@ The OPENSSL_cipher_name() function was added in OpenSSL 1.1.1. =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/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_new.pod b/doc/man3/SSL_CTX_new.pod index f467f93659b5..627d9e7f0dc3 100644 --- a/doc/man3/SSL_CTX_new.pod +++ b/doc/man3/SSL_CTX_new.pod @@ -104,10 +104,12 @@ On session establishment, by default, no peer credentials verification is done. This must be explicitly requested, typically using L<SSL_CTX_set_verify(3)>. For verifying peer certificates many options can be set using various functions such as L<SSL_CTX_load_verify_locations(3)> and L<SSL_CTX_set1_param(3)>. -The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction -with L<SSL_CTX_get0_param(3)>, to set the intended purpose of the session. -The default is B<X509_PURPOSE_SSL_SERVER> on the client side + +The SSL/(D)TLS implementation uses the L<X509_STORE_CTX_set_default(3)> +function to prepare checks for B<X509_PURPOSE_SSL_SERVER> on the client side and B<X509_PURPOSE_SSL_CLIENT> on the server side. +The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction +with L<SSL_CTX_get0_param(3)>, to override the default purpose of the session. The SSL_CTX object uses I<method> as the connection method. Three method variants are available: a generic method (for either client or @@ -228,7 +230,7 @@ SSL_CTX_up_ref() returns 1 for success and 0 for failure. =head1 SEE ALSO -L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, +L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<X509_STORE_CTX_set_default(3)>, SSL_CTX_set_verify(3), L<SSL_CTX_set1_param(3)>, L<SSL_CTX_get0_param(3)>, L<SSL_connect(3)>, L<SSL_accept(3)>, L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)> 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_CTX_set_tmp_dh_callback.pod b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod index 4799ada6844b..902cefdfa366 100644 --- a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod +++ b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod @@ -58,9 +58,11 @@ the actual key is newly generated during the negotiation. Typically applications should use well known DH parameters that have built-in support in OpenSSL. The macros SSL_CTX_set_dh_auto() and SSL_set_dh_auto() configure OpenSSL to use the default built-in DH parameters for the B<SSL_CTX> -and B<SSL> objects respectively. Passing a value of 1 in the I<onoff> parameter -switches the feature on, and passing a value of 0 switches it off. The default -setting is off. +and B<SSL> objects respectively. Passing a value of 2 or 1 in the I<onoff> +parameter switches it on. If the I<onoff> parameter is set to 2, it will force +the DH key size to 1024 if the B<SSL_CTX> or B<SSL> security level +L<SSL_CTX_set_security_level(3)> is 0 or 1. Passing a value of 0 switches +it off. The default setting is off. If "auto" DH parameters are switched on then the parameters will be selected to be consistent with the size of the key associated with the server's certificate. @@ -112,7 +114,7 @@ L<openssl-ciphers(1)>, L<openssl-dhparam(1)> =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..0140deee9a5e 100644 --- a/doc/man3/SSL_SESSION_get0_hostname.pod +++ b/doc/man3/SSL_SESSION_get0_hostname.pod @@ -23,11 +23,10 @@ SSL_SESSION_set1_alpn_selected =head1 DESCRIPTION -SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the -client when the session was created 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. +SSL_SESSION_get0_hostname() retrieves the Server Name Indication (SNI) value +that was sent by the client when the session was created if the server +acknowledged the client's SNI extension by including an empty SNI extension +in response. Otherwise NULL is returned. The value returned is a pointer to memory maintained within B<s> and should not be free'd. @@ -46,8 +45,7 @@ B<alpn>. =head1 RETURN VALUES -SSL_SESSION_get0_hostname() returns either a string or NULL based on if there -is the SNI value sent by client. +SSL_SESSION_get0_hostname() returns the SNI string if available, or NULL if not. SSL_SESSION_set1_hostname() returns 1 on success or 0 on error. @@ -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_get_shared_sigalgs.pod b/doc/man3/SSL_get_shared_sigalgs.pod index c18114cdf472..cb9ce025002f 100644 --- a/doc/man3/SSL_get_shared_sigalgs.pod +++ b/doc/man3/SSL_get_shared_sigalgs.pod @@ -64,7 +64,7 @@ ordered according to configuration and peer preferences. The raw values correspond to the on the wire form as defined by RFC5246 et al. The NIDs are OpenSSL equivalents. For example if the peer sent sha256(4) and rsa(1) then B<*rhash> would be 4, B<*rsign> 1, B<*phash> NID_sha256, B<*psig> -NID_rsaEncryption and B<*psighash> NID_sha256WithRSAEncryption. +NID_rsaEncryption and B<*psignhash> NID_sha256WithRSAEncryption. If a signature algorithm is not recognised the corresponding NIDs will be set to B<NID_undef>. This may be because the value is not supported, 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/SSL_set_bio.pod b/doc/man3/SSL_set_bio.pod index c666dc466ecd..aaffeedf779b 100644 --- a/doc/man3/SSL_set_bio.pod +++ b/doc/man3/SSL_set_bio.pod @@ -23,6 +23,9 @@ function, any existing B<rbio> that was previously set will also be freed via a call to L<BIO_free_all(3)> (this includes the case where the B<rbio> is set to the same value as previously). +If using a custom BIO, B<rbio> must implement either +L<BIO_meth_set_read_ex(3)> or L<BIO_meth_set_read(3)>. + SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects the BIO B<wbio> for the write operations of the B<ssl> object. Note that if the rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take @@ -30,6 +33,12 @@ ownership of one reference. Therefore, it may be necessary to increment the number of references available using L<BIO_up_ref(3)> before calling the set0 functions. +If using a custom BIO, B<wbio> must implement +L<BIO_meth_set_write_ex(3)> or L<BIO_meth_set_write(3)>. It additionally must +implement L<BIO_flush(3)> using B<BIO_CTRL_FLUSH> and L<BIO_meth_set_ctrl(3)>. +If flushing is unnecessary with B<wbio>, L<BIO_flush(3)> should return one and +do nothing. + SSL_set_bio() is similar to SSL_set0_rbio() and SSL_set0_wbio() except that it connects both the B<rbio> and the B<wbio> at the same time, and transfers the ownership of B<rbio> and B<wbio> to B<ssl> according to diff --git a/doc/man3/X509V3_set_ctx.pod b/doc/man3/X509V3_set_ctx.pod index 8287802e41b2..7819c344f751 100644 --- a/doc/man3/X509V3_set_ctx.pod +++ b/doc/man3/X509V3_set_ctx.pod @@ -42,8 +42,7 @@ or not) to provide fallback data for the authority key identifier extension. =head1 RETURN VALUES -X509V3_set_ctx() and X509V3_set_issuer_pkey() -return 1 on success and 0 on error. +X509V3_set_issuer_pkey() returns 1 on success and 0 on error. =head1 SEE ALSO @@ -57,7 +56,7 @@ CTX_TEST was deprecated in OpenSSL 3.0; use X509V3_CTX_TEST instead. =head1 COPYRIGHT -Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-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_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod index c508a1d3fc1b..9929a98e0cf5 100644 --- a/doc/man3/X509_STORE_CTX_new.pod +++ b/doc/man3/X509_STORE_CTX_new.pod @@ -74,6 +74,12 @@ X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx> is no longer valid. If I<ctx> is NULL nothing is done. +X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation. + +X509_STORE_CTX_init() initializes the internal state and resources of the +given I<ctx>. Among others, it sets the verification parameters associcated +with the method name C<default>, which includes the C<any> purpose, +and takes over callback function pointers from I<trust_store> (unless NULL). It must be called before each call to L<X509_verify_cert(3)> or L<X509_STORE_CTX_verify(3)>, i.e., a context is only good for one verification. If you want to verify a further certificate or chain with the same I<ctx> @@ -144,12 +150,13 @@ by I<ctx> to be I<chain>. Ownership of the chain is transferred to I<ctx>, and so it should not be free'd by the caller. -X509_STORE_CTX_set_default() looks up and sets the default verification -method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to -find an appropriate set of parameters from the purpose identifier I<name>. -Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>, -C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>, -and C<any>. +X509_STORE_CTX_set_default() looks up and sets the default verification method. +This uses the function X509_VERIFY_PARAM_lookup() to find +the set of parameters associated with the given verification method I<name>. +Among others, the parameters determine the trust model and verification purpose. +More detail, including the list of currently predefined methods, +is described for the B<-verify_name> command-line option +in L<openssl-verification-options(1)/Verification Options>. X509_STORE_CTX_set_verify() provides the capability for overriding the default verify function. This function is responsible for verifying chain signatures and 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/man3/X509_add_cert.pod b/doc/man3/X509_add_cert.pod index 907164e9710e..f59b93ba54d4 100644 --- a/doc/man3/X509_add_cert.pod +++ b/doc/man3/X509_add_cert.pod @@ -16,6 +16,7 @@ X509 certificate list addition functions =head1 DESCRIPTION X509_add_cert() adds a certificate I<cert> to the given list I<sk>. +It is an error for the I<cert> argument to be NULL. X509_add_certs() adds a list of certificate I<certs> to the given list I<sk>. The I<certs> argument may be NULL, which implies no effect. @@ -66,7 +67,7 @@ were 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/X509_load_http.pod b/doc/man3/X509_load_http.pod index a147c43caa3f..e17330b05587 100644 --- a/doc/man3/X509_load_http.pod +++ b/doc/man3/X509_load_http.pod @@ -27,6 +27,9 @@ see L<openssl_user_macros(7)>: X509_load_http() and X509_CRL_load_http() loads a certificate or a CRL, respectively, in ASN.1 format using HTTP from the given B<url>. +Maximum size of the HTTP response is 100 kB for certificates and 32 MB for CRLs +and hard coded in the functions. + If B<bio> is given and B<rbio> is NULL then this BIO is used instead of an internal one for connecting, writing the request, and reading the response. If both B<bio> and B<rbio> are given (which may be memory BIOs, for instance) diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index c4b589dd8957..2d21b799a100 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -500,8 +500,9 @@ freed in the event of error and I<*a> is set to NULL. B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative value if an error occurs. -B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an -error occurs. +B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>(), +as well as i2d_ASN1_bio_stream(), +return 1 for success and 0 if an error occurs. =head1 EXAMPLES @@ -617,7 +618,7 @@ efficiency reasons. =head1 COPYRIGHT -Copyright 1998-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 1998-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/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod index 5fc0a73241cc..b563efa5f5d7 100644 --- a/doc/man7/EVP_KDF-HKDF.pod +++ b/doc/man7/EVP_KDF-HKDF.pod @@ -15,6 +15,8 @@ and "extracts" from it a fixed-length pseudorandom key K. The second stage "expands" the key K into several additional pseudorandom keys (the output of the KDF). +The output is considered to be keying material. + =head2 Identity "HKDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-KB.pod b/doc/man7/EVP_KDF-KB.pod index 6e25882d674c..78b81673a5bd 100644 --- a/doc/man7/EVP_KDF-KB.pod +++ b/doc/man7/EVP_KDF-KB.pod @@ -10,6 +10,8 @@ The EVP_KDF-KB algorithm implements the Key-Based key derivation function (KBKDF). KBKDF derives a key from repeated application of a keyed MAC to an input secret (and other optional values). +The output is considered to be keying material. + =head2 Identity "KBKDF" is the name for this implementation; it can be used with the diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod index e6cadc8b826d..9a90f7583abe 100644 --- a/doc/man7/EVP_KDF-PBKDF2.pod +++ b/doc/man7/EVP_KDF-PBKDF2.pod @@ -13,6 +13,8 @@ The EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key derivation function, as described in SP800-132; it derives a key from a password using a salt and iteration count. +The output is considered to be a cryptographic key. + =head2 Identity "PBKDF2" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-SS.pod b/doc/man7/EVP_KDF-SS.pod index c8d19691a797..6640703eef1c 100644 --- a/doc/man7/EVP_KDF-SS.pod +++ b/doc/man7/EVP_KDF-SS.pod @@ -11,6 +11,8 @@ SSKDF derives a key using input such as a shared secret key (that was generated during the execution of a key establishment scheme) and fixedinfo. SSKDF is also informally referred to as 'Concat KDF'. +The output is considered to be keying material. + =head2 Auxiliary function The implementation uses a selectable auxiliary function H, which can be one of: diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod index c7a3263f455a..a5b153947558 100644 --- a/doc/man7/EVP_KDF-SSHKDF.pod +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -15,6 +15,8 @@ Five inputs are required to perform key derivation: The hashing function (for example SHA256), the Initial Key, the Exchange Hash, the Session ID, and the derivation key type. +The output is considered to be keying material. + =head2 Identity "SSHKDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-TLS13_KDF.pod b/doc/man7/EVP_KDF-TLS13_KDF.pod index d588b121faf5..7fad55ca61f1 100644 --- a/doc/man7/EVP_KDF-TLS13_KDF.pod +++ b/doc/man7/EVP_KDF-TLS13_KDF.pod @@ -12,6 +12,8 @@ the B<EVP_KDF> API. The EVP_KDF-TLS13_KDF algorithm implements the HKDF key derivation function as used by TLS 1.3. +The output is considered to be keying material. + =head2 Identity "TLS13-KDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod index 8a60e9731554..90b357e70f0b 100644 --- a/doc/man7/EVP_KDF-TLS1_PRF.pod +++ b/doc/man7/EVP_KDF-TLS1_PRF.pod @@ -11,6 +11,8 @@ Support for computing the B<TLS1> PRF through the B<EVP_KDF> API. The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to and including TLS 1.2. +The output is considered to be keying material. + =head2 Identity "TLS1-PRF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-X942-ASN1.pod b/doc/man7/EVP_KDF-X942-ASN1.pod index a5786ab83faa..17464738b511 100644 --- a/doc/man7/EVP_KDF-X942-ASN1.pod +++ b/doc/man7/EVP_KDF-X942-ASN1.pod @@ -13,6 +13,8 @@ contains a 32 bit counter as well as optional fields for "partyu-info", "partyv-info", "supp-pubinfo" and "supp-privinfo". This kdf is used by Cryptographic Message Syntax (CMS). +The output is considered to be keying material. + =head2 Identity "X942KDF-ASN1" or "X942KDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-X963.pod b/doc/man7/EVP_KDF-X963.pod index 3d6f4372cf31..ca2f7c1df0ef 100644 --- a/doc/man7/EVP_KDF-X963.pod +++ b/doc/man7/EVP_KDF-X963.pod @@ -10,6 +10,8 @@ The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF). X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to derive a key using input such as a shared secret key and shared info. +The output is considered to be keying material. + =head2 Identity "X963KDF" is the name for this implementation; it diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod index cdafc0edad5c..54619553f927 100644 --- a/doc/man7/EVP_PKEY-DSA.pod +++ b/doc/man7/EVP_PKEY-DSA.pod @@ -104,7 +104,7 @@ The following sections of FIPS186-4: =head1 SEE ALSO L<EVP_PKEY-FFC(7)>, -L<EVP_SIGNATURE-DSA(7)> +L<EVP_SIGNATURE-DSA(7)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>, L<EVP_KEYMGMT(3)>, @@ -113,7 +113,7 @@ L<OSSL_PROVIDER-FIPS(7)> =head1 COPYRIGHT -Copyright 2020-2022 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/man7/EVP_PKEY-FFC.pod b/doc/man7/EVP_PKEY-FFC.pod index 0b96bc24a614..a28bb84e0a36 100644 --- a/doc/man7/EVP_PKEY-FFC.pod +++ b/doc/man7/EVP_PKEY-FFC.pod @@ -213,7 +213,7 @@ The following sections of FIPS186-4: L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_SIGNATURE-DSA(7)>, -L<EVP_KEYEXCH-DH(7)> +L<EVP_KEYEXCH-DH(7)>, L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>, @@ -222,7 +222,7 @@ L<OSSL_PROVIDER-FIPS(7)>, =head1 COPYRIGHT -Copyright 2020-2022 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/man7/EVP_SIGNATURE-DSA.pod b/doc/man7/EVP_SIGNATURE-DSA.pod index 5a42d6b1cd22..326a86ee0b42 100644 --- a/doc/man7/EVP_SIGNATURE-DSA.pod +++ b/doc/man7/EVP_SIGNATURE-DSA.pod @@ -7,7 +7,9 @@ EVP_SIGNATURE-DSA =head1 DESCRIPTION -Support for computing DSA signatures. +Support for computing DSA signatures. The signature produced with +L<EVP_PKEY_sign(3)> is DER encoded ASN.1 in the form described in +RFC 3279, section 2.2.2. See L<EVP_PKEY-DSA(7)> for information related to DSA keys. =head2 Signature Parameters 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/openssl-env.pod b/doc/man7/openssl-env.pod index a2443d54d822..c7dbd2277dc6 100644 --- a/doc/man7/openssl-env.pod +++ b/doc/man7/openssl-env.pod @@ -51,6 +51,99 @@ See L<OPENSSL_malloc(3)>. Specifies the directory from which cryptographic providers are loaded. Equivalently, the generic B<-provider-path> command-line option may be used. +=item B<OPENSSL_TRACE> + +By default the OpenSSL trace feature is disabled statically. +To enable it, OpenSSL must be built with tracing support, +which may be configured like this: C<./config enable-trace> + +Unless OpenSSL tracing support is generally disabled, +enable trace output of specific parts of OpenSSL libraries, by name. +This output usually makes sense only if you know OpenSSL internals well. + +The value of this environment varialble is a comma-separated list of names, +with the following available: + +=over 4 + +=item B<TRACE> + +Traces the OpenSSL trace API itself. + +=item B<INIT> + +Traces OpenSSL library initialization and cleanup. + +=item B<TLS> + +Traces the TLS/SSL protocol. + +=item B<TLS_CIPHER> + +Traces the ciphers used by the TLS/SSL protocol. + +=item B<CONF> + +Show details about provider and engine configuration. + +=item B<ENGINE_TABLE> + +The function that is used by RSA, DSA (etc) code to select registered +ENGINEs, cache defaults and functional references (etc), will generate +debugging summaries. + +=item B<ENGINE_REF_COUNT> + +Reference counts in the ENGINE structure will be monitored with a line +of generated for each change. + +=item B<PKCS5V2> + +Traces PKCS#5 v2 key generation. + +=item B<PKCS12_KEYGEN> + +Traces PKCS#12 key generation. + +=item B<PKCS12_DECRYPT> + +Traces PKCS#12 decryption. + +=item B<X509V3_POLICY> + +Generates the complete policy tree at various points during X.509 v3 +policy evaluation. + +=item B<BN_CTX> + +Traces BIGNUM context operations. + +=item B<CMP> + +Traces CMP client and server activity. + +=item B<STORE> + +Traces STORE operations. + +=item B<DECODER> + +Traces decoder operations. + +=item B<ENCODER> + +Traces encoder operations. + +=item B<REF_COUNT> + +Traces decrementing certain ASN.1 structure references. + +=item B<HTTP> + +Traces the HTTP client and server, such as messages being sent and received. + +=back + =item B<OPENSSL_WIN32_UTF8> If set, then L<UI_OpenSSL(3)> returns UTF-8 encoded strings, rather than 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 diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index a061fc4709d0..08ac1d02907f 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -227,6 +227,18 @@ MODE is only present where applicable. Other aliases may exist for example where standards bodies or common practice use alternative names or names that OpenSSL has used historically. +=head3 Provider dependencies + +Providers may depend for their proper operation on the availability of +(functionality implemented in) other providers. As there is no mechanism to +express such dependencies towards the OpenSSL core, provider authors must +take care that such dependencies are either completely avoided or made visible +to users, e.g., by documentation and/or defensive programming, e.g., +outputting error messages if required external dependencies are not available, +e.g., when no provider implementing the required functionality has been +activated. In particular, provider initialization should not depend on other +providers already having been initialized. + =head1 OPENSSL PROVIDERS OpenSSL provides a number of its own providers. These are the default, base, |