BRANCH-README - serf - Git at Google

 Support for OCSP Verification in Serf
 =====================================

 Serf trunk currently supports OCSP stapling for verifying server
 certificates. The purpose of this branch is to add minimal support
 for issuing OCSP requests to responders from the client application.

 The idea is that the application decides when and where to send OCSP
 requests and how to verify responses, and Serf provides some basic
 utility functions for constructing the requests and parsing the
 responses.

 These are the proposed changes:

 1. serf_ssl_cert_certificate()

    Extract the OCSP responder locations from the certificate's x509v3
    extension field authorityInfoAccess:OCSP;URI and, if it is present,
    insert the array into the returned hash table with key "OCSP".


 2. serf_ssl_cert_export2()

    /**
     * Export a certificate to base64-encoded, zero-terminated string.
     * The returned string is allocated in @a result_pool.
     * Uses @a scratch_pool for temporary allocations.
     * Returns NULL on failure.
     */
    const char *serf_ssl_cert_export2(
        const serf_ssl_certificate_t *cert,
        apr_pool_t *result_pool,
        apr_pool_t *scratch_pool);


    Discussion:

      serf_ssl_cert_export() uses a single pool for both the result and
      for teporary allocations. The size of the temporary buffer is on
      the order of the size of the result, so if we can use a scratch
      pool for that, we can effectively halve the memory used by
      exported certs.


 3. serf_ssl_cert_import()

    Add a new function that is the inverse of serf_ssl_cert_export():

    /**
     * Import a certificate from a base64-encoded, zero-terminated string.
     * The returned certificate is allocated in @a result_pool.
     * Uses @a scratch_pool for temporary allocations.
     * Returns NULL on failure.
     */
    serf_ssl_certificate_t *serf_ssl_cert_import(
        const char *encoded_cert,
        apr_pool_t *result_pool,
        apr_pool_t *scratch_pool);

    Discussion:

      In order to create an OCSP request, the application needs both
      the server certificate and its issuer certificate. An application
      may have to issue OCSP requests independently and asynchronously
      of any other processing, so it's nice if it can store the
      certificates in a form that's independent of pool lifetimes. We
      provide this form with serf_ssl_cert_export(), but there's no
      easy way to consume the exported form in existing Serf APIs
      (writing it to a file in PEM format and reading it back through
      serf_ssl_load_cert_file() is neither easy nor sane).


 4. OCSP requests

    Add a new opaque type and accessor functions that can be used from
    within a request setup handler to create an OCSP request.

    Discussion:

      HTTP OCSP requests can be sent using eithe the GET or POST
      methods; see https://www.ietf.org/rfc/rfc2560.txt section A.1.1.
      It's up to the application to decide which method to use, so we
      don't provide a function to create the request body or set
      request headers.

    /**
     * Internal representation of an OCSP request.
     */
    typedef struct serf_ssl_ocsp_request_t serf_ssl_ocsp_request_t;

    /**
     * Constructs an OCSP verification request for @a server_cert with
     * issuer certificate @a issuer_cert. If @a generate_nonce is
     * non-zero, the request will contain a random nonce.
     *
     * The request will be allocated from @a result_pool.
     *
     * Use @a scratch_pool for temporary allocations.
     *
     * Returns @c NULL on failure, e.g., if @a issuer_cert is not the
     * issuer certificate of @a server_cert.
     */
    serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_create(
        const serf_ssl_certificate_t *server_cert,
        const serf_ssl_certificate_t *issuer_cert,
        int generate_nonce,
        apr_pool_t *result_pool,
        apr_pool_t *scratch_pool);

    /**
     * Returns an pointer to the DER-encoded OCSP request
     * body within the @a ocsp_request structure.
     *
     * The application must decide whether to use this data as the body of
     * an HTTP POST request or Base64-encoded as part of the URI for a GET
     * request; see RFC 2560, section A.1.1.
     *
     * @see serf_ssl_ocsp_request_body_size()
     */
    const void *serf_ssl_ocsp_request_body(
        const serf_ssl_ocsp_request_t *ocsp_request);

    /**
     * Returns the size of the DER-encoded OCSP request body.
     * @see serf_ssl_ocsp_request_body().
     */
    apr_size_t serf_ssl_ocsp_request_body_size(
        const serf_ssl_ocsp_request_t *ocsp_request);

    /**
     * Export @a ocsp_request to a zero-terminated string,
     * allocated from @a result_pool.
     *
     * Use @a scratch_pool for temporary allocations.
     *
     * Returns @c NULL on failure.
     */
    const char *serf_ssl_ocsp_request_export(
        const serf_ssl_ocsp_request_t *ocsp_request,
        apr_pool_t *result_pool,
        apr_pool_t *scratch_pool);

    /**
     * Create an OCSP request from a previously exported zero-terminated
     * string @a encoded_ocsp_request. The returned request will be
     * allocated from @a result_pool.
     *
     * Use @a scratch_pool for temporary allocations.
     *
     * Returns @c NULL on failure.
     */
    serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_import(
        const char *encoded_ocsp_request,
        apr_pool_t *result_pool,
        apr_pool_t *scratch_pool);


 5. OCSP responses

    Add a new opaque type, response body parser and response validator.

    Add a new function that can be used from within a response handler
    to verify an OCSP response:

    Discussion:

      Parses and verifies the OCSP response received in the HTTP response
      body as per RFC 2560, section 3.2.

    /**
     * Internal representation of an OCSP response.
     */
    typedef struct serf_ssl_ocsp_response_t serf_ssl_ocsp_response_t;

    /**
     * Parse the body of an OCSP response in DER form, @a ocsp_response,
     * of size @a ocsp_response_size, and construct an internal
     * representation, allocated from @a result_pool.
     *
     * If @a failures is not @c NULL, it will be set as in
     * #serf_ssl_need_server_cert_t.
     *
     * Use @a scratch_pool for temporary allocations.
     *
     * Returns @c NULL if on failure.
     */
    serf_ssl_ocsp_response_t *serf_ssl_ocsp_response_parse(
        const void *ocsp_response,
        apr_size_t ocsp_response_size,
        int *failures,
        apr_pool_t *result_pool,
        apr_pool_t *scratch_pool);

    /**
     * Check if the given @a ocsp_response is valid for the given
     * @a ocsp_request in the provided @a ssl_ctx, as defined by
     * the algorithm documented in RFC 2560, section 3.5.
     *
     * The OCSP responder and application wall clocks may be out of sync
     * by @a clock_skew, and @a max_age is the acceptable age of the
     * request. Their values are truncated to the nearest second.
     *
     * The returned value will be:
     *
     *   - APR_SUCCESS,
     *     if all steps of the verification succeeded;
     *   - SERF_ERROR_SSL_OCSP_RESPONSE_CERT_REVOKED,
     *     if the certificate was revoked;
     *   - SERF_ERROR_SSL_OCSP_RESPONSE_CERT_UNKNOWN,
     *     if the responder knows nothing about the certificate;
     *   - SERF_ERROR_SSL_OCSP_RESPONSE_INVALID,
     *     if the response itself is invalid or not well-formed.
     *
     * The @a this_update and @a next_update output arguments are
     * described in RFC 2560, section 2.4 and, when not @c NULL and if the
     * verificateion succeeded, will be parsed from the response. Any of
     * these times that are not present in the response will be set to the
     * epoch, i.e., @c APR_TIME_C(0).
     *
     * Uses @a scratch_pool for temporary allocations.
     */
    apr_status_t serf_ssl_ocsp_response_verify(
        serf_ssl_context_t *ssl_ctx,
        const serf_ssl_ocsp_response_t *ocsp_response,
        const serf_ssl_ocsp_request_t *ocsp_request,
        apr_time_t clock_skew,
        apr_time_t max_age,
        apr_time_t *this_update,
        apr_time_t *next_update,
        apr_pool_t *scratch_pool);


 6. New error codes and macros

        #define SERF_ERROR_SSL_OCSP_RESPONSE_CERT_REVOKED
        #define SERF_ERROR_SSL_OCSP_RESPONSE_CERT_UNKNOWN
        #define SERF_ERROR_SSL_OCSP_RESPONSE_INVALID

        #define SERF_OCSP_UNGOOD_ERROR(status)

    Discussion:

      These error codes are returned from serf_ssl_ocsp_response_verify().
      The SERF_OCSP_UNGOOD_ERROR() macro combines the _CERT_REVOKED
      and _CERT_UNKNOWN error codes..
	Support for OCSP Verification in Serf
	=====================================

	Serf trunk currently supports OCSP stapling for verifying server
	certificates. The purpose of this branch is to add minimal support
	for issuing OCSP requests to responders from the client application.

	The idea is that the application decides when and where to send OCSP
	requests and how to verify responses, and Serf provides some basic
	utility functions for constructing the requests and parsing the
	responses.

	These are the proposed changes:

	1. serf_ssl_cert_certificate()

	Extract the OCSP responder locations from the certificate's x509v3
	extension field authorityInfoAccess:OCSP;URI and, if it is present,
	insert the array into the returned hash table with key "OCSP".


	2. serf_ssl_cert_export2()

	/**
	* Export a certificate to base64-encoded, zero-terminated string.
	* The returned string is allocated in @a result_pool.
	* Uses @a scratch_pool for temporary allocations.
	* Returns NULL on failure.
	*/
	const char *serf_ssl_cert_export2(
	const serf_ssl_certificate_t *cert,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);


	Discussion:

	serf_ssl_cert_export() uses a single pool for both the result and
	for teporary allocations. The size of the temporary buffer is on
	the order of the size of the result, so if we can use a scratch
	pool for that, we can effectively halve the memory used by
	exported certs.


	3. serf_ssl_cert_import()

	Add a new function that is the inverse of serf_ssl_cert_export():

	/**
	* Import a certificate from a base64-encoded, zero-terminated string.
	* The returned certificate is allocated in @a result_pool.
	* Uses @a scratch_pool for temporary allocations.
	* Returns NULL on failure.
	*/
	serf_ssl_certificate_t *serf_ssl_cert_import(
	const char *encoded_cert,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);

	Discussion:

	In order to create an OCSP request, the application needs both
	the server certificate and its issuer certificate. An application
	may have to issue OCSP requests independently and asynchronously
	of any other processing, so it's nice if it can store the
	certificates in a form that's independent of pool lifetimes. We
	provide this form with serf_ssl_cert_export(), but there's no
	easy way to consume the exported form in existing Serf APIs
	(writing it to a file in PEM format and reading it back through
	serf_ssl_load_cert_file() is neither easy nor sane).


	4. OCSP requests

	Add a new opaque type and accessor functions that can be used from
	within a request setup handler to create an OCSP request.

	Discussion:

	HTTP OCSP requests can be sent using eithe the GET or POST
	methods; see https://www.ietf.org/rfc/rfc2560.txt section A.1.1.
	It's up to the application to decide which method to use, so we
	don't provide a function to create the request body or set
	request headers.

	/**
	* Internal representation of an OCSP request.
	*/
	typedef struct serf_ssl_ocsp_request_t serf_ssl_ocsp_request_t;

	/**
	* Constructs an OCSP verification request for @a server_cert with
	* issuer certificate @a issuer_cert. If @a generate_nonce is
	* non-zero, the request will contain a random nonce.
	*
	* The request will be allocated from @a result_pool.
	*
	* Use @a scratch_pool for temporary allocations.
	*
	* Returns @c NULL on failure, e.g., if @a issuer_cert is not the
	* issuer certificate of @a server_cert.
	*/
	serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_create(
	const serf_ssl_certificate_t *server_cert,
	const serf_ssl_certificate_t *issuer_cert,
	int generate_nonce,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);

	/**
	* Returns an pointer to the DER-encoded OCSP request
	* body within the @a ocsp_request structure.
	*
	* The application must decide whether to use this data as the body of
	* an HTTP POST request or Base64-encoded as part of the URI for a GET
	* request; see RFC 2560, section A.1.1.
	*
	* @see serf_ssl_ocsp_request_body_size()
	*/
	const void *serf_ssl_ocsp_request_body(
	const serf_ssl_ocsp_request_t *ocsp_request);

	/**
	* Returns the size of the DER-encoded OCSP request body.
	* @see serf_ssl_ocsp_request_body().
	*/
	apr_size_t serf_ssl_ocsp_request_body_size(
	const serf_ssl_ocsp_request_t *ocsp_request);

	/**
	* Export @a ocsp_request to a zero-terminated string,
	* allocated from @a result_pool.
	*
	* Use @a scratch_pool for temporary allocations.
	*
	* Returns @c NULL on failure.
	*/
	const char *serf_ssl_ocsp_request_export(
	const serf_ssl_ocsp_request_t *ocsp_request,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);

	/**
	* Create an OCSP request from a previously exported zero-terminated
	* string @a encoded_ocsp_request. The returned request will be
	* allocated from @a result_pool.
	*
	* Use @a scratch_pool for temporary allocations.
	*
	* Returns @c NULL on failure.
	*/
	serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_import(
	const char *encoded_ocsp_request,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);


	5. OCSP responses

	Add a new opaque type, response body parser and response validator.

	Add a new function that can be used from within a response handler
	to verify an OCSP response:

	Discussion:

	Parses and verifies the OCSP response received in the HTTP response
	body as per RFC 2560, section 3.2.

	/**
	* Internal representation of an OCSP response.
	*/
	typedef struct serf_ssl_ocsp_response_t serf_ssl_ocsp_response_t;

	/**
	* Parse the body of an OCSP response in DER form, @a ocsp_response,
	* of size @a ocsp_response_size, and construct an internal
	* representation, allocated from @a result_pool.
	*
	* If @a failures is not @c NULL, it will be set as in
	* #serf_ssl_need_server_cert_t.
	*
	* Use @a scratch_pool for temporary allocations.
	*
	* Returns @c NULL if on failure.
	*/
	serf_ssl_ocsp_response_t *serf_ssl_ocsp_response_parse(
	const void *ocsp_response,
	apr_size_t ocsp_response_size,
	int *failures,
	apr_pool_t *result_pool,
	apr_pool_t *scratch_pool);

	/**
	* Check if the given @a ocsp_response is valid for the given
	* @a ocsp_request in the provided @a ssl_ctx, as defined by
	* the algorithm documented in RFC 2560, section 3.5.
	*
	* The OCSP responder and application wall clocks may be out of sync
	* by @a clock_skew, and @a max_age is the acceptable age of the
	* request. Their values are truncated to the nearest second.
	*
	* The returned value will be:
	*
	* - APR_SUCCESS,
	* if all steps of the verification succeeded;
	* - SERF_ERROR_SSL_OCSP_RESPONSE_CERT_REVOKED,
	* if the certificate was revoked;
	* - SERF_ERROR_SSL_OCSP_RESPONSE_CERT_UNKNOWN,
	* if the responder knows nothing about the certificate;
	* - SERF_ERROR_SSL_OCSP_RESPONSE_INVALID,
	* if the response itself is invalid or not well-formed.
	*
	* The @a this_update and @a next_update output arguments are
	* described in RFC 2560, section 2.4 and, when not @c NULL and if the
	* verificateion succeeded, will be parsed from the response. Any of
	* these times that are not present in the response will be set to the
	* epoch, i.e., @c APR_TIME_C(0).
	*
	* Uses @a scratch_pool for temporary allocations.
	*/
	apr_status_t serf_ssl_ocsp_response_verify(
	serf_ssl_context_t *ssl_ctx,
	const serf_ssl_ocsp_response_t *ocsp_response,
	const serf_ssl_ocsp_request_t *ocsp_request,
	apr_time_t clock_skew,
	apr_time_t max_age,
	apr_time_t *this_update,
	apr_time_t *next_update,
	apr_pool_t *scratch_pool);


	6. New error codes and macros

	#define SERF_ERROR_SSL_OCSP_RESPONSE_CERT_REVOKED
	#define SERF_ERROR_SSL_OCSP_RESPONSE_CERT_UNKNOWN
	#define SERF_ERROR_SSL_OCSP_RESPONSE_INVALID

	#define SERF_OCSP_UNGOOD_ERROR(status)

	Discussion:

	These error codes are returned from serf_ssl_ocsp_response_verify().
	The SERF_OCSP_UNGOOD_ERROR() macro combines the _CERT_REVOKED
	and _CERT_UNKNOWN error codes..