| @@ -1,208 +1,208 @@ | | | @@ -1,208 +1,208 @@ |
1 | .\" $NetBSD: libnetpgp.3,v 1.4 2009/05/02 02:44:36 agc Exp $ | | 1 | .\" $NetBSD: libnetpgp.3,v 1.5 2009/05/02 09:40:01 wiz Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 2009 The NetBSD Foundation, Inc. | | 3 | .\" Copyright (c) 2009 The NetBSD Foundation, Inc. |
4 | .\" All rights reserved. | | 4 | .\" All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" This manual page is derived from software contributed to The | | 6 | .\" This manual page is derived from software contributed to The |
7 | .\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) | | 7 | .\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) |
8 | .\" | | 8 | .\" |
9 | .\" Redistribution and use in source and binary forms, with or without | | 9 | .\" Redistribution and use in source and binary forms, with or without |
10 | .\" modification, are permitted provided that the following conditions | | 10 | .\" modification, are permitted provided that the following conditions |
11 | .\" are met: | | 11 | .\" are met: |
12 | .\" 1. Redistributions of source code must retain the above copyright | | 12 | .\" 1. Redistributions of source code must retain the above copyright |
13 | .\" notice, this list of conditions and the following disclaimer. | | 13 | .\" notice, this list of conditions and the following disclaimer. |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 14 | .\" 2. Redistributions in binary form must reproduce the above copyright |
15 | .\" notice, this list of conditions and the following disclaimer in the | | 15 | .\" notice, this list of conditions and the following disclaimer in the |
16 | .\" documentation and/or other materials provided with the distribution. | | 16 | .\" documentation and/or other materials provided with the distribution. |
17 | .\" | | 17 | .\" |
18 | .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS | | 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 | | 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 | | 20 | .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
21 | .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS | | 21 | .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS |
22 | .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | | 22 | .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
23 | .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | | 23 | .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
24 | .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | | 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 | | 25 | .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
26 | .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | | 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 | | 27 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
28 | .\" POSSIBILITY OF SUCH DAMAGE. | | 28 | .\" POSSIBILITY OF SUCH DAMAGE. |
29 | .\" | | 29 | .\" |
30 | .Dd January 30, 2009 | | 30 | .Dd May 2, 2009 |
31 | .Dt LIBNETPGP 3 | | 31 | .Dt LIBNETPGP 3 |
32 | .Os | | 32 | .Os |
33 | .Sh NAME | | 33 | .Sh NAME |
34 | .Nm libnetpgp | | 34 | .Nm libnetpgp |
35 | .Nd digital signing and verification, encryption and decryption | | 35 | .Nd digital signing and verification, encryption and decryption |
36 | .Sh LIBRARY | | 36 | .Sh LIBRARY |
37 | .Lb libnetpgp | | 37 | .Lb libnetpgp |
38 | .Sh SYNOPSIS | | 38 | .Sh SYNOPSIS |
39 | .In netpgp.h | | 39 | .In netpgp.h |
40 | .Ft int | | 40 | .Ft int |
41 | .Fo netpgp_init | | 41 | .Fo netpgp_init |
42 | .Fa "netpgp_t *netpgp" "char *userid" "char *pubringfile" "char *secringfile" | | 42 | .Fa "netpgp_t *netpgp" "char *userid" "char *pubringfile" "char *secringfile" |
43 | .Fc | | 43 | .Fc |
44 | .Ft int | | 44 | .Ft int |
45 | .Fo netpgp_end | | 45 | .Fo netpgp_end |
46 | .Fa "netpgp_t *netpgp" | | 46 | .Fa "netpgp_t *netpgp" |
47 | .Fc | | 47 | .Fc |
48 | .Ft int | | 48 | .Ft int |
49 | .Fo netpgp_list_keys | | 49 | .Fo netpgp_list_keys |
50 | .Fa "netpgp_t *netpgp" | | 50 | .Fa "netpgp_t *netpgp" |
51 | .Fc | | 51 | .Fc |
52 | .Ft int | | 52 | .Ft int |
53 | .Fo netpgp_find_key | | 53 | .Fo netpgp_find_key |
54 | .Fa "netpgp_t *netpgp" "char *userid" | | 54 | .Fa "netpgp_t *netpgp" "char *userid" |
55 | .Fc | | 55 | .Fc |
56 | .Ft int | | 56 | .Ft int |
57 | .Fo netpgp_export_key | | 57 | .Fo netpgp_export_key |
58 | .Fa "netpgp_t *netpgp" "char *userid" | | 58 | .Fa "netpgp_t *netpgp" "char *userid" |
59 | .Fc | | 59 | .Fc |
60 | .Ft int | | 60 | .Ft int |
61 | .Fo netpgp_import_key | | 61 | .Fo netpgp_import_key |
62 | .Fa "netpgp_t *netpgp" "char *file" | | 62 | .Fa "netpgp_t *netpgp" "char *file" |
63 | .Fc | | 63 | .Fc |
64 | .Ft int | | 64 | .Ft int |
65 | .Fo netpgp_generate_key | | 65 | .Fo netpgp_generate_key |
66 | .Fa "netpgp_t *netpgp" "char *userid" "int numbits" | | 66 | .Fa "netpgp_t *netpgp" "char *userid" "int numbits" |
67 | .Fc | | 67 | .Fc |
68 | .Ft int | | 68 | .Ft int |
69 | .Fo netpgp_encrypt_file | | 69 | .Fo netpgp_encrypt_file |
70 | .Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" | | 70 | .Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" |
71 | .Fa "int armored" | | 71 | .Fa "int armored" |
72 | .Fc | | 72 | .Fc |
73 | .Ft int | | 73 | .Ft int |
74 | .Fo netpgp_decrypt_file | | 74 | .Fo netpgp_decrypt_file |
75 | .Fa "netpgp_t *netpgp" "char *filename" "char *out" "int armored" | | 75 | .Fa "netpgp_t *netpgp" "char *filename" "char *out" "int armored" |
76 | .Fc | | 76 | .Fc |
77 | .Ft int | | 77 | .Ft int |
78 | .Fo netpgp_sign_file | | 78 | .Fo netpgp_sign_file |
79 | .Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" | | 79 | .Fa "netpgp_t *netpgp" "char *userid" "char *filename" "char *out" |
80 | .Fa "int armored" "int cleartext" "int detached" | | 80 | .Fa "int armored" "int cleartext" "int detached" |
81 | .Fc | | 81 | .Fc |
82 | .Ft int | | 82 | .Ft int |
83 | .Fo netpgp_verify_file | | 83 | .Fo netpgp_verify_file |
84 | .Fa "netpgp_t *netpgp" "char *f" "int armored" | | 84 | .Fa "netpgp_t *netpgp" "char *f" "int armored" |
85 | .Fc | | 85 | .Fc |
86 | .Ft int | | 86 | .Ft int |
87 | .Fo netpgp_set_debug | | 87 | .Fo netpgp_set_debug |
88 | .Fa "const char *filename" | | 88 | .Fa "const char *filename" |
89 | .Fc | | 89 | .Fc |
90 | .Ft int | | 90 | .Ft int |
91 | .Fo netpgp_get_debug | | 91 | .Fo netpgp_get_debug |
92 | .Fa "const char *filename" | | 92 | .Fa "const char *filename" |
93 | .Fc | | 93 | .Fc |
94 | .Ft int | | 94 | .Ft int |
95 | .Fo netpgp_get_info | | 95 | .Fo netpgp_get_info |
96 | .Fa "const char *type" | | 96 | .Fa "const char *type" |
97 | .Fc | | 97 | .Fc |
98 | .Sh DESCRIPTION | | 98 | .Sh DESCRIPTION |
99 | .Nm | | 99 | .Nm |
100 | is a library interface to enable digital signatures to be created and | | 100 | is a library interface to enable digital signatures to be created and |
101 | verified, and also for files and memory to be encrypted and decrypted. | | 101 | verified, and also for files and memory to be encrypted and decrypted. |
102 | Functions are also provided for management of user keys. | | 102 | Functions are also provided for management of user keys. |
103 | .Pp | | 103 | .Pp |
104 | The library uses functions from the openssl library for multi-precision | | 104 | The library uses functions from the openssl library for multi-precision |
105 | integer arithmetic, and for RSA and DSA key signing and verification, | | 105 | integer arithmetic, and for RSA and DSA key signing and verification, |
106 | encryption and decryption. | | 106 | encryption and decryption. |
107 | .Pp | | 107 | .Pp |
108 | Normal operation sees the | | 108 | Normal operation sees the |
109 | .Nm | | 109 | .Nm |
110 | process be initialised using the | | 110 | process be initialised using the |
111 | .Fn netpgp_init | | 111 | .Fn netpgp_init |
112 | function, which will set up the public and private keyrings, and set the | | 112 | function, which will set up the public and private keyrings, and set the |
113 | user identity to the | | 113 | user identity to the |
114 | .Ar userid | | 114 | .Ar userid |
115 | argument passed to the function. | | 115 | argument passed to the function. |
116 | If no public key ring file is provided, initial values will be taken from those | | 116 | If no public key ring file is provided, initial values will be taken from those |
117 | in the | | 117 | in the |
118 | .Pa .gnupg/pubring.gpg | | 118 | .Pa .gnupg/pubring.gpg |
119 | file in the user's home directory. | | 119 | file in the user's home directory. |
120 | Similarily, if no secret key ring file is provided, | | 120 | Similarily, if no secret key ring file is provided, |
121 | initial values will be taken from those | | 121 | initial values will be taken from those |
122 | in the | | 122 | in the |
123 | .Pa .gnupg/secring.gpg | | 123 | .Pa .gnupg/secring.gpg |
124 | file in the user's home directory. | | 124 | file in the user's home directory. |
125 | The | | 125 | The |
126 | .Fn netpgp_init | | 126 | .Fn netpgp_init |
127 | returns 1 on sucess, 0 on failure. | | 127 | returns 1 on sucess, 0 on failure. |
128 | .Pp | | 128 | .Pp |
129 | To list all the keys in a keyring, the | | 129 | To list all the keys in a keyring, the |
130 | .Fn netpgp_list_keys | | 130 | .Fn netpgp_list_keys |
131 | function is used. | | 131 | function is used. |
132 | .Pp | | 132 | .Pp |
133 | To export a key, the | | 133 | To export a key, the |
134 | .Fn netpgp_export_key | | 134 | .Fn netpgp_export_key |
135 | is used. | | 135 | is used. |
136 | Output is sent to the standard output. | | 136 | Output is sent to the standard output. |
137 | .Pp | | 137 | .Pp |
138 | To import a key onto the public keyring, the | | 138 | To import a key onto the public keyring, the |
139 | .Fn netpgp_import_key | | 139 | .Fn netpgp_import_key |
140 | is used. | | 140 | is used. |
141 | The name of the file containing the key to be imported is provided | | 141 | The name of the file containing the key to be imported is provided |
142 | as the filename argument. | | 142 | as the filename argument. |
143 | .Pp | | 143 | .Pp |
144 | To generate a key, the | | 144 | To generate a key, the |
145 | .Fn netpgp_generate_key | | 145 | .Fn netpgp_generate_key |
146 | is used. | | 146 | is used. |
147 | It takes an argument of the number of bits to use in the key. | | 147 | It takes an argument of the number of bits to use in the key. |
148 | At the time that this manual page was created (April 2009), | | 148 | At the time that this manual page was created (April 2009), |
149 | the recommendations are that the bare minimum key size | | 149 | the recommendations are that the bare minimum key size |
150 | of at least 2048 bits is used, and it would be much better | | 150 | of at least 2048 bits is used, and it would be much better |
151 | to use at least 4096 or 8192 bits. | | 151 | to use at least 4096 or 8192 bits. |
152 | This situation should be monitored to ensure that it does | | 152 | This situation should be monitored to ensure that it does |
153 | not go out of date. | | 153 | not go out of date. |
154 | .Pp | | 154 | .Pp |
155 | Encryption, decryption, signing and verification of | | 155 | Encryption, decryption, signing and verification of |
156 | files are the lifeblood of the | | 156 | files are the lifeblood of the |
157 | .Nm | | 157 | .Nm |
158 | library. | | 158 | library. |
159 | To encrypt a file, the | | 159 | To encrypt a file, the |
160 | .Fn netpgp_encrypt_file | | 160 | .Fn netpgp_encrypt_file |
161 | and the | | 161 | and the |
162 | .Fn netpgp_decrypt_file | | 162 | .Fn netpgp_decrypt_file |
163 | is used to decrypt the results of the encryption. | | 163 | is used to decrypt the results of the encryption. |
164 | To sign a file, the | | 164 | To sign a file, the |
165 | .Fn netpgp_sign_file | | 165 | .Fn netpgp_sign_file |
166 | is used, and the resulting signed file can be verified | | 166 | is used, and the resulting signed file can be verified |
167 | using the | | 167 | using the |
168 | .Fn netpgp_verify_file | | 168 | .Fn netpgp_verify_file |
169 | function. | | 169 | function. |
170 | .Pp | | 170 | .Pp |
171 | In | | 171 | In |
172 | .Nm | | 172 | .Nm |
173 | files are encrypted using the public key of the userid. | | 173 | files are encrypted using the public key of the userid. |
174 | The secret key is used to decrypt the results of that encryption. | | 174 | The secret key is used to decrypt the results of that encryption. |
175 | Files are signed using the secret key of the userid. | | 175 | Files are signed using the secret key of the userid. |
176 | The public key is used to verify that the file was signed, | | 176 | The public key is used to verify that the file was signed, |
177 | who signed the file, and the date and time at which it was signed. | | 177 | who signed the file, and the date and time at which it was signed. |
178 | .Pp | | 178 | .Pp |
179 | Some utility functions are also provided for debugging, and for | | 179 | Some utility functions are also provided for debugging, and for |
180 | finding out version and maintainer information from calling programs. | | 180 | finding out version and maintainer information from calling programs. |
181 | These are the | | 181 | These are the |
182 | .Fn netpgp_set_debug | | 182 | .Fn netpgp_set_debug |
183 | and the | | 183 | and the |
184 | .Fn netpgp_get_debug | | 184 | .Fn netpgp_get_debug |
185 | functions (for getting verbose debugging information on a per-source | | 185 | functions (for getting verbose debugging information on a per-source |
186 | file basis). | | 186 | file basis). |
187 | .Pp | | 187 | .Pp |
188 | The | | 188 | The |
189 | .Fn netpgp_get_info | | 189 | .Fn netpgp_get_info |
190 | returns the information depending upon the | | 190 | returns the information depending upon the |
191 | .Ar type | | 191 | .Ar type |
192 | argument. | | 192 | argument. |
193 | .Sh SEE ALSO | | 193 | .Sh SEE ALSO |
194 | .Xr netpgp 1 , | | 194 | .Xr netpgp 1 , |
195 | .Xr ssl 3 | | 195 | .Xr ssl 3 |
196 | .Sh HISTORY | | 196 | .Sh HISTORY |
197 | The | | 197 | The |
198 | .Nm | | 198 | .Nm |
199 | library first appeared in | | 199 | library first appeared in |
200 | .Nx 6.0 . | | 200 | .Nx 6.0 . |
201 | .Sh AUTHORS | | 201 | .Sh AUTHORS |
202 | .An Ben Laurie , | | 202 | .An Ben Laurie , |
203 | .An Rachel Willmer . | | 203 | .An Rachel Willmer . |
204 | .An Alistair Crooks | | 204 | .An Alistair Crooks |
205 | wrote this high-level interface. | | 205 | wrote this high-level interface. |
206 | .Pp | | 206 | .Pp |
207 | This manual page was written by | | 207 | This manual page was written by |
208 | .An Alistair Crooks Aq agc@NetBSD.org . | | 208 | .An Alistair Crooks Aq agc@NetBSD.org . |