.\"	$Id$
.\"
.\" Copyright (c) 2016, 2018 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt KHTTPBASIC_VALIDATE 3
.Os
.Sh NAME
.Nm khttpbasic_validate
.Nd validate an HTTP basic authorisation request
.Sh LIBRARY
.Lb libkcgi
.Sh SYNOPSIS
.In sys/types.h
.In stdarg.h
.In stdint.h
.In kcgi.h
.Ft int
.Fo khttpbasic_validate
.Fa "struct kreq *req"
.Fa "const char *user"
.Fa "const char *password"
.Fc
.Sh DESCRIPTION
The
.Fn khttpbasic_validate
function validates the given
.Fa user
and
.Fa password
with the HTTP
.Dq basic
or
.Dq bearer
authorised request
.Fa req
as returned by
.Xr khttp_parse 3
or
.Xr khttp_fcgi_parse 3 .
.Pp
In both cases, the request is validated by base64-encoding
.Fa user Ns : Ns Fa password
and comparing it to the given token.
.Sh RETURN VALUES
.Fn khttpbasic_validate
will return zero if validation failed, less than zero if the request was
not properly set up for HTTP basic or bearer validation (no HTTP method,
not a basic or bearer request, not already authenticated by the web
server), or greater than zero if the validation succeeded.
.Sh EXAMPLES
In the following fragment, assume
.Fa r
a pointer to a
.Ft struct kreq
successfully initialised by
.Xr khttp_parse 3 .
If validation is not provided, it returns an HTTP 401.
The expected principle is
.Qq james ,
password
.Qq bond .
Otherwise, it returns an HTTP 200.
.Bd -literal -offset indent
if (khttpbasic_validate(r, "james", "bond") <= 0) {
  khttp_head(r, kresps[KRESP_STATUS],
    "%s", khttps[KHTTP_401]);
  khttp_head(r, kresps[KRESP_WWW_AUTHENTICATE],
    "basic realm=\e"%s\e"", "some realm");
} else
  khttp_head(r, kresps[KRESP_STATUS],
    "%s", khttps[KHTTP_200]);
.Ed
.Sh SEE ALSO
.Xr kcgi 3 ,
.Xr khttp_fcgi_parse 3 ,
.Xr khttp_parse 3 ,
.Xr khttpdigest_validate 3
.Sh AUTHORS
Written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .