1.\" $NetBSD: libpaa.3,v 1.2 2010/09/10 12:18:48 wiz Exp $ 2.\" 3.\" Copyright (c) 2009,2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This manual page is derived from software contributed to The 7.\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 9, 2010 31.Dt LIBPAA 3 32.Os 33.Sh NAME 34.Nm libpaa 35.Nd Public key Access Authentication Library 36.Sh LIBRARY 37.Lb libpaa 38.Sh SYNOPSIS 39.In libpaa.h 40.Ft int 41.Fo paa_server_init 42.Fa "paa_server_info_t *server" "unsigned secretsize" 43.Fc 44.Ft int 45.Fo paa_format_challenge 46.Fa "paa_challenge_t *challenge" "paa_server_info_t *server" 47.Fa "char *buf" "size_t size" 48.Fc 49.Ft int 50.Fo paa_format_response 51.Fa "paa_response_t *response" "netpgp_t *netpgp" "char *in" 52.Fa "char *out" "size_t outsize" 53.Fc 54.Ft int 55.Fo paa_check_response 56.Fa "paa_challenge_t *challenge" "paa_identity_t *id" 57.Fa "netpgp_t *netpgp" "char *response" 58.Fc 59.Ft int 60.Fo paa_print_identity 61.Fa "FILE *fp" "paa_identity_t *id" 62.Fc 63.Sh DESCRIPTION 64.Nm 65is a library interface which provides an authentication mechanism 66layered on top of 67.Xr libnetpgp 3 . 68This is targeted at web services, and allows authentication by 69means of digitally signing a generated challenge. 70By verifying the signed response from the client, the server 71can verify the identity of the user receiving the challenge, 72and producing the signed response. 73Random seeds and blinded secrets are used to protect against 74spoofed signatures. 75.Pp 76The main reason for writing this authentication mechanism is 77so that identities can be verified across a network without 78transferring any secret information across the wire. 79.Pp 80Binary information is transferred using internal base64 81functions. 82.Pp 83In the server 84process, the server information is initialised using the 85.Fn paa_server_init 86function, which will set up the random data and secrets. 87The challenge is generated using the 88.Fn paa_format_challenge 89function. 90This will format the challenge into the buffer provided, 91and can be transferred to the client using any means. 92.Pp 93The client reads the challenge, and produces a response 94using the 95.Fn paa_format_response 96function to format the response in the buffer provided. 97This response is given to the server. 98.Pp 99In the server, the response is verified using 100the 101.Fn paa_check_response 102function. 103If a positive verification has occurred, the identity of 104various fields in the response can be displayed 105using the 106.Fn paa_print_identity 107function. 108.Sh SEE ALSO 109.Xr libnetpgp 3 , 110.Xr sha1 3 111.Sh HISTORY 112The 113.Nm 114library first appeared in 115.Nx 6.0 . 116.Sh AUTHORS 117.An Alistair Crooks Aq agc@NetBSD.org 118