Annotation of embedaddon/libpdel/http/servlet/http_servlet_basicauth.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_basicauth.3,v 1.4 2004/06/02 17:24:37 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt HTTP_SERVLET_AUTH 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm http_servlet_basicauth
! 45: .Nd HTTP basic 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/basicauth.h
! 56: .Ft "struct http_servlet *"
! 57: .Fn http_servlet_basicauth_create "http_servlet_basicauth_t *auth" "void *arg" "void (*destroy)(void *)"
! 58: .Sh DESCRIPTION
! 59: .Fn http_servlet_basicauth_create
! 60: creates a new servlet that implements HTTP basic authentication.
! 61: The servlet should be registered with a lower order than the other
! 62: servlets that it protects, so that it executes first.
! 63: .Pp
! 64: .Fa auth
! 65: is a pointer to a function having this type:
! 66: .Pp
! 67: .Bd -literal -compact -offset 3n
! 68: typedef const char *http_servlet_basicauth_t(void *arg,
! 69: struct http_request *req, const char *username,
! 70: const char *password);
! 71: .Ed
! 72: .Pp
! 73: .Fa arg
! 74: is the opaque cookie supplied to
! 75: .Fn http_servlet_basicauth_create .
! 76: .Fa req
! 77: is the HTTP request object and
! 78: .Fa username
! 79: and
! 80: .Fa password
! 81: are the credentials supplied with the request, or the empty string
! 82: if none were supplied.
! 83: .Pp
! 84: .Fn auth
! 85: should return
! 86: .Dv NULL
! 87: to allow access.
! 88: Otherwise, it should return the authorization realm string
! 89: to deny access.
! 90: This string is not freed by the calling function.
! 91: .Em Warning :
! 92: this is reversed from usual semantics; returning
! 93: .Dv NULL
! 94: indicates success and allows access.
! 95: .Pp
! 96: When the servlet is destroyed, if
! 97: .Fa destroy
! 98: is not
! 99: .Dv NULL ,
! 100: it will be invoked with
! 101: .Fa arg
! 102: as its parameter.
! 103: .Sh RETURN VALUES
! 104: On failure,
! 105: .Fn http_servlet_basicauth_create
! 106: returns
! 107: .Dv NULL
! 108: and sets
! 109: .Va errno
! 110: to an appropriate value.
! 111: .Sh SEE ALSO
! 112: .Xr http_request 3 ,
! 113: .Xr http_response 3 ,
! 114: .Xr http_server 3 ,
! 115: .Xr http_servlet 3 ,
! 116: .Xr http_servlet_cookieauth 3 ,
! 117: .Xr libpdel 3
! 118: .Rs
! 119: .%A J. Franks
! 120: .%A P. Hallam-Baker
! 121: .%A J. Hostetler
! 122: .%A S. Lawrence
! 123: .%A P. Leach
! 124: .%A A. Luotonen
! 125: .%A L. Stewart
! 126: .%T "HTTP Authentication: Basic and Digest Access Authentication"
! 127: .%O RFC 2617
! 128: .Re
! 129: .Sh HISTORY
! 130: The PDEL library was developed at Packet Design, LLC.
! 131: .Dv "http://www.packetdesign.com/"
! 132: .Sh AUTHORS
! 133: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>