|
Packit Service |
4684c1 |
AutoGen Definitions options;
|
|
Packit Service |
4684c1 |
prog-name = ocsptool;
|
|
Packit Service |
4684c1 |
prog-title = "GnuTLS OCSP tool";
|
|
Packit Service |
4684c1 |
prog-desc = "Program to handle OCSP request/responses.";
|
|
Packit Service |
4684c1 |
detail = "ocsptool is a program that can parse and print information about
|
|
Packit Service |
4684c1 |
OCSP requests/responses, generate requests and verify responses. Unlike
|
|
Packit Service |
4684c1 |
other GnuTLS applications it outputs DER encoded structures by default
|
|
Packit Service |
4684c1 |
unless the '--outpem' option is specified.";
|
|
Packit Service |
4684c1 |
short-usage = "ocsptool [options]\nocsptool --help for usage instructions.\n";
|
|
Packit Service |
4684c1 |
explain = "";
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
doc-section = {
|
|
Packit Service |
4684c1 |
ds-type = 'DESCRIPTION';
|
|
Packit Service |
4684c1 |
ds-format = 'texi';
|
|
Packit Service |
4684c1 |
ds-text = <<-_EOT_
|
|
Packit Service |
4684c1 |
@subheading 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 |
_EOT_;
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
#define INFILE_OPT 1
|
|
Packit Service |
4684c1 |
#define OUTFILE_OPT 1
|
|
Packit Service |
4684c1 |
#define VERBOSE_OPT 1
|
|
Packit Service |
4684c1 |
#include args-std.def
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = ask;
|
|
Packit Service |
4684c1 |
arg-type = string;
|
|
Packit Service |
4684c1 |
arg-name = "server name|url";
|
|
Packit Service |
4684c1 |
arg-optional;
|
|
Packit Service |
4684c1 |
descrip = "Ask an OCSP/HTTP server on a certificate validity";
|
|
Packit Service |
4684c1 |
doc = "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 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = verify-response;
|
|
Packit Service |
4684c1 |
value = e;
|
|
Packit Service |
4684c1 |
descrip = "Verify response";
|
|
Packit Service |
4684c1 |
doc = "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 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = request-info;
|
|
Packit Service |
4684c1 |
value = i;
|
|
Packit Service |
4684c1 |
descrip = "Print information on a OCSP request";
|
|
Packit Service |
4684c1 |
doc = "Display detailed information on the provided OCSP request.";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = response-info;
|
|
Packit Service |
4684c1 |
value = j;
|
|
Packit Service |
4684c1 |
descrip = "Print information on a OCSP response";
|
|
Packit Service |
4684c1 |
doc = "Display detailed information on the provided OCSP response.";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = generate-request;
|
|
Packit Service |
4684c1 |
value = q;
|
|
Packit Service |
4684c1 |
descrip = "Generates an OCSP request";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = nonce;
|
|
Packit Service |
4684c1 |
disabled = yes;
|
|
Packit Service |
4684c1 |
disable = "no";
|
|
Packit Service |
4684c1 |
descrip = "Use (or not) a nonce to OCSP request";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = load-chain;
|
|
Packit Service |
4684c1 |
arg-type = file;
|
|
Packit Service |
4684c1 |
file-exists = yes;
|
|
Packit Service |
4684c1 |
descrip = "Reads a set of certificates forming a chain from file";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = load-issuer;
|
|
Packit Service |
4684c1 |
arg-type = file;
|
|
Packit Service |
4684c1 |
file-exists = yes;
|
|
Packit Service |
4684c1 |
descrip = "Reads issuer's certificate from file";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = load-cert;
|
|
Packit Service |
4684c1 |
arg-type = file;
|
|
Packit Service |
4684c1 |
file-exists = yes;
|
|
Packit Service |
4684c1 |
descrip = "Reads the certificate to check from file";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = load-trust;
|
|
Packit Service |
4684c1 |
arg-type = file;
|
|
Packit Service |
4684c1 |
file-exists = yes;
|
|
Packit Service |
4684c1 |
descrip = "Read OCSP trust anchors from file";
|
|
Packit Service |
4684c1 |
flags-cant = load-signer;
|
|
Packit Service |
4684c1 |
doc = "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 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = load-signer;
|
|
Packit Service |
4684c1 |
arg-type = file;
|
|
Packit Service |
4684c1 |
file-exists = yes;
|
|
Packit Service |
4684c1 |
descrip = "Reads the OCSP response signer from file";
|
|
Packit Service |
4684c1 |
flags-cant = load-trust;
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = inder;
|
|
Packit Service |
4684c1 |
disabled;
|
|
Packit Service |
4684c1 |
disable = "no";
|
|
Packit Service |
4684c1 |
descrip = "Use DER format for input certificates and private keys";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = outder;
|
|
Packit Service |
4684c1 |
descrip = "Use DER format for output of responses (this is the default)";
|
|
Packit Service |
4684c1 |
doc = "The output will be in DER encoded format. Unlike other GnuTLS tools, this is the default for this tool";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = outpem;
|
|
Packit Service |
4684c1 |
descrip = "Use PEM format for output of responses";
|
|
Packit Service |
4684c1 |
doc = "The output will be in PEM format.";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = load-request;
|
|
Packit Service |
4684c1 |
value = Q;
|
|
Packit Service |
4684c1 |
arg-type = file;
|
|
Packit Service |
4684c1 |
file-exists = yes;
|
|
Packit Service |
4684c1 |
descrip = "Reads the DER encoded OCSP request from file";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = load-response;
|
|
Packit Service |
4684c1 |
value = S;
|
|
Packit Service |
4684c1 |
arg-type = file;
|
|
Packit Service |
4684c1 |
file-exists = yes;
|
|
Packit Service |
4684c1 |
descrip = "Reads the DER encoded OCSP response from file";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = ignore-errors;
|
|
Packit Service |
4684c1 |
descrip = "Ignore any verification errors";
|
|
Packit Service |
4684c1 |
doc = "";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
flag = {
|
|
Packit Service |
4684c1 |
name = verify-allow-broken;
|
|
Packit Service |
4684c1 |
descrip = "Allow broken algorithms, such as MD5 for verification";
|
|
Packit Service |
4684c1 |
doc = "This can be combined with --verify-response.";
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
doc-section = {
|
|
Packit Service |
4684c1 |
ds-type = 'SEE ALSO';
|
|
Packit Service |
4684c1 |
ds-format = 'texi';
|
|
Packit Service |
4684c1 |
ds-text = <<-_EOT_
|
|
Packit Service |
4684c1 |
certtool (1)
|
|
Packit Service |
4684c1 |
_EOT_;
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
doc-section = {
|
|
Packit Service |
4684c1 |
ds-type = 'EXAMPLES';
|
|
Packit Service |
4684c1 |
ds-format = 'texi';
|
|
Packit Service |
4684c1 |
ds-text = <<-_EOF_
|
|
Packit Service |
4684c1 |
@subheading 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 |
@subheading 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 |
@subheading 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 |
@subheading 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 |
@subheading 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 |
@subheading 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
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
_EOF_;
|
|
Packit Service |
4684c1 |
};
|
|
Packit Service |
4684c1 |
|