1 files changed, 128 insertions, 0 deletions
diff --git a/doc/ocsptool-examples.texi b/doc/ocsptool-examples.texi
new file mode 100644
index 0000000000..38b5db7124
--- /dev/null
+++ b/doc/ocsptool-examples.texi
@@ -0,0 +1,128 @@
+@subheading Print information about an OCSP request
+
+To parse an OCSP request and print information about the content, the
+@code{-i} or @code{--request-info} parameter may be used as follows.
+The @code{-Q} parameter specify the name of the file containing the
+OCSP request, and it should contain the OCSP request in binary DER
+format.
+
+@example
+$ ocsptool -i -Q ocsp-request.der
+@end example
+
+The input file may also be sent to standard input like this:
+
+@example
+$ cat ocsp-request.der | ocsptool --request-info
+@end example
+
+@subheading Print information about an OCSP response
+
+Similar to parsing OCSP requests, OCSP responses can be parsed using
+the @code{-j} or @code{--response-info} as follows.
+
+@example
+$ ocsptool -j -Q ocsp-response.der
+$ cat ocsp-response.der | ocsptool --response-info
+@end example
+
+@subheading Generate an OCSP request
+
+The @code{-q} or @code{--generate-request} parameters are used to
+generate an OCSP request.  By default the OCSP request is written to
+standard output in binary DER format, but can be stored in a file
+using @code{--outfile}.  To generate an OCSP request the issuer of the
+certificate to check needs to be specified with @code{--load-issuer}
+and the certificate to check with @code{--load-cert}.  By default PEM
+format is used for these files, although @code{--inder} can be used to
+specify that the input files are in DER format.
+
+@example
+$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \
+           --outfile ocsp-request.der
+@end example
+
+When generating OCSP requests, the tool will add an OCSP extension
+containing a nonce.  This behaviour can be disabled by specifying
+@code{--no-nonce}.
+
+@subheading Verify signature in OCSP response
+
+To verify the signature in an OCSP response the @code{-e} or
+@code{--verify-response} parameter is used.  The tool will read an
+OCSP response in DER format from standard input, or from the file
+specified by @code{--load-response}.  The OCSP response is verified
+against a set of trust anchors, which are specified using
+@code{--load-trust}.  The trust anchors are concatenated certificates
+in PEM format.  The certificate that signed the OCSP response needs to
+be in the set of trust anchors, or the issuer of the signer
+certificate needs to be in the set of trust anchors and the OCSP
+Extended Key Usage bit has to be asserted in the signer certificate.
+
+@example
+$ ocsptool -e --load-trust issuer.pem \
+           --load-response ocsp-response.der
+@end example
+
+The tool will print status of verification.
+
+@subheading Verify signature in OCSP response against given certificate
+
+It is possible to override the normal trust logic if you know that a
+certain certificate is supposed to have signed the OCSP response, and
+you want to use it to check the signature.  This is achieved using
+@code{--load-signer} instead of @code{--load-trust}.  This will load
+one certificate and it will be used to verify the signature in the
+OCSP response.  It will not check the Extended Key Usage bit.
+
+@example
+$ ocsptool -e --load-signer ocsp-signer.pem \
+           --load-response ocsp-response.der
+@end example
+
+This approach is normally only relevant in two situations.  The first
+is when the OCSP response does not contain a copy of the signer
+certificate, so the @code{--load-trust} code would fail.  The second
+is if you want to avoid the indirect mode where the OCSP response
+signer certificate is signed by a trust anchor.
+
+@subheading Real-world example
+
+Here is an example of how to generate an OCSP request for a
+certificate and to verify the response.  For illustration we'll use
+the @code{blog.josefsson.org} host, which (as of writing) uses a
+certificate from CACert.  First we'll use @code{gnutls-cli} to get a
+copy of the server certificate chain.  The server is not required to
+send this information, but this particular one is configured to do so.
+
+@example
+$ echo | gnutls-cli -p 443 blog.josefsson.org --save-cert chain.pem
+@end example
+
+The saved certificates normally contain a pointer to where the OCSP
+responder is located, in the Authority Information Access Information
+extension.  For example, from @code{certtool -i < chain.pem} there is
+this information:
+
+@example
+		Authority Information Access Information (not critical):
+			Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
+			Access Location URI: https://ocsp.CAcert.org/
+@end example
+
+This means that ocsptool can discover the servers to contact over HTTP.
+We can now request information on the chain certificates.
+
+@example
+$ ocsptool --ask --load-chain chain.pem
+@end example
+
+The request is sent via HTTP to the OCSP server address found in
+the certificates. It is possible to override the address of the
+OCSP server as well as ask information on a particular certificate
+using --load-cert and --load-issuer.
+
+@example
+$ ocsptool --ask https://ocsp.CAcert.org/ --load-chain chain.pem
+@end example
+