1.\" $NetBSD: libnetpgpverify.3,v 1.4 2017/04/17 19:50:28 agc Exp $ 2.\" 3.\" Copyright (c) 2014,2015,2016 Alistair Crooks <agc@NetBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd June 26, 2016 27.Dt LIBNETPGPVERIFY 3 28.Os 29.Sh NAME 30.Nm libnetpgpverify 31.Nd library to verify digital signatures 32.Sh LIBRARY 33.Lb libnetpgpverify 34.Sh SYNOPSIS 35.In netpgp/verify.h 36.Ft int 37.Fo pgpv_new 38.Fa "void" 39.Fc 40.Ft int 41.Fo pgpv_new_cursor 42.Fa "void" 43.Fc 44.Ft int 45.Fo pgpv_read_pubring 46.Fa "pgpv_t *pgp" "const void *keyring" "ssize_t size" 47.Fc 48.Ft int 49.Fo pgpv_read_ssh_pubkeys 50.Fa "pgpv_t *pgp" "const void *keyring" "ssize_t size" 51.Fc 52.Ft size_t 53.Fo pgpv_verify 54.Fa "pgpv_cursor_t *cursor" "pgpv_t *pgp" "const void *ptr" "ssize_t size" 55.Fc 56.Ft size_t 57.Fo pgpv_get_verified 58.Fa "pgpv_cursor_t *cursor" "size_t cookie" "char **ret" 59.Fc 60.Ft size_t 61.Fo pgpv_get_cursor_element 62.Fa "pgpv_cursor_t *cursor" "size_t element" 63.Fc 64.Ft size_t 65.Fo pgpv_dump 66.Fa "pgpv_t *pgp" "char **data" 67.Fc 68.Ft size_t 69.Fo pgpv_get_entry 70.Fa "pgpv_t *pgp" "unsigned ent" "char **ret" "const char *modifiers" 71.Fc 72.Ft int64_t 73.Fo pgpv_get_cursor_num 74.Fa "pgpv_t *pgp" "const char *field" 75.Fc 76.Ft char * 77.Fo pgpv_get_cursor_str 78.Fa "pgpv_t *pgp" "const char *field" 79.Fc 80.Ft int 81.Fo pgpv_close 82.Fa "pgpv_t *pgp" 83.Fc 84.Sh DESCRIPTION 85.Nm 86is a small library which will verify a digital signature on a text or 87binary document. 88It has been kept deliberately small and only uses compression libraries 89to function. 90.Pp 91PGP messages, including key rings, are made up of PGP packets, defined 92in RFC 4880. 93To match a digital signature, the public key of the signer must be 94located in a public key ring. 95This library has enough functionality to parse a pubkey keyring, 96using 97.Fn pgpv_read_pubring 98to read the public keys of trusted identities, 99and to read files or memory which has already been signed. 100SSH public keys can also be used for signature verification 101by using the 102.Fn pgpv_read_ssh_pubkeys 103function. 104Please note that the creation date of the signature key 105will show up as January 1st 1970, due to the fact that the 106creation date of the key is not encoded anywhere for an ssh 107key, whilst it is an inherent part of the PGP fingerprint. 108In order that the correct fingerprint is used, the key creation 109date is forced to 0. 110.Pp 111The 112.Fn pgpv_verify 113function is used to verify the signature, either on data, or on memory. 114To signal to 115.Fn pgpv_verify 116to read a file and verify it, the 117.Dv size 118argument should be set to 119.Dv -1 120whilst a positive size signals that the pointer value should be that 121of signed memory. 122.Fn pgpv_verify 123returns a cookie if the ignature was verified, or 0 if it did not. 124This cookie can subsequently be used to retrieve the data which 125was verified. 126.Pp 127If the signature does match, then the file or memory can be considered as being 128verified as being unmodified and unchanged, integrally sound. 129.Pp 130Signatures have validity dates on them, and it is possible for a signature to 131have expired when it is being checked. 132If for any reason the signature does not match, then the reason for not 133verifying the signature will be stored in the 134.Dv why 135buffer in the 136.Dv pgpv_cursor_t 137structure. 138.Pp 139Occasionally, the memory or contents of the file which matched the signature 140will be needed, rather than a boolean value of whether it was verified. 141To do this, the 142.Fn pgpv_get_verified 143function is used. 144Arguments to 145.Fn pgpv_get_verified 146are the cookie returned from the verification, and a buffer 147allocated for the returned data and its size. 148If an error occurs, or the signature is not verified, a zero value is returned 149for the size. 150.Nm 151stores the starts of the data of all verified matches, and so the entry 152number argument is the index of the occurrence of verification. 153The first match will have an entry number of 0, the second 1, and so on. 154.Pp 155The 156.Fn pgpv_close 157function is used to clean up after all matching and verification has taken place. 158It frees and de-allocates all resources used in the verification of the signature. 159.Pp 160The program used for signing may encode into base64 encoding, and it may also 161use embedded compression to make the output smaller than it would otherwise be. 162This is handled automatically by 163.Nm 164.Sh SEE ALSO 165.Xr bn 3 , 166.\" .Xr bzlib2 3 , 167.Xr zlib 3 168.Sh STANDARDS 169The 170.Nm 171utility is designed to conform to IETF RFC 4880. 172.Sh HISTORY 173The 174.Nm 175library first appeared in 176.Nx 7.0 . 177.Sh AUTHORS 178.An Alistair Crooks Aq Mt agc@NetBSD.org 179