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