GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  LIBNETPGP (3)

NAME

libnetpgp - digital signing and verification, encryption and decryption

CONTENTS

Library
Synopsis
Description
See Also
History
Authors

LIBRARY


.Lb libnetpgp

SYNOPSIS


.In netpgp.h

The following functions relate to initialisations and finalisations: int
.Fo netpgp_init netpgp_t *netpgp
.Fc int
.Fo netpgp_end netpgp_t *netpgp
.Fc

The following functions are for debugging, reflection and information: int
.Fo netpgp_set_debug const char *filename
.Fc int
.Fo netpgp_get_debug const char *filename
.Fc int
.Fo netpgp_get_info const char *type
.Fc int
.Fo netpgp_list_packets netpgp_t *netpgp char *filename int armour char *pubringname
.Fc

The following functions are for variable management: int
.Fo netpgp_setvar netpgp_t *netpgp const char *name const char *value
.Fc char *
.Fo netpgp_getvar netpgp_t *netpgp const char *name
.Fc int
.Fo netpgp_incvar netpgp_t *netpgp const char *name const int delta
.Fc

The following function sets the home directory: int
.Fo netpgp_set_homedir netpgp_t *netpgp char *homedir char *subdir const int quiet
.Fc

The following functions are used for key management: int
.Fo netpgp_list_keys netpgp_t *netpgp const int printsigs
.Fc int
.Fo netpgp_match_list_keys netpgp_t *netpgp char *pattern
.Fc int
.Fo netpgp_find_key netpgp_t *netpgp char *userid
.Fc char *
.Fo netpgp_get_key netpgp_t *netpgp const char *id
.Fc int
.Fo netpgp_export_key netpgp_t *netpgp char *userid
.Fc int
.Fo netpgp_import_key netpgp_t *netpgp char *file
.Fc int
.Fo netpgp_generate_key netpgp_t *netpgp char *userid int numbits
.Fc

The following functions are used for file management: int
.Fo netpgp_encrypt_file netpgp_t *netpgp char *userid char *filename char *out int armored
.Fc int
.Fo netpgp_decrypt_file netpgp_t *netpgp char *filename char *out int armored
.Fc int
.Fo netpgp_sign_file netpgp_t *netpgp char *userid char *filename char *out int armored int cleartext int detached
.Fc int
.Fo netpgp_verify_file netpgp_t *netpgp char *f int armored
.Fc

The following functions are used for memory signing and encryption: int
.Fo netpgp_encrypt_memory netpgp_t *netpgp char *userid void *in const size_t insize char *out size_t outsize int armored
.Fc int
.Fo netpgp_decrypt_memory netpgp_t *netpgp const void *input const size_t insize char *out size_t outsize const int armored
.Fc int
.Fo 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
.Fc int
.Fo netpgp_verify_memory netpgp_t *netpgp const void *in const size_t insize void *out size_t outsize const int armored
.Fc

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, 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. 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 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. The signature subkey fields can also be displayed using this function. The netpgp_match_list_keys function is used to match (via regular 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 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 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 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 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". 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
.Nx 6.0 .

AUTHORS


.An -nosplit
.An Ben Laurie ,
.An Rachel Willmer .
.An Alistair Crooks Aq Mt agc@NetBSD.org wrote this high-level interface.

This manual page was written by
.An Alistair Crooks .

Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.