File: gnupg-pkcs11-scd.1

package info (click to toggle)
gnupg-pkcs11-scd 0.7.3-3
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 800 kB
  • ctags: 162
  • sloc: sh: 3,824; ansic: 3,065; makefile: 64
file content (321 lines) | stat: -rw-r--r-- 10,851 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
.\"
.\" Copyright (c) 2006-2007 Zeljko Vrba <zvrba@globalnet.hr>
.\" Copyright (c) 2006-2011 Alon Bar-Lev <alon.barlev@gmail.com>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\"     o Redistributions of source code must retain the above copyright notice,
.\"       this list of conditions and the following disclaimer.
.\"     o Redistributions in binary form must reproduce the above copyright
.\"       notice, this list of conditions and the following disclaimer in the
.\"       documentation and/or other materials provided with the distribution.
.\"     o Neither the name of the <ORGANIZATION> nor the names of its
.\"       contributors may be used to endorse or promote products derived from
.\"       this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 15, 2006
.Os POSIX-compatible
.Dt gnupg-pkcs11-scd 1
.Sh NAME
.Nm gnupg-pkcs11-scd
.Nd GnuPG-compatible smart-card daemon with PKCS#11 support
.Sh SYNOPSIS
.Nm gnupg-pkcs11-scd
.Op --server
.Op --multi-server
.Op --daemon
.Op --verbose
.Op --quiet
.Op --sh
.Op --csh
.Op --options Ar file
.Op --no-detach
.Op --log-file Ar file
.Op --help
.Sh DESCRIPTION
.Nm gnupg-pkcs11-scd
is a drop-in replacement for the smart-card daemon (scd) shipped with the
next-generation GnuPG (gnupg-2). The daemon interfaces to smart-cards
by using RSA Security Inc. PKCS#11 Cryptographic Token Interface (Cryptoki).
The following options are available:
.Bl -tag -width "AA"
.It --server
Run in server mode (foreground). If not redirected, input and output are
over stdin/stdout.
.It --multi-server
Run in multi-server mode (foreground). In addition to communicating over
stdin/stdout, the server also opens an additional listening UNIX socket.
.It --daemon
Detach and run in background.
.It --verbose
Be verbose while running.
.It --quiet
Be as quiet as possible.
.It --sh
Output sh-style environment variable definition.
.It --csh
Output csh-style environment variable definition.
.It --options Ar file
Read options from
.Ar file .
Some of the configuration options can only be set in the configuration
file (see the
.Sx CONFIGURATION
section).
.It --no-detach
Do not detach from console (useful for debugging purposes).
.It --log-file Ar file
Output log to
.Ar file .
.It --help
Print help information.
.El
.Pp
When the daemon receives any of the SIGHUP, SIGTERM and SIGINT signals,
it cleans up and exits.
.Pp
.Nm gnupg-pkcs11-scd
works only with
.Em already personalized cards ,
and supports (for the time being) only RSA keypairs.  The following
constraints must be satisfied:
.Pp
.Bl -enum -compact
.It
For each private key object, a certificate object must exist on the card.
The existence of the corresponding public key object is not important
(since the certificate includes public key).
.It
The certificate and the corresponding private key must have identical CKA_ID
attribute.
.El
.Pp
The PKCS#11 implementation is not obliged to enforce any of the above rules.
However, practice has shown that popular PKCS#11 implementations found "in
the wild" seem to respect them.
.Sh NOTES
Unlike gpg-agent,
.Nm gnupg-pkcs11-scd
supports more than one token available
at the same time. In order to make gpg-agent happy,
.Nm gnupg-pkcs11-scd
always returns the same card serial number to gpg-agent.
When unavailable token is requested,
.Nm gnupg-pkcs11-scd
will use NEEDPIN callback in order to ask for the requested token.
When and if gpg-agent will support more than one serial number or NEEDTOKEN
callback, this behavior will be modified.
.Sh ENVIRONMENT
.Bl -tag -width "USERPROFILE" -compact
.It HOME
Used to locate the home directory.
.It GNUPGHOME
Used instead of
.Pa ~/.gnupg .
.It USERPROFILE
Used only on Win32 to locate the home directory.
.El
.Pp
Additionally, the \\\\Software\\\\GNU\\\\GnuPG\\\\HomeDir registry key is used on
Win32 to locate the default GNUPGHOME.
.Sh FILES
Files affecting the operation of
.Nm gnupg-pkcs11-scd :
.Bl -tag
.It Pa ~/.gnupg/gnupg-pkcs11-scd.conf
.Nm gnupg-pkcs11-scd
uses this as a default configuration file.
.It Pa /etc/gnupg-pkcs11-scd.conf
.Nm gnupg-pkcs11-scd
uses this as a default system wide configuration file.
.It Pa ~/.gnupg/gpg-agent.conf
Default configuration file for gpg-agent.
.El
.Sh CONFIGURATION
To tell gpg-agent to use another smart-card daemon, the following needs to
be put in
.Pa ~/.gnupg/gpg-agent.conf :
.Bd -literal -offset indent
scdaemon-program /usr/bin/gnupg-pkcs11-scd
pinentry-program /usr/bin/pinentry-qt
.Ed
.Pp
The first line is mandatory in order to use
.Nm gnupg-pkcs11-scd .
With the second line you can set your preferred pinentry program (it has to be
one compatible with GnuPG). Of course, you need to adjust the paths according
to your system setup.
.Pp
An example
.Pa ~/.gnupg/gnupg-pkcs11-scd.conf
file (lines beginning with # are comments):
.Bd -literal -offset indent
# Log file.
#log-file log1

# Default is not verbose.
#verbose

# Default is no debugging.
#debug-all

# Pin cache period in seconds; default is infinite.
#pin-cache 20

# Comma-separated list of available provider names. Then set
# attributes for each provider using the provider-[name]-attribute
# syntax.
providers p1

# Provider attributes (see below for detailed description)
provider-p1-library /usr/lib/pkcs11/p1.so
#provider-p1-allow-protected-auth
#provider-p1-cert-private
#provider-p1-private-mask 0

#emulate-openpgpg
#openpgp-sign 5C661B8C07CFD957F7D98D5B9A0F31D236BFAC2A
#openpgp-encr D2DC0BD1EDD185969748B6025B452816F97CBA57
#openpgp-auth A7B8C1A3A8F71FCEC018886F8767927B9C8D871F
.Ed
.Pp
The following attributes can be set for each provider:
.Bl -tag -width "AA"
.It library
Full path to the PKCS#11 shared library (= provider).
.It allow-protected-auth
Allow protected authentication for provider. This needs to be supported by
the provider and you should have appropriate reader hardware.
.It cert-private
Authentication is required before certificates can be accessed. Most
configurations store certificates as public, so there is no need to use this
option.
.It private-mask
Private key mask mode. Use this only when you have problem using
private key operations. The value is hex encoded mask number.
.Bl -tag -width "RECOVER" -compact
.It 0
Determine automatically.
.It 1
Force sign.
.It 2
Force sign with recovery.
.It 4
Force decrypt.
.It 8
Force decrypt with unwrap.
.El
.It emulate-openpgp
Emulate OpenPGP card. Unfortunately, gnupg cannot handle the OpenPGP card with certificates.
So you need to turn this on in order to learn card keys.
.Pp
In OpenPGP card emulation we cannot guess which key should match a type, so you have
to specify the SHA1 of the key explicitly.
.Pp
In order to determine which key is which, use the following command:
.Dl gpg-agent --server gpg-connect-agent
Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first field is the hash, the second
is the subject name.
.Pp
You still have to store a certificate (may be self-signed) that corresponds to the keypair.
.It openpgp-sign
Hex string (Upper letter, no space) SHA1 of signing public key.
.It openpgp-encr
Hex string (Upper letter, no space) SHA1 of encryption public key.
.It openpgp-auth
Hex string (Upper letter, no space) SHA1 of authentication public key.
.El
.Sh GNUPG INTEGRATION
Typical steps to set up a card for gpgsm usage:
.Bl -enum
.It
Import the CA certificate of your issuer:
.Dl gpgsm --import < ca-certificate
You should also manually import all self-signed certificates.
.It
Instruct GnuPG to discover all useful certificates on the card:
.Dl gpgsm --learn-card
.El
.Pp
Signing, verification, etc. work as usual with gpgsm.
.Pp
Typical steps to set up a card for gpg usage:
.Bl -enum
.It
Acquire key ids:
.Dl gpg-agent --server gpg-connect-agent
Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first field is the hash, the second
is the subject name.
.It
Configure gnupg-pkcs11-scd for opengpg emulation, specify the public key hashes
to be used for signature, encryption and authentication.
.It
Instruct GnuPG to discover all useful information of card:
.Dl gpg --card-status
You should see valid card status.
.It
Now, you should virtual generate keys, the keys are not actually generated, but returned
to gpg to be registered.
.Dl gpg --card-edit
.Dl admin
.Dl generate (DO NOT BACKUP KEYS)
.It
Disable the opengpg emulation.
.El
.Pp
Now you can use the same card with your gpg and gpgsm keys. We don't know if this is a
bug or feature in gnupg, but we glad that it works.
.Pp
Signing, verification, etc. work as usual with gpg.
.Sh SECURITY CONSIDERATIONS
All communication between components is currently unprotected and in plain
text (that's how the Assuan protocol operates). It is trivial to trace (using
e.g. the
.Xr strace 1
program) individual components (e.g. pinentry) and steal sensitive data (such
as the smart-card PIN) or even change it (e.g. the hash to be signed).
.Pp
When using the software in production scenario,
.Sy be sure to turn off debugging/verbose options
in configuration of all components. Otherwise, some sensitive data might be
displayed on the screen (most notably, the PIN).
.Sh SEE ALSO
.Xr strace 1
.Xr truss 1
.Xr gnupg 7
.Rs
.%T "GnuPG Home Page"
.%O http://www.gnupg.org
.Re
.Rs
.%T "gnupg-pkcs11 Home Page"
.%O http://gnupg-pkcs11.sourceforge.net
.Re
.Sh AUTHORS AND COPYRIGHT
Copyright (c) 2006-2007 Zeljko Vrba <zvrba@globalnet.hr>
.Pp
Copyright (c) 2006-2011 Alon Bar-Lev <alon.barlev@gmail.com>
.Pp
All rights reserved.
.Pp
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.