diff options
Diffstat (limited to 'secure/usr.bin/openssl/man/ts.1')
| -rw-r--r-- | secure/usr.bin/openssl/man/ts.1 | 209 |
1 files changed, 138 insertions, 71 deletions
diff --git a/secure/usr.bin/openssl/man/ts.1 b/secure/usr.bin/openssl/man/ts.1 index 34c30ebffa6f7..7b597e4b42e83 100644 --- a/secure/usr.bin/openssl/man/ts.1 +++ b/secure/usr.bin/openssl/man/ts.1 @@ -129,24 +129,24 @@ .\" ======================================================================== .\" .IX Title "TS 1" -.TH TS 1 "2018-08-14" "1.0.2p" "OpenSSL" +.TH TS 1 "2018-09-11" "1.1.1" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -openssl\-ts, -ts \- Time Stamping Authority tool (client/server) +openssl\-ts, ts \- Time Stamping Authority tool (client/server) .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBopenssl\fR \fBts\fR \&\fB\-query\fR -[\fB\-rand\fR file:file...] +[\fB\-rand file...\fR] +[\fB\-writerand file\fR] [\fB\-config\fR configfile] [\fB\-data\fR file_to_hash] [\fB\-digest\fR digest_bytes] -[\fB\-md2\fR|\fB\-md4\fR|\fB\-md5\fR|\fB\-sha\fR|\fB\-sha1\fR|\fB\-mdc2\fR|\fB\-ripemd160\fR|\fB...\fR] -[\fB\-policy\fR object_id] +[\fB\-\f(BIdigest\fB\fR] +[\fB\-tspolicy\fR object_id] [\fB\-no_nonce\fR] [\fB\-cert\fR] [\fB\-in\fR request.tsq] @@ -160,9 +160,10 @@ ts \- Time Stamping Authority tool (client/server) [\fB\-queryfile\fR request.tsq] [\fB\-passin\fR password_src] [\fB\-signer\fR tsa_cert.pem] -[\fB\-inkey\fR private.pem] +[\fB\-inkey\fR file_or_id] +[\fB\-\f(BIdigest\fB\fR] [\fB\-chain\fR certs_file.pem] -[\fB\-policy\fR object_id] +[\fB\-tspolicy\fR object_id] [\fB\-in\fR response.tsr] [\fB\-token_in\fR] [\fB\-out\fR response.tsr] @@ -180,6 +181,38 @@ ts \- Time Stamping Authority tool (client/server) [\fB\-CApath\fR trusted_cert_path] [\fB\-CAfile\fR trusted_certs.pem] [\fB\-untrusted\fR cert_file.pem] +[\fIverify options\fR] +.PP +\&\fIverify options:\fR +[\-attime timestamp] +[\-check_ss_sig] +[\-crl_check] +[\-crl_check_all] +[\-explicit_policy] +[\-extended_crl] +[\-ignore_critical] +[\-inhibit_any] +[\-inhibit_map] +[\-issuer_checks] +[\-no_alt_chains] +[\-no_check_time] +[\-partial_chain] +[\-policy arg] +[\-policy_check] +[\-policy_print] +[\-purpose purpose] +[\-suiteB_128] +[\-suiteB_128_only] +[\-suiteB_192] +[\-trusted_first] +[\-use_deltas] +[\-auth_level num] +[\-verify_depth num] +[\-verify_email email] +[\-verify_hostname hostname] +[\-verify_ip ip] +[\-verify_name name] +[\-x509_strict] .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBts\fR command is a basic Time Stamping Authority (\s-1TSA\s0) client and server @@ -216,16 +249,22 @@ requests either by ftp or e\-mail. .IX Subsection "Time Stamp Request generation" The \fB\-query\fR switch can be used for creating and printing a time stamp request with the following options: -.IP "\fB\-rand\fR file:file..." 4 -.IX Item "-rand file:file..." -The files containing random data for seeding the random number -generator. Multiple files can be specified, the separator is \fB;\fR for -MS-Windows, \fB,\fR for \s-1VMS\s0 and \fB:\fR for all other platforms. (Optional) +.IP "\fB\-rand file...\fR" 4 +.IX Item "-rand file..." +A file or files containing random data used to seed the random number +generator. +Multiple files can be specified separated by an OS-dependent character. +The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for +all others. +.IP "[\fB\-writerand file\fR]" 4 +.IX Item "[-writerand file]" +Writes random data to the specified \fIfile\fR upon exit. +This can be used with a subsequent \fB\-rand\fR flag. .IP "\fB\-config\fR configfile" 4 .IX Item "-config configfile" -The configuration file to use, this option overrides the -\&\fB\s-1OPENSSL_CONF\s0\fR environment variable. Only the \s-1OID\s0 section -of the config file is used with the \fB\-query\fR command. (Optional) +The configuration file to use. +Optional; for a description of the default value, +see \*(L"\s-1COMMAND SUMMARY\*(R"\s0 in \fIopenssl\fR\|(1). .IP "\fB\-data\fR file_to_hash" 4 .IX Item "-data file_to_hash" The data file for which the time stamp request needs to be @@ -236,15 +275,15 @@ parameter is specified. (Optional) It is possible to specify the message imprint explicitly without the data file. The imprint must be specified in a hexadecimal format, two characters per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or -1AF601...). The number of bytes must match the message digest algorithm +1AF601...). The number of bytes must match the message digest algorithm in use. (Optional) -.IP "\fB\-md2\fR|\fB\-md4\fR|\fB\-md5\fR|\fB\-sha\fR|\fB\-sha1\fR|\fB\-mdc2\fR|\fB\-ripemd160\fR|\fB...\fR" 4 -.IX Item "-md2|-md4|-md5|-sha|-sha1|-mdc2|-ripemd160|..." -The message digest to apply to the data file, it supports all the message -digest algorithms that are supported by the openssl \fBdgst\fR command. +.IP "\fB\-\f(BIdigest\fB\fR" 4 +.IX Item "-digest" +The message digest to apply to the data file. +Any digest supported by the OpenSSL \fBdgst\fR command can be used. The default is \s-1SHA\-1.\s0 (Optional) -.IP "\fB\-policy\fR object_id" 4 -.IX Item "-policy object_id" +.IP "\fB\-tspolicy\fR object_id" 4 +.IX Item "-tspolicy object_id" The policy that the client expects the \s-1TSA\s0 to use for creating the time stamp token. Either the dotted \s-1OID\s0 notation or \s-1OID\s0 names defined in the config file can be used. If no policy is requested the \s-1TSA\s0 will @@ -264,7 +303,6 @@ response. (Optional) This option specifies a previously created time stamp request in \s-1DER\s0 format that will be printed into the output file. Useful when you need to examine the content of a request in human-readable -.Sp format. (Optional) .IP "\fB\-out\fR request.tsq" 4 .IX Item "-out request.tsq" @@ -285,12 +323,13 @@ specified the output is always a time stamp response (TimeStampResp), otherwise it is a time stamp token (ContentInfo). .IP "\fB\-config\fR configfile" 4 .IX Item "-config configfile" -The configuration file to use, this option overrides the -\&\fB\s-1OPENSSL_CONF\s0\fR environment variable. See \fB\s-1CONFIGURATION FILE -OPTIONS\s0\fR for configurable variables. (Optional) +The configuration file to use. +Optional; for a description of the default value, +see \*(L"\s-1COMMAND SUMMARY\*(R"\s0 in \fIopenssl\fR\|(1). +See \fB\s-1CONFIGURATION FILE OPTIONS\s0\fR for configurable variables. .IP "\fB\-section\fR tsa_section" 4 .IX Item "-section tsa_section" -The name of the config file section conatining the settings for the +The name of the config file section containing the settings for the response generation. If not specified the default \s-1TSA\s0 section is used, see \fB\s-1CONFIGURATION FILE OPTIONS\s0\fR for details. (Optional) .IP "\fB\-queryfile\fR request.tsq" 4 @@ -307,10 +346,16 @@ certificate must have exactly one extended key usage assigned to it: timeStamping. The extended key usage must also be critical, otherwise the certificate is going to be refused. Overrides the \fBsigner_cert\fR variable of the config file. (Optional) -.IP "\fB\-inkey\fR private.pem" 4 -.IX Item "-inkey private.pem" +.IP "\fB\-inkey\fR file_or_id" 4 +.IX Item "-inkey file_or_id" The signer private key of the \s-1TSA\s0 in \s-1PEM\s0 format. Overrides the \&\fBsigner_key\fR config file option. (Optional) +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. +.IP "\fB\-\f(BIdigest\fB\fR" 4 +.IX Item "-digest" +Signing digest to use. Overrides the \fBsigner_digest\fR config file +option. (Optional) .IP "\fB\-chain\fR certs_file.pem" 4 .IX Item "-chain certs_file.pem" The collection of certificates in \s-1PEM\s0 format that will all @@ -319,8 +364,8 @@ the \fB\-cert\fR option was used for the request. This file is supposed to contain the certificate chain for the signer certificate from its issuer upwards. The \fB\-reply\fR command does not build a certificate chain automatically. (Optional) -.IP "\fB\-policy\fR object_id" 4 -.IX Item "-policy object_id" +.IP "\fB\-tspolicy\fR object_id" 4 +.IX Item "-tspolicy object_id" The default policy to use for the response unless the client explicitly requires a particular \s-1TSA\s0 policy. The \s-1OID\s0 can be specified either in dotted notation or with its name. Overrides the @@ -366,7 +411,7 @@ data file. The \fB\-verify\fR command does not use the configuration file. .IP "\fB\-data\fR file_to_hash" 4 .IX Item "-data file_to_hash" The response or token must be verified against file_to_hash. The file -is hashed with the message digest algorithm specified in the token. +is hashed with the message digest algorithm specified in the token. The \fB\-digest\fR and \fB\-queryfile\fR options must not be specified with this one. (Optional) .IP "\fB\-digest\fR digest_bytes" 4 @@ -389,14 +434,14 @@ that the input is a \s-1DER\s0 encoded time stamp token (ContentInfo) instead of a time stamp response (TimeStampResp). (Optional) .IP "\fB\-CApath\fR trusted_cert_path" 4 .IX Item "-CApath trusted_cert_path" -The name of the directory containing the trused \s-1CA\s0 certificates of the +The name of the directory containing the trusted \s-1CA\s0 certificates of the client. See the similar option of \fIverify\fR\|(1) for additional details. Either this option or \fB\-CAfile\fR must be specified. (Optional) .IP "\fB\-CAfile\fR trusted_certs.pem" 4 .IX Item "-CAfile trusted_certs.pem" -The name of the file containing a set of trusted self-signed \s-1CA\s0 -certificates in \s-1PEM\s0 format. See the similar option of -\&\fIverify\fR\|(1) for additional details. Either this option +The name of the file containing a set of trusted self-signed \s-1CA\s0 +certificates in \s-1PEM\s0 format. See the similar option of +\&\fIverify\fR\|(1) for additional details. Either this option or \fB\-CApath\fR must be specified. (Optional) .IP "\fB\-untrusted\fR cert_file.pem" 4 @@ -406,10 +451,21 @@ needed when building the certificate chain for the \s-1TSA\s0's signing certificate. This file must contain the \s-1TSA\s0 signing certificate and all intermediate \s-1CA\s0 certificates unless the response includes them. (Optional) +.IP "\fIverify options\fR" 4 +.IX Item "verify options" +The options \fB\-attime timestamp\fR, \fB\-check_ss_sig\fR, \fB\-crl_check\fR, +\&\fB\-crl_check_all\fR, \fB\-explicit_policy\fR, \fB\-extended_crl\fR, \fB\-ignore_critical\fR, +\&\fB\-inhibit_any\fR, \fB\-inhibit_map\fR, \fB\-issuer_checks\fR, \fB\-no_alt_chains\fR, +\&\fB\-no_check_time\fR, \fB\-partial_chain\fR, \fB\-policy\fR, \fB\-policy_check\fR, +\&\fB\-policy_print\fR, \fB\-purpose\fR, \fB\-suiteB_128\fR, \fB\-suiteB_128_only\fR, +\&\fB\-suiteB_192\fR, \fB\-trusted_first\fR, \fB\-use_deltas\fR, \fB\-auth_level\fR, +\&\fB\-verify_depth\fR, \fB\-verify_email\fR, \fB\-verify_hostname\fR, \fB\-verify_ip\fR, +\&\fB\-verify_name\fR, and \fB\-x509_strict\fR can be used to control timestamp +verification. See \fIverify\fR\|(1). .SH "CONFIGURATION FILE OPTIONS" .IX Header "CONFIGURATION FILE OPTIONS" -The \fB\-query\fR and \fB\-reply\fR commands make use of a configuration file -defined by the \fB\s-1OPENSSL_CONF\s0\fR environment variable. See \fIconfig\fR\|(5) +The \fB\-query\fR and \fB\-reply\fR commands make use of a configuration file. +See \fIconfig\fR\|(5) for a general description of the syntax of the config file. The \&\fB\-query\fR command uses only the symbolic \s-1OID\s0 names section and it can work without it. However, the \fB\-reply\fR command needs the @@ -439,8 +495,8 @@ each response. If the file does not exist at the time of response generation a new file is created with serial number 1. (Mandatory) .IP "\fBcrypto_device\fR" 4 .IX Item "crypto_device" -Specifies the OpenSSL engine that will be set as the default for -all available algorithms. The default value is builtin, you can specify +Specifies the OpenSSL engine that will be set as the default for +all available algorithms. The default value is builtin, you can specify any other engines supported by OpenSSL (e.g. use chil for the NCipher \s-1HSM\s0). (Optional) .IP "\fBsigner_cert\fR" 4 @@ -456,10 +512,14 @@ option. (Optional) .IX Item "signer_key" The private key of the \s-1TSA\s0 in \s-1PEM\s0 format. The same as the \fB\-inkey\fR command line option. (Optional) +.IP "\fBsigner_digest\fR" 4 +.IX Item "signer_digest" +Signing digest to use. The same as the +\&\fB\-\f(BIdigest\fB\fR command line option. (Optional) .IP "\fBdefault_policy\fR" 4 .IX Item "default_policy" The default policy to use when the request does not mandate any -policy. The same as the \fB\-policy\fR command line option. (Optional) +policy. The same as the \fB\-tspolicy\fR command line option. (Optional) .IP "\fBother_policies\fR" 4 .IX Item "other_policies" Comma separated list of policies that are also acceptable by the \s-1TSA\s0 @@ -475,7 +535,7 @@ and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of the components is missing zero is assumed for that field. (Optional) .IP "\fBclock_precision_digits\fR" 4 .IX Item "clock_precision_digits" -Specifies the maximum number of digits, which represent the fraction of +Specifies the maximum number of digits, which represent the fraction of seconds, that need to be included in the time field. The trailing zeroes must be removed from the time, so there might actually be fewer digits, or no fraction of seconds at all. Supported only on \s-1UNIX\s0 platforms. @@ -500,18 +560,18 @@ is specified then the certificate identifiers of the chain will also be included in the SigningCertificate signed attribute. If this variable is set to no, only the signing certificate identifier is included. Default is no. (Optional) -.SH "ENVIRONMENT VARIABLES" -.IX Header "ENVIRONMENT VARIABLES" -\&\fB\s-1OPENSSL_CONF\s0\fR contains the path of the configuration file and can be -overridden by the \fB\-config\fR command line option. +.IP "\fBess_cert_id_alg\fR" 4 +.IX Item "ess_cert_id_alg" +This option specifies the hash function to be used to calculate the \s-1TSA\s0's +public key certificate identifier. Default is sha1. (Optional) .SH "EXAMPLES" .IX Header "EXAMPLES" All the examples below presume that \fB\s-1OPENSSL_CONF\s0\fR is set to a proper -configuration file, e.g. the example configuration file +configuration file, e.g. the example configuration file openssl/apps/openssl.cnf will do. .SS "Time Stamp Request" .IX Subsection "Time Stamp Request" -To create a time stamp request for design1.txt with \s-1SHA\-1\s0 +To create a time stamp request for design1.txt with \s-1SHA\-1\s0 without nonce and policy and no certificate is required in the response: .PP .Vb 2 @@ -533,23 +593,27 @@ To print the content of the previous request in human readable format: \& openssl ts \-query \-in design1.tsq \-text .Ve .PP -To create a time stamp request which includes the \s-1MD\-5\s0 digest +To create a time stamp request which includes the \s-1MD\-5\s0 digest of design2.txt, requests the signer certificate and nonce, specifies a policy id (assuming the tsa_policy1 name is defined in the \&\s-1OID\s0 section of the config file): .PP .Vb 2 \& openssl ts \-query \-data design2.txt \-md5 \e -\& \-policy tsa_policy1 \-cert \-out design2.tsq +\& \-tspolicy tsa_policy1 \-cert \-out design2.tsq .Ve .SS "Time Stamp Response" .IX Subsection "Time Stamp Response" Before generating a response a signing certificate must be created for the \s-1TSA\s0 that contains the \fBtimeStamping\fR critical extended key usage extension -without any other key usage extensions. You can add the -\&'extendedKeyUsage = critical,timeStamping' line to the user certificate section -of the config file to generate a proper certificate. See \fIreq\fR\|(1), -\&\fIca\fR\|(1), \fIx509\fR\|(1) for instructions. The examples +without any other key usage extensions. You can add this line to the +user certificate section of the config file to generate a proper certificate; +.PP +.Vb 1 +\& extendedKeyUsage = critical,timeStamping +.Ve +.PP +See \fIreq\fR\|(1), \fIca\fR\|(1), and \fIx509\fR\|(1) for instructions. The examples below assume that cacert.pem contains the certificate of the \s-1CA,\s0 tsacert.pem is the signing certificate issued by cacert.pem and tsakey.pem is the private key of the \s-1TSA.\s0 @@ -615,41 +679,44 @@ To verify a time stamp reply that includes the certificate chain: .PP To verify a time stamp token against the original data file: openssl ts \-verify \-data design2.txt \-in design2.tsr \e - \-CAfile cacert.pem + \-CAfile cacert.pem .PP To verify a time stamp token against a message imprint: openssl ts \-verify \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e - \-in design2.tsr \-CAfile cacert.pem + \-in design2.tsr \-CAfile cacert.pem .PP You could also look at the 'test' directory for more examples. .SH "BUGS" .IX Header "BUGS" -If you find any bugs or you have suggestions please write to -Zoltan Glozik <zglozik@opentsa.org>. Known issues: -.IP "\(bu" 4 +.IP "\(bu" 2 No support for time stamps over \s-1SMTP,\s0 though it is quite easy -to implement an automatic e\-mail based \s-1TSA\s0 with \fIprocmail\fR\|(1) -and \fIperl\fR\|(1). \s-1HTTP\s0 server support is provided in the form of +to implement an automatic e\-mail based \s-1TSA\s0 with \fIprocmail\fR\|(1) +and \fIperl\fR\|(1). \s-1HTTP\s0 server support is provided in the form of a separate apache module. \s-1HTTP\s0 client support is provided by \&\fItsget\fR\|(1). Pure \s-1TCP/IP\s0 protocol is not supported. -.IP "\(bu" 4 +.IP "\(bu" 2 The file containing the last serial number of the \s-1TSA\s0 is not locked when being read or written. This is a problem if more than one instance of \fIopenssl\fR\|(1) is trying to create a time stamp response at the same time. This is not an issue when using the apache server module, it does proper locking. -.IP "\(bu" 4 +.IP "\(bu" 2 Look for the \s-1FIXME\s0 word in the source files. -.IP "\(bu" 4 +.IP "\(bu" 2 The source code should really be reviewed by somebody else, too. -.IP "\(bu" 4 +.IP "\(bu" 2 More testing is needed, I have done only some basic tests (see test/testtsa). -.SH "AUTHOR" -.IX Header "AUTHOR" -Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fItsget\fR\|(1), \fIopenssl\fR\|(1), \fIreq\fR\|(1), -\&\fIx509\fR\|(1), \fIca\fR\|(1), \fIgenrsa\fR\|(1), +\&\fItsget\fR\|(1), \fIopenssl\fR\|(1), \fIreq\fR\|(1), +\&\fIx509\fR\|(1), \fIca\fR\|(1), \fIgenrsa\fR\|(1), \&\fIconfig\fR\|(5) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2006\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |