720 lines
29 KiB
Groff
Executable File
720 lines
29 KiB
Groff
Executable File
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.ie \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.el \{\
|
|
. de IX
|
|
..
|
|
.\}
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "OPENSSL-TS 1"
|
|
.TH OPENSSL-TS 1 "2020-03-02" "3.0.0-dev" "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 \- Time Stamping Authority tool (client/server)
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
\&\fBopenssl\fR \fBts\fR
|
|
\&\fB\-help\fR
|
|
.PP
|
|
\&\fBopenssl\fR \fBts\fR
|
|
\&\fB\-query\fR
|
|
[\fB\-config\fR \fIconfigfile\fR]
|
|
[\fB\-data\fR \fIfile_to_hash\fR]
|
|
[\fB\-digest\fR \fIdigest_bytes\fR]
|
|
[\fB\-\f(BIdigest\fB\fR]
|
|
[\fB\-tspolicy\fR \fIobject_id\fR]
|
|
[\fB\-no_nonce\fR]
|
|
[\fB\-cert\fR]
|
|
[\fB\-in\fR \fIrequest.tsq\fR]
|
|
[\fB\-out\fR \fIrequest.tsq\fR]
|
|
[\fB\-text\fR]
|
|
[\fB\-rand\fR \fIfiles\fR]
|
|
[\fB\-writerand\fR \fIfile\fR]
|
|
.PP
|
|
\&\fBopenssl\fR \fBts\fR
|
|
\&\fB\-reply\fR
|
|
[\fB\-config\fR \fIconfigfile\fR]
|
|
[\fB\-section\fR \fItsa_section\fR]
|
|
[\fB\-queryfile\fR \fIrequest.tsq\fR]
|
|
[\fB\-passin\fR \fIpassword_src\fR]
|
|
[\fB\-signer\fR \fItsa_cert.pem\fR]
|
|
[\fB\-inkey\fR \fIfile_or_id\fR]
|
|
[\fB\-\f(BIdigest\fB\fR]
|
|
[\fB\-chain\fR \fIcerts_file.pem\fR]
|
|
[\fB\-tspolicy\fR \fIobject_id\fR]
|
|
[\fB\-in\fR \fIresponse.tsr\fR]
|
|
[\fB\-untrusted\fR \fIfile\fR]
|
|
[\fB\-token_in\fR]
|
|
[\fB\-out\fR \fIresponse.tsr\fR]
|
|
[\fB\-token_out\fR]
|
|
[\fB\-text\fR]
|
|
[\fB\-engine\fR \fIid\fR]
|
|
.PP
|
|
\&\fBopenssl\fR \fBts\fR
|
|
\&\fB\-verify\fR
|
|
[\fB\-data\fR \fIfile_to_hash\fR]
|
|
[\fB\-digest\fR \fIdigest_bytes\fR]
|
|
[\fB\-queryfile\fR \fIrequest.tsq\fR]
|
|
[\fB\-in\fR \fIresponse.tsr\fR]
|
|
[\fB\-token_in\fR]
|
|
[\fB\-CAfile\fR \fIfile\fR]
|
|
[\fB\-CApath\fR \fIdir\fR]
|
|
[\fB\-CAstore\fR \fIuri\fR]
|
|
[\fB\-allow_proxy_certs\fR]
|
|
[\fB\-attime\fR \fItimestamp\fR]
|
|
[\fB\-no_check_time\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\-partial_chain\fR]
|
|
[\fB\-policy\fR \fIarg\fR]
|
|
[\fB\-policy_check\fR]
|
|
[\fB\-policy_print\fR]
|
|
[\fB\-purpose\fR \fIpurpose\fR]
|
|
[\fB\-suiteB_128\fR]
|
|
[\fB\-suiteB_128_only\fR]
|
|
[\fB\-suiteB_192\fR]
|
|
[\fB\-trusted_first\fR]
|
|
[\fB\-no_alt_chains\fR]
|
|
[\fB\-use_deltas\fR]
|
|
[\fB\-auth_level\fR \fInum\fR]
|
|
[\fB\-verify_depth\fR \fInum\fR]
|
|
[\fB\-verify_email\fR \fIemail\fR]
|
|
[\fB\-verify_hostname\fR \fIhostname\fR]
|
|
[\fB\-verify_ip\fR \fIip\fR]
|
|
[\fB\-verify_name\fR \fIname\fR]
|
|
[\fB\-x509_strict\fR]
|
|
[\fB\-issuer_checks\fR]
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
This command is a basic Time Stamping Authority (\s-1TSA\s0) client and
|
|
server application as specified in \s-1RFC\s0 3161 (Time-Stamp Protocol, \s-1TSP\s0). A
|
|
\&\s-1TSA\s0 can be part of a \s-1PKI\s0 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:
|
|
.IP "1." 4
|
|
The \s-1TSA\s0 client computes a one-way hash value for a data file and sends
|
|
the hash to the \s-1TSA\s0.
|
|
.IP "2." 4
|
|
The \s-1TSA\s0 attaches the current date and time to the received hash value,
|
|
signs them and sends the timestamp token back to the client. By
|
|
creating this token the \s-1TSA\s0 certifies the existence of the original
|
|
data file at the time of response generation.
|
|
.IP "3." 4
|
|
The \s-1TSA\s0 client receives the timestamp token and verifies the
|
|
signature on it. It also checks if the token contains the same hash
|
|
value that it had sent to the \s-1TSA\s0.
|
|
.PP
|
|
There is one \s-1DER\s0 encoded protocol data unit defined for transporting a time
|
|
stamp request to the \s-1TSA\s0 and one for sending the timestamp response
|
|
back to the client. This command has three main functions:
|
|
creating a timestamp request based on a data file,
|
|
creating a timestamp response based on a request, verifying if a
|
|
response corresponds to a particular request or a data file.
|
|
.PP
|
|
There is no support for sending the requests/responses automatically
|
|
over \s-1HTTP\s0 or \s-1TCP\s0 yet as suggested in \s-1RFC\s0 3161. The users must send the
|
|
requests either by ftp or e\-mail.
|
|
.SH "OPTIONS"
|
|
.IX Header "OPTIONS"
|
|
.IP "\fB\-help\fR" 4
|
|
.IX Item "-help"
|
|
Print out a usage message.
|
|
.SS "Timestamp Request generation"
|
|
.IX Subsection "Timestamp Request generation"
|
|
The \fB\-query\fR switch can be used for creating and printing a timestamp
|
|
request with the following options:
|
|
.IP "\fB\-config\fR \fIconfigfile\fR" 4
|
|
.IX Item "-config configfile"
|
|
The configuration file to use.
|
|
Optional; for a description of the default value,
|
|
see \*(L"\s-1COMMAND\s0 \s-1SUMMARY\s0\*(R" in \fIopenssl\fR\|(1).
|
|
.IP "\fB\-data\fR \fIfile_to_hash\fR" 4
|
|
.IX Item "-data file_to_hash"
|
|
The data file for which the timestamp request needs to be
|
|
created. stdin is the default if neither the \fB\-data\fR nor the \fB\-digest\fR
|
|
parameter is specified. (Optional)
|
|
.IP "\fB\-digest\fR \fIdigest_bytes\fR" 4
|
|
.IX Item "-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)
|
|
.IP "\fB\-\f(BIdigest\fB\fR" 4
|
|
.IX Item "-digest"
|
|
The message digest to apply to the data file.
|
|
Any digest supported by the \fIopenssl\-dgst\fR\|(1) command can be used.
|
|
The default is \s-1SHA\-256\s0. (Optional)
|
|
.IP "\fB\-tspolicy\fR \fIobject_id\fR" 4
|
|
.IX Item "-tspolicy object_id"
|
|
The policy that the client expects the \s-1TSA\s0 to use for creating the
|
|
timestamp 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
|
|
use its own default policy. (Optional)
|
|
.IP "\fB\-no_nonce\fR" 4
|
|
.IX Item "-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)
|
|
.IP "\fB\-cert\fR" 4
|
|
.IX Item "-cert"
|
|
The \s-1TSA\s0 is expected to include its signing certificate in the
|
|
response. (Optional)
|
|
.IP "\fB\-in\fR \fIrequest.tsq\fR" 4
|
|
.IX Item "-in request.tsq"
|
|
This option specifies a previously created timestamp 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
|
|
format. (Optional)
|
|
.IP "\fB\-out\fR \fIrequest.tsq\fR" 4
|
|
.IX Item "-out request.tsq"
|
|
Name of the output file to which the request will be written. Default
|
|
is stdout. (Optional)
|
|
.IP "\fB\-text\fR" 4
|
|
.IX Item "-text"
|
|
If this option is specified the output is human-readable text format
|
|
instead of \s-1DER\s0. (Optional)
|
|
.IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4
|
|
.IX Item "-rand files, -writerand file"
|
|
See \*(L"Random State Options\*(R" in \fIopenssl\fR\|(1) for details.
|
|
.SS "Timestamp Response generation"
|
|
.IX Subsection "Timestamp Response generation"
|
|
A timestamp response (TimeStampResp) consists of a response status
|
|
and the timestamp token itself (ContentInfo), if the token generation was
|
|
successful. The \fB\-reply\fR command is for creating a timestamp
|
|
response or timestamp token based on a request and printing the
|
|
response/token in human-readable format. If \fB\-token_out\fR is not
|
|
specified the output is always a timestamp response (TimeStampResp),
|
|
otherwise it is a timestamp token (ContentInfo).
|
|
.IP "\fB\-config\fR \fIconfigfile\fR" 4
|
|
.IX Item "-config configfile"
|
|
The configuration file to use.
|
|
Optional; for a description of the default value,
|
|
see \*(L"\s-1COMMAND\s0 \s-1SUMMARY\s0\*(R" in \fIopenssl\fR\|(1).
|
|
See \*(L"\s-1CONFIGURATION\s0 \s-1FILE\s0 \s-1OPTIONS\s0\*(R" for configurable variables.
|
|
.IP "\fB\-section\fR \fItsa_section\fR" 4
|
|
.IX Item "-section tsa_section"
|
|
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 \*(L"\s-1CONFIGURATION\s0 \s-1FILE\s0 \s-1OPTIONS\s0\*(R" for details. (Optional)
|
|
.IP "\fB\-queryfile\fR \fIrequest.tsq\fR" 4
|
|
.IX Item "-queryfile request.tsq"
|
|
The name of the file containing a \s-1DER\s0 encoded timestamp request. (Optional)
|
|
.IP "\fB\-passin\fR \fIpassword_src\fR" 4
|
|
.IX Item "-passin password_src"
|
|
Specifies the password source for the private key of the \s-1TSA\s0. See
|
|
description in \fIopenssl\fR\|(1). (Optional)
|
|
.IP "\fB\-signer\fR \fItsa_cert.pem\fR" 4
|
|
.IX Item "-signer tsa_cert.pem"
|
|
The signer certificate of the \s-1TSA\s0 in \s-1PEM\s0 format. The \s-1TSA\s0 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 \fBsigner_cert\fR
|
|
variable of the config file. (Optional)
|
|
.IP "\fB\-inkey\fR \fIfile_or_id\fR" 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. (Mandatory unless specified in the config file)
|
|
.IP "\fB\-chain\fR \fIcerts_file.pem\fR" 4
|
|
.IX Item "-chain certs_file.pem"
|
|
The collection of certificates in \s-1PEM\s0 format that will all
|
|
be included in the response in addition to the signer certificate if
|
|
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\-tspolicy\fR \fIobject_id\fR" 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
|
|
\&\fBdefault_policy\fR config file option. (Optional)
|
|
.IP "\fB\-in\fR \fIresponse.tsr\fR" 4
|
|
.IX Item "-in response.tsr"
|
|
Specifies a previously created timestamp response or timestamp token
|
|
(if \fB\-token_in\fR is also specified) in \s-1DER\s0 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 timestamp token from a response. If
|
|
the input is a token and the output is a timestamp response a default
|
|
\&'granted' status info is added to the token. (Optional)
|
|
.IP "\fB\-token_in\fR" 4
|
|
.IX Item "-token_in"
|
|
This flag can be used together with the \fB\-in\fR option and indicates
|
|
that the input is a \s-1DER\s0 encoded timestamp token (ContentInfo) instead
|
|
of a timestamp response (TimeStampResp). (Optional)
|
|
.IP "\fB\-out\fR \fIresponse.tsr\fR" 4
|
|
.IX Item "-out response.tsr"
|
|
The response is written to this file. The format and content of the
|
|
file depends on other options (see \fB\-text\fR, \fB\-token_out\fR). The default is
|
|
stdout. (Optional)
|
|
.IP "\fB\-token_out\fR" 4
|
|
.IX Item "-token_out"
|
|
The output is a timestamp token (ContentInfo) instead of timestamp
|
|
response (TimeStampResp). (Optional)
|
|
.IP "\fB\-text\fR" 4
|
|
.IX Item "-text"
|
|
If this option is specified the output is human-readable text format
|
|
instead of \s-1DER\s0. (Optional)
|
|
.IP "\fB\-engine\fR \fIid\fR" 4
|
|
.IX Item "-engine id"
|
|
See \*(L"Engine Options\*(R" in \fIopenssl\fR\|(1).
|
|
.SS "Timestamp Response verification"
|
|
.IX Subsection "Timestamp Response verification"
|
|
The \fB\-verify\fR command is for verifying if a timestamp response or time
|
|
stamp token is valid and matches a particular timestamp request or
|
|
data file. The \fB\-verify\fR command does not use the configuration file.
|
|
.IP "\fB\-data\fR \fIfile_to_hash\fR" 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.
|
|
The \fB\-digest\fR and \fB\-queryfile\fR options must not be specified with this one.
|
|
(Optional)
|
|
.IP "\fB\-digest\fR \fIdigest_bytes\fR" 4
|
|
.IX Item "-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 \fB\-data\fR and \fB\-queryfile\fR options must not be
|
|
specified with this one. (Optional)
|
|
.IP "\fB\-queryfile\fR \fIrequest.tsq\fR" 4
|
|
.IX Item "-queryfile request.tsq"
|
|
The original timestamp request in \s-1DER\s0 format. The \fB\-data\fR and \fB\-digest\fR
|
|
options must not be specified with this one. (Optional)
|
|
.IP "\fB\-in\fR \fIresponse.tsr\fR" 4
|
|
.IX Item "-in response.tsr"
|
|
The timestamp response that needs to be verified in \s-1DER\s0 format. (Mandatory)
|
|
.IP "\fB\-token_in\fR" 4
|
|
.IX Item "-token_in"
|
|
This flag can be used together with the \fB\-in\fR option and indicates
|
|
that the input is a \s-1DER\s0 encoded timestamp token (ContentInfo) instead
|
|
of a timestamp response (TimeStampResp). (Optional)
|
|
.IP "\fB\-untrusted\fR \fIcert_file.pem\fR" 4
|
|
.IX Item "-untrusted cert_file.pem"
|
|
Set of additional untrusted certificates in \s-1PEM\s0 format which may be
|
|
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 "\fB\-CAfile\fR \fIfile\fR, \fB\-CApath\fR \fIdir\fR, \fB\-CAstore\fR \fIuri\fR" 4
|
|
.IX Item "-CAfile file, -CApath dir, -CAstore uri"
|
|
See \*(L"Trusted Certificate Options\*(R" in \fIopenssl\fR\|(1) for details.
|
|
At least one of \fB\-CApath\fR, \fB\-CAfile\fR or \fB\-CAstore\fR must be specified.
|
|
.IP "\fB\-allow_proxy_certs\fR, \fB\-attime\fR, \fB\-no_check_time\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\-no_alt_chains\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, \fB\-x509_strict\fR \fB\-issuer_checks\fR" 4
|
|
.IX Item "-allow_proxy_certs, -attime, -no_check_time, -check_ss_sig, -crl_check, -crl_check_all, -explicit_policy, -extended_crl, -ignore_critical, -inhibit_any, -inhibit_map, -no_alt_chains, -partial_chain, -policy, -policy_check, -policy_print, -purpose, -suiteB_128, -suiteB_128_only, -suiteB_192, -trusted_first, -use_deltas, -auth_level, -verify_depth, -verify_email, -verify_hostname, -verify_ip, -verify_name, -x509_strict -issuer_checks"
|
|
Set various options of certificate chain verification.
|
|
See \*(L"Verification Options\*(R" in \fIopenssl\fR\|(1) for details.
|
|
.Sp
|
|
Any verification errors cause the command to exit.
|
|
.SH "CONFIGURATION FILE OPTIONS"
|
|
.IX Header "CONFIGURATION FILE OPTIONS"
|
|
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
|
|
config file for its operation.
|
|
.PP
|
|
When there is a command line switch equivalent of a variable the
|
|
switch always overrides the settings in the config file.
|
|
.IP "\fBtsa\fR section, \fBdefault_tsa\fR" 4
|
|
.IX Item "tsa section, default_tsa"
|
|
This is the main section and it specifies the name of another section
|
|
that contains all the options for the \fB\-reply\fR command. This default
|
|
section can be overridden with the \fB\-section\fR command line switch. (Optional)
|
|
.IP "\fBoid_file\fR" 4
|
|
.IX Item "oid_file"
|
|
This specifies a file containing additional \fB\s-1OBJECT\s0 \s-1IDENTIFIERS\s0\fR.
|
|
Each line of the file should consist of the numerical form of the
|
|
object identifier followed by white space then the short name followed
|
|
by white space and finally the long name. (Optional)
|
|
.IP "\fBoid_section\fR" 4
|
|
.IX Item "oid_section"
|
|
This specifies a section in the configuration file containing extra
|
|
object identifiers. Each line should consist of the short name of the
|
|
object identifier followed by \fB=\fR and the numerical form. The short
|
|
and long names are the same when this option is used. (Optional)
|
|
.IP "\fB\s-1RANDFILE\s0\fR" 4
|
|
.IX Item "RANDFILE"
|
|
At startup the specified file is loaded into the random number generator,
|
|
and at exit 256 bytes will be written to it. (Note: Using a \s-1RANDFILE\s0 is
|
|
not necessary anymore, see the \*(L"\s-1HISTORY\s0\*(R" section.
|
|
.IP "\fBserial\fR" 4
|
|
.IX Item "serial"
|
|
The name of the file containing the hexadecimal serial number of the
|
|
last timestamp 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)
|
|
.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 built-in, 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
|
|
.IX Item "signer_cert"
|
|
\&\s-1TSA\s0 signing certificate in \s-1PEM\s0 format. The same as the \fB\-signer\fR
|
|
command line option. (Optional)
|
|
.IP "\fBcerts\fR" 4
|
|
.IX Item "certs"
|
|
A file containing a set of \s-1PEM\s0 encoded certificates that need to be
|
|
included in the response. The same as the \fB\-chain\fR command line
|
|
option. (Optional)
|
|
.IP "\fBsigner_key\fR" 4
|
|
.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. (Mandatory unless specified on the command
|
|
line)
|
|
.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\-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
|
|
and used only if the request explicitly specifies one of them. (Optional)
|
|
.IP "\fBdigests\fR" 4
|
|
.IX Item "digests"
|
|
The list of message digest algorithms that the \s-1TSA\s0 accepts. At least
|
|
one algorithm must be specified. (Mandatory)
|
|
.IP "\fBaccuracy\fR" 4
|
|
.IX Item "accuracy"
|
|
The accuracy of the time source of the \s-1TSA\s0 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)
|
|
.IP "\fBclock_precision_digits\fR" 4
|
|
.IX Item "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 zeros
|
|
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.
|
|
The maximum value is 6, default is 0.
|
|
(Optional)
|
|
.IP "\fBordering\fR" 4
|
|
.IX Item "ordering"
|
|
If this option is yes the responses generated by this \s-1TSA\s0 can always
|
|
be ordered, even if the time difference between two responses is less
|
|
than the sum of their accuracies. Default is no. (Optional)
|
|
.IP "\fBtsa_name\fR" 4
|
|
.IX Item "tsa_name"
|
|
Set this option to yes if the subject name of the \s-1TSA\s0 must be included in
|
|
the \s-1TSA\s0 name field of the response. Default is no. (Optional)
|
|
.IP "\fBess_cert_id_chain\fR" 4
|
|
.IX Item "ess_cert_id_chain"
|
|
The SignedData objects created by the \s-1TSA\s0 always contain the
|
|
certificate identifier of the signing certificate in a signed
|
|
attribute (see \s-1RFC\s0 2634, Enhanced Security Services). If this option
|
|
is set to yes and either the \fBcerts\fR variable or the \fB\-chain\fR 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)
|
|
.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 sha256. (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
|
|
\&\fIopenssl/apps/openssl.cnf\fR will do.
|
|
.SS "Timestamp Request"
|
|
.IX Subsection "Timestamp Request"
|
|
To create a timestamp request for \fIdesign1.txt\fR with \s-1SHA\-256\s0 digest,
|
|
without nonce and policy, and without requirement for a certificate
|
|
in the response:
|
|
.PP
|
|
.Vb 2
|
|
\& openssl ts \-query \-data design1.txt \-no_nonce \e
|
|
\& \-out design1.tsq
|
|
.Ve
|
|
.PP
|
|
To create a similar timestamp request with specifying the message imprint
|
|
explicitly:
|
|
.PP
|
|
.Vb 2
|
|
\& openssl ts \-query \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
|
|
\& \-no_nonce \-out design1.tsq
|
|
.Ve
|
|
.PP
|
|
To print the content of the previous request in human readable format:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl ts \-query \-in design1.tsq \-text
|
|
.Ve
|
|
.PP
|
|
To create a timestamp request which includes the \s-1SHA\-512\s0 digest
|
|
of \fIdesign2.txt\fR, requests the signer certificate and nonce, and
|
|
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 \-sha512 \e
|
|
\& \-tspolicy tsa_policy1 \-cert \-out design2.tsq
|
|
.Ve
|
|
.SS "Timestamp Response"
|
|
.IX Subsection "Timestamp 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 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 \fIopenssl\-req\fR\|(1), \fIopenssl\-ca\fR\|(1), and \fIopenssl\-x509\fR\|(1) for
|
|
instructions. The examples below assume that \fIcacert.pem\fR contains the
|
|
certificate of the \s-1CA\s0, \fItsacert.pem\fR is the signing certificate issued
|
|
by \fIcacert.pem\fR and \fItsakey.pem\fR is the private key of the \s-1TSA\s0.
|
|
.PP
|
|
To create a timestamp response for a request:
|
|
.PP
|
|
.Vb 2
|
|
\& openssl ts \-reply \-queryfile design1.tsq \-inkey tsakey.pem \e
|
|
\& \-signer tsacert.pem \-out design1.tsr
|
|
.Ve
|
|
.PP
|
|
If you want to use the settings in the config file you could just write:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl ts \-reply \-queryfile design1.tsq \-out design1.tsr
|
|
.Ve
|
|
.PP
|
|
To print a timestamp reply to stdout in human readable format:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl ts \-reply \-in design1.tsr \-text
|
|
.Ve
|
|
.PP
|
|
To create a timestamp token instead of timestamp response:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl ts \-reply \-queryfile design1.tsq \-out design1_token.der \-token_out
|
|
.Ve
|
|
.PP
|
|
To print a timestamp token to stdout in human readable format:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl ts \-reply \-in design1_token.der \-token_in \-text \-token_out
|
|
.Ve
|
|
.PP
|
|
To extract the timestamp token from a response:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl ts \-reply \-in design1.tsr \-out design1_token.der \-token_out
|
|
.Ve
|
|
.PP
|
|
To add 'granted' status info to a timestamp token thereby creating a
|
|
valid response:
|
|
.PP
|
|
.Vb 1
|
|
\& openssl ts \-reply \-in design1_token.der \-token_in \-out design1.tsr
|
|
.Ve
|
|
.SS "Timestamp Verification"
|
|
.IX Subsection "Timestamp Verification"
|
|
To verify a timestamp reply against a request:
|
|
.PP
|
|
.Vb 2
|
|
\& openssl ts \-verify \-queryfile design1.tsq \-in design1.tsr \e
|
|
\& \-CAfile cacert.pem \-untrusted tsacert.pem
|
|
.Ve
|
|
.PP
|
|
To verify a timestamp reply that includes the certificate chain:
|
|
.PP
|
|
.Vb 2
|
|
\& openssl ts \-verify \-queryfile design2.tsq \-in design2.tsr \e
|
|
\& \-CAfile cacert.pem
|
|
.Ve
|
|
.PP
|
|
To verify a timestamp token against the original data file:
|
|
openssl ts \-verify \-data design2.txt \-in design2.tsr \e
|
|
\-CAfile cacert.pem
|
|
.PP
|
|
To verify a timestamp token against a message imprint:
|
|
openssl ts \-verify \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
|
|
\-in design2.tsr \-CAfile cacert.pem
|
|
.PP
|
|
You could also look at the 'test' directory for more examples.
|
|
.SH "BUGS"
|
|
.IX Header "BUGS"
|
|
.IP "\(bu" 2
|
|
No support for timestamps 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
|
|
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" 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 timestamp
|
|
response at the same time. This is not an issue when using the apache
|
|
server module, it does proper locking.
|
|
.IP "\(bu" 2
|
|
Look for the \s-1FIXME\s0 word in the source files.
|
|
.IP "\(bu" 2
|
|
The source code should really be reviewed by somebody else, too.
|
|
.IP "\(bu" 2
|
|
More testing is needed, I have done only some basic tests (see
|
|
test/testtsa).
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
OpenSSL 1.1.1 introduced a new random generator (\s-1CSPRNG\s0) with an improved
|
|
seeding mechanism. The new seeding mechanism makes it unnecessary to
|
|
define a \s-1RANDFILE\s0 for saving and restoring randomness. This option is
|
|
retained mainly for compatibility reasons.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fIopenssl\fR\|(1),
|
|
\&\fItsget\fR\|(1),
|
|
\&\fIopenssl\-req\fR\|(1),
|
|
\&\fIopenssl\-x509\fR\|(1),
|
|
\&\fIopenssl\-ca\fR\|(1),
|
|
\&\fIopenssl\-genrsa\fR\|(1),
|
|
\&\fIconfig\fR\|(5),
|
|
\&\fIossl_store\-file\fR\|(7)
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2006\-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the Apache License 2.0 (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>.
|