You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
594 lines
19 KiB
594 lines
19 KiB
=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 overridden 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 |
|
overridden 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
|
|
|