1.\" $NetBSD: libnetpgp.3,v 1.27 2018/05/10 15:00:36 sevan Exp $ 2.\" 3.\" Copyright (c) 2009,2010 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 10, 2018 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" 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.Ft int 83.Fo netpgp_unsetvar 84.Fa "netpgp_t *netpgp" "const char *name" 85.Fc 86.Pp 87The following function sets the home directory: 88.Ft int 89.Fo netpgp_set_homedir 90.Fa "netpgp_t *netpgp" "char *homedir" "char *subdir" "const int quiet" 91.Fc 92.Pp 93The following functions are used for key management: 94.Ft int 95.Fo netpgp_list_keys 96.Fa "netpgp_t *netpgp" "const int printsigs" 97.Fc 98.Ft int 99.Fo netpgp_list_keys_json 100.Fa "netpgp_t *netpgp" "char **json" "const int psigs" 101.Fc 102.Ft int 103.Fo netpgp_match_keys 104.Fa "netpgp_t *netpgp" "char *name" "const char *fmt" "void *vp" "const int psigs" 105.Fc 106.Ft int 107.Fo netpgp_match_keys_json 108.Fa "netpgp_t *netpgp" "char **json" "char *name" "const char *fmt" "const int psigs" 109.Fc 110.Ft int 111.Fo netpgp_match_pubkeys 112.Fa "netpgp_t *netpgp" "char *name" "void *vp" 113.Fc 114.Ft int 115.Fo netpgp_find_key 116.Fa "netpgp_t *netpgp" "char *userid" 117.Fc 118.Ft char * 119.Fo netpgp_get_key 120.Fa "netpgp_t *netpgp" "const char *name" "const char *fmt" 121.Fc 122.Ft int 123.Fo netpgp_export_key 124.Fa "netpgp_t *netpgp" "char *userid" 125.Fc 126.Ft int 127.Fo netpgp_import_key 128.Fa "netpgp_t *netpgp" "char *file" 129.Fc 130.Ft int 131.Fo netpgp_generate_key 132.Fa "netpgp_t *netpgp" "char *userid" "int numbits" 133.Fc 134.Ft int 135.Fo netpgp_validate_sigs 136.Fa "netpgp_t *netpgp" 137.Fc 138.Ft int 139.Fo netpgp_format_json 140.Fa "void *vp" "const char *json" "const int psigs" 141.Fc 142.Pp 143The following functions are used for file management: 144.Ft int 145.Fo netpgp_encrypt_file 146.Fa "netpgp_t *netpgp" "const char *userid" "const char *filename" "char *out" 147.Fa "int armored" 148.Fc 149.Ft int 150.Fo netpgp_decrypt_file 151.Fa "netpgp_t *netpgp" "const char *filename" "char *out" "int armored" 152.Fc 153.Ft int 154.Fo netpgp_sign_file 155.Fa "netpgp_t *netpgp" "const char *userid" "const char *filename" "char *out" 156.Fa "int armored" "int cleartext" "int detached" 157.Fc 158.Ft int 159.Fo netpgp_verify_file 160.Fa "netpgp_t *netpgp" "const char *in" "const char *out" "int armored" 161.Fc 162.Pp 163The following functions are used for memory signing and encryption: 164.Ft int 165.Fo netpgp_encrypt_memory 166.Fa "netpgp_t *netpgp" "const char *userid" "void *in" "const size_t insize" 167.Fa "char *out" "size_t outsize" "int armored" 168.Fc 169.Ft int 170.Fo netpgp_decrypt_memory 171.Fa "netpgp_t *netpgp" "const void *input" "const size_t insize" 172.Fa "char *out" "size_t outsize" "const int armored" 173.Fc 174.Ft int 175.Fo netpgp_sign_memory 176.Fa "netpgp_t *netpgp" "const char *userid" "char *mem" 177.Fa "size_t size" "char *out" "size_t outsize" 178.Fa "const unsigned armored" "const unsigned cleartext" 179.Fc 180.Ft int 181.Fo netpgp_verify_memory 182.Fa "netpgp_t *netpgp" "const void *in" "const size_t insize" 183.Fa "void *out" "size_t outsize" "const int armored" 184.Fc 185.Sh DESCRIPTION 186.Nm 187is a library interface to enable digital signatures to be created and 188verified, and also for files and memory to be encrypted and decrypted. 189Functions are also provided for management of user keys. 190.Pp 191The library uses functions from the openssl library for multi-precision 192integer arithmetic, and for RSA and DSA key signing and verification, 193encryption and decryption. 194.Pp 195Normal operation sees the 196.Nm 197process be initialised using the 198.Fn netpgp_init 199function, which will set up the public and private keyrings, as well as set the 200user identity in the 201.Ar userid 202member of the 203.Dv netpgp_t 204structure. 205These are set using the 206.Fn netpgp_setvar 207function and unset using the 208.Fn netpgp_unsetvar 209function. 210If no public key ring file is set, initial values will be taken from those 211in the 212.Pa .gnupg/pubring.gpg 213file in the user's home directory. 214Similarly, if no secret key ring file is set, 215initial values will be taken from those 216in the 217.Pa .gnupg/secring.gpg 218file in the user's home directory. 219The user identity is obtained from the 220.Ev userid 221environment variable, or failing that, the value of the 222.Dq default-key 223setting from 224.Pa .gnupg/gpg.conf 225file in the user's home directory is used. 226The 227.Fn netpgp_init 228function returns 1 on success, 0 on failure. 229.Pp 230To list all the keys in a keyring, the 231.Fn netpgp_list_keys 232function is used. 233To list all the keys in a keyring as a JSON encoded string, the 234.Fn netpgp_list_keys_json 235function is used. 236To find and list keys in a keyring, the 237.Fn netpgp_match_keys 238function is used. 239To find and list keys in a keyring, output as a JSON encoded string, 240the 241.Fn netpgp_match_keys_json 242function is used. 243To find and list keys in a better suited machine-readble format, such as for 244redirection to other parsing engines, the 245.Fn netpgp_match_pubkeys 246function is used. 247The signature subkey fields can also be displayed 248using this function. 249.Pp 250The home directory is specified as an internal variable, 251and its existence is checked using the 252.Fn netpgp_set_homedir 253function. 254This function can operate in a verbose or quiet 255manner, depending on the value of the argument provided. 256If the subdirectory argument is provided, this subdirectory 257is appended to the home directory in order to search for 258the keyrings. 259.Pp 260To print key information from a JSON encoded string, stored in a file, the 261.Fn netpgp_format_json 262function is used. 263.Pp 264To validate the signature of keys in a public key keyring, the 265.Fn netpgp_validate_sigs 266function is used. 267.Pp 268To export a key, the 269.Fn netpgp_export_key 270function is used. 271Output is sent to the standard output. 272.Pp 273To import a key onto the public keyring, the 274.Fn netpgp_import_key 275function is used. 276The name of the file containing the key to be imported is provided 277as the filename argument. 278.Pp 279To generate a key, the 280.Fn netpgp_generate_key 281function is used. 282It takes an argument of the number of bits to use in the key. 283At the time that this manual page was created (April 2009), 284the recommendations are that the bare minimum key size 285of at least 2048 bits is used, and it would be much better 286to use at least 4096 or 8192 bits. 287This situation should be monitored to ensure that it does 288not go out of date. 289.Pp 290Encryption, decryption, signing and verification of 291files are the lifeblood of the 292.Nm 293library. 294To encrypt a file, the 295.Fn netpgp_encrypt_file 296function is used, and the 297.Fn netpgp_decrypt_file 298function is used to decrypt the results of the encryption. 299To sign a file, the 300.Fn netpgp_sign_file 301function is used, and the resulting signed file can be verified 302using the 303.Fn netpgp_verify_file 304function. 305.Pp 306.Fn netpgp_sign_memory 307is a function which can sign an area 308of memory, and 309.Fn netpgp_verify_memory 310verifies the digital signature produced. 311.Pp 312Internally, an encrypted or signed file 313is made up of 314.Dq packets 315which hold information pertaining to the signature, 316encryption method, and the data which is being protected. 317This information can be displayed in a verbose manner using 318the 319.Fn netpgp_list_packets 320function. 321.Pp 322The 323.Fn netpgp_setvar 324and 325.Fn netpgp_getvar 326functions are used to manage the hash algorithm that 327is used with RSA signatures. 328These functions are general purpose functions, and 329are used to set and retrieve values for internal variables. 330For example, they 331can be used to set and to retrieve the 332value of the user id 333which has been set, 334the home directory from which to find the keyrings, 335the verbosity settings, and many more. 336The 337.Fn netpgp_incvar 338function is used to add a numeric increment to the 339internal variable. 340This incremental value can be negative. 341It is primarily used to increase the verbosity settings. 342.Pp 343In 344.Nm 345files are encrypted using the public key of the userid. 346The secret key is used to decrypt the results of that encryption. 347Files are signed using the secret key of the userid. 348The public key is used to verify that the file was signed, 349who signed the file, and the date and time at which it was signed. 350.Pp 351Some utility functions are also provided for debugging, and for 352finding out version and maintainer information from calling programs. 353These are the 354.Fn netpgp_set_debug 355and the 356.Fn netpgp_get_debug 357functions (for getting verbose debugging information on a per-source 358file basis). 359.Pp 360The 361.Fn netpgp_get_info 362function returns the version or maintainer information depending upon the 363.Ar type 364argument. 365At the present time, two types are defined: 366.Dq version 367and 368.Dq maintainer . 369The maintainer information returned contains the name, email address, 370and PGP short key id. 371A failure to present a known 372.Ar type 373argument to 374.Fn netpgp_get_info 375will result in the string 376.Dq [unknown] 377being returned. 378.Sh SEE ALSO 379.Xr netpgp 1 , 380.Xr ssl 3 381.Sh HISTORY 382The 383.Nm 384library first appeared in 385.Nx 6.0 . 386.Sh AUTHORS 387.An -nosplit 388.An Ben Laurie , 389.An Rachel Willmer . 390.An Alistair Crooks Aq Mt agc@NetBSD.org 391wrote this high-level interface. 392.Pp 393This manual page was written by 394.An Alistair Crooks . 395