diff options
| author | Enji Cooper <ngie@FreeBSD.org> | 2025-03-14 06:40:59 +0000 |
|---|---|---|
| committer | Philip Paeps <philip@FreeBSD.org> | 2025-04-10 14:38:58 +0000 |
| commit | 862cd6b8fa9df7057bad47d01ccaf36a959e9166 (patch) | |
| tree | 35bd6034ae1e5396fb6420037f2f8ba1b19ef588 /crypto/openssl/doc | |
| parent | 4651d400f1000834365a21c59d6803da4474c63e (diff) | |
openssl: Import OpenSSL 3.0.16
This release incorporates the following bug fixes and mitigations:
- [CVE-2024-13176](https://www.openssl.org/news/vulnerabilities.html#CVE-2024-13176
- [CVE-2024-9143](https://www.openssl.org/news/vulnerabilities.html#CVE-2024-9143)
Release notes can be found at:
https://openssl-library.org/news/openssl-3.0-notes/index.html
Approved by: so
Security: FreeBSD-EN-25:07.openssl
Differential Revision: https://reviews.freebsd.org/D49296
Differential Revision: https://reviews.freebsd.org/D49297
(cherry picked from commit 0d0c8621fd181e507f0fb50ffcca606faf66a8c2)
(cherry picked from commit cb29db243bd09d16604435639ae43ef7af0ea254)
(cherry picked from commit d2a55e6a9348bb55038dbc6b727ab041085f22db)
(cherry picked from commit 0d61082e3c64a43f52ec5f1bf3d85671d97d9514)
Diffstat (limited to 'crypto/openssl/doc')
47 files changed, 525 insertions, 281 deletions
diff --git a/crypto/openssl/doc/man1/openssl-ca.pod.in b/crypto/openssl/doc/man1/openssl-ca.pod.in index 1d497e848e79..1c07db3c8ef1 100644 --- a/crypto/openssl/doc/man1/openssl-ca.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-cmp.pod.in b/crypto/openssl/doc/man1/openssl-cmp.pod.in index 9240916fce40..889a59cd497e 100644 --- a/crypto/openssl/doc/man1/openssl-cmp.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-cms.pod.in b/crypto/openssl/doc/man1/openssl-cms.pod.in index 65a61ee97f1d..f4d12312b7cb 100644 --- a/crypto/openssl/doc/man1/openssl-cms.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-fipsinstall.pod.in b/crypto/openssl/doc/man1/openssl-fipsinstall.pod.in index 97e2ae910c17..57758597cdae 100644 --- a/crypto/openssl/doc/man1/openssl-fipsinstall.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-ocsp.pod.in b/crypto/openssl/doc/man1/openssl-ocsp.pod.in index fbad5079af67..fd23a44df063 100644 --- a/crypto/openssl/doc/man1/openssl-ocsp.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-pkeyutl.pod.in b/crypto/openssl/doc/man1/openssl-pkeyutl.pod.in index cf3427a35c0b..2f6ef0021d14 100644 --- a/crypto/openssl/doc/man1/openssl-pkeyutl.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-req.pod.in b/crypto/openssl/doc/man1/openssl-req.pod.in index a56f548de8ee..7ba599b54a06 100644 --- a/crypto/openssl/doc/man1/openssl-req.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-s_client.pod.in b/crypto/openssl/doc/man1/openssl-s_client.pod.in index bd6171aa265c..caebe10bffb8 100644 --- a/crypto/openssl/doc/man1/openssl-s_client.pod.in +++ b/crypto/openssl/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> @@ -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 diff --git a/crypto/openssl/doc/man1/openssl-s_server.pod.in b/crypto/openssl/doc/man1/openssl-s_server.pod.in index 99a252a82254..f0825ad33d1f 100644 --- a/crypto/openssl/doc/man1/openssl-s_server.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-s_time.pod.in b/crypto/openssl/doc/man1/openssl-s_time.pod.in index 2b82cf1e9837..ca41f59362f9 100644 --- a/crypto/openssl/doc/man1/openssl-s_time.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-smime.pod.in b/crypto/openssl/doc/man1/openssl-smime.pod.in index 0b5dbb5df8f7..ffd09704f834 100644 --- a/crypto/openssl/doc/man1/openssl-smime.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-ts.pod.in b/crypto/openssl/doc/man1/openssl-ts.pod.in index 5f4895b34d6c..cd6dfd5305f0 100644 --- a/crypto/openssl/doc/man1/openssl-ts.pod.in +++ b/crypto/openssl/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/crypto/openssl/doc/man1/openssl-verification-options.pod b/crypto/openssl/doc/man1/openssl-verification-options.pod index bf9ed9c1a62e..17fcd4eb79f5 100644 --- a/crypto/openssl/doc/man1/openssl-verification-options.pod +++ b/crypto/openssl/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. +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. -A complete description of each check is given below. The comments about +=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> + +Any given extended key usage extension must allow for C<emailProtection>. -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 +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/crypto/openssl/doc/man1/openssl.pod b/crypto/openssl/doc/man1/openssl.pod index 201428e87004..4865e5c33e6e 100644 --- a/crypto/openssl/doc/man1/openssl.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/ASN1_TIME_set.pod b/crypto/openssl/doc/man3/ASN1_TIME_set.pod index 66d9fefe1af6..bdef3fdbb155 100644 --- a/crypto/openssl/doc/man3/ASN1_TIME_set.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/ASN1_aux_cb.pod b/crypto/openssl/doc/man3/ASN1_aux_cb.pod index f87b51d5efac..9963ea135025 100644 --- a/crypto/openssl/doc/man3/ASN1_aux_cb.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/BIO_s_accept.pod b/crypto/openssl/doc/man3/BIO_s_accept.pod index 25a752998cae..22b3d35b7374 100644 --- a/crypto/openssl/doc/man3/BIO_s_accept.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/BIO_s_connect.pod b/crypto/openssl/doc/man3/BIO_s_connect.pod index ab813b32d031..a3c9e6428e47 100644 --- a/crypto/openssl/doc/man3/BIO_s_connect.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/ECDSA_sign.pod b/crypto/openssl/doc/man3/ECDSA_sign.pod index 7e5646665335..88e851885a01 100644 --- a/crypto/openssl/doc/man3/ECDSA_sign.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/EVP_EncryptInit.pod b/crypto/openssl/doc/man3/EVP_EncryptInit.pod index f037d135c9da..a4635f994c2f 100644 --- a/crypto/openssl/doc/man3/EVP_EncryptInit.pod +++ b/crypto/openssl/doc/man3/EVP_EncryptInit.pod @@ -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. diff --git a/crypto/openssl/doc/man3/EVP_PKEY_decapsulate.pod b/crypto/openssl/doc/man3/EVP_PKEY_decapsulate.pod index 819291627bb8..cd6f5f0221a2 100644 --- a/crypto/openssl/doc/man3/EVP_PKEY_decapsulate.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/EVP_PKEY_encapsulate.pod b/crypto/openssl/doc/man3/EVP_PKEY_encapsulate.pod index 0ee7d627904d..eb51836d7951 100644 --- a/crypto/openssl/doc/man3/EVP_PKEY_encapsulate.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/OSSL_CMP_CTX_new.pod b/crypto/openssl/doc/man3/OSSL_CMP_CTX_new.pod index cab88ae88c91..f2a38b0adef4 100644 --- a/crypto/openssl/doc/man3/OSSL_CMP_CTX_new.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/OSSL_CMP_validate_msg.pod b/crypto/openssl/doc/man3/OSSL_CMP_validate_msg.pod index 555624a40358..c5e68065beff 100644 --- a/crypto/openssl/doc/man3/OSSL_CMP_validate_msg.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/OSSL_HTTP_parse_url.pod b/crypto/openssl/doc/man3/OSSL_HTTP_parse_url.pod index 768f0acdb14c..4379c122d66a 100644 --- a/crypto/openssl/doc/man3/OSSL_HTTP_parse_url.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/OSSL_HTTP_transfer.pod b/crypto/openssl/doc/man3/OSSL_HTTP_transfer.pod index 716e365ef50d..6da1d91b9f37 100644 --- a/crypto/openssl/doc/man3/OSSL_HTTP_transfer.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/OSSL_PARAM.pod b/crypto/openssl/doc/man3/OSSL_PARAM.pod index 1e5bf06cf767..22fd0f0d7dd7 100644 --- a/crypto/openssl/doc/man3/OSSL_PARAM.pod +++ b/crypto/openssl/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 */ diff --git a/crypto/openssl/doc/man3/OSSL_trace_enabled.pod b/crypto/openssl/doc/man3/OSSL_trace_enabled.pod index f9c9dffd8c6a..bad5b1515353 100644 --- a/crypto/openssl/doc/man3/OSSL_trace_enabled.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/SSL_CTX_new.pod b/crypto/openssl/doc/man3/SSL_CTX_new.pod index f467f93659b5..627d9e7f0dc3 100644 --- a/crypto/openssl/doc/man3/SSL_CTX_new.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/SSL_get_shared_sigalgs.pod b/crypto/openssl/doc/man3/SSL_get_shared_sigalgs.pod index c18114cdf472..cb9ce025002f 100644 --- a/crypto/openssl/doc/man3/SSL_get_shared_sigalgs.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/SSL_set_bio.pod b/crypto/openssl/doc/man3/SSL_set_bio.pod index c666dc466ecd..aaffeedf779b 100644 --- a/crypto/openssl/doc/man3/SSL_set_bio.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/X509V3_set_ctx.pod b/crypto/openssl/doc/man3/X509V3_set_ctx.pod index 8287802e41b2..7819c344f751 100644 --- a/crypto/openssl/doc/man3/X509V3_set_ctx.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/X509_STORE_CTX_new.pod b/crypto/openssl/doc/man3/X509_STORE_CTX_new.pod index c508a1d3fc1b..9929a98e0cf5 100644 --- a/crypto/openssl/doc/man3/X509_STORE_CTX_new.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/X509_add_cert.pod b/crypto/openssl/doc/man3/X509_add_cert.pod index 907164e9710e..f59b93ba54d4 100644 --- a/crypto/openssl/doc/man3/X509_add_cert.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man3/X509_load_http.pod b/crypto/openssl/doc/man3/X509_load_http.pod index a147c43caa3f..e17330b05587 100644 --- a/crypto/openssl/doc/man3/X509_load_http.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-HKDF.pod b/crypto/openssl/doc/man7/EVP_KDF-HKDF.pod index 5fc0a73241cc..b563efa5f5d7 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-HKDF.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-KB.pod b/crypto/openssl/doc/man7/EVP_KDF-KB.pod index 6e25882d674c..78b81673a5bd 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-KB.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-PBKDF2.pod b/crypto/openssl/doc/man7/EVP_KDF-PBKDF2.pod index e6cadc8b826d..9a90f7583abe 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-PBKDF2.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-SS.pod b/crypto/openssl/doc/man7/EVP_KDF-SS.pod index c8d19691a797..6640703eef1c 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-SS.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-SSHKDF.pod b/crypto/openssl/doc/man7/EVP_KDF-SSHKDF.pod index c7a3263f455a..a5b153947558 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-SSHKDF.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-TLS13_KDF.pod b/crypto/openssl/doc/man7/EVP_KDF-TLS13_KDF.pod index d588b121faf5..7fad55ca61f1 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-TLS13_KDF.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-TLS1_PRF.pod b/crypto/openssl/doc/man7/EVP_KDF-TLS1_PRF.pod index 8a60e9731554..90b357e70f0b 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-TLS1_PRF.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-X942-ASN1.pod b/crypto/openssl/doc/man7/EVP_KDF-X942-ASN1.pod index a5786ab83faa..17464738b511 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-X942-ASN1.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_KDF-X963.pod b/crypto/openssl/doc/man7/EVP_KDF-X963.pod index 3d6f4372cf31..ca2f7c1df0ef 100644 --- a/crypto/openssl/doc/man7/EVP_KDF-X963.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/EVP_SIGNATURE-DSA.pod b/crypto/openssl/doc/man7/EVP_SIGNATURE-DSA.pod index 5a42d6b1cd22..326a86ee0b42 100644 --- a/crypto/openssl/doc/man7/EVP_SIGNATURE-DSA.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/openssl-env.pod b/crypto/openssl/doc/man7/openssl-env.pod index a2443d54d822..c7dbd2277dc6 100644 --- a/crypto/openssl/doc/man7/openssl-env.pod +++ b/crypto/openssl/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/crypto/openssl/doc/man7/provider.pod b/crypto/openssl/doc/man7/provider.pod index a061fc4709d0..08ac1d02907f 100644 --- a/crypto/openssl/doc/man7/provider.pod +++ b/crypto/openssl/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, |