123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594 |
- =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
|