Annotation of embedaddon/libpdel/http/servlet/http_servlet_cookieauth.3, revision 1.1
1.1 ! misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
! 2: .\" All rights reserved.
! 3: .\"
! 4: .\" Subject to the following obligations and disclaimer of warranty,
! 5: .\" use and redistribution of this software, in source or object code
! 6: .\" forms, with or without modifications are expressly permitted by
! 7: .\" Packet Design; provided, however, that:
! 8: .\"
! 9: .\" (i) Any and all reproductions of the source or object code
! 10: .\" must include the copyright notice above and the following
! 11: .\" disclaimer of warranties; and
! 12: .\" (ii) No rights are granted, in any manner or form, to use
! 13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
! 14: .\" on advertising, endorsements, or otherwise except as such
! 15: .\" appears in the above copyright notice or in the software.
! 16: .\"
! 17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 34: .\" THE POSSIBILITY OF SUCH DAMAGE.
! 35: .\"
! 36: .\" Author: Archie Cobbs <archie@freebsd.org>
! 37: .\"
! 38: .\" $Id: http_servlet_cookieauth.3,v 1.13 2004/06/02 17:24:37 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt HTTP_SERVLET_COOKIEAUTH 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm http_servlet_cookieauth
! 45: .Nd HTTP secure cookie authentication servlet
! 46: .Sh LIBRARY
! 47: PDEL Library (libpdel, \-lpdel)
! 48: .Sh SYNOPSIS
! 49: .In sys/types.h
! 50: .In stdio.h
! 51: .In netinet/in.h
! 52: .In openssl/ssl.h
! 53: .In pdel/http/http_defs.h
! 54: .In pdel/http/http_server.h
! 55: .In pdel/http/servlet/cookieauth.h
! 56: .Ft "struct http_servlet *"
! 57: .Fn http_servlet_cookieauth_create "const char *redirect" "int append" "http_servlet_cookieauth_reqd_t *authreqd" "void *arg" "void (*destroy)(void *)" "const char *privkey" "const void *id" "size_t idlen" "const char *cookiename"
! 58: .Ft int
! 59: .Fn http_servlet_cookieauth_login "struct http_response *resp" "const char *privkey" "const char *username" "u_int max_linger" "time_t expire" "int session_only" "const u_char *id" "size_t idlen" "const char *cookiename" "const char *path" "const char *domain" "int secure"
! 60: .Ft int
! 61: .Fn http_servlet_cookieauth_logout "const char *cookiename" "const char *path" "const char *domain" "struct http_response *resp"
! 62: .Ft "char *"
! 63: .Fn http_servlet_cookieauth_user "const char *privkey" "const void *id" "size_t idlen" "const char *cookiename" "struct http_request *req" "const char *mtype"
! 64: .Sh DESCRIPTION
! 65: .Fn http_servlet_cookieauth_create
! 66: creates a new servlet that enforces client authentication using
! 67: public key cryptography and HTTP cookies.
! 68: Any requests that fail to present a valid cookie are redirected to
! 69: a login page.
! 70: The servlet should be registered with a lower order than the other
! 71: servlets that it protects, so that it executes first.
! 72: .Pp
! 73: .Fa redirect
! 74: and
! 75: .Fa append
! 76: are used when redirecting a request, and are the same as the arguments to
! 77: .Xr http_servlet_redirect_create 3 .
! 78: .Pp
! 79: .Fa authreqd
! 80: is invoked for every request and is a pointer to a function of this type:
! 81: .Pp
! 82: .Bd -literal -compact -offset 3n
! 83: typedef int http_servlet_cookieauth_reqd_t(void *arg,
! 84: struct http_request *req);
! 85: .Ed
! 86: .Pp
! 87: The
! 88: .Fa arg
! 89: is the same value supplied to
! 90: .Fn http_servlet_cookieauth_create .
! 91: .Fn authreqd
! 92: should return a non-zero value if the request requires a valid login cookie
! 93: to proceed.
! 94: If
! 95: .Fn authreqd
! 96: returns zero, no authentication will be required.
! 97: Typically this is used to make an exception for the login page, etc.
! 98: .Pp
! 99: .Fa privkey
! 100: is a pointer to a PEM-encoded RSA private key.
! 101: If the HTTP server supports SSL, the server private key may be used
! 102: for convenience (though this slightly weakens overall security).
! 103: .Pp
! 104: .Fa id
! 105: points to arbitrary binary data having length
! 106: .Fa idlen
! 107: that uniquely identifies the authenticated resource.
! 108: Only cookies generated with the same identity and signed with the same
! 109: RSA private key will satisfy this servlet (see
! 110: .Fn http_servlet_cookieauth_login
! 111: below).
! 112: The identity information should not be too long, to avoid overflowing
! 113: the client's 4K cookie buffer.
! 114: .Pp
! 115: The
! 116: .Fa cookiename
! 117: specifies the name to use for the cookie; multiple cookies with
! 118: different names may be used simultaneously.
! 119: .Pp
! 120: When the servlet is destroyed, if
! 121: .Fa destroy
! 122: is not
! 123: .Dv NULL ,
! 124: it will be invoked with
! 125: .Fa arg
! 126: as its parameter.
! 127: .Pp
! 128: .Fn http_servlet_cookieauth_login
! 129: causes a cookie to be generated and passed to the client via
! 130: .Fa resp .
! 131: When the client includes this cookie in a subsequent HTTP request,
! 132: the servlet will allow the request to proceed.
! 133: The
! 134: .Fa privkey ,
! 135: .Fa id ,
! 136: and
! 137: .Fa idlen
! 138: arguments must match the same arguments to
! 139: .Fn http_servlet_cookieauth_create .
! 140: .Pp
! 141: .Fa username
! 142: is an arbirary string that may be retrieved in a subsequent request by
! 143: .Fn http_servlet_cookieauth_user
! 144: (see below).
! 145: .Pp
! 146: .Fa max_linger ,
! 147: if non-zero, specifies a maximum time in seconds between requests before
! 148: the cookie becomes invalid.
! 149: This means each request will cause a new cookie to be generated.
! 150: If an otherwise valid cookie is received but it was generated more than
! 151: .Fa max_linger
! 152: seconds ago, it is rejected.
! 153: .Pp
! 154: .Fa expire
! 155: specifies an absolute time at which the cookie should expire.
! 156: Cookies presented beyond their expiration time (which should only be sent
! 157: if the client is broken, malicious, or not synchronized) will be rejected.
! 158: .Pp
! 159: .Fa session_only
! 160: specifies that the client should be instructed to discard the cookie
! 161: when the client's session terminates.
! 162: Implementation of this feature is client-dependent.
! 163: .Pp
! 164: .Fa path
! 165: and
! 166: .Fa domain
! 167: may be
! 168: .Dv NULL
! 169: to use the default, which means the client should send the cookie with
! 170: all requests to this web server.
! 171: Otherwise, see
! 172: .Li "http://www.netscape.com/newsref/std/cookie_spec.html"
! 173: for a description.
! 174: .Pp
! 175: The
! 176: .Fa secure
! 177: flag indicates to the client that this cookie should only be sent over
! 178: an HTTPS (i.e., encrypted) connection.
! 179: Implementation of this feature is client-dependent.
! 180: .Pp
! 181: .Fn http_servlet_cookieauth_logout
! 182: invalidates the client cookie by sending the client an invalid cookie
! 183: which should overwrite the valid one.
! 184: Correct implementation of this feature is client-dependent.
! 185: Note also that it's possible (though unlikely) that this function may
! 186: return an error, in which case the invalid cookie was not sent.
! 187: .Pp
! 188: .Fn http_servlet_cookieauth_user
! 189: retrieves the
! 190: .Fa username
! 191: argument previously passed to
! 192: .Fn http_servlet_cookieauth_login
! 193: from a valid cookie included with the HTTP request
! 194: .Fa req .
! 195: The string is dynamically allocated with
! 196: .Xr typed_mem 3
! 197: type
! 198: .Fa mtype
! 199: and must be eventually freed by the caller.
! 200: The identity specified by
! 201: .Fa id
! 202: and
! 203: .Fa idlen
! 204: must be the same as when the cookie was created.
! 205: If
! 206: .Fa req
! 207: does not contain a valid cookie,
! 208: .Dv NULL
! 209: is returned.
! 210: .Pp
! 211: Note that it is not necessary to create a servlet in order to use the
! 212: .Fn http_servlet_cookieauth_login ,
! 213: .Fn http_servlet_cookieauth_logout ,
! 214: and
! 215: .Fn http_servlet_cookieauth_user
! 216: functions.
! 217: .Sh SECURITY NOTES
! 218: Because public key cryptography is used, as long as the RSA private key
! 219: is kept secret then there is no known way for an attacker to create a
! 220: .Em new
! 221: cookie that appears valid to this servlet.
! 222: However, if an attacker somehow acquires an existing cookie before its
! 223: expiration time, it can be presented by the hacker and will fool this
! 224: servlet into believing that the attacker had previously authenticated.
! 225: .Pp
! 226: Also, while the information in the cookie includes a secure digital
! 227: signature that is used to validate the cookie, the cookie itself is
! 228: .Em not
! 229: encrypted.
! 230: In particular, the
! 231: .Fa username
! 232: will travel across the HTTP connection (and be stored on the browser's
! 233: computer) unprotected.
! 234: .Pp
! 235: For these reasons,
! 236: .Sy "this servlet should only be used with SSL web servers" .
! 237: .Pp
! 238: Creation of the identity must be done carefully to avoid security holes.
! 239: The important point is to avoid using the same identity and private key
! 240: to secure two things that should be considered different from an
! 241: authentication point of view.
! 242: Therefore, any information which makes the identity unique to the
! 243: particular resource being protected is good.
! 244: .Pp
! 245: A common pitfall is creating an identity by concatenating strings
! 246: without inserting a separator character that does not appear in
! 247: the strings. E.g., the concatenation of
! 248: .Dq abc
! 249: and
! 250: .Dq def
! 251: is the same as the concatenation of
! 252: .Dq ab
! 253: and
! 254: .Dq cdef.
! 255: However,
! 256: .Dq abc:def
! 257: is different from
! 258: .Dq ab:cdef .
! 259: .Pp
! 260: Hashing the identity components together is a good way to limit
! 261: .Fa idlen
! 262: and therefore the size of the cookie.
! 263: However, if hashing is done a secure hash function such
! 264: as MD5 or SHA-1 should be used.
! 265: .Sh RETURN VALUES
! 266: .Fn http_servlet_cookieauth_create ,
! 267: .Fn http_servlet_cookieauth_login ,
! 268: .Fn http_servlet_cookieauth_logout ,
! 269: and
! 270: .Fn http_servlet_cookieauth_user
! 271: return
! 272: .Dv NULL
! 273: or -1 and set
! 274: .Va errno
! 275: to an appropriate value to indicate failure.
! 276: .Pp
! 277: The
! 278: .Va errno
! 279: value
! 280: .Er EACCES
! 281: is used to indicate that no valid cookie was found.
! 282: .Sh SEE ALSO
! 283: .Xr http_request 3 ,
! 284: .Xr http_response 3 ,
! 285: .Xr http_server 3 ,
! 286: .Xr http_servlet 3 ,
! 287: .Xr http_servlet_basicauth 3 ,
! 288: .Xr http_servlet_redirect 3 ,
! 289: .Xr libpdel 3 ,
! 290: .Xr md5 3 ,
! 291: .Xr sha 3 ,
! 292: .Xr typed_mem 3
! 293: .Rs
! 294: .%T "Persistent Client State HTTP Cookies"
! 295: .%O "http://www.netscape.com/newsref/std/cookie_spec.html"
! 296: .Re
! 297: .Rs
! 298: .%A D. Kristol
! 299: .%A L. Montulli
! 300: .%T "HTTP State Management Mechanism"
! 301: .%O RFC 2109
! 302: .Re
! 303: .Sh HISTORY
! 304: The PDEL library was developed at Packet Design, LLC.
! 305: .Dv "http://www.packetdesign.com/"
! 306: .Sh AUTHORS
! 307: .An Archie Cobbs Aq archie@freebsd.org
! 308: .Sh BUGS
! 309: The client must support HTTP cookies for any of this to work.
! 310: .Pp
! 311: Only the original Netscape cookie spec is supported;
! 312: RFC 2109 support should be added.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_servlet_cookieauth.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / http / servlet