diff options
Diffstat (limited to 'doc/ocsp-api.texi')
| -rw-r--r-- | doc/ocsp-api.texi | 758 |
1 files changed, 758 insertions, 0 deletions
diff --git a/doc/ocsp-api.texi b/doc/ocsp-api.texi new file mode 100644 index 0000000..f3183ed --- /dev/null +++ b/doc/ocsp-api.texi @@ -0,0 +1,758 @@ + +@subheading gnutls_ocsp_req_add_cert +@anchor{gnutls_ocsp_req_add_cert} +@deftypefun {int} {gnutls_ocsp_req_add_cert} (gnutls_ocsp_req_t @var{req}, gnutls_digest_algorithm_t @var{digest}, gnutls_x509_crt_t @var{issuer}, gnutls_x509_crt_t @var{cert}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +@var{digest}: hash algorithm, a @code{gnutls_digest_algorithm_t} value + +@var{issuer}: issuer of @code{subject} certificate + +@var{cert}: certificate to request status for + +This function will add another request to the OCSP request for a +particular certificate. The issuer name hash, issuer key hash, and +serial number fields is populated as follows. The issuer name and +the serial number is taken from @code{cert} . The issuer key is taken +from @code{issuer} . The hashed values will be hashed using the @code{digest} algorithm, normally @code{GNUTLS_DIG_SHA1} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_req_add_cert_id +@anchor{gnutls_ocsp_req_add_cert_id} +@deftypefun {int} {gnutls_ocsp_req_add_cert_id} (gnutls_ocsp_req_t @var{req}, gnutls_digest_algorithm_t @var{digest}, const gnutls_datum_t * @var{issuer_name_hash}, const gnutls_datum_t * @var{issuer_key_hash}, const gnutls_datum_t * @var{serial_number}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +@var{digest}: hash algorithm, a @code{gnutls_digest_algorithm_t} value + +@var{issuer_name_hash}: hash of issuer's DN + +@var{issuer_key_hash}: hash of issuer's public key + +@var{serial_number}: serial number of certificate to check + +This function will add another request to the OCSP request for a +particular certificate having the issuer name hash of + @code{issuer_name_hash} and issuer key hash of @code{issuer_key_hash} (both +hashed using @code{digest} ) and serial number @code{serial_number} . + +The information needed corresponds to the CertID structure: + +<informalexample><programlisting> +CertID ::= SEQUENCE @{ +hashAlgorithm AlgorithmIdentifier, +issuerNameHash OCTET STRING, -- Hash of Issuer's DN +issuerKeyHash OCTET STRING, -- Hash of Issuers public key +serialNumber CertificateSerialNumber @} +</programlisting></informalexample> + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_req_deinit +@anchor{gnutls_ocsp_req_deinit} +@deftypefun {void} {gnutls_ocsp_req_deinit} (gnutls_ocsp_req_t @var{req}) +@var{req}: The data to be deinitialized + +This function will deinitialize a OCSP request structure. +@end deftypefun + +@subheading gnutls_ocsp_req_export +@anchor{gnutls_ocsp_req_export} +@deftypefun {int} {gnutls_ocsp_req_export} (gnutls_ocsp_req_const_t @var{req}, gnutls_datum_t * @var{data}) +@var{req}: Holds the OCSP request + +@var{data}: newly allocate buffer holding DER encoded OCSP request + +This function will export the OCSP request to DER format. + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. +@end deftypefun + +@subheading gnutls_ocsp_req_get_cert_id +@anchor{gnutls_ocsp_req_get_cert_id} +@deftypefun {int} {gnutls_ocsp_req_get_cert_id} (gnutls_ocsp_req_const_t @var{req}, unsigned @var{indx}, gnutls_digest_algorithm_t * @var{digest}, gnutls_datum_t * @var{issuer_name_hash}, gnutls_datum_t * @var{issuer_key_hash}, gnutls_datum_t * @var{serial_number}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +@var{indx}: Specifies which extension OID to get. Use (0) to get the first one. + +@var{digest}: output variable with @code{gnutls_digest_algorithm_t} hash algorithm + +@var{issuer_name_hash}: output buffer with hash of issuer's DN + +@var{issuer_key_hash}: output buffer with hash of issuer's public key + +@var{serial_number}: output buffer with serial number of certificate to check + +This function will return the certificate information of the + @code{indx} 'ed request in the OCSP request. The information returned +corresponds to the CertID structure: + +<informalexample><programlisting> +CertID ::= SEQUENCE @{ +hashAlgorithm AlgorithmIdentifier, +issuerNameHash OCTET STRING, -- Hash of Issuer's DN +issuerKeyHash OCTET STRING, -- Hash of Issuers public key +serialNumber CertificateSerialNumber @} +</programlisting></informalexample> + +Each of the pointers to output variables may be NULL to indicate +that the caller is not interested in that value. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. If you have reached the last +CertID available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be +returned. +@end deftypefun + +@subheading gnutls_ocsp_req_get_extension +@anchor{gnutls_ocsp_req_get_extension} +@deftypefun {int} {gnutls_ocsp_req_get_extension} (gnutls_ocsp_req_const_t @var{req}, unsigned @var{indx}, gnutls_datum_t * @var{oid}, unsigned int * @var{critical}, gnutls_datum_t * @var{data}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +@var{indx}: Specifies which extension OID to get. Use (0) to get the first one. + +@var{oid}: will hold newly allocated buffer with OID of extension, may be NULL + +@var{critical}: output variable with critical flag, may be NULL. + +@var{data}: will hold newly allocated buffer with extension data, may be NULL + +This function will return all information about the requested +extension in the OCSP request. The information returned is the +OID, the critical flag, and the data itself. The extension OID +will be stored as a string. Any of @code{oid} , @code{critical} , and @code{data} may +be NULL which means that the caller is not interested in getting +that information back. + +The caller needs to deallocate memory by calling @code{gnutls_free()} on + @code{oid} ->data and @code{data} ->data. + +Since 3.7.0 @code{oid} ->size does not account for the terminating null byte. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. If you have reached the last +extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will +be returned. +@end deftypefun + +@subheading gnutls_ocsp_req_get_nonce +@anchor{gnutls_ocsp_req_get_nonce} +@deftypefun {int} {gnutls_ocsp_req_get_nonce} (gnutls_ocsp_req_const_t @var{req}, unsigned int * @var{critical}, gnutls_datum_t * @var{nonce}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +@var{critical}: whether nonce extension is marked critical, or NULL + +@var{nonce}: will hold newly allocated buffer with nonce data + +This function will return the OCSP request nonce extension data. + +The caller needs to deallocate memory by calling @code{gnutls_free()} on + @code{nonce} ->data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_req_get_version +@anchor{gnutls_ocsp_req_get_version} +@deftypefun {int} {gnutls_ocsp_req_get_version} (gnutls_ocsp_req_const_t @var{req}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +This function will return the version of the OCSP request. +Typically this is always 1 indicating version 1. + +@strong{Returns:} version of OCSP request, or a negative error code on error. +@end deftypefun + +@subheading gnutls_ocsp_req_import +@anchor{gnutls_ocsp_req_import} +@deftypefun {int} {gnutls_ocsp_req_import} (gnutls_ocsp_req_t @var{req}, const gnutls_datum_t * @var{data}) +@var{req}: The data to store the parsed request. + +@var{data}: DER encoded OCSP request. + +This function will convert the given DER encoded OCSP request to +the native @code{gnutls_ocsp_req_t} format. The output will be stored in + @code{req} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_req_init +@anchor{gnutls_ocsp_req_init} +@deftypefun {int} {gnutls_ocsp_req_init} (gnutls_ocsp_req_t * @var{req}) +@var{req}: A pointer to the type to be initialized + +This function will initialize an OCSP request structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_req_print +@anchor{gnutls_ocsp_req_print} +@deftypefun {int} {gnutls_ocsp_req_print} (gnutls_ocsp_req_const_t @var{req}, gnutls_ocsp_print_formats_t @var{format}, gnutls_datum_t * @var{out}) +@var{req}: The data to be printed + +@var{format}: Indicate the format to use + +@var{out}: Newly allocated datum with (0) terminated string. + +This function will pretty print a OCSP request, suitable for +display to a human. + +If the format is @code{GNUTLS_OCSP_PRINT_FULL} then all fields of the +request will be output, on multiple lines. + +The output @code{out} ->data needs to be deallocate using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_req_randomize_nonce +@anchor{gnutls_ocsp_req_randomize_nonce} +@deftypefun {int} {gnutls_ocsp_req_randomize_nonce} (gnutls_ocsp_req_t @var{req}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +This function will add or update an nonce extension to the OCSP +request with a newly generated random value. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_req_set_extension +@anchor{gnutls_ocsp_req_set_extension} +@deftypefun {int} {gnutls_ocsp_req_set_extension} (gnutls_ocsp_req_t @var{req}, const char * @var{oid}, unsigned int @var{critical}, const gnutls_datum_t * @var{data}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +@var{oid}: buffer with OID of extension as a string. + +@var{critical}: critical flag, normally false. + +@var{data}: the extension data + +This function will add an extension to the OCSP request. Calling +this function multiple times for the same OID will overwrite values +from earlier calls. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_req_set_nonce +@anchor{gnutls_ocsp_req_set_nonce} +@deftypefun {int} {gnutls_ocsp_req_set_nonce} (gnutls_ocsp_req_t @var{req}, unsigned int @var{critical}, const gnutls_datum_t * @var{nonce}) +@var{req}: should contain a @code{gnutls_ocsp_req_t} type + +@var{critical}: critical flag, normally false. + +@var{nonce}: the nonce data + +This function will add an nonce extension to the OCSP request. +Calling this function multiple times will overwrite values from +earlier calls. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_resp_check_crt +@anchor{gnutls_ocsp_resp_check_crt} +@deftypefun {int} {gnutls_ocsp_resp_check_crt} (gnutls_ocsp_resp_const_t @var{resp}, unsigned int @var{indx}, gnutls_x509_crt_t @var{crt}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{indx}: Specifies response number to get. Use (0) to get the first one. + +@var{crt}: The certificate to check + +This function will check whether the OCSP response +is about the provided certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_ocsp_resp_deinit +@anchor{gnutls_ocsp_resp_deinit} +@deftypefun {void} {gnutls_ocsp_resp_deinit} (gnutls_ocsp_resp_t @var{resp}) +@var{resp}: The data to be deinitialized + +This function will deinitialize a OCSP response structure. +@end deftypefun + +@subheading gnutls_ocsp_resp_export +@anchor{gnutls_ocsp_resp_export} +@deftypefun {int} {gnutls_ocsp_resp_export} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_datum_t * @var{data}) +@var{resp}: Holds the OCSP response + +@var{data}: newly allocate buffer holding DER encoded OCSP response + +This function will export the OCSP response to DER format. + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. +@end deftypefun + +@subheading gnutls_ocsp_resp_export2 +@anchor{gnutls_ocsp_resp_export2} +@deftypefun {int} {gnutls_ocsp_resp_export2} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{fmt}) +@var{resp}: Holds the OCSP response + +@var{data}: newly allocate buffer holding DER or PEM encoded OCSP response + +@var{fmt}: DER or PEM + +This function will export the OCSP response to DER or PEM format. + +@strong{Returns:} In case of failure a negative error code will be +returned, and 0 on success. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_ocsp_resp_get_certs +@anchor{gnutls_ocsp_resp_get_certs} +@deftypefun {int} {gnutls_ocsp_resp_get_certs} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_x509_crt_t ** @var{certs}, size_t * @var{ncerts}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{certs}: newly allocated array with @code{gnutls_x509_crt_t} certificates + +@var{ncerts}: output variable with number of allocated certs. + +This function will extract the X.509 certificates found in the +Basic OCSP Response. The @code{certs} output variable will hold a newly +allocated zero-terminated array with X.509 certificates. + +Every certificate in the array needs to be de-allocated with +@code{gnutls_x509_crt_deinit()} and the array itself must be freed using +@code{gnutls_free()} . + +Both the @code{certs} and @code{ncerts} variables may be NULL. Then the +function will work as normal but will not return the NULL:d +information. This can be used to get the number of certificates +only, or to just get the certificate array without its size. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_extension +@anchor{gnutls_ocsp_resp_get_extension} +@deftypefun {int} {gnutls_ocsp_resp_get_extension} (gnutls_ocsp_resp_const_t @var{resp}, unsigned @var{indx}, gnutls_datum_t * @var{oid}, unsigned int * @var{critical}, gnutls_datum_t * @var{data}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{indx}: Specifies which extension OID to get. Use (0) to get the first one. + +@var{oid}: will hold newly allocated buffer with OID of extension, may be NULL + +@var{critical}: output variable with critical flag, may be NULL. + +@var{data}: will hold newly allocated buffer with extension data, may be NULL + +This function will return all information about the requested +extension in the OCSP response. The information returned is the +OID, the critical flag, and the data itself. The extension OID +will be stored as a string. Any of @code{oid} , @code{critical} , and @code{data} may +be NULL which means that the caller is not interested in getting +that information back. + +The caller needs to deallocate memory by calling @code{gnutls_free()} on + @code{oid} ->data and @code{data} ->data. + +Since 3.7.0 @code{oid} ->size does not account for the terminating null byte. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. If you have reached the last +extension available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will +be returned. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_nonce +@anchor{gnutls_ocsp_resp_get_nonce} +@deftypefun {int} {gnutls_ocsp_resp_get_nonce} (gnutls_ocsp_resp_const_t @var{resp}, unsigned int * @var{critical}, gnutls_datum_t * @var{nonce}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{critical}: whether nonce extension is marked critical + +@var{nonce}: will hold newly allocated buffer with nonce data + +This function will return the Basic OCSP Response nonce extension +data. + +The caller needs to deallocate memory by calling @code{gnutls_free()} on + @code{nonce} ->data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_produced +@anchor{gnutls_ocsp_resp_get_produced} +@deftypefun {time_t} {gnutls_ocsp_resp_get_produced} (gnutls_ocsp_resp_const_t @var{resp}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +This function will return the time when the OCSP response was +signed. + +@strong{Returns:} signing time, or (time_t)-1 on error. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_responder +@anchor{gnutls_ocsp_resp_get_responder} +@deftypefun {int} {gnutls_ocsp_resp_get_responder} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_datum_t * @var{dn}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{dn}: newly allocated buffer with name + +This function will extract the name of the Basic OCSP Response in +the provided buffer. The name will be in the form +"C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string +will be ASCII or UTF-8 encoded, depending on the certificate data. + +If the responder ID is not a name but a hash, this function +will return zero and the @code{dn} elements will be set to @code{NULL} . + +The caller needs to deallocate memory by calling @code{gnutls_free()} on + @code{dn} ->data. + +This function does not output a fully RFC4514 compliant string, if +that is required see @code{gnutls_ocsp_resp_get_responder2()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. When no data exist it will +return success and set @code{dn} elements to zero. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_responder2 +@anchor{gnutls_ocsp_resp_get_responder2} +@deftypefun {int} {gnutls_ocsp_resp_get_responder2} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_datum_t * @var{dn}, unsigned @var{flags}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{dn}: newly allocated buffer with name + +@var{flags}: zero or @code{GNUTLS_X509_DN_FLAG_COMPAT} + +This function will extract the name of the Basic OCSP Response in +the provided buffer. The name will be in the form +"C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string +will be ASCII or UTF-8 encoded, depending on the certificate data. + +If the responder ID is not a name but a hash, this function +will return zero and the @code{dn} elements will be set to @code{NULL} . + +The caller needs to deallocate memory by calling @code{gnutls_free()} on + @code{dn} ->data. + +When the flag @code{GNUTLS_X509_DN_FLAG_COMPAT} is specified, the output +format will match the format output by previous to 3.5.6 versions of GnuTLS +which was not not fully RFC4514-compliant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. When no data exist it will return +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} . +@end deftypefun + +@subheading gnutls_ocsp_resp_get_responder_raw_id +@anchor{gnutls_ocsp_resp_get_responder_raw_id} +@deftypefun {int} {gnutls_ocsp_resp_get_responder_raw_id} (gnutls_ocsp_resp_const_t @var{resp}, unsigned @var{type}, gnutls_datum_t * @var{raw}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{type}: should be @code{GNUTLS_OCSP_RESP_ID_KEY} or @code{GNUTLS_OCSP_RESP_ID_DN} + +@var{raw}: newly allocated buffer with the raw ID + +This function will extract the raw key (or DN) ID of the Basic OCSP Response in +the provided buffer. If the responder ID is not a key ID then +this function will return @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} . + +The caller needs to deallocate memory by calling @code{gnutls_free()} on + @code{dn} ->data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_response +@anchor{gnutls_ocsp_resp_get_response} +@deftypefun {int} {gnutls_ocsp_resp_get_response} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_datum_t * @var{response_type_oid}, gnutls_datum_t * @var{response}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{response_type_oid}: newly allocated output buffer with response type OID + +@var{response}: newly allocated output buffer with DER encoded response + +This function will extract the response type OID in and the +response data from an OCSP response. Normally the + @code{response_type_oid} is always "1.3.6.1.5.5.7.48.1.1" which means the + @code{response} should be decoded as a Basic OCSP Response, but +technically other response types could be used. + +This function is typically only useful when you want to extract the +response type OID of an response for diagnostic purposes. +Otherwise @code{gnutls_ocsp_resp_import()} will decode the basic OCSP +response part and the caller need not worry about that aspect. + +Since 3.7.0 @code{response_type_oid} ->size does not account for the terminating +null byte. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_signature +@anchor{gnutls_ocsp_resp_get_signature} +@deftypefun {int} {gnutls_ocsp_resp_get_signature} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_datum_t * @var{sig}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{sig}: newly allocated output buffer with signature data + +This function will extract the signature field of a OCSP response. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_signature_algorithm +@anchor{gnutls_ocsp_resp_get_signature_algorithm} +@deftypefun {int} {gnutls_ocsp_resp_get_signature_algorithm} (gnutls_ocsp_resp_const_t @var{resp}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +This function will return a value of the @code{gnutls_sign_algorithm_t} +enumeration that is the signature algorithm that has been used to +sign the OCSP response. + +@strong{Returns:} a @code{gnutls_sign_algorithm_t} value, or a negative error code +on error. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_single +@anchor{gnutls_ocsp_resp_get_single} +@deftypefun {int} {gnutls_ocsp_resp_get_single} (gnutls_ocsp_resp_const_t @var{resp}, unsigned @var{indx}, gnutls_digest_algorithm_t * @var{digest}, gnutls_datum_t * @var{issuer_name_hash}, gnutls_datum_t * @var{issuer_key_hash}, gnutls_datum_t * @var{serial_number}, unsigned int * @var{cert_status}, time_t * @var{this_update}, time_t * @var{next_update}, time_t * @var{revocation_time}, unsigned int * @var{revocation_reason}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{indx}: Specifies response number to get. Use (0) to get the first one. + +@var{digest}: output variable with @code{gnutls_digest_algorithm_t} hash algorithm + +@var{issuer_name_hash}: output buffer with hash of issuer's DN + +@var{issuer_key_hash}: output buffer with hash of issuer's public key + +@var{serial_number}: output buffer with serial number of certificate to check + +@var{cert_status}: a certificate status, a @code{gnutls_ocsp_cert_status_t} enum. + +@var{this_update}: time at which the status is known to be correct. + +@var{next_update}: when newer information will be available, or (time_t)-1 if unspecified + +@var{revocation_time}: when @code{cert_status} is @code{GNUTLS_OCSP_CERT_REVOKED} , holds time of revocation. + +@var{revocation_reason}: revocation reason, a @code{gnutls_x509_crl_reason_t} enum. + +This function will return the certificate information of the + @code{indx} 'ed response in the Basic OCSP Response @code{resp} . The +information returned corresponds to the OCSP SingleResponse structure +except the final singleExtensions. + +Each of the pointers to output variables may be NULL to indicate +that the caller is not interested in that value. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error code is returned. If you have reached the last +CertID available @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be +returned. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_status +@anchor{gnutls_ocsp_resp_get_status} +@deftypefun {int} {gnutls_ocsp_resp_get_status} (gnutls_ocsp_resp_const_t @var{resp}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +This function will return the status of a OCSP response, an +@code{gnutls_ocsp_resp_status_t} enumeration. + +@strong{Returns:} status of OCSP request as a @code{gnutls_ocsp_resp_status_t} , or +a negative error code on error. +@end deftypefun + +@subheading gnutls_ocsp_resp_get_version +@anchor{gnutls_ocsp_resp_get_version} +@deftypefun {int} {gnutls_ocsp_resp_get_version} (gnutls_ocsp_resp_const_t @var{resp}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +This function will return the version of the Basic OCSP Response. +Typically this is always 1 indicating version 1. + +@strong{Returns:} version of Basic OCSP response, or a negative error code +on error. +@end deftypefun + +@subheading gnutls_ocsp_resp_import +@anchor{gnutls_ocsp_resp_import} +@deftypefun {int} {gnutls_ocsp_resp_import} (gnutls_ocsp_resp_t @var{resp}, const gnutls_datum_t * @var{data}) +@var{resp}: The data to store the parsed response. + +@var{data}: DER encoded OCSP response. + +This function will convert the given DER encoded OCSP response to +the native @code{gnutls_ocsp_resp_t} format. It also decodes the Basic +OCSP Response part, if any. The output will be stored in @code{resp} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_resp_import2 +@anchor{gnutls_ocsp_resp_import2} +@deftypefun {int} {gnutls_ocsp_resp_import2} (gnutls_ocsp_resp_t @var{resp}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{fmt}) +@var{resp}: The data to store the parsed response. + +@var{data}: DER or PEM encoded OCSP response. + +@var{fmt}: DER or PEM + +This function will convert the given OCSP response to +the native @code{gnutls_ocsp_resp_t} format. It also decodes the Basic +OCSP Response part, if any. The output will be stored in @code{resp} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_ocsp_resp_init +@anchor{gnutls_ocsp_resp_init} +@deftypefun {int} {gnutls_ocsp_resp_init} (gnutls_ocsp_resp_t * @var{resp}) +@var{resp}: A pointer to the type to be initialized + +This function will initialize an OCSP response structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_resp_list_import2 +@anchor{gnutls_ocsp_resp_list_import2} +@deftypefun {int} {gnutls_ocsp_resp_list_import2} (gnutls_ocsp_resp_t ** @var{ocsps}, unsigned int * @var{size}, const gnutls_datum_t * @var{resp_data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags}) +@var{ocsps}: Will hold the parsed OCSP response list. + +@var{size}: It will contain the size of the list. + +@var{resp_data}: The PEM encoded OCSP list. + +@var{format}: One of @code{GNUTLS_X509_FMT_PEM} or @code{GNUTLS_X509_FMT_DER} + +@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags. + +This function will convert the given PEM encoded OCSP response list +to the native gnutls_ocsp_resp_t format. The output will be stored +in @code{ocsps} which will be allocated and initialized. + +The OCSP responses should have a header of "OCSP RESPONSE". + +To deinitialize responses, you need to deinitialize each @code{gnutls_ocsp_resp_t} +structure independently, and use @code{gnutls_free()} at @code{ocsps} . + +In PEM files, when no OCSP responses are detected +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. + +@strong{Returns:} the number of responses read or a negative error value. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_ocsp_resp_print +@anchor{gnutls_ocsp_resp_print} +@deftypefun {int} {gnutls_ocsp_resp_print} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_ocsp_print_formats_t @var{format}, gnutls_datum_t * @var{out}) +@var{resp}: The data to be printed + +@var{format}: Indicate the format to use + +@var{out}: Newly allocated datum with (0) terminated string. + +This function will pretty print a OCSP response, suitable for +display to a human. + +If the format is @code{GNUTLS_OCSP_PRINT_FULL} then all fields of the +response will be output, on multiple lines. + +The output @code{out} ->data needs to be deallocate using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_resp_verify +@anchor{gnutls_ocsp_resp_verify} +@deftypefun {int} {gnutls_ocsp_resp_verify} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_x509_trust_list_t @var{trustlist}, unsigned int * @var{verify}, unsigned int @var{flags}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{trustlist}: trust anchors as a @code{gnutls_x509_trust_list_t} type + +@var{verify}: output variable with verification status, an @code{gnutls_ocsp_verify_reason_t} + +@var{flags}: verification flags from @code{gnutls_certificate_verify_flags} + +Verify signature of the Basic OCSP Response against the public key +in the certificate of a trusted signer. The @code{trustlist} should be +populated with trust anchors. The function will extract the signer +certificate from the Basic OCSP Response and will verify it against +the @code{trustlist} . A trusted signer is a certificate that is either +in @code{trustlist} , or it is signed directly by a certificate in + @code{trustlist} and has the id-ad-ocspSigning Extended Key Usage bit +set. + +The output @code{verify} variable will hold verification status codes +(e.g., @code{GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND} , +@code{GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM} ) which are only valid if the +function returned @code{GNUTLS_E_SUCCESS} . + +Note that the function returns @code{GNUTLS_E_SUCCESS} even when +verification failed. The caller must always inspect the @code{verify} variable to find out the verification status. + +The @code{flags} variable should be 0 for now. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_ocsp_resp_verify_direct +@anchor{gnutls_ocsp_resp_verify_direct} +@deftypefun {int} {gnutls_ocsp_resp_verify_direct} (gnutls_ocsp_resp_const_t @var{resp}, gnutls_x509_crt_t @var{issuer}, unsigned int * @var{verify}, unsigned int @var{flags}) +@var{resp}: should contain a @code{gnutls_ocsp_resp_t} type + +@var{issuer}: certificate believed to have signed the response + +@var{verify}: output variable with verification status, an @code{gnutls_ocsp_verify_reason_t} + +@var{flags}: verification flags from @code{gnutls_certificate_verify_flags} + +Verify signature of the Basic OCSP Response against the public key +in the @code{issuer} certificate. + +The output @code{verify} variable will hold verification status codes +(e.g., @code{GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND} , +@code{GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM} ) which are only valid if the +function returned @code{GNUTLS_E_SUCCESS} . + +Note that the function returns @code{GNUTLS_E_SUCCESS} even when +verification failed. The caller must always inspect the @code{verify} variable to find out the verification status. + +The @code{flags} variable should be 0 for now. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + |