NAME
libnetpgp —
digital signing and verification,
encryption and decryption
LIBRARY
library “libnetpgp”
SYNOPSIS
#include
<netpgp.h>
The following functions relate to initialisations and
finalisations:
int
netpgp_init(netpgp_t
*netpgp);
int
netpgp_end(netpgp_t
*netpgp);
The following functions are for debugging, reflection and
information:
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);
The following functions are for variable management:
int
netpgp_setvar(netpgp_t *netpgp,
const char *name, const char
*value);
char *
netpgp_getvar(netpgp_t *netpgp,
const char *name);
int
netpgp_incvar(netpgp_t *netpgp,
const char *name, const int
delta);
int
netpgp_unsetvar(netpgp_t
*netpgp, const char *name);
The following function sets the home directory:
int
netpgp_set_homedir(netpgp_t
*netpgp, char *homedir, char
*subdir, const int quiet);
The following functions are used for key management:
int
netpgp_list_keys(netpgp_t
*netpgp, const int printsigs);
int
netpgp_list_keys_json(netpgp_t
*netpgp, char **json, const int
psigs);
int
netpgp_match_keys(netpgp_t
*netpgp, char *name, const char
*fmt, void *vp, const int
psigs);
int
netpgp_match_keys_json(netpgp_t
*netpgp, char **json, char
*name, const char *fmt, const
int psigs);
int
netpgp_match_pubkeys(netpgp_t
*netpgp, char *name, void
*vp);
int
netpgp_find_key(netpgp_t
*netpgp, char *userid);
char *
netpgp_get_key(netpgp_t *netpgp,
const char *name, const char
*fmt);
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_validate_sigs(netpgp_t
*netpgp);
int
netpgp_format_json(void *vp,
const char *json, const int
psigs);
The following functions are used for file management:
int
netpgp_encrypt_file(netpgp_t
*netpgp, const char *userid,
const char *filename, char *out,
int armored);
int
netpgp_decrypt_file(netpgp_t
*netpgp, const char *filename,
char *out, int armored);
int
netpgp_sign_file(netpgp_t
*netpgp, const char *userid,
const char *filename, char *out,
int armored, int cleartext,
int detached);
int
netpgp_verify_file(netpgp_t
*netpgp, const char *in, const
char *out, int armored);
The following functions are used for memory signing and
encryption:
int
netpgp_encrypt_memory(netpgp_t
*netpgp, const char *userid,
void *in, const size_t insize,
char *out, size_t outsize,
int armored);
int
netpgp_decrypt_memory(netpgp_t
*netpgp, const void *input,
const size_t insize, char *out,
size_t outsize, const int
armored);
int
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);
int
netpgp_verify_memory(netpgp_t
*netpgp, const void *in, const
size_t insize, void *out, size_t
outsize, const int armored);
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, as well as set
the user identity in the userid member of the
netpgp_t structure. These are set using the
netpgp_setvar() function and unset using the
netpgp_unsetvar()
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. Similarly, 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 user identity is obtained from the
userid environment variable, or failing that, the
value of the “default-key” setting from
.gnupg/gpg.conf file in the user's home directory is
used. The netpgp_init() function returns 1 on
success, 0 on failure.
To list all the keys in a keyring, the
netpgp_list_keys()
function is used. To list all the keys in a keyring as a JSON encoded
string, the
netpgp_list_keys_json()
function is used. To find and list keys in a keyring, the
netpgp_match_keys()
function is used. To find and list keys in a keyring, output as a JSON
encoded string, the
netpgp_match_keys_json()
function is used. To find and list keys in a better suited machine-readble
format, such as for redirection to other parsing engines, the
netpgp_match_pubkeys()
function is used. The signature subkey fields can also be displayed using
this function.
The home directory is specified as an
internal variable, and its existence 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 subdirectory is appended to the home directory in order to
search for the keyrings.
To print key information from a JSON
encoded string, stored in a file, the
netpgp_format_json()
function is used.
To validate the signature of keys in a
public key keyring, the
netpgp_validate_sigs()
function is used.
To export a key, the
netpgp_export_key()
function is used. Output is sent to the standard output.
To import a key onto the public keyring,
the
netpgp_import_key()
function 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()
function 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()
function is used, and the
netpgp_decrypt_file()
function is used to decrypt the results of the encryption. To sign a file,
the
netpgp_sign_file()
function is used, and the resulting signed file can be verified using the
netpgp_verify_file()
function.
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 internal 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()
function returns the version or maintainer information depending upon the
type argument. At the present time, two types are
defined: “version” and “maintainer”. The
maintainer information returned contains the name, email address, and PGP
short key id. A failure to present a known type
argument to netpgp_get_info() will result in the
string “[unknown]” being returned.
SEE ALSO
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.