| LIBNETPGP(3) | Library Functions Manual | LIBNETPGP(3) | 
libnetpgp —
#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);
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.
libnetpgp library first appeared in
  NetBSD 6.0.
This manual page was written by Alistair Crooks.
| May 10, 2018 | NetBSD 10.0 |