diff options
Diffstat (limited to 'openssl/doc/apps/ts.pod')
| -rw-r--r-- | openssl/doc/apps/ts.pod | 594 |
1 files changed, 594 insertions, 0 deletions
diff --git a/openssl/doc/apps/ts.pod b/openssl/doc/apps/ts.pod new file mode 100644 index 000000000..7fb6caa96 --- /dev/null +++ b/openssl/doc/apps/ts.pod @@ -0,0 +1,594 @@ +=pod + +=head1 NAME + +ts - Time Stamping Authority tool (client/server) + +=head1 SYNOPSIS + +B<openssl> B<ts> +B<-query> +[B<-rand> file:file...] +[B<-config> configfile] +[B<-data> file_to_hash] +[B<-digest> digest_bytes] +[B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>] +[B<-policy> object_id] +[B<-no_nonce>] +[B<-cert>] +[B<-in> request.tsq] +[B<-out> request.tsq] +[B<-text>] + +B<openssl> B<ts> +B<-reply> +[B<-config> configfile] +[B<-section> tsa_section] +[B<-queryfile> request.tsq] +[B<-passin> password_src] +[B<-signer> tsa_cert.pem] +[B<-inkey> private.pem] +[B<-chain> certs_file.pem] +[B<-policy> object_id] +[B<-in> response.tsr] +[B<-token_in>] +[B<-out> response.tsr] +[B<-token_out>] +[B<-text>] +[B<-engine> id] + +B<openssl> B<ts> +B<-verify> +[B<-data> file_to_hash] +[B<-digest> digest_bytes] +[B<-queryfile> request.tsq] +[B<-in> response.tsr] +[B<-token_in>] +[B<-CApath> trusted_cert_path] +[B<-CAfile> trusted_certs.pem] +[B<-untrusted> cert_file.pem] + +=head1 DESCRIPTION + +The B<ts> command is a basic Time Stamping Authority (TSA) client and server +application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A +TSA can be part of a PKI deployment and its role is to provide long +term proof of the existence of a certain datum before a particular +time. Here is a brief description of the protocol: + +=over 4 + +=item 1. + +The TSA client computes a one-way hash value for a data file and sends +the hash to the TSA. + +=item 2. + +The TSA attaches the current date and time to the received hash value, +signs them and sends the time stamp token back to the client. By +creating this token the TSA certifies the existence of the original +data file at the time of response generation. + +=item 3. + +The TSA client receives the time stamp token and verifies the +signature on it. It also checks if the token contains the same hash +value that it had sent to the TSA. + +=back + +There is one DER encoded protocol data unit defined for transporting a time +stamp request to the TSA and one for sending the time stamp response +back to the client. The B<ts> command has three main functions: +creating a time stamp request based on a data file, +creating a time stamp response based on a request, verifying if a +response corresponds to a particular request or a data file. + +There is no support for sending the requests/responses automatically +over HTTP or TCP yet as suggested in RFC 3161. The users must send the +requests either by ftp or e-mail. + +=head1 OPTIONS + +=head2 Time Stamp Request generation + +The B<-query> switch can be used for creating and printing a time stamp +request with the following options: + +=over 4 + +=item B<-rand> file:file... + +The files containing random data for seeding the random number +generator. Multiple files can be specified, the separator is B<;> for +MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) + +=item B<-config> configfile + +The configuration file to use, this option overrides the +B<OPENSSL_CONF> environment variable. Only the OID section +of the config file is used with the B<-query> command. (Optional) + +=item B<-data> file_to_hash + +The data file for which the time stamp request needs to be +created. stdin is the default if neither the B<-data> nor the B<-digest> +parameter is specified. (Optional) + +=item B<-digest> digest_bytes + +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 +in use. (Optional) + +=item B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...> + +The message digest to apply to the data file, it supports all the message +digest algorithms that are supported by the openssl B<dgst> command. +The default is SHA-1. (Optional) + +=item B<-policy> object_id + +The policy that the client expects the TSA to use for creating the +time stamp token. Either the dotted OID notation or OID names defined +in the config file can be used. If no policy is requested the TSA will +use its own default policy. (Optional) + +=item B<-no_nonce> + +No nonce is specified in the request if this option is +given. Otherwise a 64 bit long pseudo-random none is +included in the request. It is recommended to use nonce to +protect against replay-attacks. (Optional) + +=item B<-cert> + +The TSA is expected to include its signing certificate in the +response. (Optional) + +=item B<-in> request.tsq + +This option specifies a previously created time stamp request in DER +format that will be printed into the output file. Useful when you need +to examine the content of a request in human-readable + +format. (Optional) + +=item B<-out> request.tsq + +Name of the output file to which the request will be written. Default +is stdout. (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=back + +=head2 Time Stamp Response generation + +A time stamp response (TimeStampResp) consists of a response status +and the time stamp token itself (ContentInfo), if the token generation was +successful. The B<-reply> command is for creating a time stamp +response or time stamp token based on a request and printing the +response/token in human-readable format. If B<-token_out> is not +specified the output is always a time stamp response (TimeStampResp), +otherwise it is a time stamp token (ContentInfo). + +=over 4 + +=item B<-config> configfile + +The configuration file to use, this option overrides the +B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE +OPTIONS> for configurable variables. (Optional) + +=item B<-section> tsa_section + +The name of the config file section conatining the settings for the +response generation. If not specified the default TSA section is +used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional) + +=item B<-queryfile> request.tsq + +The name of the file containing a DER encoded time stamp request. (Optional) + +=item B<-passin> password_src + +Specifies the password source for the private key of the TSA. See +B<PASS PHRASE ARGUMENTS> in L<openssl(1)|openssl(1)>. (Optional) + +=item B<-signer> tsa_cert.pem + +The signer certificate of the TSA in PEM format. The TSA signing +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 B<signer_cert> +variable of the config file. (Optional) + +=item B<-inkey> private.pem + +The signer private key of the TSA in PEM format. Overrides the +B<signer_key> config file option. (Optional) + +=item B<-chain> certs_file.pem + +The collection of certificates in PEM format that will all +be included in the response in addition to the signer certificate if +the B<-cert> option was used for the request. This file is supposed to +contain the certificate chain for the signer certificate from its +issuer upwards. The B<-reply> command does not build a certificate +chain automatically. (Optional) + +=item B<-policy> object_id + +The default policy to use for the response unless the client +explicitly requires a particular TSA policy. The OID can be specified +either in dotted notation or with its name. Overrides the +B<default_policy> config file option. (Optional) + +=item B<-in> response.tsr + +Specifies a previously created time stamp response or time stamp token +(if B<-token_in> is also specified) in DER format that will be written +to the output file. This option does not require a request, it is +useful e.g. when you need to examine the content of a response or +token or you want to extract the time stamp token from a response. If +the input is a token and the output is a time stamp response a default +'granted' status info is added to the token. (Optional) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-out> response.tsr + +The response is written to this file. The format and content of the +file depends on other options (see B<-text>, B<-token_out>). The default is +stdout. (Optional) + +=item B<-token_out> + +The output is a time stamp token (ContentInfo) instead of time stamp +response (TimeStampResp). (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=item B<-engine> id + +Specifying an engine (by its unique B<id> string) will cause B<ts> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. Default is builtin. (Optional) + +=back + +=head2 Time Stamp Response verification + +The B<-verify> command is for verifying if a time stamp response or time +stamp token is valid and matches a particular time stamp request or +data file. The B<-verify> command does not use the configuration file. + +=over 4 + +=item B<-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. +The B<-digest> and B<-queryfile> options must not be specified with this one. +(Optional) + +=item B<-digest> digest_bytes + +The response or token must be verified against the message digest specified +with this option. The number of bytes must match the message digest algorithm +specified in the token. The B<-data> and B<-queryfile> options must not be +specified with this one. (Optional) + +=item B<-queryfile> request.tsq + +The original time stamp request in DER format. The B<-data> and B<-digest> +options must not be specified with this one. (Optional) + +=item B<-in> response.tsr + +The time stamp response that needs to be verified in DER format. (Mandatory) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-CApath> trusted_cert_path + +The name of the directory containing the trused CA certificates of the +client. See the similar option of L<verify(1)|verify(1)> for additional +details. Either this option or B<-CAfile> must be specified. (Optional) + + +=item B<-CAfile> trusted_certs.pem + +The name of the file containing a set of trusted self-signed CA +certificates in PEM format. See the similar option of +L<verify(1)|verify(1)> for additional details. Either this option +or B<-CApath> must be specified. +(Optional) + +=item B<-untrusted> cert_file.pem + +Set of additional untrusted certificates in PEM format which may be +needed when building the certificate chain for the TSA's signing +certificate. This file must contain the TSA signing certificate and +all intermediate CA certificates unless the response includes them. +(Optional) + +=back + +=head1 CONFIGURATION FILE OPTIONS + +The B<-query> and B<-reply> commands make use of a configuration file +defined by the B<OPENSSL_CONF> environment variable. See L<config(5)|config(5)> +for a general description of the syntax of the config file. The +B<-query> command uses only the symbolic OID names section +and it can work without it. However, the B<-reply> command needs the +config file for its operation. + +When there is a command line switch equivalent of a variable the +switch always overrides the settings in the config file. + +=over 4 + +=item B<tsa> section, B<default_tsa> + +This is the main section and it specifies the name of another section +that contains all the options for the B<-reply> command. This default +section can be overriden with the B<-section> command line switch. (Optional) + +=item B<oid_file> + +See L<ca(1)|ca(1)> for description. (Optional) + +=item B<oid_section> + +See L<ca(1)|ca(1)> for description. (Optional) + +=item B<RANDFILE> + +See L<ca(1)|ca(1)> for description. (Optional) + +=item B<serial> + +The name of the file containing the hexadecimal serial number of the +last time stamp response created. This number is incremented by 1 for +each response. If the file does not exist at the time of response +generation a new file is created with serial number 1. (Mandatory) + +=item B<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 +any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM). +(Optional) + +=item B<signer_cert> + +TSA signing certificate in PEM format. The same as the B<-signer> +command line option. (Optional) + +=item B<certs> + +A file containing a set of PEM encoded certificates that need to be +included in the response. The same as the B<-chain> command line +option. (Optional) + +=item B<signer_key> + +The private key of the TSA in PEM format. The same as the B<-inkey> +command line option. (Optional) + +=item B<default_policy> + +The default policy to use when the request does not mandate any +policy. The same as the B<-policy> command line option. (Optional) + +=item B<other_policies> + +Comma separated list of policies that are also acceptable by the TSA +and used only if the request explicitly specifies one of them. (Optional) + +=item B<digests> + +The list of message digest algorithms that the TSA accepts. At least +one algorithm must be specified. (Mandatory) + +=item B<accuracy> + +The accuracy of the time source of the TSA in seconds, milliseconds +and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of +the components is missing zero is assumed for that field. (Optional) + +=item B<clock_precision_digits> + +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 UNIX platforms. +The maximum value is 6, default is 0. +(Optional) + +=item B<ordering> + +If this option is yes the responses generated by this TSA can always +be ordered, even if the time difference between two responses is less +than the sum of their accuracies. Default is no. (Optional) + +=item B<tsa_name> + +Set this option to yes if the subject name of the TSA must be included in +the TSA name field of the response. Default is no. (Optional) + +=item B<ess_cert_id_chain> + +The SignedData objects created by the TSA always contain the +certificate identifier of the signing certificate in a signed +attribute (see RFC 2634, Enhanced Security Services). If this option +is set to yes and either the B<certs> variable or the B<-chain> option +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) + +=back + +=head1 ENVIRONMENT VARIABLES + +B<OPENSSL_CONF> contains the path of the configuration file and can be +overriden by the B<-config> command line option. + +=head1 EXAMPLES + +All the examples below presume that B<OPENSSL_CONF> is set to a proper +configuration file, e.g. the example configuration file +openssl/apps/openssl.cnf will do. + +=head2 Time Stamp Request + +To create a time stamp request for design1.txt with SHA-1 +without nonce and policy and no certificate is required in the response: + + openssl ts -query -data design1.txt -no_nonce \ + -out design1.tsq + +To create a similar time stamp request with specifying the message imprint +explicitly: + + openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -no_nonce -out design1.tsq + +To print the content of the previous request in human readable format: + + openssl ts -query -in design1.tsq -text + +To create a time stamp request which includes the MD-5 digest +of design2.txt, requests the signer certificate and nonce, +specifies a policy id (assuming the tsa_policy1 name is defined in the +OID section of the config file): + + openssl ts -query -data design2.txt -md5 \ + -policy tsa_policy1 -cert -out design2.tsq + +=head2 Time Stamp Response + +Before generating a response a signing certificate must be created for +the TSA that contains the B<timeStamping> 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 L<req(1)|req(1)>, +L<ca(1)|ca(1)>, L<x509(1)|x509(1)> for instructions. The examples +below assume that cacert.pem contains the certificate of the CA, +tsacert.pem is the signing certificate issued by cacert.pem and +tsakey.pem is the private key of the TSA. + +To create a time stamp response for a request: + + openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \ + -signer tsacert.pem -out design1.tsr + +If you want to use the settings in the config file you could just write: + + openssl ts -reply -queryfile design1.tsq -out design1.tsr + +To print a time stamp reply to stdout in human readable format: + + openssl ts -reply -in design1.tsr -text + +To create a time stamp token instead of time stamp response: + + openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out + +To print a time stamp token to stdout in human readable format: + + openssl ts -reply -in design1_token.der -token_in -text -token_out + +To extract the time stamp token from a response: + + openssl ts -reply -in design1.tsr -out design1_token.der -token_out + +To add 'granted' status info to a time stamp token thereby creating a +valid response: + + openssl ts -reply -in design1_token.der -token_in -out design1.tsr + +=head2 Time Stamp Verification + +To verify a time stamp reply against a request: + + openssl ts -verify -queryfile design1.tsq -in design1.tsr \ + -CAfile cacert.pem -untrusted tsacert.pem + +To verify a time stamp reply that includes the certificate chain: + + openssl ts -verify -queryfile design2.tsq -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against the original data file: + openssl ts -verify -data design2.txt -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against a message imprint: + openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -in design2.tsr -CAfile cacert.pem + +You could also look at the 'test' directory for more examples. + +=head1 BUGS + +If you find any bugs or you have suggestions please write to +Zoltan Glozik <zglozik@opentsa.org>. Known issues: + +=over 4 + +=item * No support for time stamps over SMTP, though it is quite easy +to implement an automatic e-mail based TSA with L<procmail(1)|procmail(1)> +and L<perl(1)|perl(1)>. HTTP server support is provided in the form of +a separate apache module. HTTP client support is provided by +L<tsget(1)|tsget(1)>. Pure TCP/IP protocol is not supported. + +=item * The file containing the last serial number of the TSA is not +locked when being read or written. This is a problem if more than one +instance of L<openssl(1)|openssl(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. + +=item * Look for the FIXME word in the source files. + +=item * The source code should really be reviewed by somebody else, too. + +=item * More testing is needed, I have done only some basic tests (see +test/testtsa). + +=back + +=cut + +=head1 AUTHOR + +Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) + +=head1 SEE ALSO + +L<tsget(1)|tsget(1)>, L<openssl(1)|openssl(1)>, L<req(1)|req(1)>, +L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, +L<config(5)|config(5)> + +=cut |