Annotation of embedaddon/libpdel/http/servlet/http_servlet_cookieauth.3, revision 1.1.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