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