- NetBSD Manual Pages
LIBNETPGP(3) NetBSD Library Functions Manual LIBNETPGP(3)
Powered by man-cgi (2020-09-24).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.
libnetpgp -- digital signing and verification, encryption and decryption
Netpgp signing, verification, encryption and decryption (libnetpgp,
The following functions relate to initialisations and finalisations:
The following functions are for debugging, reflection and information:
netpgp_set_debug(const char *filename);
netpgp_get_debug(const char *filename);
netpgp_get_info(const char *type);
netpgp_list_packets(netpgp_t *netpgp, char *filename, int armour,
The following functions are for variable management:
netpgp_setvar(netpgp_t *netpgp, const char *name, const char *value);
netpgp_getvar(netpgp_t *netpgp, const char *name);
netpgp_incvar(netpgp_t *netpgp, const char *name, const int delta);
The following function sets the home directory:
netpgp_set_homedir(netpgp_t *netpgp, char *homedir, char *subdir,
const int quiet);
The following functions are used for key management:
netpgp_list_keys(netpgp_t *netpgp, const int printsigs);
netpgp_match_list_keys(netpgp_t *netpgp, char *pattern);
netpgp_find_key(netpgp_t *netpgp, char *userid);
netpgp_get_key(netpgp_t *netpgp, const char *id);
netpgp_export_key(netpgp_t *netpgp, char *userid);
netpgp_import_key(netpgp_t *netpgp, char *file);
netpgp_generate_key(netpgp_t *netpgp, char *userid, int numbits);
The following functions are used for file management:
netpgp_encrypt_file(netpgp_t *netpgp, char *userid, char *filename,
char *out, int armored);
netpgp_decrypt_file(netpgp_t *netpgp, char *filename, char *out,
netpgp_sign_file(netpgp_t *netpgp, char *userid, char *filename,
char *out, int armored, int cleartext, int detached);
netpgp_verify_file(netpgp_t *netpgp, char *f, int armored);
The following functions are used for memory signing and encryption:
netpgp_encrypt_memory(netpgp_t *netpgp, char *userid, void *in,
const size_t insize, char *out, size_t outsize, int armored);
netpgp_decrypt_memory(netpgp_t *netpgp, const void *input,
const size_t insize, char *out, size_t outsize, const int armored);
netpgp_sign_memory(netpgp_t *netpgp, const char *userid, char *mem,
size_t size, char *out, size_t outsize, const unsigned armored,
const unsigned cleartext);
netpgp_verify_memory(netpgp_t *netpgp, const void *in,
const size_t insize, void *out, size_t outsize, const int armored);
libnetpgp is a library interface to enable digital signatures to be cre-
ated 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 stored
in the netpgp_t structure, and set using the netpgp_setvar() function.
If no public key ring file is set, initial values will be taken from
those in the .gnupg/pubring.gpg file in the user's home directory. Simi-
larily, if no secret key ring file is set, 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. The signature subkey fields can also be displayed using this func-
tion. The netpgp_match_list_keys() function is used to match (via regu-
lar expression) a subset of the keys in the keyring. If the expression
to match is NULL, the search will degenerate into a listing of all keys
in the keyring.
The home directory is specified as an internal variable, and its exis-
tence is checked using the netpgp_set_homedir() function. This function
can operate in a verbose or quiet manner, depending on the value of the
argument provided. If the subdirectory argument is provided, this subdi-
rectory is appended to the home directory in order to search for the
To export a key, the netpgp_export_key() is used. Output is sent to the
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
To generate a key, the netpgp_generate_key() is used. It takes an argu-
ment of the number of bits to use in the key. At the time that this man-
ual 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 bet-
ter to use at least 4096 or 8192 bits. This situation should be moni-
tored 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_sign_memory() is a function which can sign an area of memory, and
netpgp_verify_memory() verifies the digital signature produced.
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 are
general purpose functions, and are used to set and retrieve values for
internal variables. For example, they can be used to set and to retrieve
the value of the user id which has been set, the home directory from
which to find the keyrings, the verbosity settings, and many more. The
netpgp_incvar() function is used to add a numeric increment to the inter-
nal variable. This incremental value can be negative. It is primarily
used to increase the verbosity settings.
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 version or maintainer information
depending upon the type argument. At the present time, two types are
defined: ``version'' and ``maintainer''. A failure to present a known
type argument to netpgp_get_info() will result in the string
``[unknown]'' being returned.
The libnetpgp library first appeared in NetBSD 6.0.
Alistair Crooks <agc@NetBSD.org> wrote this high-level interface.
This manual page was written by
NetBSD 6.0 June 17, 2010 NetBSD 6.0