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 #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 "Max-Age=0;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  */
  64 AP_DECLARE(apr_status_t) ap_cookie_write(request_rec * r, const char *name, const char *val,
  65                                          const char *attrs, long maxage);
  66
  67 /**
  68  * Write an RFC2965 compliant cookie.
  69  *
  70  * @param r The request
  71  * @param name2 The name of the cookie.
  72  * @param val The value to place in the cookie.
  73  * @param attrs2 The string containing additional cookie attributes. If NULL, the
  74  *               DEFAULT_ATTRS will be used.
  75  * @param maxage If non zero, a Max-Age header will be added to the cookie.
  76  */
  77 AP_DECLARE(apr_status_t) ap_cookie_write2(request_rec * r, const char *name2, const char *val,
  78                                           const char *attrs2, long maxage);
  79
  80 /**
  81  * Remove an RFC2109 compliant cookie.
  82  *
  83  * @param r The request
  84  * @param name The name of the cookie.
  85  */
  86 AP_DECLARE(apr_status_t) ap_cookie_remove(request_rec * r, const char *name);
  87
  88 /**
  89  * Remove an RFC2965 compliant cookie.
  90  *
  91  * @param r The request
  92  * @param name2 The name of the cookie.
  93  */
  94 AP_DECLARE(apr_status_t) ap_cookie_remove2(request_rec * r, const char *name2);
  95
  96 /**
  97  * Read a cookie called name, placing its value in val.
  98  *
  99  * Both the Cookie and Cookie2 headers are scanned for the cookie.
 100  *
 101  * If the cookie is duplicated, this function returns APR_EGENERAL. If found,
 102  * and if remove is non zero, the cookie will be removed from the headers, and
 103  * thus kept private from the backend.
 104  */
 105 AP_DECLARE(apr_status_t) ap_cookie_read(request_rec * r, const char *name, const char **val,
 106                                         int remove);
 107
 108 /**
 109  * Sanity check a given string that it exists, is not empty,
 110  * and does not contain the special characters '=', ';' and '&'.
 111  *
 112  * It is used to sanity check the cookie names.
 113  */
 114 AP_DECLARE(apr_status_t) ap_cookie_check_string(const char *string);
 115
 116 #ifdef __cplusplus
 117 }
 118 #endif
 119
 120 #endif /* !UTIL_COOKIES_H */