doc/apps/ocsp.pod

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