|
Packit Service |
4684c1 |
@node ocsptool Invocation
|
|
Packit Service |
4684c1 |
@subsection Invoking ocsptool
|
|
Packit Service |
4684c1 |
@pindex ocsptool
|
|
Packit Service |
4684c1 |
@ignore
|
|
Packit Service |
4684c1 |
# -*- buffer-read-only: t -*- vi: set ro:
|
|
Packit Service |
4684c1 |
#
|
|
Packit Service |
4684c1 |
# DO NOT EDIT THIS FILE (invoke-ocsptool.texi)
|
|
Packit Service |
4684c1 |
#
|
|
Packit Service |
4684c1 |
# It has been AutoGen-ed
|
|
Packit Service |
4684c1 |
# From the definitions ../src/ocsptool-args.def
|
|
Packit Service |
4684c1 |
# and the template file agtexi-cmd.tpl
|
|
Packit Service |
4684c1 |
@end ignore
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading On verification
|
|
Packit Service |
4684c1 |
Responses are typically signed/issued by designated certificates or
|
|
Packit Service |
4684c1 |
certificate authorities and thus this tool requires on verification
|
|
Packit Service |
4684c1 |
the certificate of the issuer or the full certificate chain in order to
|
|
Packit Service |
4684c1 |
determine the appropriate signing authority. The specified certificate
|
|
Packit Service |
4684c1 |
of the issuer is assumed trusted.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This section was generated by @strong{AutoGen},
|
|
Packit Service |
4684c1 |
using the @code{agtexi-cmd} template and the option descriptions for the @code{ocsptool} program.
|
|
Packit Service |
4684c1 |
This software is released under the GNU General Public License, version 3 or later.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@anchor{ocsptool usage}
|
|
Packit Service |
4684c1 |
@subsubheading ocsptool help/usage (@option{--help})
|
|
Packit Service |
4684c1 |
@cindex ocsptool help
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the automatically generated usage text for ocsptool.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The text printed is the same whether selected with the @code{help} option
|
|
Packit Service |
4684c1 |
(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
|
|
Packit Service |
4684c1 |
the usage text by passing it through a pager program.
|
|
Packit Service |
4684c1 |
@code{more-help} is disabled on platforms without a working
|
|
Packit Service |
4684c1 |
@code{fork(2)} function. The @code{PAGER} environment variable is
|
|
Packit Service |
4684c1 |
used to select the program, defaulting to @file{more}. Both will exit
|
|
Packit Service |
4684c1 |
with a status code of 0.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@exampleindent 0
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
ocsptool - GnuTLS OCSP tool
|
|
Packit Service |
4684c1 |
Usage: ocsptool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
-d, --debug=num Enable debugging
|
|
Packit Service |
4684c1 |
- it must be in the range:
|
|
Packit Service |
4684c1 |
0 to 9999
|
|
Packit Service |
4684c1 |
-V, --verbose More verbose output
|
|
Packit Service |
4684c1 |
- may appear multiple times
|
|
Packit Service |
4684c1 |
--infile=file Input file
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
--outfile=str Output file
|
|
Packit Service |
4684c1 |
--ask[=arg] Ask an OCSP/HTTP server on a certificate validity
|
|
Packit Service |
4684c1 |
-e, --verify-response Verify response
|
|
Packit Service |
4684c1 |
-i, --request-info Print information on a OCSP request
|
|
Packit Service |
4684c1 |
-j, --response-info Print information on a OCSP response
|
|
Packit Service |
4684c1 |
-q, --generate-request Generates an OCSP request
|
|
Packit Service |
4684c1 |
--nonce Use (or not) a nonce to OCSP request
|
|
Packit Service |
4684c1 |
- disabled as '--no-nonce'
|
|
Packit Service |
4684c1 |
--load-chain=file Reads a set of certificates forming a chain from file
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
--load-issuer=file Reads issuer's certificate from file
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
--load-cert=file Reads the certificate to check from file
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
--load-trust=file Read OCSP trust anchors from file
|
|
Packit Service |
4684c1 |
- prohibits the option 'load-signer'
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
--load-signer=file Reads the OCSP response signer from file
|
|
Packit Service |
4684c1 |
- prohibits the option 'load-trust'
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
--inder Use DER format for input certificates and private keys
|
|
Packit Service |
4684c1 |
- disabled as '--no-inder'
|
|
Packit Service |
4684c1 |
--outder Use DER format for output of responses (this is the default)
|
|
Packit Service |
4684c1 |
--outpem Use PEM format for output of responses
|
|
Packit Service |
4684c1 |
-Q, --load-request=file Reads the DER encoded OCSP request from file
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
-S, --load-response=file Reads the DER encoded OCSP response from file
|
|
Packit Service |
4684c1 |
- file must pre-exist
|
|
Packit Service |
4684c1 |
--ignore-errors Ignore any verification errors
|
|
Packit Service |
4684c1 |
--verify-allow-broken Allow broken algorithms, such as MD5 for verification
|
|
Packit Service |
4684c1 |
-v, --version[=arg] output version information and exit
|
|
Packit Service |
4684c1 |
-h, --help display extended usage information and exit
|
|
Packit Service |
4684c1 |
-!, --more-help extended usage information passed thru pager
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Options are specified by doubled hyphens and their name or by a single
|
|
Packit Service |
4684c1 |
hyphen and the flag character.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
ocsptool is a program that can parse and print information about OCSP
|
|
Packit Service |
4684c1 |
requests/responses, generate requests and verify responses. Unlike other
|
|
Packit Service |
4684c1 |
GnuTLS applications it outputs DER encoded structures by default unless the
|
|
Packit Service |
4684c1 |
'--outpem' option is specified.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
@exampleindent 4
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@anchor{ocsptool debug}
|
|
Packit Service |
4684c1 |
@subsubheading debug option (-d)
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``enable debugging'' option.
|
|
Packit Service |
4684c1 |
This option takes a number argument.
|
|
Packit Service |
4684c1 |
Specifies the debug level.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool ask}
|
|
Packit Service |
4684c1 |
@subsubheading ask option
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``ask an ocsp/http server on a certificate validity'' option.
|
|
Packit Service |
4684c1 |
This option takes an optional string argument @file{server name|url}.
|
|
Packit Service |
4684c1 |
Connects to the specified HTTP OCSP server and queries on the validity of the loaded certificate.
|
|
Packit Service |
4684c1 |
Its argument can be a URL or a plain server name. It can be combined with --load-chain, where it checks
|
|
Packit Service |
4684c1 |
all certificates in the provided chain, or with --load-cert and
|
|
Packit Service |
4684c1 |
--load-issuer options. The latter checks the provided certificate
|
|
Packit Service |
4684c1 |
against its specified issuer certificate.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool verify-response}
|
|
Packit Service |
4684c1 |
@subsubheading verify-response option (-e)
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``verify response'' option.
|
|
Packit Service |
4684c1 |
Verifies the provided OCSP response against the system trust
|
|
Packit Service |
4684c1 |
anchors (unless --load-trust is provided). It requires the --load-signer
|
|
Packit Service |
4684c1 |
or --load-chain options to obtain the signer of the OCSP response.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool request-info}
|
|
Packit Service |
4684c1 |
@subsubheading request-info option (-i)
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``print information on a ocsp request'' option.
|
|
Packit Service |
4684c1 |
Display detailed information on the provided OCSP request.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool response-info}
|
|
Packit Service |
4684c1 |
@subsubheading response-info option (-j)
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``print information on a ocsp response'' option.
|
|
Packit Service |
4684c1 |
Display detailed information on the provided OCSP response.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool load-trust}
|
|
Packit Service |
4684c1 |
@subsubheading load-trust option
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``read ocsp trust anchors from file'' option.
|
|
Packit Service |
4684c1 |
This option takes a file argument.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@noindent
|
|
Packit Service |
4684c1 |
This option has some usage constraints. It:
|
|
Packit Service |
4684c1 |
@itemize @bullet
|
|
Packit Service |
4684c1 |
@item
|
|
Packit Service |
4684c1 |
must not appear in combination with any of the following options:
|
|
Packit Service |
4684c1 |
load-signer.
|
|
Packit Service |
4684c1 |
@end itemize
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
When verifying an OCSP response read the trust anchors from the
|
|
Packit Service |
4684c1 |
provided file. When this is not provided, the system's trust anchors will be
|
|
Packit Service |
4684c1 |
used.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool outder}
|
|
Packit Service |
4684c1 |
@subsubheading outder option
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``use der format for output of responses (this is the default)'' option.
|
|
Packit Service |
4684c1 |
The output will be in DER encoded format. Unlike other GnuTLS tools, this is the default for this tool
|
|
Packit Service |
4684c1 |
@anchor{ocsptool outpem}
|
|
Packit Service |
4684c1 |
@subsubheading outpem option
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``use pem format for output of responses'' option.
|
|
Packit Service |
4684c1 |
The output will be in PEM format.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool verify-allow-broken}
|
|
Packit Service |
4684c1 |
@subsubheading verify-allow-broken option
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This is the ``allow broken algorithms, such as md5 for verification'' option.
|
|
Packit Service |
4684c1 |
This can be combined with --verify-response.
|
|
Packit Service |
4684c1 |
@anchor{ocsptool exit status}
|
|
Packit Service |
4684c1 |
@subsubheading ocsptool exit status
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
One of the following exit values will be returned:
|
|
Packit Service |
4684c1 |
@table @samp
|
|
Packit Service |
4684c1 |
@item 0 (EXIT_SUCCESS)
|
|
Packit Service |
4684c1 |
Successful program execution.
|
|
Packit Service |
4684c1 |
@item 1 (EXIT_FAILURE)
|
|
Packit Service |
4684c1 |
The operation failed or the command syntax was not valid.
|
|
Packit Service |
4684c1 |
@end table
|
|
Packit Service |
4684c1 |
@anchor{ocsptool See Also}
|
|
Packit Service |
4684c1 |
@subsubheading ocsptool See Also
|
|
Packit Service |
4684c1 |
certtool (1)
|
|
Packit Service |
4684c1 |
@anchor{ocsptool Examples}
|
|
Packit Service |
4684c1 |
@subsubheading ocsptool Examples
|
|
Packit Service |
4684c1 |
@subsubheading Print information about an OCSP request
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
To parse an OCSP request and print information about the content, the
|
|
Packit Service |
4684c1 |
@code{-i} or @code{--request-info} parameter may be used as follows.
|
|
Packit Service |
4684c1 |
The @code{-Q} parameter specify the name of the file containing the
|
|
Packit Service |
4684c1 |
OCSP request, and it should contain the OCSP request in binary DER
|
|
Packit Service |
4684c1 |
format.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ ocsptool -i -Q ocsp-request.der
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The input file may also be sent to standard input like this:
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ cat ocsp-request.der | ocsptool --request-info
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading Print information about an OCSP response
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Similar to parsing OCSP requests, OCSP responses can be parsed using
|
|
Packit Service |
4684c1 |
the @code{-j} or @code{--response-info} as follows.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ ocsptool -j -Q ocsp-response.der
|
|
Packit Service |
4684c1 |
$ cat ocsp-response.der | ocsptool --response-info
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading Generate an OCSP request
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The @code{-q} or @code{--generate-request} parameters are used to
|
|
Packit Service |
4684c1 |
generate an OCSP request. By default the OCSP request is written to
|
|
Packit Service |
4684c1 |
standard output in binary DER format, but can be stored in a file
|
|
Packit Service |
4684c1 |
using @code{--outfile}. To generate an OCSP request the issuer of the
|
|
Packit Service |
4684c1 |
certificate to check needs to be specified with @code{--load-issuer}
|
|
Packit Service |
4684c1 |
and the certificate to check with @code{--load-cert}. By default PEM
|
|
Packit Service |
4684c1 |
format is used for these files, although @code{--inder} can be used to
|
|
Packit Service |
4684c1 |
specify that the input files are in DER format.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \
|
|
Packit Service |
4684c1 |
--outfile ocsp-request.der
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
When generating OCSP requests, the tool will add an OCSP extension
|
|
Packit Service |
4684c1 |
containing a nonce. This behaviour can be disabled by specifying
|
|
Packit Service |
4684c1 |
@code{--no-nonce}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading Verify signature in OCSP response
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
To verify the signature in an OCSP response the @code{-e} or
|
|
Packit Service |
4684c1 |
@code{--verify-response} parameter is used. The tool will read an
|
|
Packit Service |
4684c1 |
OCSP response in DER format from standard input, or from the file
|
|
Packit Service |
4684c1 |
specified by @code{--load-response}. The OCSP response is verified
|
|
Packit Service |
4684c1 |
against a set of trust anchors, which are specified using
|
|
Packit Service |
4684c1 |
@code{--load-trust}. The trust anchors are concatenated certificates
|
|
Packit Service |
4684c1 |
in PEM format. The certificate that signed the OCSP response needs to
|
|
Packit Service |
4684c1 |
be in the set of trust anchors, or the issuer of the signer
|
|
Packit Service |
4684c1 |
certificate needs to be in the set of trust anchors and the OCSP
|
|
Packit Service |
4684c1 |
Extended Key Usage bit has to be asserted in the signer certificate.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ ocsptool -e --load-trust issuer.pem \
|
|
Packit Service |
4684c1 |
--load-response ocsp-response.der
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The tool will print status of verification.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading Verify signature in OCSP response against given certificate
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
It is possible to override the normal trust logic if you know that a
|
|
Packit Service |
4684c1 |
certain certificate is supposed to have signed the OCSP response, and
|
|
Packit Service |
4684c1 |
you want to use it to check the signature. This is achieved using
|
|
Packit Service |
4684c1 |
@code{--load-signer} instead of @code{--load-trust}. This will load
|
|
Packit Service |
4684c1 |
one certificate and it will be used to verify the signature in the
|
|
Packit Service |
4684c1 |
OCSP response. It will not check the Extended Key Usage bit.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ ocsptool -e --load-signer ocsp-signer.pem \
|
|
Packit Service |
4684c1 |
--load-response ocsp-response.der
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This approach is normally only relevant in two situations. The first
|
|
Packit Service |
4684c1 |
is when the OCSP response does not contain a copy of the signer
|
|
Packit Service |
4684c1 |
certificate, so the @code{--load-trust} code would fail. The second
|
|
Packit Service |
4684c1 |
is if you want to avoid the indirect mode where the OCSP response
|
|
Packit Service |
4684c1 |
signer certificate is signed by a trust anchor.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading Real-world example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Here is an example of how to generate an OCSP request for a
|
|
Packit Service |
4684c1 |
certificate and to verify the response. For illustration we'll use
|
|
Packit Service |
4684c1 |
the @code{blog.josefsson.org} host, which (as of writing) uses a
|
|
Packit Service |
4684c1 |
certificate from CACert. First we'll use @code{gnutls-cli} to get a
|
|
Packit Service |
4684c1 |
copy of the server certificate chain. The server is not required to
|
|
Packit Service |
4684c1 |
send this information, but this particular one is configured to do so.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ echo | gnutls-cli -p 443 blog.josefsson.org --save-cert chain.pem
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The saved certificates normally contain a pointer to where the OCSP
|
|
Packit Service |
4684c1 |
responder is located, in the Authority Information Access Information
|
|
Packit Service |
4684c1 |
extension. For example, from @code{certtool -i < chain.pem} there is
|
|
Packit Service |
4684c1 |
this information:
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
Authority Information Access Information (not critical):
|
|
Packit Service |
4684c1 |
Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
|
|
Packit Service |
4684c1 |
Access Location URI: https://ocsp.CAcert.org/
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
This means that ocsptool can discover the servers to contact over HTTP.
|
|
Packit Service |
4684c1 |
We can now request information on the chain certificates.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ ocsptool --ask --load-chain chain.pem
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The request is sent via HTTP to the OCSP server address found in
|
|
Packit Service |
4684c1 |
the certificates. It is possible to override the address of the
|
|
Packit Service |
4684c1 |
OCSP server as well as ask information on a particular certificate
|
|
Packit Service |
4684c1 |
using --load-cert and --load-issuer.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
$ ocsptool --ask https://ocsp.CAcert.org/ --load-chain chain.pem
|
|
Packit Service |
4684c1 |
@end example
|