granicus.if.org Git - apache/blob - include/util_cookies.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_cookies.h
  19  * @brief Apache cookie library
  20  */
  21
  22 #ifndef UTIL_COOKIES_H
  23 #define UTIL_COOKIES_H
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @defgroup APACHE_CORE_COOKIE Cookies
  31  * @ingroup  APACHE_CORE
  32  *
  33  * RFC2109 and RFC2965 compliant HTTP cookies can be read from and written
  34  * to using this set of functions.
  35  *
  36  * @{
  37  *
  38  */
  39
  40 #include "apr_errno.h"
  41 #include "httpd.h"
  42
  43 #define SET_COOKIE "Set-Cookie"
  44 #define SET_COOKIE2 "Set-Cookie2"
  45 #define DEFAULT_ATTRS "HttpOnly;Secure;Version=1"
  46 #define CLEAR_ATTRS "Version=1"
  47
  48 typedef struct {
  49     request_rec *r;
  50     const char *name;
  51     const char *encoded;
  52     apr_table_t *new_cookies;
  53     int duplicated;
  54 } ap_cookie_do;
  55
  56 /**
  57  * Write an RFC2109 compliant cookie.
  58  *
  59  * @param r The request
  60  * @param name The name of the cookie.
  61  * @param val The value to place in the cookie.
  62  * @param attrs The string containing additional cookie attributes. If NULL, the
  63  *              DEFAULT_ATTRS will be used.
  64  * @param maxage If non zero, a Max-Age header will be added to the cookie.
  65  * @param ... A varargs array of zero or more (apr_table_t *) tables followed by NULL
  66  *            to which the cookies should be added.
  67  */
  68 AP_DECLARE(apr_status_t) ap_cookie_write(request_rec * r, const char *name,
  69                                          const char *val, const char *attrs,
  70                                          long maxage, ...)
  71                          AP_FN_ATTR_SENTINEL;
  72
  73 /**
  74  * Write an RFC2965 compliant cookie.
  75  *
  76  * @param r The request
  77  * @param name2 The name of the cookie.
  78  * @param val The value to place in the cookie.
  79  * @param attrs2 The string containing additional cookie attributes. If NULL, the
  80  *               DEFAULT_ATTRS will be used.
  81  * @param maxage If non zero, a Max-Age header will be added to the cookie.
  82  * @param ... A varargs array of zero or more (apr_table_t *) tables followed by NULL
  83  *            to which the cookies should be added.
  84  */
  85 AP_DECLARE(apr_status_t) ap_cookie_write2(request_rec * r, const char *name2,
  86                                           const char *val, const char *attrs2,
  87                                           long maxage, ...)
  88                          AP_FN_ATTR_SENTINEL;
  89
  90 /**
  91  * Remove an RFC2109 compliant cookie.
  92  *
  93  * @param r The request
  94  * @param name The name of the cookie.
  95  * @param attrs The string containing additional cookie attributes. If NULL, the
  96  *              CLEAR_ATTRS will be used.
  97  * @param ... A varargs array of zero or more (apr_table_t *) tables followed by NULL
  98  *            to which the cookies should be added.
  99  */
 100 AP_DECLARE(apr_status_t) ap_cookie_remove(request_rec * r, const char *name,
 101                                           const char *attrs, ...)
 102                          AP_FN_ATTR_SENTINEL;
 103
 104 /**
 105  * Remove an RFC2965 compliant cookie.
 106  *
 107  * @param r The request
 108  * @param name2 The name of the cookie.
 109  * @param attrs2 The string containing additional cookie attributes. If NULL, the
 110  *               CLEAR_ATTRS will be used.
 111  * @param ... A varargs array of zero or more (apr_table_t *) tables followed by NULL
 112  *            to which the cookies should be added.
 113  */
 114 AP_DECLARE(apr_status_t) ap_cookie_remove2(request_rec * r, const char *name2,
 115                                            const char *attrs2, ...)
 116                          AP_FN_ATTR_SENTINEL;
 117
 118 /**
 119  * Read a cookie called name, placing its value in val.
 120  *
 121  * Both the Cookie and Cookie2 headers are scanned for the cookie.
 122  *
 123  * If the cookie is duplicated, this function returns APR_EGENERAL. If found,
 124  * and if remove is non zero, the cookie will be removed from the headers, and
 125  * thus kept private from the backend.
 126  */
 127 AP_DECLARE(apr_status_t) ap_cookie_read(request_rec * r, const char *name, const char **val,
 128                                         int remove);
 129
 130 /**
 131  * Sanity check a given string that it exists, is not empty,
 132  * and does not contain the special characters '=', ';' and '&'.
 133  *
 134  * It is used to sanity check the cookie names.
 135  */
 136 AP_DECLARE(apr_status_t) ap_cookie_check_string(const char *string);
 137
 138 /**
 139  * @}
 140  */
 141
 142 #ifdef __cplusplus
 143 }
 144 #endif
 145
 146 #endif /* !UTIL_COOKIES_H */