From 497e295047a93876a573d3833770ea89a9373008 Mon Sep 17 00:00:00 2001
From: jmc <>
Date: Fri, 15 Oct 2010 18:17:10 +0000
Subject: document "openssl ts";

---
 src/usr.sbin/openssl/openssl.1 | 633 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 629 insertions(+), 4 deletions(-)

diff --git a/src/usr.sbin/openssl/openssl.1 b/src/usr.sbin/openssl/openssl.1
index 015adda638..9934bb6a10 100644
--- a/src/usr.sbin/openssl/openssl.1
+++ b/src/usr.sbin/openssl/openssl.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: openssl.1,v 1.79 2010/10/14 20:41:28 jmc Exp $
+.\" $OpenBSD: openssl.1,v 1.80 2010/10/15 18:17:10 jmc Exp $
 .\" ====================================================================
 .\" Copyright (c) 1998-2002 The OpenSSL Project.  All rights reserved.
 .\"
@@ -112,7 +112,7 @@
 .\"
 .\" OPENSSL
 .\"
-.Dd $Mdocdate: October 14 2010 $
+.Dd $Mdocdate: October 15 2010 $
 .Dt OPENSSL 1
 .Os
 .Sh NAME
@@ -365,6 +365,8 @@ S/MIME mail processing.
 Algorithm speed measurement.
 .It Cm spkac
 SPKAC printing and generating utility.
+.It Cm ts
+Time stamping authority tool (client/server).
 .It Cm verify
 X.509 certificate verification.
 .It Cm version
@@ -5193,8 +5195,12 @@ Print out text version of parameters:
 $ openssl pkeyparam -in param.pem -text
 .Ed
 .Sh PKEYPARAM NOTES
-There are no B<-inform> or B<-outform> options for this command because only
-PEM format is supported because the key type is determined by the PEM headers.
+There are no
+.Fl inform
+or
+.Fl outform
+options for this command because only PEM format is supported
+because the key type is determined by the PEM headers.
 .\"
 .\" PKEYUTL
 .\"
@@ -8266,6 +8272,625 @@ Run
 benchmarks in parallel.
 .El
 .\"
