LIBNETPGP(3)            NetBSD 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 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, 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 signa-
     ture subkey fields can also be displayed using this function.

     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
     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 pro-
     vided 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 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() function returns the version or maintainer informa-
     tion 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 fail-
     ure 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.

NetBSD 8.0                       May 10, 2018                       NetBSD 8.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias
©1996-2018 Modified for NetBSD by Kimmo Suominen