1.\" $NetBSD: libnetpgp.3,v 1.1.1.1 2009/04/23 06:32:03 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 January 30, 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" 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.Sh DESCRIPTION 99.Nm 100is a library interface to enable digital signatures to be created and 101verified, and also for files and memory to be encrypted and decrypted. 102Functions are also provided for management of user keys. 103.Pp 104The library uses functions from the openssl library for multi-precision 105integer arithmetic, and for RSA and DSA key signing and verification, 106encryption and decryption. 107.Pp 108Normal operation sees the 109.Nm 110process be initialised using the 111.Fn netpgp_init 112function, which will set up the public and private keyrings, and set the 113user identity to the 114.It userid 115argument passed to the function. 116If no public key ring file is provided, initial values will be taken from those 117in the 118.It .gnupg/pubring.gpg 119file in the user's home directory. 120Similarily, if no secret key ring file is provided, 121initial values will be taken from those 122in the 123.It .gnupg/secring.gpg 124file in the user's home directory. 125The 126.Fn netpgp_init 127returns 1 on sucess, 0 on failure. 128.Pp 129To list all the keys in a keyring, the 130.Fn netpgp_list_keys 131function is used. 132.Pp 133To export a key, the 134.Fn netpgp_export_key 135is used. 136Output is sent to the standard output. 137.Pp 138To import a key onto the public keyring, the 139.Fn netpgp_import_key 140is used. 141The name of the file containing the key to be imported is provided 142as the filename argument. 143.Pp 144To generate a key, the 145.Fn netpgp_generate_key 146is used. 147It takes an argument of the number of bits to use in the key. 148At the time that this manual page was created (April 2009), 149the recommendations are that the bare minimum key size 150of at least 2048 bits is used, and it would be much better 151to use at least 4096 or 8192 bits. 152This situation should be monitored to ensure that it does 153not go out of date. 154.Pp 155Encryption, decryption, signing and verification of 156files are the lifeblood of the 157.Nm 158library. 159To encrypt a file, the 160.Fn netpgp_encrypt_file 161and the 162.Fn netpgp_decrypt_file 163is used to decrypt the results of the encryption. 164To sign a file, the 165.Fn netpgp_sign_file 166is used, and the resulting signed file can be verified 167using the 168.Fn netpgp_verify_file 169function. 170.Pp 171In 172.Nm 173files are encrypted using the public key of the userid. 174The secret key is used to decrypt the results of that encryption. 175Files are signed using the secret key of the userid. 176The public key is used to verify that the file was signed, 177who signed the file, and the date and time at which it was signed. 178.Pp 179Some utility functions are also provided for debugging, and for 180finding out version and maintainer information from calling programs. 181These are the 182.Fn netpgp_set_debug 183and the 184.Fn netpgp_get_debug 185functions (for getting verbose debugging information on a per-source 186file basis). 187.Pp 188The 189.Fn netpgp_get_info 190returns the information depending upon the 191.It type 192argument. 193.Sh SEE ALSO 194.Xr netpgp 1 , 195.Xr ssl 3 196.Sh HISTORY 197The 198.Nm 199library first appeared in 200.Nx 6.0 . 201.Sh AUTHORS 202.An Ben Laurie 203.An Rachel Willmer. 204.An Alistair Crooks 205wrote this high-level interface. 206.Pp 207This manual page was written by 208.An Alistair Crooks Aq agc@NetBSD.org . 209