secure/usr.bin/openssl/man/ts.1

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "TS 1"
 132 .TH TS 1 "2017-05-25" "1.0.2l" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 ts \- Time Stamping Authority tool (client/server)
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 \&\fBopenssl\fR \fBts\fR
 142 \&\fB\-query\fR
 143 [\fB\-rand\fR file:file...]
 144 [\fB\-config\fR configfile]
 145 [\fB\-data\fR file_to_hash]
 146 [\fB\-digest\fR digest_bytes]
 147 [\fB\-md2\fR|\fB\-md4\fR|\fB\-md5\fR|\fB\-sha\fR|\fB\-sha1\fR|\fB\-mdc2\fR|\fB\-ripemd160\fR|\fB...\fR]
 148 [\fB\-policy\fR object_id]
 149 [\fB\-no_nonce\fR]
 150 [\fB\-cert\fR]
 151 [\fB\-in\fR request.tsq]
 152 [\fB\-out\fR request.tsq]
 153 [\fB\-text\fR]
 154 .PP
 155 \&\fBopenssl\fR \fBts\fR
 156 \&\fB\-reply\fR
 157 [\fB\-config\fR configfile]
 158 [\fB\-section\fR tsa_section]
 159 [\fB\-queryfile\fR request.tsq]
 160 [\fB\-passin\fR password_src]
 161 [\fB\-signer\fR tsa_cert.pem]
 162 [\fB\-inkey\fR private.pem]
 163 [\fB\-chain\fR certs_file.pem]
 164 [\fB\-policy\fR object_id]
 165 [\fB\-in\fR response.tsr]
 166 [\fB\-token_in\fR]
 167 [\fB\-out\fR response.tsr]
 168 [\fB\-token_out\fR]
 169 [\fB\-text\fR]
 170 [\fB\-engine\fR id]
 171 .PP
 172 \&\fBopenssl\fR \fBts\fR
 173 \&\fB\-verify\fR
 174 [\fB\-data\fR file_to_hash]
 175 [\fB\-digest\fR digest_bytes]
 176 [\fB\-queryfile\fR request.tsq]
 177 [\fB\-in\fR response.tsr]
 178 [\fB\-token_in\fR]
 179 [\fB\-CApath\fR trusted_cert_path]
 180 [\fB\-CAfile\fR trusted_certs.pem]
 181 [\fB\-untrusted\fR cert_file.pem]
 182 .SH "DESCRIPTION"
 183 .IX Header "DESCRIPTION"
 184 The \fBts\fR command is a basic Time Stamping Authority (\s-1TSA\s0) client and server
 185 application as specified in \s-1RFC 3161 \s0(Time-Stamp Protocol, \s-1TSP\s0). A
 186 \&\s-1TSA\s0 can be part of a \s-1PKI\s0 deployment and its role is to provide long
 187 term proof of the existence of a certain datum before a particular
 188 time. Here is a brief description of the protocol:
 189 .IP "1." 4
 190 The \s-1TSA\s0 client computes a one-way hash value for a data file and sends
 191 the hash to the \s-1TSA.\s0
 192 .IP "2." 4
 193 The \s-1TSA\s0 attaches the current date and time to the received hash value,
 194 signs them and sends the time stamp token back to the client. By
 195 creating this token the \s-1TSA\s0 certifies the existence of the original
 196 data file at the time of response generation.
 197 .IP "3." 4
 198 The \s-1TSA\s0 client receives the time stamp token and verifies the
 199 signature on it. It also checks if the token contains the same hash
 200 value that it had sent to the \s-1TSA.\s0
 201 .PP
 202 There is one \s-1DER\s0 encoded protocol data unit defined for transporting a time
 203 stamp request to the \s-1TSA\s0 and one for sending the time stamp response
 204 back to the client. The \fBts\fR command has three main functions:
 205 creating a time stamp request based on a data file,
 206 creating a time stamp response based on a request, verifying if a
 207 response corresponds to a particular request or a data file.
 208 .PP
 209 There is no support for sending the requests/responses automatically
 210 over \s-1HTTP\s0 or \s-1TCP\s0 yet as suggested in \s-1RFC 3161.\s0 The users must send the
 211 requests either by ftp or e\-mail.
 212 .SH "OPTIONS"
 213 .IX Header "OPTIONS"
 214 .SS "Time Stamp Request generation"
 215 .IX Subsection "Time Stamp Request generation"
 216 The \fB\-query\fR switch can be used for creating and printing a time stamp
 217 request with the following options:
 218 .IP "\fB\-rand\fR file:file..." 4
 219 .IX Item "-rand file:file..."
 220 The files containing random data for seeding the random number
 221 generator. Multiple files can be specified, the separator is \fB;\fR for
 222 MS-Windows, \fB,\fR for \s-1VMS\s0 and \fB:\fR for all other platforms. (Optional)
 223 .IP "\fB\-config\fR configfile" 4
 224 .IX Item "-config configfile"
 225 The configuration file to use, this option overrides the
 226 \&\fB\s-1OPENSSL_CONF\s0\fR environment variable. Only the \s-1OID\s0 section
 227 of the config file is used with the \fB\-query\fR command. (Optional)
 228 .IP "\fB\-data\fR file_to_hash" 4
 229 .IX Item "-data file_to_hash"
 230 The data file for which the time stamp request needs to be
 231 created. stdin is the default if neither the \fB\-data\fR nor the \fB\-digest\fR
 232 parameter is specified. (Optional)
 233 .IP "\fB\-digest\fR digest_bytes" 4
 234 .IX Item "-digest digest_bytes"
 235 It is possible to specify the message imprint explicitly without the data
 236 file. The imprint must be specified in a hexadecimal format, two characters
 237 per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
 238 1AF601...). The number of bytes must match the message digest algorithm
 239 in use. (Optional)
 240 .IP "\fB\-md2\fR|\fB\-md4\fR|\fB\-md5\fR|\fB\-sha\fR|\fB\-sha1\fR|\fB\-mdc2\fR|\fB\-ripemd160\fR|\fB...\fR" 4
 241 .IX Item "-md2|-md4|-md5|-sha|-sha1|-mdc2|-ripemd160|..."
 242 The message digest to apply to the data file, it supports all the message
 243 digest algorithms that are supported by the openssl \fBdgst\fR command.
 244 The default is \s-1SHA\-1. \s0(Optional)
 245 .IP "\fB\-policy\fR object_id" 4
 246 .IX Item "-policy object_id"
 247 The policy that the client expects the \s-1TSA\s0 to use for creating the
 248 time stamp token. Either the dotted \s-1OID\s0 notation or \s-1OID\s0 names defined
 249 in the config file can be used. If no policy is requested the \s-1TSA\s0 will
 250 use its own default policy. (Optional)
 251 .IP "\fB\-no_nonce\fR" 4
 252 .IX Item "-no_nonce"
 253 No nonce is specified in the request if this option is
 254 given. Otherwise a 64 bit long pseudo-random none is
 255 included in the request. It is recommended to use nonce to
 256 protect against replay-attacks. (Optional)
 257 .IP "\fB\-cert\fR" 4
 258 .IX Item "-cert"
 259 The \s-1TSA\s0 is expected to include its signing certificate in the
 260 response. (Optional)
 261 .IP "\fB\-in\fR request.tsq" 4
 262 .IX Item "-in request.tsq"
 263 This option specifies a previously created time stamp request in \s-1DER\s0
 264 format that will be printed into the output file. Useful when you need
 265 to examine the content of a request in human-readable
 266 .Sp
 267 format. (Optional)
 268 .IP "\fB\-out\fR request.tsq" 4
 269 .IX Item "-out request.tsq"
 270 Name of the output file to which the request will be written. Default
 271 is stdout. (Optional)
 272 .IP "\fB\-text\fR" 4
 273 .IX Item "-text"
 274 If this option is specified the output is human-readable text format
 275 instead of \s-1DER. \s0(Optional)
 276 .SS "Time Stamp Response generation"
 277 .IX Subsection "Time Stamp Response generation"
 278 A time stamp response (TimeStampResp) consists of a response status
 279 and the time stamp token itself (ContentInfo), if the token generation was
 280 successful. The \fB\-reply\fR command is for creating a time stamp
 281 response or time stamp token based on a request and printing the
 282 response/token in human-readable format. If \fB\-token_out\fR is not
 283 specified the output is always a time stamp response (TimeStampResp),
 284 otherwise it is a time stamp token (ContentInfo).
 285 .IP "\fB\-config\fR configfile" 4
 286 .IX Item "-config configfile"
 287 The configuration file to use, this option overrides the
 288 \&\fB\s-1OPENSSL_CONF\s0\fR environment variable. See \fB\s-1CONFIGURATION FILE
 289 OPTIONS\s0\fR for configurable variables. (Optional)
 290 .IP "\fB\-section\fR tsa_section" 4
 291 .IX Item "-section tsa_section"
 292 The name of the config file section conatining the settings for the
 293 response generation. If not specified the default \s-1TSA\s0 section is
 294 used, see \fB\s-1CONFIGURATION FILE OPTIONS\s0\fR for details. (Optional)
 295 .IP "\fB\-queryfile\fR request.tsq" 4
 296 .IX Item "-queryfile request.tsq"
 297 The name of the file containing a \s-1DER\s0 encoded time stamp request. (Optional)
 298 .IP "\fB\-passin\fR password_src" 4
 299 .IX Item "-passin password_src"
 300 Specifies the password source for the private key of the \s-1TSA.\s0 See
 301 \&\fB\s-1PASS PHRASE ARGUMENTS\s0\fR in \fIopenssl\fR\|(1). (Optional)
 302 .IP "\fB\-signer\fR tsa_cert.pem" 4
 303 .IX Item "-signer tsa_cert.pem"
 304 The signer certificate of the \s-1TSA\s0 in \s-1PEM\s0 format. The \s-1TSA\s0 signing
 305 certificate must have exactly one extended key usage assigned to it:
 306 timeStamping. The extended key usage must also be critical, otherwise
 307 the certificate is going to be refused. Overrides the \fBsigner_cert\fR
 308 variable of the config file. (Optional)
 309 .IP "\fB\-inkey\fR private.pem" 4
 310 .IX Item "-inkey private.pem"
 311 The signer private key of the \s-1TSA\s0 in \s-1PEM\s0 format. Overrides the
 312 \&\fBsigner_key\fR config file option. (Optional)
 313 .IP "\fB\-chain\fR certs_file.pem" 4
 314 .IX Item "-chain certs_file.pem"
 315 The collection of certificates in \s-1PEM\s0 format that will all
 316 be included in the response in addition to the signer certificate if
 317 the \fB\-cert\fR option was used for the request. This file is supposed to
 318 contain the certificate chain for the signer certificate from its
 319 issuer upwards. The \fB\-reply\fR command does not build a certificate
 320 chain automatically. (Optional)
 321 .IP "\fB\-policy\fR object_id" 4
 322 .IX Item "-policy object_id"
 323 The default policy to use for the response unless the client
 324 explicitly requires a particular \s-1TSA\s0 policy. The \s-1OID\s0 can be specified
 325 either in dotted notation or with its name. Overrides the
 326 \&\fBdefault_policy\fR config file option. (Optional)
 327 .IP "\fB\-in\fR response.tsr" 4
 328 .IX Item "-in response.tsr"
 329 Specifies a previously created time stamp response or time stamp token
 330 (if \fB\-token_in\fR is also specified) in \s-1DER\s0 format that will be written
 331 to the output file. This option does not require a request, it is
 332 useful e.g. when you need to examine the content of a response or
 333 token or you want to extract the time stamp token from a response. If
 334 the input is a token and the output is a time stamp response a default
 335 \&'granted' status info is added to the token. (Optional)
 336 .IP "\fB\-token_in\fR" 4
 337 .IX Item "-token_in"
 338 This flag can be used together with the \fB\-in\fR option and indicates
 339 that the input is a \s-1DER\s0 encoded time stamp token (ContentInfo) instead
 340 of a time stamp response (TimeStampResp). (Optional)
 341 .IP "\fB\-out\fR response.tsr" 4
 342 .IX Item "-out response.tsr"
 343 The response is written to this file. The format and content of the
 344 file depends on other options (see \fB\-text\fR, \fB\-token_out\fR). The default is
 345 stdout. (Optional)
 346 .IP "\fB\-token_out\fR" 4
 347 .IX Item "-token_out"
 348 The output is a time stamp token (ContentInfo) instead of time stamp
 349 response (TimeStampResp). (Optional)
 350 .IP "\fB\-text\fR" 4
 351 .IX Item "-text"
 352 If this option is specified the output is human-readable text format
 353 instead of \s-1DER. \s0(Optional)
 354 .IP "\fB\-engine\fR id" 4
 355 .IX Item "-engine id"
 356 Specifying an engine (by its unique \fBid\fR string) will cause \fBts\fR
 357 to attempt to obtain a functional reference to the specified engine,
 358 thus initialising it if needed. The engine will then be set as the default
 359 for all available algorithms. Default is builtin. (Optional)
 360 .SS "Time Stamp Response verification"
 361 .IX Subsection "Time Stamp Response verification"
 362 The \fB\-verify\fR command is for verifying if a time stamp response or time
 363 stamp token is valid and matches a particular time stamp request or
 364 data file. The \fB\-verify\fR command does not use the configuration file.
 365 .IP "\fB\-data\fR file_to_hash" 4
 366 .IX Item "-data file_to_hash"
 367 The response or token must be verified against file_to_hash. The file
 368 is hashed with the message digest algorithm specified in the token.
 369 The \fB\-digest\fR and \fB\-queryfile\fR options must not be specified with this one.
 370 (Optional)
 371 .IP "\fB\-digest\fR digest_bytes" 4
 372 .IX Item "-digest digest_bytes"
 373 The response or token must be verified against the message digest specified
 374 with this option. The number of bytes must match the message digest algorithm
 375 specified in the token. The \fB\-data\fR and \fB\-queryfile\fR options must not be
 376 specified with this one. (Optional)
 377 .IP "\fB\-queryfile\fR request.tsq" 4
 378 .IX Item "-queryfile request.tsq"
 379 The original time stamp request in \s-1DER\s0 format. The \fB\-data\fR and \fB\-digest\fR
 380 options must not be specified with this one. (Optional)
 381 .IP "\fB\-in\fR response.tsr" 4
 382 .IX Item "-in response.tsr"
 383 The time stamp response that needs to be verified in \s-1DER\s0 format. (Mandatory)
 384 .IP "\fB\-token_in\fR" 4
 385 .IX Item "-token_in"
 386 This flag can be used together with the \fB\-in\fR option and indicates
 387 that the input is a \s-1DER\s0 encoded time stamp token (ContentInfo) instead
 388 of a time stamp response (TimeStampResp). (Optional)
 389 .IP "\fB\-CApath\fR trusted_cert_path" 4
 390 .IX Item "-CApath trusted_cert_path"
 391 The name of the directory containing the trused \s-1CA\s0 certificates of the
 392 client. See the similar option of \fIverify\fR\|(1) for additional
 393 details. Either this option or \fB\-CAfile\fR must be specified. (Optional)
 394 .IP "\fB\-CAfile\fR trusted_certs.pem" 4
 395 .IX Item "-CAfile trusted_certs.pem"
 396 The name of the file containing a set of trusted self-signed \s-1CA \s0
 397 certificates in \s-1PEM\s0 format. See the similar option of
 398 \&\fIverify\fR\|(1) for additional details. Either this option
 399 or \fB\-CApath\fR must be specified.
 400 (Optional)
 401 .IP "\fB\-untrusted\fR cert_file.pem" 4
 402 .IX Item "-untrusted cert_file.pem"
 403 Set of additional untrusted certificates in \s-1PEM\s0 format which may be
 404 needed when building the certificate chain for the \s-1TSA\s0's signing
 405 certificate. This file must contain the \s-1TSA\s0 signing certificate and
 406 all intermediate \s-1CA\s0 certificates unless the response includes them.
 407 (Optional)
 408 .SH "CONFIGURATION FILE OPTIONS"
 409 .IX Header "CONFIGURATION FILE OPTIONS"
 410 The \fB\-query\fR and \fB\-reply\fR commands make use of a configuration file
 411 defined by the \fB\s-1OPENSSL_CONF\s0\fR environment variable. See \fIconfig\fR\|(5)
 412 for a general description of the syntax of the config file. The
 413 \&\fB\-query\fR command uses only the symbolic \s-1OID\s0 names section
 414 and it can work without it. However, the \fB\-reply\fR command needs the
 415 config file for its operation.
 416 .PP
 417 When there is a command line switch equivalent of a variable the
 418 switch always overrides the settings in the config file.
 419 .IP "\fBtsa\fR section, \fBdefault_tsa\fR" 4
 420 .IX Item "tsa section, default_tsa"
 421 This is the main section and it specifies the name of another section
 422 that contains all the options for the \fB\-reply\fR command. This default
 423 section can be overridden with the \fB\-section\fR command line switch. (Optional)
 424 .IP "\fBoid_file\fR" 4
 425 .IX Item "oid_file"
 426 See \fIca\fR\|(1) for description. (Optional)
 427 .IP "\fBoid_section\fR" 4
 428 .IX Item "oid_section"
 429 See \fIca\fR\|(1) for description. (Optional)
 430 .IP "\fB\s-1RANDFILE\s0\fR" 4
 431 .IX Item "RANDFILE"
 432 See \fIca\fR\|(1) for description. (Optional)
 433 .IP "\fBserial\fR" 4
 434 .IX Item "serial"
 435 The name of the file containing the hexadecimal serial number of the
 436 last time stamp response created. This number is incremented by 1 for
 437 each response. If the file does not exist at the time of response
 438 generation a new file is created with serial number 1. (Mandatory)
 439 .IP "\fBcrypto_device\fR" 4
 440 .IX Item "crypto_device"
 441 Specifies the OpenSSL engine that will be set as the default for
 442 all available algorithms. The default value is builtin, you can specify
 443 any other engines supported by OpenSSL (e.g. use chil for the NCipher \s-1HSM\s0).
 444 (Optional)
 445 .IP "\fBsigner_cert\fR" 4
 446 .IX Item "signer_cert"
 447 \&\s-1TSA\s0 signing certificate in \s-1PEM\s0 format. The same as the \fB\-signer\fR
 448 command line option. (Optional)
 449 .IP "\fBcerts\fR" 4
 450 .IX Item "certs"
 451 A file containing a set of \s-1PEM\s0 encoded certificates that need to be
 452 included in the response. The same as the \fB\-chain\fR command line
 453 option. (Optional)
 454 .IP "\fBsigner_key\fR" 4
 455 .IX Item "signer_key"
 456 The private key of the \s-1TSA\s0 in \s-1PEM\s0 format. The same as the \fB\-inkey\fR
 457 command line option. (Optional)
 458 .IP "\fBdefault_policy\fR" 4
 459 .IX Item "default_policy"
 460 The default policy to use when the request does not mandate any
 461 policy. The same as the \fB\-policy\fR command line option. (Optional)
 462 .IP "\fBother_policies\fR" 4
 463 .IX Item "other_policies"
 464 Comma separated list of policies that are also acceptable by the \s-1TSA\s0
 465 and used only if the request explicitly specifies one of them. (Optional)
 466 .IP "\fBdigests\fR" 4
 467 .IX Item "digests"
 468 The list of message digest algorithms that the \s-1TSA\s0 accepts. At least
 469 one algorithm must be specified. (Mandatory)
 470 .IP "\fBaccuracy\fR" 4
 471 .IX Item "accuracy"
 472 The accuracy of the time source of the \s-1TSA\s0 in seconds, milliseconds
 473 and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
 474 the components is missing zero is assumed for that field. (Optional)
 475 .IP "\fBclock_precision_digits\fR" 4
 476 .IX Item "clock_precision_digits"
 477 Specifies the maximum number of digits, which represent the fraction of
 478 seconds, that  need to be included in the time field. The trailing zeroes
 479 must be removed from the time, so there might actually be fewer digits,
 480 or no fraction of seconds at all. Supported only on \s-1UNIX\s0 platforms.
 481 The maximum value is 6, default is 0.
 482 (Optional)
 483 .IP "\fBordering\fR" 4
 484 .IX Item "ordering"
 485 If this option is yes the responses generated by this \s-1TSA\s0 can always
 486 be ordered, even if the time difference between two responses is less
 487 than the sum of their accuracies. Default is no. (Optional)
 488 .IP "\fBtsa_name\fR" 4
 489 .IX Item "tsa_name"
 490 Set this option to yes if the subject name of the \s-1TSA\s0 must be included in
 491 the \s-1TSA\s0 name field of the response. Default is no. (Optional)
 492 .IP "\fBess_cert_id_chain\fR" 4
 493 .IX Item "ess_cert_id_chain"
 494 The SignedData objects created by the \s-1TSA\s0 always contain the
 495 certificate identifier of the signing certificate in a signed
 496 attribute (see \s-1RFC 2634,\s0 Enhanced Security Services). If this option
 497 is set to yes and either the \fBcerts\fR variable or the \fB\-chain\fR option
 498 is specified then the certificate identifiers of the chain will also
 499 be included in the SigningCertificate signed attribute. If this
 500 variable is set to no, only the signing certificate identifier is
 501 included. Default is no. (Optional)
 502 .SH "ENVIRONMENT VARIABLES"
 503 .IX Header "ENVIRONMENT VARIABLES"
 504 \&\fB\s-1OPENSSL_CONF\s0\fR contains the path of the configuration file and can be
 505 overridden by the \fB\-config\fR command line option.
 506 .SH "EXAMPLES"
 507 .IX Header "EXAMPLES"
 508 All the examples below presume that \fB\s-1OPENSSL_CONF\s0\fR is set to a proper
 509 configuration file, e.g. the example configuration file
 510 openssl/apps/openssl.cnf will do.
 511 .SS "Time Stamp Request"
 512 .IX Subsection "Time Stamp Request"
 513 To create a time stamp request for design1.txt with \s-1SHA\-1 \s0
 514 without nonce and policy and no certificate is required in the response:
 515 .PP
 516 .Vb 2
 517 \&  openssl ts \-query \-data design1.txt \-no_nonce \e
 518 \&        \-out design1.tsq
 519 .Ve
 520 .PP
 521 To create a similar time stamp request with specifying the message imprint
 522 explicitly:
 523 .PP
 524 .Vb 2
 525 \&  openssl ts \-query \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
 526 \&         \-no_nonce \-out design1.tsq
 527 .Ve
 528 .PP
 529 To print the content of the previous request in human readable format:
 530 .PP
 531 .Vb 1
 532 \&  openssl ts \-query \-in design1.tsq \-text
 533 .Ve
 534 .PP
 535 To create a time stamp request which includes the \s-1MD\-5\s0 digest
 536 of design2.txt, requests the signer certificate and nonce,
 537 specifies a policy id (assuming the tsa_policy1 name is defined in the
 538 \&\s-1OID\s0 section of the config file):
 539 .PP
 540 .Vb 2
 541 \&  openssl ts \-query \-data design2.txt \-md5 \e
 542 \&        \-policy tsa_policy1 \-cert \-out design2.tsq
 543 .Ve
 544 .SS "Time Stamp Response"
 545 .IX Subsection "Time Stamp Response"
 546 Before generating a response a signing certificate must be created for
 547 the \s-1TSA\s0 that contains the \fBtimeStamping\fR critical extended key usage extension
 548 without any other key usage extensions. You can add the
 549 \&'extendedKeyUsage = critical,timeStamping' line to the user certificate section
 550 of the config file to generate a proper certificate. See \fIreq\fR\|(1),
 551 \&\fIca\fR\|(1), \fIx509\fR\|(1) for instructions. The examples
 552 below assume that cacert.pem contains the certificate of the \s-1CA,\s0
 553 tsacert.pem is the signing certificate issued by cacert.pem and
 554 tsakey.pem is the private key of the \s-1TSA.\s0
 555 .PP
 556 To create a time stamp response for a request:
 557 .PP
 558 .Vb 2
 559 \&  openssl ts \-reply \-queryfile design1.tsq \-inkey tsakey.pem \e
 560 \&        \-signer tsacert.pem \-out design1.tsr
 561 .Ve
 562 .PP
 563 If you want to use the settings in the config file you could just write:
 564 .PP
 565 .Vb 1
 566 \&  openssl ts \-reply \-queryfile design1.tsq \-out design1.tsr
 567 .Ve
 568 .PP
 569 To print a time stamp reply to stdout in human readable format:
 570 .PP
 571 .Vb 1
 572 \&  openssl ts \-reply \-in design1.tsr \-text
 573 .Ve
 574 .PP
 575 To create a time stamp token instead of time stamp response:
 576 .PP
 577 .Vb 1
 578 \&  openssl ts \-reply \-queryfile design1.tsq \-out design1_token.der \-token_out
 579 .Ve
 580 .PP
 581 To print a time stamp token to stdout in human readable format:
 582 .PP
 583 .Vb 1
 584 \&  openssl ts \-reply \-in design1_token.der \-token_in \-text \-token_out
 585 .Ve
 586 .PP
 587 To extract the time stamp token from a response:
 588 .PP
 589 .Vb 1
 590 \&  openssl ts \-reply \-in design1.tsr \-out design1_token.der \-token_out
 591 .Ve
 592 .PP
 593 To add 'granted' status info to a time stamp token thereby creating a
 594 valid response:
 595 .PP
 596 .Vb 1
 597 \&  openssl ts \-reply \-in design1_token.der \-token_in \-out design1.tsr
 598 .Ve
 599 .SS "Time Stamp Verification"
 600 .IX Subsection "Time Stamp Verification"
 601 To verify a time stamp reply against a request:
 602 .PP
 603 .Vb 2
 604 \&  openssl ts \-verify \-queryfile design1.tsq \-in design1.tsr \e
 605 \&        \-CAfile cacert.pem \-untrusted tsacert.pem
 606 .Ve
 607 .PP
 608 To verify a time stamp reply that includes the certificate chain:
 609 .PP
 610 .Vb 2
 611 \&  openssl ts \-verify \-queryfile design2.tsq \-in design2.tsr \e
 612 \&        \-CAfile cacert.pem
 613 .Ve
 614 .PP
 615 To verify a time stamp token against the original data file:
 616   openssl ts \-verify \-data design2.txt \-in design2.tsr \e
 617         \-CAfile cacert.pem
 618 .PP
 619 To verify a time stamp token against a message imprint:
 620   openssl ts \-verify \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
 621          \-in design2.tsr \-CAfile cacert.pem
 622 .PP
 623 You could also look at the 'test' directory for more examples.
 624 .SH "BUGS"
 625 .IX Header "BUGS"
 626 If you find any bugs or you have suggestions please write to
 627 Zoltan Glozik <zglozik@opentsa.org>. Known issues:
 628 .IP "\(bu" 4
 629 No support for time stamps over \s-1SMTP,\s0 though it is quite easy
 630 to implement an automatic e\-mail based \s-1TSA\s0 with \fIprocmail\fR\|(1)
 631 and \fIperl\fR\|(1). \s-1HTTP\s0 server support is provided in the form of
 632 a separate apache module. \s-1HTTP\s0 client support is provided by
 633 \&\fItsget\fR\|(1). Pure \s-1TCP/IP\s0 protocol is not supported.
 634 .IP "\(bu" 4
 635 The file containing the last serial number of the \s-1TSA\s0 is not
 636 locked when being read or written. This is a problem if more than one
 637 instance of \fIopenssl\fR\|(1) is trying to create a time stamp
 638 response at the same time. This is not an issue when using the apache
 639 server module, it does proper locking.
 640 .IP "\(bu" 4
 641 Look for the \s-1FIXME\s0 word in the source files.
 642 .IP "\(bu" 4
 643 The source code should really be reviewed by somebody else, too.
 644 .IP "\(bu" 4
 645 More testing is needed, I have done only some basic tests (see
 646 test/testtsa).
 647 .SH "AUTHOR"
 648 .IX Header "AUTHOR"
 649 Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
 650 .SH "SEE ALSO"
 651 .IX Header "SEE ALSO"
 652 \&\fItsget\fR\|(1), \fIopenssl\fR\|(1), \fIreq\fR\|(1),
 653 \&\fIx509\fR\|(1), \fIca\fR\|(1), \fIgenrsa\fR\|(1),
 654 \&\fIconfig\fR\|(5)