1.\" $NetBSD: libnetpgp.3,v 1.8 2009/05/14 09:42:09 wiz 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 May 12, 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.Ft int 41.Fo netpgp_init 42.Fa "netpgp_t *netpgp" "char *userid" "char *pubringfile" "char *secringfile" 43.Fc 44.Ft int 45.Fo netpgp_end 46.Fa "netpgp_t *netpgp" 47.Fc 48.Ft int 49.Fo netpgp_list_keys 50.Fa "netpgp_t *netpgp" 51.Fc 52.Ft int 53.Fo netpgp_find_key 54.Fa "netpgp_t *netpgp" "char *userid" 55.Fc 56.Ft int 57.Fo netpgp_export_key 58.Fa "netpgp_t *netpgp" "char *userid" 59.Fc 60.Ft int 61.Fo netpgp_import_key 62.Fa "netpgp_t *netpgp" "char *file" 63.Fc 64.Ft int 65.Fo netpgp_generate_key 66.Fa "netpgp_t *netpgp" "char *userid" "int numbits" 67.Fc 68.Ft int 69.Fo netpgp_encrypt_file 70.Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" 71.Fa "int armored" 72.Fc 73.Ft int 74.Fo netpgp_decrypt_file 75.Fa "netpgp_t *netpgp" "char *filename" "char *out" "int armored" 76.Fc 77.Ft int 78.Fo netpgp_sign_file 79.Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" 80.Fa "int armored" "int cleartext" "int detached" 81.Fc 82.Ft int 83.Fo netpgp_verify_file 84.Fa "netpgp_t *netpgp" "char *f" "int armored" 85.Fc 86.Ft int 87.Fo netpgp_set_debug 88.Fa "const char *filename" 89.Fc 90.Ft int 91.Fo netpgp_get_debug 92.Fa "const char *filename" 93.Fc 94.Ft int 95.Fo netpgp_get_info 96.Fa "const char *type" 97.Fc 98.Ft int 99.Fo netpgp_list_packets 100.Fa "netpgp_t *netpgp" "char *filename" "int armour" "char *pubringname" 101.Fc 102.Ft int 103.Fo netpgp_setvar 104.Fa "netpgp_t *netpgp" "const char *name" "const char *value" 105.Fc 106.Ft char * 107.Fo netpgp_getvar 108.Fa "netpgp_t *netpgp" "const char *name" 109.Fc 110.Sh DESCRIPTION 111.Nm 112is a library interface to enable digital signatures to be created and 113verified, and also for files and memory to be encrypted and decrypted. 114Functions are also provided for management of user keys. 115.Pp 116The library uses functions from the openssl library for multi-precision 117integer arithmetic, and for RSA and DSA key signing and verification, 118encryption and decryption. 119.Pp 120Normal operation sees the 121.Nm 122process be initialised using the 123.Fn netpgp_init 124function, which will set up the public and private keyrings, and set the 125user identity to the 126.Ar userid 127argument passed to the function. 128If no public key ring file is provided, initial values will be taken from those 129in the 130.Pa .gnupg/pubring.gpg 131file in the user's home directory. 132Similarily, if no secret key ring file is provided, 133initial values will be taken from those 134in the 135.Pa .gnupg/secring.gpg 136file in the user's home directory. 137The 138.Fn netpgp_init 139returns 1 on sucess, 0 on failure. 140.Pp 141To list all the keys in a keyring, the 142.Fn netpgp_list_keys 143function is used. 144.Pp 145To export a key, the 146.Fn netpgp_export_key 147is used. 148Output is sent to the standard output. 149.Pp 150To import a key onto the public keyring, the 151.Fn netpgp_import_key 152is used. 153The name of the file containing the key to be imported is provided 154as the filename argument. 155.Pp 156To generate a key, the 157.Fn netpgp_generate_key 158is used. 159It takes an argument of the number of bits to use in the key. 160At the time that this manual page was created (April 2009), 161the recommendations are that the bare minimum key size 162of at least 2048 bits is used, and it would be much better 163to use at least 4096 or 8192 bits. 164This situation should be monitored to ensure that it does 165not go out of date. 166.Pp 167Encryption, decryption, signing and verification of 168files are the lifeblood of the 169.Nm 170library. 171To encrypt a file, the 172.Fn netpgp_encrypt_file 173and the 174.Fn netpgp_decrypt_file 175is used to decrypt the results of the encryption. 176To sign a file, the 177.Fn netpgp_sign_file 178is used, and the resulting signed file can be verified 179using the 180.Fn netpgp_verify_file 181function. 182.Pp 183Internally, an encrypted or signed file 184is made up of 185.Dq packets 186which hold information pertaining to the signature, 187encryption method, and the data which is being protected. 188This information can be displayed in a verbose manner using 189the 190.Fn netpgp_list_packets 191function. 192.Pp 193The 194.Fn netpgp_setvar 195and 196.Fn netpgp_getvar 197functions are used to manage the hash algorithm that 198is used with RSA signatures. 199These functions can also be used to set and to retrieve the 200value of the user id 201which has been set. 202.Pp 203In 204.Nm 205files are encrypted using the public key of the userid. 206The secret key is used to decrypt the results of that encryption. 207Files are signed using the secret key of the userid. 208The public key is used to verify that the file was signed, 209who signed the file, and the date and time at which it was signed. 210.Pp 211Some utility functions are also provided for debugging, and for 212finding out version and maintainer information from calling programs. 213These are the 214.Fn netpgp_set_debug 215and the 216.Fn netpgp_get_debug 217functions (for getting verbose debugging information on a per-source 218file basis). 219.Pp 220The 221.Fn netpgp_get_info 222returns the information depending upon the 223.Ar type 224argument. 225.Sh SEE ALSO 226.Xr netpgp 1 , 227.Xr ssl 3 228.Sh HISTORY 229The 230.Nm 231library first appeared in 232.Nx 6.0 . 233.Sh AUTHORS 234.An Ben Laurie , 235.An Rachel Willmer . 236.An Alistair Crooks Aq agc@NetBSD.org 237wrote this high-level interface. 238.Pp 239This manual page was written by 240.An Alistair Crooks . 241