1.\" $OpenBSD: OCSP_sendreq_new.3,v 1.4 2017/07/06 15:42:04 schwarze Exp $ 2.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2014, 2016 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: July 6 2017 $ 52.Dt OCSP_SENDREQ_NEW 3 53.Os 54.Sh NAME 55.Nm OCSP_sendreq_new , 56.Nm OCSP_sendreq_nbio , 57.Nm OCSP_REQ_CTX_free , 58.Nm OCSP_REQ_CTX_add1_header , 59.Nm OCSP_REQ_CTX_set1_req , 60.Nm OCSP_sendreq_bio 61.Nd OCSP responder query functions 62.Sh SYNOPSIS 63.In openssl/ocsp.h 64.Ft OCSP_REQ_CTX * 65.Fo OCSP_sendreq_new 66.Fa "BIO *io" 67.Fa "const char *path" 68.Fa "OCSP_REQUEST *req" 69.Fa "int maxline" 70.Fc 71.Ft int 72.Fo OCSP_sendreq_nbio 73.Fa "OCSP_RESPONSE **presp" 74.Fa "OCSP_REQ_CTX *rctx" 75.Fc 76.Ft void 77.Fo OCSP_REQ_CTX_free 78.Fa "OCSP_REQ_CTX *rctx" 79.Fc 80.Ft int 81.Fo OCSP_REQ_CTX_add1_header 82.Fa "OCSP_REQ_CTX *rctx" 83.Fa "const char *name" 84.Fa "const char *value" 85.Fc 86.Ft int 87.Fo OCSP_REQ_CTX_set1_req 88.Fa "OCSP_REQ_CTX *rctx" 89.Fa "OCSP_REQUEST *req" 90.Fc 91.Ft OCSP_RESPONSE * 92.Fo OCSP_sendreq_bio 93.Fa "BIO *io" 94.Fa "const char *path" 95.Fa "OCSP_REQUEST *req" 96.Fc 97.Sh DESCRIPTION 98The function 99.Fn OCSP_sendreq_new 100returns an 101.Vt OCSP_REQ_CTX 102structure using the responder 103.Fa io , 104the URI path 105.Fa path , 106the OCSP request 107.Fa req 108and with a response header maximum line length of 109.Fa maxline . 110If 111.Fa maxline 112is zero, a default value of 4k is used. 113The OCSP request 114.Fa req 115may be set to 116.Dv NULL 117and provided later if required. 118.Pp 119The arguments to 120.Fn OCSP_sendreq_new 121correspond to the components of the URI. 122For example, if the responder URI is 123.Pa http://ocsp.com/ocspreq , 124the BIO 125.Fa io 126should be connected to host 127.Pa ocsp.com 128on port 80 and 129.Fa path 130should be set to 131.Qq /ocspreq . 132.Pp 133.Fn OCSP_sendreq_nbio 134performs non-blocking I/O on the OCSP request context 135.Fa rctx . 136When the operation is complete it returns the response in 137.Pf * Fa presp . 138If 139.Fn OCSP_sendreq_nbio 140indicates an operation should be retried, the corresponding BIO can 141be examined to determine which operation (read or write) should be 142retried and appropriate action can be taken, for example a 143.Xr select 2 144call on the underlying socket. 145.Pp 146.Fn OCSP_REQ_CTX_free 147frees up the OCSP context 148.Fa rctx . 149.Pp 150.Fn OCSP_REQ_CTX_add1_header 151adds header 152.Fa name 153with value 154.Fa value 155to the context 156.Fa rctx . 157The added headers are of the form 158.Qq Fa name : value 159or just 160.Qq Fa name 161if 162.Fa value 163is 164.Dv NULL . 165.Fn OCSP_REQ_CTX_add1_header 166can be called more than once to add multiple headers. 167It must be called before any calls to 168.Fn OCSP_sendreq_nbio . 169The 170.Fa req 171parameter in the initial to 172.Fn OCSP_sendreq_new 173call must be set to 174.Dv NULL 175if additional headers are set. 176.Pp 177.Fn OCSP_REQ_CTX_set1_req 178sets the OCSP request in 179.Fa rctx 180to 181.Fa req . 182This function should be called after any calls to 183.Fn OCSP_REQ_CTX_add1_header . 184.Pp 185.Fn OCSP_sendreq_bio 186performs an OCSP request using the responder 187.Fa io , 188the URI path 189.Fa path , 190the OCSP request 191.Fa req . 192It does not support retries and so cannot handle non-blocking I/O 193efficiently. 194It is retained for compatibility and its use in new applications 195is not recommended. 196.Sh RETURN VALUES 197.Fn OCSP_sendreq_new 198returns a valid 199.Vt OCSP_REQ_CTX 200structure or 201.Dv NULL 202if an error occurred. 203.Pp 204.Fn OCSP_sendreq_nbio 205returns 1 if the operation was completed successfully, 206-1 if the operation should be retried, 207or 0 if an error occurred. 208.Pp 209.Fn OCSP_REQ_CTX_add1_header 210and 211.Fn OCSP_REQ_CTX_set1_req 212return 1 for success or 0 for failure. 213.Pp 214.Fn OCSP_sendreq_bio 215returns the 216.Vt OCSP_RESPONSE 217structure sent by the responder or 218.Dv NULL 219if an error occurred. 220.Sh EXAMPLES 221Add a Host header for 222.Pa ocsp.com : 223.Pp 224.Dl OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com"); 225.Sh SEE ALSO 226.Xr OCSP_cert_to_id 3 , 227.Xr OCSP_request_add1_nonce 3 , 228.Xr OCSP_REQUEST_new 3 , 229.Xr OCSP_resp_find_status 3 , 230.Xr OCSP_response_status 3 231.Sh CAVEATS 232These functions only perform a minimal HTTP query to a responder. 233If an application wishes to support more advanced features, it 234should use an alternative, more complete, HTTP library. 235.Pp 236Currently only HTTP POST queries to responders are supported. 237