diff options
Diffstat (limited to 'doc/man1')
| -rw-r--r-- | doc/man1/openssl-ca.pod.in | 2 | ||||
| -rw-r--r-- | doc/man1/openssl-cmp.pod.in | 11 | ||||
| -rw-r--r-- | doc/man1/openssl-cms.pod.in | 9 | ||||
| -rw-r--r-- | doc/man1/openssl-fipsinstall.pod.in | 4 | ||||
| -rw-r--r-- | doc/man1/openssl-ocsp.pod.in | 30 | ||||
| -rw-r--r-- | doc/man1/openssl-pkeyutl.pod.in | 77 | ||||
| -rw-r--r-- | doc/man1/openssl-req.pod.in | 4 | ||||
| -rw-r--r-- | doc/man1/openssl-s_client.pod.in | 77 | ||||
| -rw-r--r-- | doc/man1/openssl-s_server.pod.in | 11 | ||||
| -rw-r--r-- | doc/man1/openssl-s_time.pod.in | 1 | ||||
| -rw-r--r-- | doc/man1/openssl-smime.pod.in | 4 | ||||
| -rw-r--r-- | doc/man1/openssl-ts.pod.in | 2 | ||||
| -rw-r--r-- | doc/man1/openssl-verification-options.pod | 194 | ||||
| -rw-r--r-- | doc/man1/openssl.pod | 107 |
14 files changed, 300 insertions, 233 deletions
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-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..caebe10bffb8 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> @@ -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/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)>, |