Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

LIBNETPGPVERIFY(3)         Library Functions Manual         LIBNETPGPVERIFY(3)

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>

NetBSD 10.99                     June 26, 2016                    NetBSD 10.99