Apache2
HTTP Protocol Handling
Collaboration diagram for HTTP Protocol Handling:

Data Structures

struct  etag_rec
 A structure with the ingredients for a file based etag. More...
 
struct  ap_bucket_error
 A bucket referring to an HTTP error. More...
 
struct  ap_bucket_request
 A bucket referring to a HTTP request. More...
 
struct  ap_bucket_response
 A bucket referring to a HTTP response. More...
 
struct  ap_bucket_headers
 A bucket referring to an HTTP header set. More...
 

Macros

#define AP_METHOD_CHECK_ALLOWED(mask, methname)    ((mask) & (AP_METHOD_BIT << ap_method_number_of((methname))))
 
#define AP_GET_BASIC_AUTH_PW_NOTE   "AP_GET_BASIC_AUTH_PW_NOTE"
 
#define AP_GETLINE_FOLD   (1 << 0) /* Whether to merge continuation lines */
 
#define AP_GETLINE_CRLF   (1 << 1) /* Whether line ends must be CRLF */
 
#define AP_GETLINE_NOSPC_EOL
 
#define AP_GETLINE_NONBLOCK   (1 << 3) /* Whether to read non-blocking */
 
#define AP_PROTOCOL_HTTP1   "http/1.1"
 
#define AP_BUCKET_IS_ERROR(e)   (e->type == &ap_bucket_type_error)
 
#define AP_BUCKET_IS_REQUEST(e)   (e->type == &ap_bucket_type_request)
 
#define AP_BUCKET_IS_RESPONSE(e)   (e->type == &ap_bucket_type_response)
 
#define AP_BUCKET_IS_HEADERS(e)   (e->type == &ap_bucket_type_headers)
 

Typedefs

typedef struct etag_rec etag_rec
 
typedef struct ap_bucket_error ap_bucket_error
 
typedef struct ap_bucket_request ap_bucket_request
 
typedef struct ap_bucket_response ap_bucket_response
 
typedef struct ap_bucket_headers ap_bucket_headers
 
typedef void ap_ssl_ocsp_copy_resp(const unsigned char *der, apr_size_t der_len, void *userdata)
 

Enumerations

enum  ap_condition_e { AP_CONDITION_NONE , AP_CONDITION_NOMATCH , AP_CONDITION_WEAK , AP_CONDITION_STRONG }
 

Functions

request_recap_create_request (conn_rec *c)
 
request_recap_read_request (conn_rec *c)
 
int ap_assign_request_line (request_rec *r, const char *method, const char *uri, const char *protocol)
 
int ap_h1_tokenize_request_line (request_rec *r, const char *line, const char **pmethod, const char **puri, const char **pprotocol)
 
int ap_parse_request_line (request_rec *r)
 
int ap_check_request_header (request_rec *r)
 
void ap_get_mime_headers (request_rec *r)
 
void ap_get_mime_headers_core (request_rec *r, apr_bucket_brigade *bb)
 
int ap_post_read_request (request_rec *r)
 
void ap_finalize_request_protocol (request_rec *r)
 
void ap_send_error_response (request_rec *r, int recursive_error)
 
void ap_set_content_length (request_rec *r, apr_off_t length)
 
int ap_set_keepalive (request_rec *r)
 
apr_time_t ap_rationalize_mtime (request_rec *r, apr_time_t mtime)
 
const char * ap_make_content_type (request_rec *r, const char *type)
 
void ap_setup_make_content_type (apr_pool_t *pool)
 
char * ap_make_etag (request_rec *r, int force_weak)
 
char * ap_make_etag_ex (request_rec *r, etag_rec *er)
 
void ap_set_etag (request_rec *r)
 
void ap_set_etag_fd (request_rec *r, apr_file_t *fd)
 
void ap_set_last_modified (request_rec *r)
 
ap_condition_e ap_condition_if_match (request_rec *r, apr_table_t *headers)
 
ap_condition_e ap_condition_if_unmodified_since (request_rec *r, apr_table_t *headers)
 
ap_condition_e ap_condition_if_none_match (request_rec *r, apr_table_t *headers)
 
ap_condition_e ap_condition_if_modified_since (request_rec *r, apr_table_t *headers)
 
ap_condition_e ap_condition_if_range (request_rec *r, apr_table_t *headers)
 
int ap_meets_conditions (request_rec *r)
 
apr_status_t ap_send_fd (apr_file_t *fd, request_rec *r, apr_off_t offset, apr_size_t length, apr_size_t *nbytes)
 
apr_size_t ap_send_mmap (apr_mmap_t *mm, request_rec *r, apr_size_t offset, apr_size_t length)
 
int ap_method_register (apr_pool_t *p, const char *methname)
 
void ap_method_registry_init (apr_pool_t *p)
 
ap_method_list_tap_make_method_list (apr_pool_t *p, int nelts)
 
void ap_copy_method_list (ap_method_list_t *dest, ap_method_list_t *src)
 
int ap_method_in_list (ap_method_list_t *l, const char *method)
 
void ap_method_list_add (ap_method_list_t *l, const char *method)
 
void ap_method_list_remove (ap_method_list_t *l, const char *method)
 
void ap_clear_method_list (ap_method_list_t *l)
 
void ap_set_content_type (request_rec *r, const char *ct)
 
void ap_set_accept_ranges (request_rec *r)
 
int ap_rputc (int c, request_rec *r)
 
int ap_rwrite (const void *buf, int nbyte, request_rec *r)
 
int ap_rvputs (request_rec *r,...) AP_FN_ATTR_SENTINEL
 
int ap_vrprintf (request_rec *r, const char *fmt, va_list vlist)
 
