Merged the ocsp-verification branch.
git-svn-id: https://svn.apache.org/repos/asf/serf/trunk@1830823 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/BRANCH-README b/BRANCH-README
deleted file mode 100644
index 16de82a..0000000
--- a/BRANCH-README
+++ /dev/null
@@ -1,245 +0,0 @@
-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..
