libnetpgpverify(3) - NetBSD Manual Pages

LIBNETPGPVERIFY(3)      NetBSD Library Functions Manual     LIBNETPGPVERIFY(3)


NAME

     libnetpgpverify -- library to verify digital signatures


LIBRARY

     Netpgp Signature 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 function-
     ality 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 ver-
     ification 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 finger-
     print.  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 signa-
     ture 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 signa-
     ture will be needed, rather than a boolean value of whether it was veri-
     fied.  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 ver-
     ification 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