granicus.if.org Git - apache/blob - include/util_fcgi.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file  util_fcgi.h
  19  * @brief FastCGI protocol defitions and support routines
  20  *
  21  * @defgroup APACHE_CORE_FASTCGI FastCGI Tools
  22  * @ingroup  APACHE_CORE
  23  * @{
  24  */
  25
  26 #ifndef APACHE_UTIL_FCGI_H
  27 #define APACHE_UTIL_FCGI_H
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #include "httpd.h"
  34
  35 /**
  36  * @brief A structure that represents the fixed header fields
  37  * at the beginning of a "FastCGI record" (i.e., the data prior
  38  * to content data and padding).
  39  */
  40 typedef struct {
  41     /** See values for version, below */
  42     unsigned char version;
  43     /** See values for type, below */
  44     unsigned char type;
  45     /** request id, in two parts */
  46     unsigned char requestIdB1;
  47     unsigned char requestIdB0;
  48     /** content length, in two parts */
  49     unsigned char contentLengthB1;
  50     unsigned char contentLengthB0;
  51     /** padding length */
  52     unsigned char paddingLength;
  53     /** 8-bit reserved field */
  54     unsigned char reserved;
  55 } ap_fcgi_header;
  56
  57 /*
  58  * Number of bytes in the header portion of a FastCGI record
  59  * (i.e., ap_fcgi_header structure).  Future versions of the
  60  * protocol may increase the size.
  61  */
  62 #define AP_FCGI_HEADER_LEN  8
  63
  64 /*
  65  * Maximum number of bytes in the content portion of a FastCGI record.
  66  */
  67 #define AP_FCGI_MAX_CONTENT_LEN 65535
  68
  69 /**
  70  * Possible values for the version field of ap_fcgi_header
  71  */
  72 #define AP_FCGI_VERSION_1 1
  73
  74 /**
  75  * Possible values for the type field of ap_fcgi_header
  76  */
  77 #define AP_FCGI_BEGIN_REQUEST       1
  78 #define AP_FCGI_ABORT_REQUEST       2
  79 #define AP_FCGI_END_REQUEST         3
  80 #define AP_FCGI_PARAMS              4
  81 #define AP_FCGI_STDIN               5
  82 #define AP_FCGI_STDOUT              6
  83 #define AP_FCGI_STDERR              7
  84 #define AP_FCGI_DATA                8
  85 #define AP_FCGI_GET_VALUES          9
  86 #define AP_FCGI_GET_VALUES_RESULT  10
  87 #define AP_FCGI_UNKNOWN_TYPE       11
  88 #define AP_FCGI_MAXTYPE (AP_FCGI_UNKNOWN_TYPE)
  89
  90 /**
  91  * Offsets of the various fields of ap_fcgi_header
  92  */
  93 #define AP_FCGI_HDR_VERSION_OFFSET         0
  94 #define AP_FCGI_HDR_TYPE_OFFSET            1
  95 #define AP_FCGI_HDR_REQUEST_ID_B1_OFFSET   2
  96 #define AP_FCGI_HDR_REQUEST_ID_B0_OFFSET   3
  97 #define AP_FCGI_HDR_CONTENT_LEN_B1_OFFSET  4
  98 #define AP_FCGI_HDR_CONTENT_LEN_B0_OFFSET  5
  99 #define AP_FCGI_HDR_PADDING_LEN_OFFSET     6
 100 #define AP_FCGI_HDR_RESERVED_OFFSET        7
 101
 102 /**
 103  * @brief This represents the content data of the FastCGI record when
 104  * the type is AP_FCGI_BEGIN_REQUEST.
 105  */
 106 typedef struct {
 107     /**
 108      * role, in two parts
 109      * See values for role, below
 110      */
 111     unsigned char roleB1;
 112     unsigned char roleB0;
 113     /**
 114      * flags
 115      * See values for flags bits, below
 116      */
 117     unsigned char flags;
 118     /** reserved */
 119     unsigned char reserved[5];
 120 } ap_fcgi_begin_request_body;
 121
 122 /*
 123  * Values for role component of ap_fcgi_begin_request_body
 124  */
 125 #define AP_FCGI_RESPONDER  1
 126 #define AP_FCGI_AUTHORIZER 2
 127 #define AP_FCGI_FILTER     3
 128
 129 /*
 130  * Values for flags bits of ap_fcgi_begin_request_body
 131  */
 132 #define AP_FCGI_KEEP_CONN  1  /* otherwise the application closes */
 133
 134 /**
 135  * Offsets of the various fields of ap_fcgi_begin_request_body
 136  */
 137 #define AP_FCGI_BRB_ROLEB1_OFFSET       0
 138 #define AP_FCGI_BRB_ROLEB0_OFFSET       1
 139 #define AP_FCGI_BRB_FLAGS_OFFSET        2
 140 #define AP_FCGI_BRB_RESERVED0_OFFSET    3
 141 #define AP_FCGI_BRB_RESERVED1_OFFSET    4
 142 #define AP_FCGI_BRB_RESERVED2_OFFSET    5
 143 #define AP_FCGI_BRB_RESERVED3_OFFSET    6
 144 #define AP_FCGI_BRB_RESERVED4_OFFSET    7
 145
 146 /**
 147  * Pack ap_fcgi_header
 148  * @param h The header to read from
 149  * @param a The array to write to, of size AP_FCGI_HEADER_LEN
 150  */
 151 AP_DECLARE(void) ap_fcgi_header_to_array(ap_fcgi_header *h,
 152                                          unsigned char a[]);
 153
 154 /**
 155  * Unpack header of FastCGI record into ap_fcgi_header
 156  * @param h The header to write to
 157  * @param a The array to read from, of size AP_FCGI_HEADER_LEN
 158  */
 159 AP_DECLARE(void) ap_fcgi_header_from_array(ap_fcgi_header *h,
 160                                            unsigned char a[]);
 161
 162 /**
 163  * Unpack header of FastCGI record into individual fields
 164  * @param version The version, on output
 165  * @param type The type, on output
 166  * @param request_id The request id, on output
 167  * @param content_len The content length, on output
 168  * @param padding_len The amount of padding following the content, on output
 169  * @param a The array to read from, of size AP_FCGI_HEADER_LEN
 170  */
 171 AP_DECLARE(void) ap_fcgi_header_fields_from_array(unsigned char *version,
 172                                                   unsigned char *type,
 173                                                   apr_uint16_t *request_id,
 174                                                   apr_uint16_t *content_len,
 175                                                   unsigned char *padding_len,
 176                                                   unsigned char a[]);
 177
 178 /**
 179  * Pack ap_fcgi_begin_request_body
 180  * @param h The begin-request body to read from
 181  * @param a The array to write to, of size AP_FCGI_HEADER_LEN
 182  */
 183 AP_DECLARE(void) ap_fcgi_begin_request_body_to_array(ap_fcgi_begin_request_body *h,
 184                                                      unsigned char a[]);
 185
 186 /**
 187  * Fill in a FastCGI request header with the required field values.
 188  * @param header The header to fill in
 189  * @param type The type of record
 190  * @param request_id The request id
 191  * @param content_len The amount of content which follows the header
 192  * @param padding_len The amount of padding which follows the content
 193  *
 194  * The header array must be at least AP_FCGI_HEADER_LEN bytes long.
 195  */
 196 AP_DECLARE(void) ap_fcgi_fill_in_header(ap_fcgi_header *header,
 197                                         unsigned char type,
 198                                         apr_uint16_t request_id,
 199                                         apr_uint16_t content_len,
 200                                         unsigned char padding_len);
 201
 202 /**
 203  * Fill in a FastCGI begin request body with the required field values.
 204  * @param brb The begin-request-body to fill in
 205  * @param role AP_FCGI_RESPONDER or other roles
 206  * @param flags 0 or a combination of flags like AP_FCGI_KEEP_CONN
 207  */
 208 AP_DECLARE(void) ap_fcgi_fill_in_request_body(ap_fcgi_begin_request_body *brb,
 209                                               int role,
 210                                               unsigned char flags);
 211
 212 /**
 213  * Compute the buffer size needed to encode the next portion of
 214  * the provided environment table.
 215  * @param env The environment table
 216  * @param maxlen The maximum buffer size allowable, capped at
 217  * AP_FCGI_MAX_CONTENT_LEN.
 218  * @param starting_elem On input, the next element of the table array
 219  * to process in this FastCGI record.  On output, the next element to
 220  * process on the *next* FastCGI record.
 221  * @return Size of buffer needed to encode the next part, or 0
 222  * if no more can be encoded.  When 0 is returned: If starting_elem
 223  * has reached the end of the table array, all has been encoded;
 224  * otherwise, the next envvar can't be encoded within the specified
 225  * limit.
 226  * @note If an envvar can't be encoded within the specified limit,
 227  * the caller can log a warning and increment starting_elem and try
 228  * again or increase the limit or fail, as appropriate for the module.
 229  */
 230 AP_DECLARE(apr_size_t) ap_fcgi_encoded_env_len(apr_table_t *env,
 231                                                apr_size_t maxlen,
 232                                                int *starting_elem);
 233
 234 /**
 235  * Encode the next portion of the provided environment table using
 236  * a buffer previously allocated.
 237  * @param r The request, for logging
 238  * @param env The environment table
 239  * @param buffer A buffer to contain the encoded environment table
 240  * @param buflen The length of the buffer, previously computed by
 241  * ap_fcgi_encoded_env_len().
 242  * @param starting_elem On input, the next element of the table array
 243  * to process in this FastCGI record.  On output, the next element to
 244  * process on the *next* FastCGI record.
 245  * @return APR_SUCCESS if a section could be encoded or APR_ENOSPC
 246  * otherwise.
 247  * @note The output starting_elem from ap_fcgi_encoded_env_len
 248  * shouldn't be used as input to ap_fcgi_encode_env when building the
 249  * same FastCGI record.
 250  */
 251 AP_DECLARE(apr_status_t) ap_fcgi_encode_env(request_rec *r,
 252                                             apr_table_t *env,
 253                                             void *buffer,
 254                                             apr_size_t buflen,
 255                                             int *starting_elem);
 256
 257 /**
 258  * String forms for the value of the FCGI_ROLE envvar
 259  */
 260 #define AP_FCGI_RESPONDER_STR   "RESPONDER"
 261 #define AP_FCGI_AUTHORIZER_STR  "AUTHORIZER"
 262 #define AP_FCGI_FILTER_STR      "FILTER"
 263
 264 /**
 265  * FastCGI implementations that implement the AUTHORIZER role
 266  * for Apache httpd and allow the application to participate in
 267  * any of the Apache httpd AAA phases typically set the variable
 268  * FCGI_APACHE_ROLE to one of these strings to indicate the
 269  * specific AAA phase.
 270  */
 271 #define AP_FCGI_APACHE_ROLE_AUTHENTICATOR_STR  "AUTHENTICATOR"
 272 #define AP_FCGI_APACHE_ROLE_AUTHORIZER_STR     "AUTHORIZER"
 273 #define AP_FCGI_APACHE_ROLE_ACCESS_CHECKER_STR "ACCESS_CHECKER"
 274
 275 #ifdef __cplusplus
 276 }
 277 #endif
 278
 279 #endif  /* !APACHE_UTIL_FCGI_H */
 280 /** @} */