+.\" TS
+.\"
+.Sh TS
+.nr nS 1
+.Nm "openssl ts"
+.Bk -words
+.Fl query
+.Op Fl md4 | md5 | ripemd160 | sha | sha1
+.Op Fl cert
+.Op Fl no_nonce
+.Op Fl text
+.Op Fl config Ar configfile
+.Op Fl data Ar file_to_hash
+.Op Fl digest Ar digest_bytes
+.Op Fl in Ar request.tsq
+.Op Fl out Ar request.tsq
+.Op Fl policy Ar object_id
+.Op Fl rand Ar file : Ns Ar file
+.Ek
+.nr nS 0
+.Pp
+.nr nS 1
+.Nm "openssl ts"
+.Bk -words
+.Fl reply
+.Op Fl text
+.Op Fl token_in
+.Op Fl token_out
+.Op Fl chain Ar certs_file.pem
+.Op Fl config Ar configfile
+.Op Fl engine Ar id
+.Op Fl in Ar response.tsr
+.Op Fl inkey Ar private.pem
+.Op Fl out Ar response.tsr
+.Op Fl passin Ar password_src
+.Op Fl policy Ar object_id
+.Op Fl queryfile Ar request.tsq
+.Op Fl section Ar tsa_section
+.Op Fl signer Ar tsa_cert.pem
+.Ek
+.nr nS 0
+.Pp
+.nr nS 1
+.Nm "openssl ts"
+.Bk -words
+.Fl verify
+.Op Fl token_in
+.Op Fl CAfile Ar trusted_certs.pem
+.Op Fl CApath Ar trusted_cert_path
+.Op Fl data Ar file_to_hash
+.Op Fl digest Ar digest_bytes
+.Op Fl in Ar response.tsr
+.Op Fl queryfile Ar request.tsq
+.Op Fl untrusted Ar cert_file.pem
+.Ek
+.nr nS 0
+.Pp
+The
+.Nm 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:
+.Bl -enum
+.It
+The TSA client computes a one-way hash value for a data file and sends
+the hash to the TSA.
+.It
+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.
+.It
+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.
+.El
+.Pp
+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
+.Nm 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;
+and 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 HTTP or TCP yet as suggested in RFC 3161.
+Users must send the requests either by FTP or email.
+.Pp
+The
+.Fl query
+switch can be used for creating and printing a time stamp
+request with the following options:
+.Bl -tag -width Ds
+.It Fl cert
+The TSA is expected to include its signing certificate in the
+response.
+.It Fl config Ar configfile
+The configuration file to use.
+This option overrides the
+.Ev OPENSSL_CONF
+environment variable.
+Only the OID section of the config file is used with the
+.Fl query
+command.
+.It Fl data Ar file_to_hash
+The data file for which the time stamp request needs to be created.
+stdin is the default if neither the
+.Fl data
+nor the
+.Fl digest
+option is specified.
+.It Fl digest Ar 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.
+.It Fl in Ar 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.
+.It Fl md4|md5|ripemd160|sha|sha1
+The message digest to apply to the data file.
+It supports all the message digest algorithms that are supported by the
+.Nm dgst
+command.
+The default is SHA-1.
+.It Fl 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.
+.It Fl out Ar request.tsq
+Name of the output file to which the request will be written.
+The default is stdout.
+.It Fl policy Ar 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.
+.It Fl rand Ar file : Ns Ar file
+The files containing random data for seeding the random number generator.
+Multiple files can be specified.
+The separator is
+.Sq \&;
+for MS-Windows;
+.Sq \&,
+for VMS; and
+.Sq \&:
+for all other platforms.
+.It Fl text
+If this option is specified the output is in human-readable text format
+instead of DER.
+.El
+.Pp
+A time stamp response (TimeStampResp) consists of a response status
+and the time stamp token itself (ContentInfo),
+if the token generation was successful.
+The
+.Fl 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
+.Fl token_out
+is not specified the output is always a time stamp response (TimeStampResp),
+otherwise it is a time stamp token (ContentInfo).
+.Bl -tag -width Ds
+.It Fl chain Ar certs_file.pem
+The collection of certificates, in PEM format,
+that will be included in the response
+in addition to the signer certificate if the
+.Fl 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
+.Fl reply
+command does not build a certificate chain automatically.
+.It Fl config Ar configfile
+The configuration file to use.
+This option overrides the
+.Ev OPENSSL_CONF
+environment variable.
+See
+.Sx TS CONFIGURATION FILE OPTIONS
+for configurable variables.
+.It Fl engine Ar id
+Specifying an engine (by its unique
+.Ar id
+string) will cause
+.Nm 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.
+.It Fl in Ar response.tsr
+Specifies a previously created time stamp response or time stamp token, if
+.Fl 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, for example,
+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
+.Dq granted
+status info is added to the token.
+.It Fl inkey Ar private.pem
+The signer private key of the TSA in PEM format.
+Overrides the
+.Cm signer_key
+config file option.
+.It Fl out Ar response.tsr
+The response is written to this file.
+The format and content of the file depends on other options (see
+.Fl text
+and
+.Fl token_out ) .
+The default is stdout.
+.It Fl passin Ar password_src
+Specifies the password source for the private key of the TSA.
+See the
+.Sx PASS PHRASE ARGUMENTS
+section above.
+.It Fl policy Ar 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
+.Cm default_policy
+config file option.
+.It Fl queryfile Ar request.tsq
+The name of the file containing a DER-encoded time stamp request.
+.It Fl section Ar tsa_section
+The name of the config file section containing the settings for the
+response generation.
+If not specified the default TSA section is used; see
+.Sx TS CONFIGURATION FILE OPTIONS
+for details.
+.It Fl signer Ar 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
+.Cm signer_cert
+variable of the config file.
+.It Fl text
+If this option is specified the output is human-readable text format
+instead of DER.
+.It Fl token_in
+This flag can be used together with the
+.Fl in
+option and indicates that the input is a DER encoded time stamp token
+(ContentInfo) instead of a time stamp response (TimeStampResp).
+.It Fl token_out
+The output is a time stamp token (ContentInfo) instead of time stamp
+response (TimeStampResp).
+.El
+.Pp
+The
+.Fl 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
+.Fl verify
+command does not use the configuration file.
+.Bl -tag -width Ds
+.It Fl CAfile Ar 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
+.Nm verify
+for additional details.
+Either this option or
+.Fl CApath
+must be specified.
+.It Fl CApath Ar trusted_cert_path
+The name of the directory containing the trused CA certificates of the
+client.
+See the similar option of
+.Nm verify
+for additional details.
+Either this option or
+.Fl CAfile
+must be specified.
+.It Fl data Ar file_to_hash
+The response or token must be verified against
+.Ar file_to_hash .
+The file is hashed with the message digest algorithm specified in the token.
+The
+.Fl digest
+and
+.Fl queryfile
+options must not be specified with this one.
+.It Fl digest Ar 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
+.Fl data
+and
+.Fl queryfile
+options must not be specified with this one.
+.It Fl in Ar response.tsr
+The time stamp response that needs to be verified, in DER format.
+This option in mandatory.
+.It Fl queryfile Ar request.tsq
+The original time stamp request, in DER format.
+The
+.Fl data
+and
+.Fl digest
+options must not be specified with this one.
+.It Fl token_in
+This flag can be used together with the
+.Fl in
+option and indicates that the input is a DER-encoded time stamp token
+(ContentInfo) instead of a time stamp response (TimeStampResp).
+.It Fl untrusted Ar 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.
+.El
+.Sh TS CONFIGURATION FILE OPTIONS
+The
+.Fl query
+and
+.Fl reply
+options make use of a configuration file defined by the
+.Ev OPENSSL_CONF
+environment variable.
+The
+.Fl query
+option uses only the symbolic OID names section
+and it can work without it.
+However, the
+.Fl reply
+option 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.
+.Bl -tag -width Ds
+.It Cm tsa Ar section , Cm default_tsa
+This is the main section and it specifies the name of another section
+that contains all the options for the
+.Fl reply
+option.
+This default section can be overriden with the
+.Fl section
+command line switch.
+.It Cm oid_file
+See
+.Nm ca
+for a description.
+.It Cm oid_section
+See
+.Nm ca
+for a description.
+.It Cm RANDFILE
+See
+.Nm ca
+for a description.
+.It Cm 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.
+This parameter is mandatory.
+.It Cm crypto_device
+Specifies the
+.Nm OpenSSL
+engine that will be set as the default for
+all available algorithms.
+.It Cm signer_cert
+TSA signing certificate, in PEM format.
+The same as the
+.Fl signer
+command line option.
+.It Cm certs
+A file containing a set of PEM-encoded certificates that need to be
+included in the response.
+The same as the
+.Fl chain
+command line option.
+.It Cm signer_key
+The private key of the TSA, in PEM format.
+The same as the
+.Fl inkey
+command line option.
+.It Cm default_policy
+The default policy to use when the request does not mandate any policy.
+The same as the
+.Fl policy
+command line option.
+.It Cm 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.
+.It Cm digests
+The list of message digest algorithms that the TSA accepts.
+At least one algorithm must be specified.
+This parameter is mandatory.
+.It Cm accuracy
+The accuracy of the time source of the TSA in seconds, milliseconds
+and microseconds.
+For example, secs:1, millisecs:500, microsecs:100.
+If any of the components is missing,
+zero is assumed for that field.
+.It Cm 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.
+The maximum value is 6;
+the default is 0.
+.It Cm 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.
+The default is no.
+.It Cm 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.
+The default is no.
+.It Cm 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
+.Cm certs
+variable or the
+.Fl 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.
+The default is no.
+.El
+.Sh TS ENVIRONMENT VARIABLES
+.Ev OPENSSL_CONF
+contains the path of the configuration file and can be
+overriden by the
+.Fl config
+command line option.
+.Sh TS EXAMPLES
+All the examples below presume that
+.Ev OPENSSL_CONF
+is set to a proper configuration file,
+e.g. the example configuration file
+.Pa openssl/apps/openssl.cnf
+will do.
+.Pp
+To create a time stamp request for design1.txt with SHA-1
+without nonce and policy and no certificate is required in the response:
+.Bd -literal -offset indent
+$ openssl ts -query -data design1.txt -no_nonce \e
+	-out design1.tsq
+.Ed
+.Pp
+To create a similar time stamp request but specifying the message imprint
+explicitly:
+.Bd -literal -offset indent
+$ openssl ts -query \e
+	-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
+	-no_nonce -out design1.tsq
+.Ed
+.Pp
+To print the content of the previous request in human readable format:
+.Bd -literal -offset indent
+$ openssl ts -query -in design1.tsq -text
+.Ed
+.Pp
+To create a time stamp request which includes the MD5 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):
+.Bd -literal -offset indent
+$ openssl ts -query -data design2.txt -md5 \e
+	-policy tsa_policy1 -cert -out design2.tsq
+.Ed
+.Pp
+Before generating a response,
+a signing certificate must be created for the TSA that contains the
+.Cm timeStamping
+critical extended key usage extension
+without any other key usage extensions.
+You can add the
+.Dq extendedKeyUsage = critical,timeStamping
+line to the user certificate section
+of the config file to generate a proper certificate.
+See the
+.Nm req ,
+.Nm ca ,
+and
+.Nm x509
+commands 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.
+.Pp
+To create a time stamp response for a request:
+.Bd -literal -offset indent
+$ openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \e
+	-signer tsacert.pem -out design1.tsr
+.Ed
+.Pp
+If you want to use the settings in the config file you could just write:
+.Bd -literal -offset indent
+$ openssl ts -reply -queryfile design1.tsq -out design1.tsr
+.Ed
+.Pp
+To print a time stamp reply to stdout in human readable format:
+.Bd -literal -offset indent
+$ openssl ts -reply -in design1.tsr -text
+.Ed
+.Pp
+To create a time stamp token instead of time stamp response:
+.Bd -literal -offset indent
+$ openssl ts -reply -queryfile design1.tsq \e
+	-out design1_token.der -token_out
+.Ed
+.Pp
+To print a time stamp token to stdout in human readable format:
+.Bd -literal -offset indent
+$ openssl ts -reply -in design1_token.der -token_in \e
+	-text -token_out
+.Ed
+.Pp
+To extract the time stamp token from a response:
+.Bd -literal -offset indent
+$ openssl ts -reply -in design1.tsr -out design1_token.der \e
+	-token_out
+.Ed
+.Pp
+To add
+.Dq granted
+status info to a time stamp token thereby creating a valid response:
+.Bd -literal -offset indent
+$ openssl ts -reply -in design1_token.der \e
+	-token_in -out design1.tsr
+.Ed
+.Pp
+To verify a time stamp reply against a request:
+.Bd -literal -offset indent
+$ openssl ts -verify -queryfile design1.tsq -in design1.tsr \e
+	-CAfile cacert.pem -untrusted tsacert.pem
+.Ed
+.Pp
+To verify a time stamp reply that includes the certificate chain:
+.Bd -literal -offset indent
+$ openssl ts -verify -queryfile design2.tsq -in design2.tsr \e
+	-CAfile cacert.pem
+.Ed
+.Pp
+To verify a time stamp token against the original data file:
+.Bd -literal -offset indent
+$ openssl ts -verify -data design2.txt -in design2.tsr \e
+	-CAfile cacert.pem
+.Ed
+.Pp
+To verify a time stamp token against a message imprint:
+.Bd -literal -offset indent
+$ openssl ts -verify \e
+	-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
+	-in design2.tsr -CAfile cacert.pem
+.Ed
+.Sh TS BUGS
+.Pp
+No support for time stamps over SMTP, though it is quite easy
+to implement an automatic email-based TSA with
+.Xr procmail
+and
+.Xr perl 1 .
+HTTP server support is provided in the form of
+a separate
+.Xr httpd 8
+module.
+Pure TCP/IP is not supported.
+.Pp
+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
+.Nm OpenSSL
+is trying to create a time stamp
+response at the same time.
+This is not an issue when using the
+.Xr httpd 8
+server module, which does proper locking.
+.Pp
+Look for the FIXME word in the source files.
+.Pp
+The source code should really be reviewed by somebody else, too.
+.Pp
+More testing is needed.
+.Sh TS AUTHORS
+.An Zoltan Glozik Aq zglozik@opentsa.org ,
+OpenTSA project
+.Pq Pa http://www.opentsa.org .
+.\"
 .\" SPKAC
 .\"
 .Sh SPKAC
-- 
cgit v1.2.3-55-g6feb