LIBNETPGPVERIFY(3)

NAME
libnetpgpverify - library to verify digital signatures

LIBRARY
libnetpgpverify

SYNOPSIS
#include <netpgp/verify.h>
int
pgpv_read_pubring(pgpv_t *pgp, const void *keyring, ssize_t size);
size_t
pgpv_verify(pgpv_cursor_t *cursor, pgpv_t *pgp, const void *ptr, ssize_t size);
size_t
pgpv_get_verified(pgpv_cursor_t *cursor, size_t cookie, char **ret);
size_t
pgpv_get_entry(pgpv_t *pgp, unsigned ent, char **ret);
int
pgpv_close(pgpv_t *pgp);

DESCRIPTION
libnetpgpverify is a small library which will verify a digital signature on a text or binary document. It has been kept deliberately small and only uses compression libraries to function.

PGP messages, including key rings, are made up of PGP packets, defined in RFC 4880. To match a digital signature, the public key of the signer must be located in a public key ring. This library has enough functionality to parse a pubkey keyring, using pgpv_read_pubring() to read the public keys of trusted identities, and to read files or memory which has already been signed. The pgpv_verify() function is used to verify the signature, either on data, or on memory. To signal to pgpv_verify() to read a file and verify it, the size argument should be set to -1 whilst a positive size signals that the pointer value should be that of signed memory. pgpv_verify() returns a cookie if the ignature was verified, or 0 if it did not. This cookie can subsequently be used to retrieve the data which was verified.

If the signature does match, then the file or memory can be considered as being verified as being unmodified and unchanged, integrally sound.

Signatures have validity dates on them, and it is possible for a signature to have expired when it is being checked. If for any reason the signature does not match, then the reason for not verifying the signature will be stored in the why buffer in the pgpv_cursor_t structure.

Occasionally, the memory or contents of the file which matched the signature will be needed, rather than a boolean value of whether it was verified. To do this, the pgpv_get_verified() function is used. Arguments to pgpv_get_verified() are the cookie returned from the verification, and a buffer allocated for the returned data and its size. If an error occurs, or the signature is not verified, a zero value is returned for the size. libnetpgpverify stores the starts of the data of all verified matches, and so the entry number argument is the index of the occurrence of verification. The first match will have an entry number of 0, the second 1, and so on.

The pgpv_close() function is used to clean up after all matching and verification has taken place. It frees and de-allocates all resources used in the verification of the signature.

The program used for signing may encode into base64 encoding, and it may also use embedded compression to make the output smaller than it would otherwise be. This is handled automatically by libnetpgpverify.

SEE ALSO
bn(3), zlib(3)

STANDARDS
J. Callas, L. Donnerhacke, H. Finney, D. Shaw, R. Thayer, November 2007, RFC 4880, OpenPGP Message Format.

HISTORY
The libnetpgpverify library first appeared in NetBSD 7.0.

AUTHORS
Alistair Crooks <agc@NetBSD.org>