Standardize apps use of -rand, etc.

[openssl.git] / doc / man1 / ts.pod

diff --git a/doc/man1/ts.pod b/doc/man1/ts.pod
index 02b2adaa2f589df1a1939d7f5b3dc5535974256f..56ace24817e0c376fa72baf4a84d2498190522b8 100644 (file)
--- a/doc/man1/ts.pod
+++ b/doc/man1/ts.pod
@@ -8,7 +8,8 @@ ts - Time Stamping Authority tool (client/server)
 
 B<openssl> B<ts>
 B<-query>
 
 B<openssl> B<ts>
 B<-query>

-[B<-rand> file:file...]
+[B<-rand file...>]
+[B<-writerand file>]

 [B<-config> configfile]
 [B<-data> file_to_hash]
 [B<-digest> digest_bytes]
 [B<-config> configfile]
 [B<-data> file_to_hash]
 [B<-digest> digest_bytes]


@@ -27,7 +28,7 @@ B<-reply>
 [B<-queryfile> request.tsq]
 [B<-passin> password_src]
 [B<-signer> tsa_cert.pem]
 [B<-queryfile> request.tsq]
 [B<-passin> password_src]
 [B<-signer> tsa_cert.pem]

-[B<-inkey> private.pem]
+[B<-inkey> file_or_id]

 [B<-sha1|-sha224|-sha256|-sha384|-sha512>]
 [B<-chain> certs_file.pem]
 [B<-tspolicy> object_id]
 [B<-sha1|-sha224|-sha256|-sha384|-sha512>]
 [B<-chain> certs_file.pem]
 [B<-tspolicy> object_id]


@@ -131,17 +132,24 @@ request with the following options:
 
 =over 4
 
 
 =over 4
 

-=item B<-rand> file:file...
+=item B<-rand 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)
+A file or files containing random data used to seed the random number
+generator.
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item [B<-writerand file>]
+
+Writes random data to the specified I<file> upon exit.
+This can be used with a subsequent B<-rand> flag.

 
 =item B<-config> configfile
 
 
 =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)
+The configuration file to use.
+Optional; for a description of the default value,
+see L<openssl(1)/COMMAND SUMMARY>.

 
 =item B<-data> file_to_hash
 
 
 =item B<-data> file_to_hash
 


@@ -187,7 +195,6 @@ response. (Optional)
 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
 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
 format. (Optional)
 
 =item B<-out> request.tsq


@@ -216,9 +223,10 @@ otherwise it is a time stamp token (ContentInfo).
 
 =item B<-config> configfile
 
 
 =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)
+The configuration file to use.
+Optional; for a description of the default value,
+see L<openssl(1)/COMMAND SUMMARY>.
+See B<CONFIGURATION FILE OPTIONS> for configurable variables.

 
 =item B<-section> tsa_section
 
 
 =item B<-section> tsa_section
 


@@ -243,10 +251,12 @@ 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)
 
 the certificate is going to be refused. Overrides the B<signer_cert>
 variable of the config file. (Optional)
 

-=item B<-inkey> private.pem
+=item B<-inkey> file_or_id

 
 The signer private key of the TSA in PEM format. Overrides the
 B<signer_key> config file option. (Optional)
 
 The signer private key of the TSA in PEM format. Overrides the
 B<signer_key> 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.

 
 =item B<-sha1|-sha224|-sha256|-sha384|-sha512>
 
 
 =item B<-sha1|-sha224|-sha256|-sha384|-sha512>
 


@@ -386,8 +396,8 @@ verification.  See L<verify(1)>.
 
 =head1 CONFIGURATION FILE OPTIONS
 
 
 =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)>
+The B<-query> and B<-reply> commands make use of a configuration file.
+See L<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
 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


@@ -503,12 +513,12 @@ 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)
 
 variable is set to no, only the signing certificate identifier is
 included. Default is no. (Optional)
 

-=back
+=item B<ess_cert_id_alg>

 
 

-=head1 ENVIRONMENT VARIABLES
+This option specifies the hash function to be used to calculate the TSA's
+public key certificate identifier. Default is sha1. (Optional)

 
 

-B<OPENSSL_CONF> contains the path of the configuration file and can be
-overridden by the B<-config> command line option.
+=back

 
 =head1 EXAMPLES
 
 
 =head1 EXAMPLES
 


@@ -608,28 +618,37 @@ You could also look at the 'test' directory for more examples.
 
 =head1 BUGS
 
 
 =head1 BUGS
 

-If you find any bugs or you have suggestions please write to
-Zoltan Glozik <zglozik@opentsa.org>. Known issues:
+=for comment foreign manuals: procmail(1), perl(1)

 
 

-=over 4
+=over 2

 
 

-=item * No support for time stamps over SMTP, though it is quite easy
+=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)>
 and L<perl(1)>. HTTP server support is provided in the form of
 a separate apache module. HTTP client support is provided by
 L<tsget(1)>. Pure TCP/IP protocol is not supported.
 
 to implement an automatic e-mail based TSA with L<procmail(1)>
 and L<perl(1)>. HTTP server support is provided in the form of
 a separate apache module. HTTP client support is provided by
 L<tsget(1)>. Pure TCP/IP protocol is not supported.
 

-=item * The file containing the last serial number of the TSA is not
+=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)> 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.
 
 locked when being read or written. This is a problem if more than one
 instance of L<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 *
+
+Look for the FIXME word in the source files.
+
+=item *
+
+The source code should really be reviewed by somebody else, too.

 
 

-=item * The source code should really be reviewed by somebody else, too.
+=item *

 
 

-=item * More testing is needed, I have done only some basic tests (see
+More testing is needed, I have done only some basic tests (see

 test/testtsa).
 
 =back
 test/testtsa).
 
 =back


@@ -642,7 +661,7 @@ L<config(5)>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.

 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy