LIBNETPGP(3)

LIBNETPGP(3) | Library Functions Manual | LIBNETPGP(3)

# NAME

`libnetpgp` —
digital signing and verification, encryption and decryption

# LIBRARY

Netpgp Signing, Verification, Encryption and Decryption (libnetpgp, -lnetpgp)

# 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

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.

May 10, 2018 | NetBSD 9.0