int ap_rprintf (request_rec *r, const char *fmt,...) __attribute__((format(printf
 
int int ap_rflush (request_rec *r)
 
int ap_index_of_response (int status)
 
const char * ap_get_status_line (int status)
 
const char * ap_get_status_line_ex (apr_pool_t *p, int status)
 
int ap_setup_client_block (request_rec *r, int read_policy)
 
int ap_should_client_block (request_rec *r)
 
long ap_get_client_block (request_rec *r, char *buffer, apr_size_t bufsiz)
 
int ap_map_http_request_error (apr_status_t rv, int status)
 
int ap_discard_request_body (request_rec *r)
 
void ap_note_auth_failure (request_rec *r)
 
void ap_note_basic_auth_failure (request_rec *r)
 
void ap_note_digest_auth_failure (request_rec *r)
 
int note_auth_failure (request_rec *r, const char *auth_type)
 
int ap_get_basic_auth_pw (request_rec *r, const char **pw)
 
apr_status_t ap_get_basic_auth_components (const request_rec *r, const char **username, const char **password)
 
void ap_parse_uri (request_rec *r, const char *uri)
 
int ap_getline (char *s, int n, request_rec *r, int flags)
 
apr_status_t ap_fgetline (char **s, apr_size_t n, apr_size_t *read, ap_filter_t *f, int flags, apr_bucket_brigade *bb, apr_pool_t *p)
 
apr_status_t ap_rgetline (char **s, apr_size_t n, apr_size_t *read, request_rec *r, int flags, apr_bucket_brigade *bb)
 
int ap_method_number_of (const char *method)
 
const char * ap_method_name_of (apr_pool_t *p, int methnum)
 
void pre_read_request (request_rec *r, conn_rec *c)
 
int post_read_request (request_rec *r)
 
int log_transaction (request_rec *r)
 
const char * http_scheme (const request_rec *r)
 
apr_port_t default_port (const request_rec *r)
 
int protocol_propose (conn_rec *c, request_rec *r, server_rec *s, const apr_array_header_t *offers, apr_array_header_t *proposals)
 
int protocol_switch (conn_rec *c, request_rec *r, server_rec *s, const char *protocol)
 
const char * protocol_get (const conn_rec *c)
 
apr_status_t ap_get_protocol_upgrades (conn_rec *c, request_rec *r, server_rec *s, int report_all, const apr_array_header_t **pupgrades)
 
const char * ap_select_protocol (conn_rec *c, request_rec *r, server_rec *s, const apr_array_header_t *choices)
 
apr_status_t ap_switch_protocol (conn_rec *c, request_rec *r, server_rec *s, const char *protocol)
 
const char * ap_get_protocol (conn_rec *c)
 
int ap_is_allowed_protocol (conn_rec *c, request_rec *r, server_rec *s, const char *protocol)
 
apr_bucketap_bucket_error_make (apr_bucket *b, int error, const char *buf, apr_pool_t *p)
 
apr_bucketap_bucket_error_create (int error, const char *buf, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_bucketap_bucket_request_make (apr_bucket *b, const char *method, const char *uri, const char *protocol, apr_table_t *headers, apr_pool_t *p)
 
apr_bucketap_bucket_request_maken (apr_bucket *b, const char *method, const char *uri, const char *protocol, apr_table_t *headers, apr_pool_t *p)
 
apr_bucketap_bucket_request_create (const char *method, const char *uri, const char *protocol, apr_table_t *headers, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_bucketap_bucket_request_createn (const char *method, const char *uri, const char *protocol, apr_table_t *headers, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_bucketap_bucket_request_clone (apr_bucket *source, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_bucketap_bucket_response_make (apr_bucket *b, int status, const char *reason, apr_table_t *headers, apr_table_t *notes, apr_pool_t *p)
 
apr_bucketap_bucket_response_create (int status, const char *reason, apr_table_t *headers, apr_table_t *notes, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_bucketap_bucket_response_clone (apr_bucket *source, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_bucketap_bucket_headers_make (apr_bucket *b, apr_table_t *headers, apr_pool_t *p)
 
apr_bucketap_bucket_headers_create (apr_table_t *headers, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_bucketap_bucket_headers_clone (apr_bucket *source, apr_pool_t *p, apr_bucket_alloc_t *list)
 
apr_status_t ap_byterange_filter (ap_filter_t *f, apr_bucket_brigade *b)
 
apr_status_t ap_http_header_filter (ap_filter_t *f, apr_bucket_brigade *b)
 
apr_status_t ap_content_length_filter (ap_filter_t *, apr_bucket_brigade *)
 
apr_status_t ap_old_write_filter (ap_filter_t *f, apr_bucket_brigade *b)
 
void ap_set_sub_req_protocol (request_rec *rnew, const request_rec *r)
 
void ap_finalize_sub_req_protocol (request_rec *sub_r)
 
void ap_set_std_response_headers (request_rec *r)
 
void ap_send_interim_response (request_rec *r, int send_headers)
 
apr_status_t ap_h1_append_header (apr_bucket_brigade *b, apr_pool_t *pool, const char *name, const char *value)
 
apr_status_t ap_h1_append_headers (apr_bucket_brigade *b, request_rec *r, apr_table_t *headers)
 
apr_status_t ap_h1_terminate_header (apr_bucket_brigade *b)
 
void ap_h1_add_end_chunk (apr_bucket_brigade *b, apr_bucket *eos, request_rec *r, apr_table_t *trailers)
 
int ap_ssl_conn_is_ssl (conn_rec *c)
 
int ssl_bind_outgoing (conn_rec *c, struct ap_conf_vector_t *dir_conf, int enable_ssl)
 
int ap_ssl_bind_outgoing (conn_rec *c, struct ap_conf_vector_t *dir_conf, int require_ssl)
 
int ap_ssl_has_outgoing_handlers (void)
 
const char * ap_ssl_var_lookup (apr_pool_t *p, server_rec *s, conn_rec *c, request_rec *r, const char *name)
 
int ssl_add_cert_files (server_rec *s, apr_pool_t *p, apr_array_header_t *cert_files, apr_array_header_t *key_files)
 
apr_status_t ap_ssl_add_cert_files (server_rec *s, apr_pool_t *p, apr_array_header_t *cert_files, apr_array_header_t *key_files)
 
int ssl_add_fallback_cert_files (server_rec *s, apr_pool_t *p, apr_array_header_t *cert_files, apr_array_header_t *key_files)
 
apr_status_t ap_ssl_add_fallback_cert_files (server_rec *s, apr_pool_t *p, apr_array_header_t *cert_files, apr_array_header_t *key_files)
 
int ssl_answer_challenge (conn_rec *c, const char *server_name, const char **pcert_pem, const char **pkey_pem)
 
int ap_ssl_answer_challenge (conn_rec *c, const char *server_name, const char **pcert_pem, const char **pkey_pem)
 
void ap_setup_ssl_optional_fns (apr_pool_t *pool)
 
int ssl_ocsp_prime_hook (server_rec *s, apr_pool_t *p, const char *id, apr_size_t id_len, const char *pem)
 
apr_status_t ap_ssl_ocsp_prime (server_rec *s, apr_pool_t *p, const char *id, apr_size_t id_len, const char *pem)
 
int ssl_ocsp_get_resp_hook (server_rec *s, conn_rec *c, const char *id, apr_size_t id_len, ap_ssl_ocsp_copy_resp *cb, void *userdata)
 
apr_status_t ap_ssl_ocsp_get_resp (server_rec *s, conn_rec *c, const char *id, apr_size_t id_len, ap_ssl_ocsp_copy_resp *cb, void *userdata)
 

Variables

AP_DECLARE_DATA ap_filter_rec_tap_old_write_func
 
AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_error
 
AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_request
 
AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_response
 
AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_headers
 

Detailed Description

Macro Definition Documentation

◆ AP_BUCKET_IS_ERROR

#define AP_BUCKET_IS_ERROR (   e)    (e->type == &ap_bucket_type_error)

Determine if a bucket is an error bucket

Parameters
eThe bucket to inspect
Returns
true or false

◆ AP_BUCKET_IS_HEADERS

#define AP_BUCKET_IS_HEADERS (   e)    (e->type == &ap_bucket_type_headers)

Determine if a bucket is an headers bucket

Parameters
eThe bucket to inspect
Returns
true or false

◆ AP_BUCKET_IS_REQUEST

#define AP_BUCKET_IS_REQUEST (   e)    (e->type == &ap_bucket_type_request)

Determine if a bucket is a request bucket

Parameters
eThe bucket to inspect
Returns
true or false

◆ AP_BUCKET_IS_RESPONSE

#define AP_BUCKET_IS_RESPONSE (   e)    (e->type == &ap_bucket_type_response)

Determine if a bucket is a response bucket

Parameters
eThe bucket to inspect
Returns
true or false

◆ AP_GET_BASIC_AUTH_PW_NOTE

#define AP_GET_BASIC_AUTH_PW_NOTE   "AP_GET_BASIC_AUTH_PW_NOTE"

◆ AP_GETLINE_CRLF

#define AP_GETLINE_CRLF   (1 << 1) /* Whether line ends must be CRLF */

◆ AP_GETLINE_FOLD

#define AP_GETLINE_FOLD   (1 << 0) /* Whether to merge continuation lines */

◆ AP_GETLINE_NONBLOCK

#define AP_GETLINE_NONBLOCK   (1 << 3) /* Whether to read non-blocking */

◆ AP_GETLINE_NOSPC_EOL

#define AP_GETLINE_NOSPC_EOL
Value:
(1 << 2) /* Whether to consume up to and including
the end of line on APR_ENOSPC */

◆ AP_METHOD_CHECK_ALLOWED

#define AP_METHOD_CHECK_ALLOWED (   mask,
  methname 
)     ((mask) & (AP_METHOD_BIT << ap_method_number_of((methname))))

This is a convenience macro to ease with checking a mask against a method name.

◆ AP_PROTOCOL_HTTP1

#define AP_PROTOCOL_HTTP1   "http/1.1"

Typedef Documentation

◆ ap_bucket_error

◆ ap_bucket_headers

◆ ap_bucket_request

◆ ap_bucket_response

◆ ap_ssl_ocsp_copy_resp

typedef void ap_ssl_ocsp_copy_resp(const unsigned char *der, apr_size_t der_len, void *userdata)

Callback to copy over the OCSP response data. If OCSP response data is not available, this will be called with NULL, 0 parameters!

Memory allocation methods and lifetime of data will vary per module and SSL library used. The caller requesting OCSP data will need to make a copy for his own use. Any passed data may only be valid for the duration of the call.

◆ etag_rec

typedef struct etag_rec etag_rec

A structure with the ingredients for a file based etag

Enumeration Type Documentation

◆ ap_condition_e

Enumerator
AP_CONDITION_NONE 
AP_CONDITION_NOMATCH 
AP_CONDITION_WEAK 
AP_CONDITION_STRONG 

Function Documentation

◆ ap_assign_request_line()

int ap_assign_request_line ( request_rec r,
const char *  method,
const char *  uri,
const char *  protocol 
)

Assign the method, uri and protocol (in HTTP/1.x the items from the first line) to the request.

Parameters
rThe current request
methodthe HTTP method
urithe request uri
protocolthe request protocol
Returns
1 on success, 0 on failure

◆ ap_bucket_error_create()

apr_bucket* ap_bucket_error_create ( int  error,
const char *  buf,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Create a bucket referring to an HTTP error.

Parameters
errorThe HTTP error code to put in the bucket.
bufAn optional error string to put in the bucket.
pA pool to allocate the error string out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_error_make()

apr_bucket* ap_bucket_error_make ( apr_bucket b,
int  error,
const char *  buf,
apr_pool_t p 
)

Make the bucket passed in an error bucket

Parameters
bThe bucket to make into an error bucket
errorThe HTTP error code to put in the bucket.
bufAn optional error string to put in the bucket.
pA pool to allocate out of.
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_headers_clone()

apr_bucket* ap_bucket_headers_clone ( apr_bucket source,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Clone a HEADER bucket into another pool/bucket_alloc that may have a separate lifetime than the source bucket/pool.

Parameters
sourcethe header bucket to clone
pA pool to allocate the data out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_headers_create()

apr_bucket* ap_bucket_headers_create ( apr_table_t headers,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Create a bucket referring to a table of HTTP headers.

Parameters
headersthe HTTP headers in the bucket.
pA pool to allocate the error string out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_headers_make()

apr_bucket* ap_bucket_headers_make ( apr_bucket b,
apr_table_t headers,
apr_pool_t p 
)

Make the bucket passed in a headers bucket

Parameters
bThe bucket to make into a headers bucket
headersthe table of headers.
pA pool to allocate out of.
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_request_clone()

apr_bucket* ap_bucket_request_clone ( apr_bucket source,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Clone a request bucket into another pool/bucket_alloc that may have a separate lifetime than the source bucket/pool.

Parameters
sourcethe request bucket to clone
pA pool to allocate the data out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_request_create()

apr_bucket* ap_bucket_request_create ( const char *  method,
const char *  uri,
const char *  protocol,
apr_table_t headers,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Create a bucket referring to a HTTP request. Copies all parameters to the given pool.

Parameters
methodthe HTTP method
urithe uri requested
protocolthe protocol requested
headersthe table of response headers.
pA pool to allocate the error string out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_request_createn()

apr_bucket* ap_bucket_request_createn ( const char *  method,
const char *  uri,
const char *  protocol,
apr_table_t headers,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Create a bucket referring to a HTTP request. Uses all paramters without copying.

Parameters
methodthe HTTP method
urithe uri requested
protocolthe protocol requested
headersthe HTTP response headers.
pA pool to allocate the error string out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_request_make()

apr_bucket* ap_bucket_request_make ( apr_bucket b,
const char *  method,
const char *  uri,
const char *  protocol,
apr_table_t headers,
apr_pool_t p 
)

Make the bucket passed in a request bucket Copies all parameters to the given pool.

Parameters
bThe bucket to make into a request bucket
methodthe HTTP method
urithe uri requested
protocolthe protocol requested
headersthe table of response headers.
pA pool to allocate out of.
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_request_maken()

apr_bucket* ap_bucket_request_maken ( apr_bucket b,
const char *  method,
const char *  uri,
const char *  protocol,
apr_table_t headers,
apr_pool_t p 
)

Make the bucket passed in a request bucket Uses all paramters without copying.

Parameters
bThe bucket to make into a request bucket
methodthe HTTP method
urithe uri requested
protocolthe protocol requested
headersthe table of response headers.
pA pool to allocate out of.
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_response_clone()

apr_bucket* ap_bucket_response_clone ( apr_bucket source,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Clone a RESPONSE bucket into another pool/bucket_alloc that may have a separate lifetime than the source bucket/pool.

Parameters
sourcethe response bucket to clone
pA pool to allocate the data out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_response_create()

apr_bucket* ap_bucket_response_create ( int  status,
const char *  reason,
apr_table_t headers,
apr_table_t notes,
apr_pool_t p,
apr_bucket_alloc_t list 
)

Create a bucket referring to a HTTP response.

Parameters
statusThe HTTP status code.
reasontextual description of status, can be NULL.
headersthe HTTP response headers.
notesinternal notes on the response
pA pool to allocate the error string out of.
listThe bucket allocator from which to allocate the bucket
Returns
The new bucket, or NULL if allocation failed

◆ ap_bucket_response_make()

apr_bucket* ap_bucket_response_make ( apr_bucket b,
int  status,
const char *  reason,
apr_table_t headers,
apr_table_t notes,
apr_pool_t p 
)

Make the bucket passed in a response bucket

Parameters
bThe bucket to make into a response bucket
statusThe HTTP status code of the response.
reasontextual description of status, can be NULL.
headersthe table of response headers.
notesinternal notes on the response
pA pool to allocate out of.
Returns
The new bucket, or NULL if allocation failed

◆ ap_byterange_filter()

apr_status_t ap_byterange_filter ( ap_filter_t f,
apr_bucket_brigade b 
)

◆ ap_check_request_header()

int ap_check_request_header ( request_rec r)

Validate the request header and select vhost.

Parameters
rThe current request
Returns
1 on success, 0 on failure

◆ ap_clear_method_list()

void ap_clear_method_list ( ap_method_list_t l)

Reset a method list to be completely empty.

Parameters
lPointer to a method list, such as r->allowed_methods.
Returns
None.

◆ ap_condition_if_match()

ap_condition_e ap_condition_if_match ( request_rec r,
apr_table_t headers 
)

Tests conditional request rules for the If-Match header.

Parameters
rThe current request
headersThe response headers to check against
Returns
AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_STRONG for a strong match. Weak matches are not permitted for the If-Match header.

◆ ap_condition_if_modified_since()

ap_condition_e ap_condition_if_modified_since ( request_rec r,
apr_table_t headers 
)

Tests conditional request rules for the If-Modified-Since header.

Parameters
rThe current request
headersThe response headers to check against
Returns
AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_WEAK if a weak match was present and allowed by RFC2616, AP_CONDITION_STRONG for a strong match.

◆ ap_condition_if_none_match()

ap_condition_e ap_condition_if_none_match ( request_rec r,
apr_table_t headers 
)

Tests conditional request rules for the If-None-Match header.

Parameters
rThe current request
headersThe response headers to check against
Returns
AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_WEAK if a weak match was present and allowed by RFC2616, AP_CONDITION_STRONG for a strong match.

◆ ap_condition_if_range()

ap_condition_e ap_condition_if_range ( request_rec r,
apr_table_t headers 
)

Tests conditional request rules for the If-Range header.

Parameters
rThe current request
headersThe response headers to check against
Returns
AP_CONDITION_NONE if either the If-Range or Range header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_STRONG for a strong match. Weak matches are not permitted for the If-Range header.

◆ ap_condition_if_unmodified_since()

ap_condition_e ap_condition_if_unmodified_since ( request_rec r,
apr_table_t headers 
)

Tests conditional request rules for the If-Unmodified-Since header.

Parameters
rThe current request
headersThe response headers to check against
Returns
AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_WEAK if a weak match was present and allowed by RFC2616, AP_CONDITION_STRONG for a strong match.

◆ ap_content_length_filter()

apr_status_t ap_content_length_filter ( ap_filter_t ,
apr_bucket_brigade  
)

◆ ap_copy_method_list()

void ap_copy_method_list ( ap_method_list_t dest,
ap_method_list_t src 
)

Copy a method list

Parameters
destList to copy to
srcList to copy from

◆ ap_create_request()

request_rec* ap_create_request ( conn_rec c)

Read an empty request and set reasonable defaults.

Parameters
cThe current connection
Returns
The new request_rec

◆ ap_discard_request_body()

int ap_discard_request_body ( request_rec r)

In HTTP/1.1, any method can have a body. However, most GET handlers wouldn't know what to do with a request body if they received one. This helper routine tests for and reads any message body in the request, simply discarding whatever it receives. We need to do this because failing to read the request body would cause it to be interpreted as the next request on a persistent connection.

Parameters
rThe current request
Returns
error status if request is malformed, OK otherwise

◆ ap_fgetline()

apr_status_t ap_fgetline ( char **  s,
apr_size_t  n,
apr_size_t read,
ap_filter_t f,
int  flags,
apr_bucket_brigade bb,
apr_pool_t p 
)

Get the next line from an input filter

Parameters
sPointer to the pointer to the buffer into which the line should be read; if *s==NULL, a buffer of the necessary size to hold the data will be allocated from p
nThe size of the buffer
readThe length of the line.
fInput filter to read from
flagsBit mask of AP_GETLINE_* options
bbWorking brigade to use when reading buckets
pThe pool to allocate the buffer from (if needed)
Returns
APR_SUCCESS, if successful APR_ENOSPC, if the line is too big to fit in the buffer Other errors where appropriate

◆ ap_finalize_request_protocol()

void ap_finalize_request_protocol ( request_rec r)

Called at completion of sending the response. It sends the terminating protocol information.

Parameters
rThe current request

◆ ap_finalize_sub_req_protocol()

void ap_finalize_sub_req_protocol ( request_rec sub_r)

A wrapup function to keep the internal accounting straight. Indicates that there is no more content coming.

Parameters
sub_rSubrequest that is now compete

◆ ap_get_basic_auth_components()

apr_status_t ap_get_basic_auth_components ( const request_rec r,
const char **  username,
const char **  password 
)

Get the username and/or password from the request's Basic authentication headers. Unlike ap_get_basic_auth_pw(), calling this function has no side effects on the passed request_rec.

Parameters
rThe current request
usernameIf not NULL, set to the username sent by the client
passwordIf not NULL, set to the password sent by the client
Returns
APR_SUCCESS if the credentials were successfully parsed and returned; APR_EINVAL if there was no authentication header sent or if the client was not using the Basic authentication scheme. username and password are unchanged on failure.

◆ ap_get_basic_auth_pw()

int ap_get_basic_auth_pw ( request_rec r,
const char **  pw 
)

Get the password from the request headers. This function has multiple side effects due to its prior use in the old authentication framework, including setting r->user (which is supposed to indicate that the user in question has been authenticated for the current request).

Modules which call ap_get_basic_auth_pw() during the authentication phase MUST either immediately authenticate the user after the call, or else stop the request immediately with an error response, to avoid incorrectly authenticating the current request. (See CVE-2017-3167.) The replacement ap_get_basic_auth_components() API should be preferred.

Deprecated:
See also
ap_get_basic_auth_components
Parameters
rThe current request
pwThe password as set in the headers
Returns
0 (OK) if it set the 'pw' argument (and assured a correct value in r->user); otherwise it returns an error code, either HTTP_INTERNAL_SERVER_ERROR if things are really confused, HTTP_UNAUTHORIZED if no authentication at all seemed to be in use, or DECLINED if there was authentication but it wasn't Basic (in which case, the caller should presumably decline as well).

◆ ap_get_client_block()

long ap_get_client_block ( request_rec r,
char *  buffer,
apr_size_t  bufsiz 
)

Call this in a loop. It will put data into a buffer and return the length of the input block

Parameters
rThe current request
bufferThe buffer in which to store the data
bufsizThe size of the buffer
Returns
Number of bytes inserted into the buffer. When done reading, 0 if EOF, or -1 if there was an error

◆ ap_get_mime_headers()

void ap_get_mime_headers ( request_rec r)

Read the mime-encoded headers.

Parameters
rThe current request

◆ ap_get_mime_headers_core()

void ap_get_mime_headers_core ( request_rec r,
apr_bucket_brigade bb 
)

Optimized version of ap_get_mime_headers() that requires a temporary brigade to work with

Parameters
rThe current request
bbtemp brigade

◆ ap_get_protocol()

const char* ap_get_protocol ( conn_rec c)

Call the protocol_get hook to determine the protocol currently in use for the given connection.

Unless another protocol has been switch to, will default to

See also
AP_PROTOCOL_HTTP1 and modules implementing a new protocol must report a switched connection via the protocol_get hook.
Parameters
cThe connection to determine the protocol for
Returns
the protocol in use, never NULL

◆ ap_get_protocol_upgrades()

apr_status_t ap_get_protocol_upgrades ( conn_rec c,
request_rec r,
server_rec s,
int  report_all,
const apr_array_header_t **  pupgrades 
)

Get the protocols that the connection and optional request may upgrade to - besides the protocol currently active on the connection. These values may be used to announce to a client what choices it has.

If report_all == 0, only protocols more preferable than the one currently being used, are reported. Otherwise, all available protocols beside the current one are being reported.

Parameters
cThe current connection
rThe current request or NULL
sThe server/virtual host selected or NULL
report_allinclude also protocols less preferred than the current one
pupgradeson return, possible protocols to upgrade to in descending order of preference. Maybe NULL if none are available.

◆ ap_get_status_line()

const char* ap_get_status_line ( int  status)

Return the Status-Line for a given status code (excluding the HTTP-Version field). If an invalid or unknown status code is passed, "500 Internal Server Error" will be returned.

Parameters
statusThe HTTP status code
Returns
The Status-Line

◆ ap_get_status_line_ex()

const char* ap_get_status_line_ex ( apr_pool_t p,
int  status 
)

Return the Status-Line for a given status code (excluding the HTTP-Version field). If an invalid status code is passed, "500 Internal Server Error" will be returned, whereas an unknown status will be returned like "xxx Status xxx".

Parameters
pThe pool to allocate from when status is unknown
statusThe HTTP status code
Returns
The Status-Line

◆ ap_getline()

int ap_getline ( char *  s,
int  n,
request_rec r,
int  flags 
)

Get the next line of input for the request

Parameters
sThe buffer into which to read the line
nThe size of the buffer
rThe request
flagsBit mask of AP_GETLINE_* options
Returns
The length of the line, if successful n, if the line is too big to fit in the buffer -1 for miscellaneous errors

◆ ap_h1_add_end_chunk()

void ap_h1_add_end_chunk ( apr_bucket_brigade b,
apr_bucket eos,
request_rec r,
apr_table_t trailers 
)

Insert/Append the last chunk in a HTTP/1.1 Transfer-Encoding chunked.

Parameters
bthe brigade to add the chunk to
eosthe bucket before to add or NULL for insert at tail
rthe request handled
trailerstable of trailers or NULL

◆ ap_h1_append_header()

apr_status_t ap_h1_append_header ( apr_bucket_brigade b,
apr_pool_t pool,
const char *  name,
const char *  value 
)

Append a header in HTTP/1.1 format to the brigade.

Parameters
bthe brigade to append to
pthe pool to use
namethe name of the header field
valuethe value of the header field

◆ ap_h1_append_headers()

apr_status_t ap_h1_append_headers ( apr_bucket_brigade b,
request_rec r,
apr_table_t headers 
)

Append the headers in HTTP/1.1 format to the brigade.

Parameters
bthe brigade to append to
rthe request this is done for (pool and logging)
headersthe headers to append

◆ ap_h1_terminate_header()

apr_status_t ap_h1_terminate_header ( apr_bucket_brigade b)

Append the HTTP/1.1 header termination (empty CRLF) to the brigade.

Parameters
bthe brigade to append to

◆ ap_h1_tokenize_request_line()

int ap_h1_tokenize_request_line ( request_rec r,
const char *  line,
const char **  pmethod,
const char **  puri,
const char **  pprotocol 
)

Parse a HTTP/1.x request line, validate and return the components

Parameters
rThe current request
linethe line to parse
pmethodthe parsed method on success
purithe parsed uri on success
pprotocolthe parsed protocol on success
Returns
1 on success, 0 on failure

◆ ap_http_header_filter()

apr_status_t ap_http_header_filter ( ap_filter_t f,
apr_bucket_brigade b 
)

◆ ap_index_of_response()

int ap_index_of_response ( int  status)

Index used in custom_responses array for a specific error code (only use outside protocol.c is in getting them configured).

Parameters
statusHTTP status code
Returns
The index of the response

◆ ap_is_allowed_protocol()

int ap_is_allowed_protocol ( conn_rec c,
request_rec r,
server_rec s,
const char *  protocol 
)

Check if the given protocol is an allowed choice on the given combination of connection, request and server.

When server is NULL, it is taken from request_rec, unless request_rec is NULL. Then it is taken from the connection base server.

Parameters
cThe current connection
rThe current request or NULL
sThe server/virtual host selected or NULL
protocolthe protocol to switch to
Returns
!= 0 iff protocol is allowed

◆ ap_make_content_type()

const char* ap_make_content_type ( request_rec r,
const char *  type 
)

Build the content-type that should be sent to the client from the content-type specified. The following rules are followed:

  • if type is NULL or "", return NULL (do not set content-type).
  • if charset adding is disabled, stop processing and return type.
  • then, if there are no parameters on type, add the default charset
  • return type
    Parameters
    rThe current request
    typeThe content type
    Returns
    The content-type

◆ ap_make_etag()

char* ap_make_etag ( request_rec r,
int  force_weak 
)

Construct an entity tag from the resource information. If it's a real file, build in some of the file characteristics.

Parameters
rThe current request
force_weakForce the entity tag to be weak - it could be modified again in as short an interval.
Returns
The entity tag

◆ ap_make_etag_ex()

char* ap_make_etag_ex ( request_rec r,
etag_rec er 
)

Construct an entity tag from information provided in the etag_rec structure.

Parameters
rThe current request
erThe etag record, containing ingredients for the etag.

◆ ap_make_method_list()

ap_method_list_t* ap_make_method_list ( apr_pool_t p,
int  nelts 
)

Create a new method list with the specified number of preallocated slots for extension methods.

Parameters
pPointer to a pool in which the structure should be allocated.
neltsNumber of preallocated extension slots
Returns
Pointer to the newly created structure.

◆ ap_map_http_request_error()

int ap_map_http_request_error ( apr_status_t  rv,
int  status 
)

Map specific APR codes returned by the filter stack to HTTP error codes, or the default status code provided. Use it as follows:

return ap_map_http_request_error(rv, HTTP_BAD_REQUEST);

If the filter has already handled the error, AP_FILTER_ERROR will be returned, which is cleanly passed through.

These mappings imply that the filter stack is reading from the downstream client, the proxy will map these codes differently.

Parameters
rvAPR status code
statusDefault HTTP code should the APR code not be recognised
Returns
Mapped HTTP status code

◆ ap_meets_conditions()

int ap_meets_conditions ( request_rec r)

Implements condition GET rules for HTTP/1.1 specification. This function inspects the client headers and determines if the response fulfills the requirements specified.

Parameters
rThe current request
Returns
OK if the response fulfills the condition GET rules, some other status code otherwise

◆ ap_method_in_list()

int ap_method_in_list ( ap_method_list_t l,
const char *  method 
)

Search for an HTTP method name in an ap_method_list_t structure, and return true if found.

Parameters
methodString containing the name of the method to check.
lPointer to a method list, such as r->allowed_methods.
Returns
1 if method is in the list, otherwise 0

◆ ap_method_list_add()

void ap_method_list_add ( ap_method_list_t l,
const char *  method 
)

Add an HTTP method name to an ap_method_list_t structure if it isn't already listed.

Parameters
methodString containing the name of the method to check.
lPointer to a method list, such as r->allowed_methods.
Returns
None.

◆ ap_method_list_remove()

void ap_method_list_remove ( ap_method_list_t l,
const char *  method 
)

Remove an HTTP method name from an ap_method_list_t structure.

Parameters
lPointer to a method list, such as r->allowed_methods.
methodString containing the name of the method to remove.
Returns
None.

◆ ap_method_name_of()

const char* ap_method_name_of ( apr_pool_t p,
int  methnum 
)

Get the method name associated with the given internal method number. Returns NULL if not recognized.

Parameters
pA pool to use for temporary allocations.
methnumAn integer value corresponding to an internal method number
Returns
The name corresponding to the method number

◆ ap_method_number_of()

int ap_method_number_of ( const char *  method)

Get the method number associated with the given string, assumed to contain an HTTP method. Returns M_INVALID if not recognized.

Parameters
methodA string containing a valid HTTP method
Returns
The method number

◆ ap_method_register()

int ap_method_register ( apr_pool_t p,
const char *  methname 
)

Register a new request method, and return the offset that will be associated with that method.

Parameters
pThe pool to create registered method numbers from.
methnameThe name of the new method to register.
Returns
An int value representing an offset into a bitmask.

◆ ap_method_registry_init()

void ap_method_registry_init ( apr_pool_t p)

Initialize the method_registry and allocate memory for it.

Parameters
pPool to allocate memory for the registry from.

◆ ap_note_auth_failure()

void ap_note_auth_failure ( request_rec r)

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed.

Parameters
rThe current request

◆ ap_note_basic_auth_failure()

void ap_note_basic_auth_failure ( request_rec r)

◆ ap_note_digest_auth_failure()

void ap_note_digest_auth_failure ( request_rec r)

◆ ap_old_write_filter()

apr_status_t ap_old_write_filter ( ap_filter_t f,
apr_bucket_brigade b 
)

◆ ap_parse_request_line()

int ap_parse_request_line ( request_rec r)

Parse and validate the request line.

Parameters
rThe current request
Returns
1 on success, 0 on failure

◆ ap_parse_uri()

void ap_parse_uri ( request_rec r,
const char *  uri 
)

parse_uri: break apart the uri

Warning
Side Effects:
  • sets r->args to rest after '?' (or NULL if no '?')
  • sets r->uri to request uri (without r->args part)
  • sets r->hostname (if not set already) from request (scheme://host:port)
Parameters
rThe current request
uriThe uri to break apart

◆ ap_post_read_request()

int ap_post_read_request ( request_rec r)

Run post_read_request hook and validate.

Parameters
rThe current request
Returns
OK or HTTP_...

◆ ap_rationalize_mtime()

apr_time_t ap_rationalize_mtime ( request_rec r,
apr_time_t  mtime 
)

Return the latest rational time from a request/mtime pair. Mtime is returned unless it's in the future, in which case we return the current time.

Parameters
rThe current request
mtimeThe last modified time
Returns
the latest rational time.

◆ ap_read_request()

request_rec* ap_read_request ( conn_rec c)

Read a request and fill in the fields.

Parameters
cThe current connection
Returns
The new request_rec

◆ ap_rflush()

int int ap_rflush ( request_rec r)

Flush all of the data for the current request to the client

Parameters
rThe current request
Returns
0 on success, -1 if an error occurred

◆ ap_rgetline()

apr_status_t ap_rgetline ( char **  s,
apr_size_t  n,
apr_size_t read,
request_rec r,
int  flags,
apr_bucket_brigade bb 
)
See also
ap_fgetline

Note: genuinely calls, ap_fgetline(s, n, read, r->proto_input_filters, flags, bb, r->pool)

◆ ap_rprintf()

int ap_rprintf ( request_rec r,
const char *  fmt,
  ... 
)

Output data to the client in a printf format

Parameters
rThe current request
fmtThe format string
...The arguments to use to fill out the format string
Returns
The number of bytes sent

◆ ap_rputc()

int ap_rputc ( int  c,
request_rec r 
)

Output one character for this request

Parameters
cthe character to output
rthe current request
Returns
The number of bytes sent

◆ ap_rvputs()

int ap_rvputs ( request_rec r,
  ... 
)

Write an unspecified number of strings to the request

Parameters
rThe current request
...The strings to write
Returns
The number of bytes sent

◆ ap_rwrite()

int ap_rwrite ( const void *  buf,
int  nbyte,
request_rec r 
)

Write a buffer for the current request

Parameters
bufThe buffer to write
nbyteThe number of bytes to send from the buffer
rThe current request
Returns
The number of bytes sent

◆ ap_select_protocol()

const char* ap_select_protocol ( conn_rec c,
request_rec r,
server_rec s,
const apr_array_header_t choices 
)

Select a protocol for the given connection and optional request. Will return the protocol identifier selected which may be the protocol already in place on the connection. The selected protocol will be NULL if non of the given choices could be agreed upon (e.g. no proposal as made).

A special case is where the choices itself is NULL (instead of empty). In this case there are no restrictions imposed on protocol selection.

Parameters
cThe current connection
rThe current request or NULL
sThe server/virtual host selected
choicesA list of protocol identifiers, normally the client's wishes
Returns
The selected protocol or NULL if no protocol could be agreed upon

◆ ap_send_error_response()

void ap_send_error_response ( request_rec r,
int  recursive_error 
)

Send error back to client.

Parameters
rThe current request
recursive_errorlast arg indicates error status in case we get an error in the process of trying to deal with an ErrorDocument to handle some other error. In that case, we print the default report for the first thing that went wrong, and more briefly report on the problem with the ErrorDocument.

◆ ap_send_fd()

apr_status_t ap_send_fd ( apr_file_t fd,
request_rec r,
apr_off_t  offset,
apr_size_t  length,
apr_size_t nbytes 
)

Send an entire file to the client, using sendfile if supported by the current platform

Parameters
fdThe file to send.
rThe current request
offsetOffset into the file to start sending.
lengthAmount of data to send
nbytesAmount of data actually sent

◆ ap_send_interim_response()

void ap_send_interim_response ( request_rec r,
int  send_headers 
)

Send an interim (HTTP 1xx) response immediately.

Parameters
rThe request
send_headersWhether to send&clear headers in r->headers_out

◆ ap_send_mmap()

apr_size_t ap_send_mmap ( apr_mmap_t mm,
request_rec r,
apr_size_t  offset,
apr_size_t  length 
)

Send an MMAP'ed file to the client

Parameters
mmThe MMAP'ed file to send
rThe current request
offsetThe offset into the MMAP to start sending
lengthThe amount of data to send
Returns
The number of bytes sent

◆ ap_set_accept_ranges()

void ap_set_accept_ranges ( request_rec r)

Set the Accept-Ranges header for this response

Parameters
rThe current request

◆ ap_set_content_length()

void ap_set_content_length ( request_rec r,
apr_off_t  length 
)

Set the content length for this request

Parameters
rThe current request
lengthThe new content length

◆ ap_set_content_type()

void ap_set_content_type ( request_rec r,
const char *  ct 
)

Set the content type for this request (r->content_type).

Parameters
rThe current request
ctThe new content type
Warning
This function must be called to set r->content_type in order for the AddOutputFilterByType directive to work correctly.

◆ ap_set_etag()

void ap_set_etag ( request_rec r)

Set the E-tag outgoing header

Parameters
rThe current request

◆ ap_set_etag_fd()

void ap_set_etag_fd ( request_rec r,
apr_file_t fd 
)

Set the E-tag outgoing header, with the option of forcing a strong ETag.

Parameters
rThe current request
fdThe file descriptor

◆ ap_set_keepalive()

int ap_set_keepalive ( request_rec r)

Set the keepalive status for this request

Parameters
rThe current request
Returns
1 if keepalive can be set, 0 otherwise

◆ ap_set_last_modified()

void ap_set_last_modified ( request_rec r)

Set the last modified time for the file being sent

Parameters
rThe current request

◆ ap_set_std_response_headers()

void ap_set_std_response_headers ( request_rec r)

Set standard response headers, such as Date and Server in r->headers_out. Takes care of precedence of existing values from proxied requests.

◆ ap_set_sub_req_protocol()

void ap_set_sub_req_protocol ( request_rec rnew,
const request_rec r 
)

Sett up the protocol fields for subsidiary requests

Parameters
rnewNew Sub Request
rcurrent request

◆ ap_setup_client_block()

int ap_setup_client_block ( request_rec r,
int  read_policy 
)

Setup the client to allow Apache to read the request body.

Parameters
rThe current request
read_policyHow the server should interpret a chunked transfer-encoding. One of:
   REQUEST_NO_BODY          Send 413 error if message has any body
   REQUEST_CHUNKED_ERROR    Send 411 error if body without Content-Length
   REQUEST_CHUNKED_DECHUNK  If chunked, remove the chunks for me.
Returns
either OK or an error code

◆ ap_setup_make_content_type()

void ap_setup_make_content_type ( apr_pool_t pool)

Precompile metadata structures used by ap_make_content_type()

Parameters
poolThe pool to use for allocations

◆ ap_setup_ssl_optional_fns()

void ap_setup_ssl_optional_fns ( apr_pool_t pool)

Setup optional functions for ssl related queries so that functions registered by old-style SSL module functions are interrogated by the the new ap_is_ssl() and friends. Installs own optional functions, so that old modules looking for these find one and get the correct results (shadowing).

Needs to run in core's very early POST_CONFIG hook. Modules providing such functions register their own optionals during register_hooks(). Modules using such functions retrieve them often in their own post-config or in the even later retrieval hook. When shadowing other modules functions, core's early post-config is a good time.

Parameters
poolThe pool to use for allocations

◆ ap_should_client_block()

int ap_should_client_block ( request_rec r)

Determine if the client has sent any data. This also sends a 100 Continue response to HTTP/1.1 clients, so modules should not be called until the module is ready to read content.

Warning
Never call this function more than once.
Parameters
rThe current request
Returns
0 if there is no message to read, 1 otherwise

◆ ap_ssl_add_cert_files()

apr_status_t ap_ssl_add_cert_files ( server_rec s,
apr_pool_t p,
apr_array_header_t cert_files,
apr_array_header_t key_files 
)

Collect certificate/key files from all providers registered. This includes providers registered at the global 'ssl_add_cert_files', as well as those installed in the OPTIONAL 'ssl_add_cert_files' hook as may be provided by ssl modules.

Parameters
sthe server certificates are collected for
pthe pool to use for allocations
cert_filesan array of const char* with the path to the certificate chain
key_filesan array of const char* with the path to the private key file

◆ ap_ssl_add_fallback_cert_files()

apr_status_t ap_ssl_add_fallback_cert_files ( server_rec s,
apr_pool_t p,
apr_array_header_t cert_files,
apr_array_header_t key_files 
)

Collect 'fallback' certificate/key files from all registered providers, either in the global 'ssl_add_fallback_cert_files' hook or the optional one of similar name as provided by mod_ssl and sorts. Certificates obtained this way are commonly self signed, temporary crutches. To be used to the time it takes to retrieve a 'read', trusted certificate. A module using fallbacks is encouraged to answer all requests with a 503.

Parameters
sthe server certificates are collected for
pthe pool to use for allocations
cert_filesan array of const char* with the path to the certificate chain
key_filesan array of const char* with the path to the private key file

◆ ap_ssl_answer_challenge()

int ap_ssl_answer_challenge ( conn_rec c,
const char *  server_name,
const char **  pcert_pem,
const char **  pkey_pem 
)

Returns != 0 iff the connection is a challenge to the server, for example as defined in RFC 8555 for the 'tls-alpn-01' domain verification, and needs a specific certificate as answer in the handshake.

ALPN protocol negotiation via the hooks 'protocol_propose' and 'protocol_switch' need to have run before this call is made.

Certificate PEMs added must be accompanied by a private key PEM. The private key PEM may be given by a NULL pointer, in which case it is expected to be found in the certificate PEM string.

A certificate provided this way needs to replace any other certificates selected by configuration or 'ssl_add_cert_pems` on this connection.

◆ ap_ssl_bind_outgoing()

int ap_ssl_bind_outgoing ( conn_rec c,
struct ap_conf_vector_t dir_conf,
int  require_ssl 
)

Assures the connection is marked as outgoing and invokes the ssl_bind_outgoing hook. This may be called several times on an outgoing connection with varying dir_conf values. require_ssl is not allowed to change on the same connection.

Parameters
cThe connection on which requests/data are to be sent.
dir_confThe directory configuration in which this connection is being used.
require_ssl!= 0 iff this connection needs to be secured by SSL/TLS protocol.
Returns
OK iff ssl was required and is enabled, DECLINED otherwise

◆ ap_ssl_conn_is_ssl()

int ap_ssl_conn_is_ssl ( conn_rec c)

Return != 0 iff the connection is encrypted with SSL.

Parameters
cthe connection

◆ ap_ssl_has_outgoing_handlers()

int ap_ssl_has_outgoing_handlers ( void  )

Return != 0 iff handlers/hooks for outgoing connections are registered.

◆ ap_ssl_ocsp_get_resp()

apr_status_t ap_ssl_ocsp_get_resp ( server_rec s,
conn_rec c,
const char *  id,
apr_size_t  id_len,
ap_ssl_ocsp_copy_resp cb,
void *  userdata 
)

Retrieve the OCSP response data for a previously primed certificate. The id needs to be byte-wise identical to the one used on priming. If the call return ARP_SUCCESS, the callback has been invoked with the OCSP response DER data. Otherwise, a different status code must be returned. Callers in SSL connection handshakes are encouraged to continue the handshake without OCSP data for server reliability. The decision to accept or reject a handshake with missing OCSP stapling data needs to be done by the client. For similar reasons, providers of responses might return seemingly expired ones if they were unable to refresh a response in time.

The memory pointed to by id is only valid for the duration of the call. Also, the DER data passed to the callback is only valid for the duration of the call.

Parameters
sthe (SNI selected) server of the connection
cthe connection
ididentifier for the certifate, as used in ocsp_stapling_prime()
cbcallback to invoke when response data is available
userdatacaller supplied data passed to callback
Returns
APR_SUCCESS iff data has been provided

◆ ap_ssl_ocsp_prime()

apr_status_t ap_ssl_ocsp_prime ( server_rec s,
apr_pool_t p,
const char *  id,
apr_size_t  id_len,
const char *  pem 
)

Registering a certificate for Provisioning of OCSP responses. It is the caller's responsibility to provide a global (apache instance) unique id for the certificate that is then used later in retrieving the OCSP response. A certificate can be primed this way more than once, however the same identifier has to be provided each time (byte-wise same, not pointer same). The memory pointed to by id and pem is only valid for the duration of the call.

Parameters
sthe server being configured @params p a memory pool to use
idopaque data uniquely identifying the certificate, provided by caller
pemPEM data of certificate first, followed by chain certs, at least the issuer
Returns
APR_SUCCESS iff OCSP responses will be provided. APR_ENOENT when no provided was found or took responsibility.

◆ ap_ssl_var_lookup()

const char* ap_ssl_var_lookup ( apr_pool_t p,
server_rec s,
conn_rec c,
request_rec r,
const char *  name 
)

Lookup an SSL related variable for the server/connection/request or a global value when all those parameters are set to NULL. Pool and name must always be provided and the returned value (if not NULL) will be allocated from the pool.

Parameters
pThe pool to allocate a returned value in, MUST be provided
sThe server to inquire a value for, maybe NULL
cThe current connection, maybe NULL
rThe current request, maybe NULL
nameThe name of the variable to retrieve, MUST be provided
Returns
value or the variable or NULL if not provided/available

◆ ap_switch_protocol()

apr_status_t ap_switch_protocol ( conn_rec c,
request_rec r,
server_rec s,
const char *  protocol 
)

Perform the actual protocol switch. The protocol given must have been selected before on the very same connection and request pair.

Parameters
cThe current connection
rThe current request or NULL
sThe server/virtual host selected
protocolthe protocol to switch to
Returns
APR_SUCCESS, if caller may continue processing as usual APR_EOF, if caller needs to stop processing the connection APR_EINVAL, if the protocol is already in place APR_NOTIMPL, if no module performed the switch Other errors where appropriate

◆ ap_vrprintf()

int ap_vrprintf ( request_rec r,
const char *  fmt,
va_list  vlist 
)

Output data to the client in a printf format

Parameters
rThe current request
fmtThe format string
vlistThe arguments to use to fill out the format string
Returns
The number of bytes sent

◆ default_port()

apr_port_t default_port ( const request_rec r)

Return the default port from the current request

Parameters
rThe current request
Returns
The current port

◆ http_scheme()

const char* http_scheme ( const request_rec r)

This hook allows modules to retrieve the http scheme for a request. This allows Apache modules to easily extend the schemes that Apache understands

Parameters
rThe current request
Returns
The http scheme from the request

◆ log_transaction()

int log_transaction ( request_rec r)

This hook allows modules to perform any module-specific logging activities over and above the normal server things.

Parameters
rThe current request
Returns
OK, DECLINED, or HTTP_...

◆ note_auth_failure()

int note_auth_failure ( request_rec r,
const char *  auth_type 
)

This hook allows modules to add support for a specific auth type to ap_note_auth_failure

Parameters
rthe current request
auth_typethe configured auth_type
Returns
OK, DECLINED

◆ post_read_request()

int post_read_request ( request_rec r)

This hook allows modules to affect the request immediately after the request has been read, and before any other phases have been processes. This allows modules to make decisions based upon the input header fields

Parameters
rThe current request
Returns
OK or DECLINED

◆ pre_read_request()

void pre_read_request ( request_rec r,
conn_rec c 
)

This hook allows modules to affect the request or connection immediately before the request has been read, and before any other phases have been processes.

Parameters
rThe current request of the soon-to-be-read request
cThe connection
Returns
None/void

◆ protocol_get()

const char* protocol_get ( const conn_rec c)

Return the protocol used on the connection. Modules implementing protocol switching must register here and return the correct protocol identifier for connections they switched.

To find out the protocol for the current connection, better call

See also
ap_get_protocol which internally uses this hook.
Parameters
cThe current connection
Returns
The identifier of the protocol in place or NULL

◆ protocol_propose()

int protocol_propose ( conn_rec c,
request_rec r,
server_rec s,
const apr_array_header_t offers,
apr_array_header_t proposals 
)

Determine the list of protocols available for a connection/request. This may be collected with or without any request sent, in which case the request is NULL. Or it may be triggered by the request received, e.g. through the "Upgrade" header.

This hook will be run whenever protocols are being negotiated (ALPN as one example). It may also be invoked at other times, e.g. when the server wants to advertise protocols it is capable of switching to.

The identifiers for protocols are taken from the TLS extension type ALPN: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml

If no protocols are added to the proposals, the server not perform any switch. If the protocol selected from the proposals is the protocol already in place, also no protocol switch will be invoked.

The client may already have announced the protocols it is willing to accept. These will then be listed as offers. This parameter may also be NULL, indicating that offers from the client are not known and the hooks should propose all protocols that are valid for the current connection/request.

All hooks are run, unless one returns an error. Proposals may contain duplicates. The order in which proposals are added is usually ignored.

Parameters
cThe current connection
rThe current request or NULL
sThe server/virtual host selected
offersA list of protocol identifiers offered by the client or NULL to indicated that the hooks are free to propose
proposalsThe list of protocol identifiers proposed by the hooks
Returns
OK or DECLINED

◆ protocol_switch()

int protocol_switch ( conn_rec c,
request_rec r,
server_rec s,
const char *  protocol 
)

Perform a protocol switch on the connection. The exact requirements for that depend on the protocol in place and the one switched to. The first protocol module to handle the switch is the last module run.

For a connection level switch (r == NULL), the handler must on return leave the conn_rec in a state suitable for processing the switched protocol, e.g. correct filters in place.

For a request triggered switch (r != NULL), the protocol switch is done before the response is sent out. When switching from "http/1.1" via Upgrade header, the 101 intermediate response will have been sent. The hook needs then to process the connection until it can be closed. Which the server will enforce on hook return. Any error the hook might encounter must already be sent by the hook itself to the client in whatever form the new protocol requires.

Parameters
cThe current connection
rThe current request or NULL
sThe server/virtual host selected
protocolThe protocol identifier we try to switch to
Returns
OK or DECLINED

◆ ssl_add_cert_files()

int ssl_add_cert_files ( server_rec s,
apr_pool_t p,
apr_array_header_t cert_files,
apr_array_header_t key_files 
)

Register to provide certificate/key files for servers. Certificate files are expected to contain the certificate chain, beginning with the server's certificate, excluding the trust anchor, in PEM format. They must be accompanied by a private key file, also in PEM format.

Parameters
sthe server certificates are collected for
pthe pool to use for allocations
cert_filesan array of const char* with the path to the certificate chain
key_filesan array of const char* with the path to the private key file
Returns
OK if files were added, DECLINED if not, or other for error.

◆ ssl_add_fallback_cert_files()

int ssl_add_fallback_cert_files ( server_rec s,
apr_pool_t p,
apr_array_header_t cert_files,
apr_array_header_t key_files 
)

Register to provide 'fallback' certificates in case no 'real' certificates have been configured/added by other providers. Modules using these certificates are encouraged to answer requests to this server with a 503 response code.

Parameters
sthe server certificates are collected for
pthe pool to use for allocations
cert_filesan array of const char* with the path to the certificate chain
key_filesan array of const char* with the path to the private key file
Returns
OK if files were added, DECLINED if not, or other for error.

◆ ssl_answer_challenge()

int ssl_answer_challenge ( conn_rec c,
const char *  server_name,
const char **  pcert_pem,
const char **  pkey_pem 
)

On TLS connections that do not relate to a configured virtual host allow modules to provide a certificate and key to be used on the connection.

A Certificate PEM added must be accompanied by a private key PEM. The private key PEM may be given by a NULL pointer, in which case it is expected to be found in the certificate PEM string.

◆ ssl_bind_outgoing()

int ssl_bind_outgoing ( conn_rec c,
struct ap_conf_vector_t dir_conf,
int  enable_ssl 
)

This hook declares a connection to be outgoing and the configuration that applies to it. This hook can be called several times in the lifetime of an outgoing connection, e.g. when it is re-used in different request contexts. It will at least be called after the connection was created and before the pre-connection hooks is invoked. All outgoing-connection hooks are run until one returns something other than DECLINE. if enable_ssl != 0, a hook that sets up SSL for the connection needs to return OK to prevent subsequent hooks from doing the same.

Parameters
cThe connection on which requests/data are to be sent.
dir_confThe directory configuration in which this connection is being used.
enable_sslIf != 0, the SSL protocol should be enabled for this connection.
Returns
DECLINED, OK when ssl was enabled

◆ ssl_ocsp_get_resp_hook()

int ssl_ocsp_get_resp_hook ( server_rec s,
conn_rec c,
const char *  id,
apr_size_t  id_len,
ap_ssl_ocsp_copy_resp cb,
void *  userdata 
)

Asking for OCSP response DER data for a certificate formerly primed.

Parameters
sthe (SNI selected) server of the connection
cthe connection
ididentifier for the certifate, as used in ocsp_stapling_prime()
cbcallback to invoke when response data is available
userdatacaller supplied data passed to callback
Returns
OK iff response data has been provided, DECLINED otherwise

◆ ssl_ocsp_prime_hook()

int ssl_ocsp_prime_hook ( server_rec s,
apr_pool_t p,
const char *  id,
apr_size_t  id_len,
const char *  pem 
)

Providers of OCSP status responses register at this hook. Installed hooks returning OK are expected to provide later OCSP responses via a 'ap_ssl_ocsp_get_resp_hook'.

Parameters
sthe server being configured @params p a memory pool to use
idopaque data uniquely identifying the certificate, provided by caller
pemPEM data of certificate first, followed by PEM of issuer cert
Returns
OK iff stapling is being provided

Variable Documentation

◆ ap_bucket_type_error

AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_error
extern

◆ ap_bucket_type_headers

AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_headers
extern

◆ ap_bucket_type_request

AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_request
extern

◆ ap_bucket_type_response

AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_response
extern

◆ ap_old_write_func

AP_DECLARE_DATA ap_filter_rec_t* ap_old_write_func
extern

This is an optimization. We keep a record of the filter_rec that stores the old_write filter, so that we can avoid strcmp's later.