LIBNETPGP(3)

NAME
libnetpgp - digital signing and verification, encryption and decryption

LIBRARY
libnetpgp

SYNOPSIS
#include <netpgp.h>
int
netpgp_init(netpgp_t *netpgp, char *userid, char *pubringfile, char *secringfile);
int
netpgp_end(netpgp_t *netpgp);
int
netpgp_list_keys(netpgp_t *netpgp);
int
netpgp_find_key(netpgp_t *netpgp, char *userid);
int
netpgp_export_key(netpgp_t *netpgp, char *userid);
int
netpgp_import_key(netpgp_t *netpgp, char *file);
int
netpgp_generate_key(netpgp_t *netpgp, char *userid, int numbits);
int
netpgp_encrypt_file(netpgp_t *netpgp, char *userid, char *filename, char *out, int armored);
int
netpgp_decrypt_file(netpgp_t *netpgp, char *filename, char *out, int armored);
int
netpgp_sign_file(netpgp_t *netpgp, char *userid, char *filename, char *out, int armored, int cleartext, int detached);
int
netpgp_verify_file(netpgp_t *netpgp, char *f, int armored);
int
netpgp_set_debug(const char *filename);
int
netpgp_get_debug(const char *filename);
int
netpgp_get_info(const char *type);
int
netpgp_list_packets(netpgp_t *netpgp, char *filename, int armour, char *pubringname);
int
netpgp_setvar(netpgp_t *netpgp, const char *name, const char *value);
char *
netpgp_getvar(netpgp_t *netpgp, const char *name);

DESCRIPTION
libnetpgp is a library interface to enable digital signatures to be created and verified, and also for files and memory to be encrypted and decrypted. Functions are also provided for management of user keys.

The library uses functions from the openssl library for multi-precision integer arithmetic, and for RSA and DSA key signing and verification, encryption and decryption.

Normal operation sees the libnetpgp process be initialised using the netpgp_init() function, which will set up the public and private keyrings, and set the user identity to the userid argument passed to the function. If no public key ring file is provided, initial values will be taken from those in the .gnupg/pubring.gpg file in the user's home directory. Similarily, if no secret key ring file is provided, initial values will be taken from those in the .gnupg/secring.gpg file in the user's home directory. The netpgp_init() returns 1 on sucess, 0 on failure.

To list all the keys in a keyring, the netpgp_list_keys() function is used.

To export a key, the netpgp_export_key() is used. Output is sent to the standard output.

To import a key onto the public keyring, the netpgp_import_key() is used. The name of the file containing the key to be imported is provided as the filename argument.

To generate a key, the netpgp_generate_key() is used. It takes an argument of the number of bits to use in the key. At the time that this manual page was created (April 2009), the recommendations are that the bare minimum key size of at least 2048 bits is used, and it would be much better to use at least 4096 or 8192 bits. This situation should be monitored to ensure that it does not go out of date.

Encryption, decryption, signing and verification of files are the lifeblood of the libnetpgp library. To encrypt a file, the netpgp_encrypt_file() and the netpgp_decrypt_file() is used to decrypt the results of the encryption. To sign a file, the netpgp_sign_file() is used, and the resulting signed file can be verified using the netpgp_verify_file() function.

Internally, an encrypted or signed file is made up of “packets” which hold information pertaining to the signature, encryption method, and the data which is being protected. This information can be displayed in a verbose manner using the netpgp_list_packets() function.

The netpgp_setvar() and netpgp_getvar() functions are used to manage the hash algorithm that is used with RSA signatures. These functions can also be used to set and to retrieve the value of the user id which has been set.

In libnetpgp files are encrypted using the public key of the userid. The secret key is used to decrypt the results of that encryption. Files are signed using the secret key of the userid. The public key is used to verify that the file was signed, who signed the file, and the date and time at which it was signed.

Some utility functions are also provided for debugging, and for finding out version and maintainer information from calling programs. These are the netpgp_set_debug() and the netpgp_get_debug() functions (for getting verbose debugging information on a per-source file basis).

The netpgp_get_info() returns the information depending upon the type argument.

SEE ALSO
netpgp(1), ssl(3)

HISTORY
The libnetpgp library first appeared in NetBSD 6.0.

AUTHORS
Ben Laurie, Rachel Willmer. Alistair Crooks <agc@NetBSD.org> wrote this high-level interface.

This manual page was written by Alistair Crooks.