NAME
libnetpgpverify —
library to verify
digital signatures
LIBRARY
Netpgp Verification (libnetpgpverify, -lnetpgpverify)
SYNOPSIS
#include <netpgp/verify.h>
int
pgpv_new(
void);
int
pgpv_new_cursor(
void);
int
pgpv_read_pubring(
pgpv_t *pgp,
const void *keyring,
ssize_t
size);
int
pgpv_read_ssh_pubkeys(
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_cursor_element(
pgpv_cursor_t
*cursor,
size_t element);
size_t
pgpv_dump(
pgpv_t *pgp,
char **data);
size_t
pgpv_get_entry(
pgpv_t *pgp,
unsigned ent,
char **ret,
const char *modifiers);
int64_t
pgpv_get_cursor_num(
pgpv_t *pgp,
const char *field);
char *
pgpv_get_cursor_str(
pgpv_t *pgp,
const char *field);
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. SSH public keys can also be used for signature verification by using
the
pgpv_read_ssh_pubkeys() function. Please note that the
creation date of the signature key will show up as January 1st 1970, due to
the fact that the creation date of the key is not encoded anywhere for an ssh
key, whilst it is an inherent part of the PGP fingerprint. In order that the
correct fingerprint is used, the key creation date is forced to 0.
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
The
libnetpgpverify utility is designed to conform to IETF RFC
4880.
HISTORY
The
libnetpgpverify library first appeared in
NetBSD 7.0.
AUTHORS
Alistair Crooks
<
agc@NetBSD.org>