1.\" $NetBSD: libnetpgp.3,v 1.11 2009/12/22 06:03:24 agc Exp $ 2.\" 3.\" Copyright (c) 2009 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This manual page is derived from software contributed to The 7.\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 21, 2009 31.Dt LIBNETPGP 3 32.Os 33.Sh NAME 34.Nm libnetpgp 35.Nd digital signing and verification, encryption and decryption 36.Sh LIBRARY 37.Lb libnetpgp 38.Sh SYNOPSIS 39.In netpgp.h 40.Pp 41The following functions relate to initialisations and finalisations: 42.Ft int 43.Fo netpgp_init 44.Fa "netpgp_t *netpgp" "char *userid" "char *pubringfile" "char *secringfile" 45.Fc 46.Ft int 47.Fo netpgp_end 48.Fa "netpgp_t *netpgp" 49.Fc 50.Pp 51The following functions are for debugging, reflection and information: 52.Ft int 53.Fo netpgp_set_debug 54.Fa "const char *filename" 55.Fc 56.Ft int 57.Fo netpgp_get_debug 58.Fa "const char *filename" 59.Fc 60.Ft int 61.Fo netpgp_get_info 62.Fa "const char *type" 63.Fc 64.Ft int 65.Fo netpgp_list_packets 66.Fa "netpgp_t *netpgp" "char *filename" "int armour" "char *pubringname" 67.Fc 68.Pp 69The following functions are for variable management: 70.Ft int 71.Fo netpgp_setvar 72.Fa "netpgp_t *netpgp" "const char *name" "const char *value" 73.Fc 74.Ft char * 75.Fo netpgp_getvar 76.Fa "netpgp_t *netpgp" "const char *name" 77.Fc 78.Ft int 79.Fo netpgp_incvar 80.Fa "netpgp_t *netpgp" "const char *name" "const int delta" 81.Fc 82.Pp 83The following function sets the home directory: 84.Ft int 85.Fo netpgp_set_homedir 86.Fa "netpgp_t *netpgp" "char *homedir" "char *subdir" "const int quiet" 87.Fc 88.Pp 89The following functions are used for key management: 90.Ft int 91.Fo netpgp_list_keys 92.Fa "netpgp_t *netpgp" 93.Fc 94.Ft int 95.Fo netpgp_match_list_keys 96.Fa "netpgp_t *netpgp" "char *pattern" 97.Fc 98.Ft int 99.Fo netpgp_find_key 100.Fa "netpgp_t *netpgp" "char *userid" 101.Fc 102.Ft char * 103.Fo netpgp_get_key 104.Fa "netpgp_t *netpgp" "const char *id" 105.Fc 106.Ft int 107.Fo netpgp_export_key 108.Fa "netpgp_t *netpgp" "char *userid" 109.Fc 110.Ft int 111.Fo netpgp_import_key 112.Fa "netpgp_t *netpgp" "char *file" 113.Fc 114.Ft int 115.Fo netpgp_generate_key 116.Fa "netpgp_t *netpgp" "char *userid" "int numbits" 117.Fc 118.Pp 119The following functions are used for file management: 120.Ft int 121.Fo netpgp_encrypt_file 122.Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" 123.Fa "int armored" 124.Fc 125.Ft int 126.Fo netpgp_decrypt_file 127.Fa "netpgp_t *netpgp" "char *filename" "char *out" "int armored" 128.Fc 129.Ft int 130.Fo netpgp_sign_file 131.Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" 132.Fa "int armored" "int cleartext" "int detached" 133.Fc 134.Ft int 135.Fo netpgp_verify_file 136.Fa "netpgp_t *netpgp" "char *f" "int armored" 137.Fc 138.Pp 139The following functions are used for memory signing and encryption: 140.Ft int 141.Fo netpgp_encrypt_memory 142.Fa "netpgp_t *netpgp" "char *userid" "void *in" "const size_t insize" 143.Fa "char *out" "size_t outsize" "int armored" 144.Fc 145.Ft int 146.Fo netpgp_decrypt_memory 147.Fa "netpgp_t *netpgp" "const void *input" "const size_t insize" 148.Fa "char *out" "size_t outsize" "const int armored" 149.Fc 150.Ft int 151.Fo netpgp_sign_memory 152.Fa "netpgp_t *netpgp" "const char *userid" "char *mem" 153.Fa "size_t size" "char *out" "size_t outsize" 154.Fa "const unsigned armored" "const unsigned cleartext" 155.Fc 156.Ft int 157.Fo netpgp_verify_memory 158.Fa "netpgp_t *netpgp" "const void *in" "const size_t insize" 159.Fa "void *out" "size_t outsize" "const int armored" 160.Fc 161.Sh DESCRIPTION 162.Nm 163is a library interface to enable digital signatures to be created and 164verified, and also for files and memory to be encrypted and decrypted. 165Functions are also provided for management of user keys. 166.Pp 167The library uses functions from the openssl library for multi-precision 168integer arithmetic, and for RSA and DSA key signing and verification, 169encryption and decryption. 170.Pp 171Normal operation sees the 172.Nm 173process be initialised using the 174.Fn netpgp_init 175function, which will set up the public and private keyrings, and set the 176user identity to the 177.Ar userid 178argument passed to the function. 179If no public key ring file is provided, initial values will be taken from those 180in the 181.Pa .gnupg/pubring.gpg 182file in the user's home directory. 183Similarily, if no secret key ring file is provided, 184initial values will be taken from those 185in the 186.Pa .gnupg/secring.gpg 187file in the user's home directory. 188The 189.Fn netpgp_init 190returns 1 on sucess, 0 on failure. 191.Pp 192To list all the keys in a keyring, the 193.Fn netpgp_list_keys 194function is used. 195The 196.Fn netpgp_match_list_keys 197function is used to match (via regular expression) 198a subset of the keys in the keyring. 199If the expression to match is NULL, 200the search will degenerate into a 201listing of all keys in the keyring. 202.Pp 203The home directory is specified as an internal variable, 204and its existence is checked using the 205.Fn netpgp_set_homedir 206function. 207This function can operate in a verbose or quiet 208manner, depending on the value of the argument provided. 209If the subdirectory argument is provided, this subdirectory 210is appended to the home directory in order to search for 211the keyrings. 212.Pp 213To export a key, the 214.Fn netpgp_export_key 215is used. 216Output is sent to the standard output. 217.Pp 218To import a key onto the public keyring, the 219.Fn netpgp_import_key 220is used. 221The name of the file containing the key to be imported is provided 222as the filename argument. 223.Pp 224To generate a key, the 225.Fn netpgp_generate_key 226is used. 227It takes an argument of the number of bits to use in the key. 228At the time that this manual page was created (April 2009), 229the recommendations are that the bare minimum key size 230of at least 2048 bits is used, and it would be much better 231to use at least 4096 or 8192 bits. 232This situation should be monitored to ensure that it does 233not go out of date. 234.Pp 235Encryption, decryption, signing and verification of 236files are the lifeblood of the 237.Nm 238library. 239To encrypt a file, the 240.Fn netpgp_encrypt_file 241and the 242.Fn netpgp_decrypt_file 243is used to decrypt the results of the encryption. 244To sign a file, the 245.Fn netpgp_sign_file 246is used, and the resulting signed file can be verified 247using the 248.Fn netpgp_verify_file 249function. 250.Pp 251.Fn netpgp_sign_memory 252is a function which can sign an area 253of memory, and 254.Fn netpgp_verify_memory 255verifies the digital signature produced. 256.Pp 257Internally, an encrypted or signed file 258is made up of 259.Dq packets 260which hold information pertaining to the signature, 261encryption method, and the data which is being protected. 262This information can be displayed in a verbose manner using 263the 264.Fn netpgp_list_packets 265function. 266.Pp 267The 268.Fn netpgp_setvar 269and 270.Fn netpgp_getvar 271functions are used to manage the hash algorithm that 272is used with RSA signatures. 273These functions are general purpose functions, and 274are used to set and retrieve values for internal variables. 275For example, they 276can be used to set and to retrieve the 277value of the user id 278which has been set, 279the home directory from which to find the keyrings, 280the verbosity settings, and many more. 281The 282.Fn netpgp_incvar 283function is used to add a numeric increment to the 284internal variable. 285This incremental value can be negative. 286It is primarily used to increase the verbosity settings. 287.Pp 288In 289.Nm 290files are encrypted using the public key of the userid. 291The secret key is used to decrypt the results of that encryption. 292Files are signed using the secret key of the userid. 293The public key is used to verify that the file was signed, 294who signed the file, and the date and time at which it was signed. 295.Pp 296Some utility functions are also provided for debugging, and for 297finding out version and maintainer information from calling programs. 298These are the 299.Fn netpgp_set_debug 300and the 301.Fn netpgp_get_debug 302functions (for getting verbose debugging information on a per-source 303file basis). 304.Pp 305The 306.Fn netpgp_get_info 307returns the information depending upon the 308.Ar type 309argument. 310.Sh SEE ALSO 311.Xr netpgp 1 , 312.Xr ssl 3 313.Sh HISTORY 314The 315.Nm 316library first appeared in 317.Nx 6.0 . 318.Sh AUTHORS 319.An Ben Laurie , 320.An Rachel Willmer . 321.An Alistair Crooks Aq agc@NetBSD.org 322wrote this high-level interface. 323.Pp 324This manual page was written by 325.An Alistair Crooks . 326