1b2b535b406f7fd13aa24ed4c8b18704e34d99d8
[openssl.git] / doc / apps / ocsp.pod
1 =pod
2
3 =head1 NAME
4
5 ocsp - Online Certificate Status Protocol utility
6
7 =head1 SYNOPSIS
8
9 B<openssl> B<ocsp>
10 [B<-out file>]
11 [B<-issuer file>]
12 [B<-cert file>]
13 [B<-serial n>]
14 [B<-req_text>]
15 [B<-resp_text>]
16 [B<-text>]
17 [B<-reqout file>]
18 [B<-respout file>]
19 [B<-reqin file>]
20 [B<-respin file>]
21 [B<-nonce>]
22 [B<-no_nonce>]
23 [B<-host host:n>]
24 [B<-path>]
25
26 =head1 DESCRIPTION
27
28 B<WARNING: this documentation is preliminary and subject to change.>
29
30 The Online Certificate Status Protocol (OCSP) enables applications to
31 determine the (revocation) state of an identified certificate (RFC 2560).
32
33 The B<ocsp> command performs many common OCSP tasks. It can be used
34 to print out requests and responses, create requests and send queries
35 to an OCSP responder.
36
37 =head1 OPTIONS
38
39 =over 4
40
41 =item B<-out filename>
42
43 specify output filename, default is standard output.
44
45 =item B<-issuer filename>
46
47 This specifies the current issuer certificate. This option can be used
48 multiple times. The certificate specified in B<filename> must be in
49 PEM format.
50
51 =item B<-cert filename>
52
53 Add the certificate B<filename> to the request. The issuer certificate
54 is taken from the previous B<issuer> option, or an error occurs if no
55 issuer certificate is specified.
56
57 =item B<-serial num>
58
59 Same as the B<cert> option except the certificate with serial number
60 B<num> (in decimal) is added to the request.
61
62 =item B<-signer filename>, B<-signkey filename>
63
64 Sign the OCSP request using the certificate specified in the B<signer>
65 option and the private key specified by the B<signkey> option. If
66 the B<signkey> option is not present then the private key is read
67 from the same file as the certificate. If neither option is specified then
68 the OCSP request is not signed.
69
70 =item B<-nonce>, B<-no_nonce>
71
72 Add an OCSP nonce extension to a request or disable OCSP nonce addition.
73 Normally if an OCSP request is input using the B<respin> option no
74 nonce is added: using the B<nonce> option will force addition of a nonce.
75 If an OCSP request is being created (using B<cert> and B<serial> options)
76 a nonce is automatically added specifying B<no_nonce> overrides this.
77
78 =item B<-req_text>, B<-resp_text>, B<-text>
79
80 print out the text form of the OCSP request, reponse or both respectively.
81
82 =item B<-reqout file>, B<-respout file>
83
84 write out the DER encoded certificate request or response to B<file>.
85
86 =item B<-reqin file>, B<-respin file>
87
88 read OCSP request or response file from B<file>. These option are ignored
89 if OCSP request or response creation is implied by other options (for example
90 with B<serial>, B<cert> and B<host> options).
91
92 =item B<-host hostname:port>, B<-path pathname>
93
94 if the B<host> option is present then the OCSP request is sent to the host
95 B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
96 or "/" by default.
97
98 =back
99
100 =head1 NOTES
101
102 The B<-host> and B<-path> options specify the relevant parts of the OCSP
103 URI. For example the OCSP responder URL:
104
105 http://ocsp.myhost.com/ocsp/request
106
107 corresponds to the the options:
108
109  -host ocsp.myhost.com:80 -path /ocsp/request
110
111 =head1 EXAMPLES
112
113 Create an OCSP request and write it to a file:
114
115  openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
116
117 Send a query an OCSP responder with URL http://ocsp.myhost.com/ save the 
118 response to a file and print it out in text form
119
120  openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
121      -host ocsp.myhost.com:80 -resp_text -respout resp.der
122
123 Read in an OCSP response and print out text form:
124
125  openssl ocsp -respin resp.der -text
126
127 =head1 BUGS
128
129 This utility is incomplete. It currently does not check the OCSP response's
130 validity in any way.
131
132 The B<host> and B<path> options may well go away and be replaced by a B<url>
133 option and an option to determine the URI based on certificate extensions.
134
135 The B<serial> option only supports postive serial numbers and must be supplied
136 in decimal form. Some CAs issue certificates with negative serial numbers
137 (probably unintentionally) and cannot currently be specified.
138
139 SSL OCSP responders using https URLs cannot currently be queried.