Merged branch dev-0.4
[poldi.git] / doc / poldi.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @c Copyright (C) 2000, 2002, 2003, 2004, 2005, 2007, 2008 Free Software Foundation, Inc.
3 @c 
4 @c This file is part of Poldi.
5 @c
6 @c Permission is granted to copy, distribute and/or modify this document
7 @c under the terms of the GNU General Public License as published by the
8 @c Free Software Foundation; either version 2 of the License, or (at your
9 @c option) any later version. A copy of the license is included in the 
10 @c file 'gpl.texi'.
11 @c
12 @setfilename poldi.info
13 @settitle The `Poldi Reference Manual
14
15 @dircategory GNU Utilities
16 @direntry
17 * poldi: (poldi) PAM authenciation via OpenPGP smartcards.
18 @end direntry
19
20 @include version.texi
21
22 @ifinfo
23 This file documents `Poldi'.
24
25 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
26 @cite{The Poldi Manual}, for Version @value{VERSION}.
27
28 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 g10 Code GmbH.
29
30 Permission is granted to copy, distribute and/or modify this document
31 under the terms of the GNU General Public License as published by the
32 Free Software Foundation; either version 2 of the License, or (at your
33 option) any later version. The text of the license can be found in the
34 section entitled ``Copying''.
35 @end ifinfo
36
37 @titlepage
38 @center @titlefont{The Poldi Manual}
39 @sp 6
40 @center Edition @value{EDITION}
41 @sp 1
42 @center last updated @value{UPDATED}
43 @sp 1
44 @center for version @value{VERSION}
45 @page
46 @vskip 0pt plus 1filll
47 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 g10 Code GmbH.
48
49 Permission is granted to copy, distribute and/or modify this document
50 under the terms of the GNU General Public License as published by the
51 Free Software Foundation; either version 2 of the License, or (at your
52 option) any later version. The text of the license can be found in the
53 section entitled ``Copying''.
54 @end titlepage
55 @summarycontents
56 @contents
57 @page
58
59 @ifnottex
60 @node Top
61 @top Main Menu
62 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
63 @cite{The Poldi Manual}, for Version
64 @value{VERSION} of Poldi.
65
66 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 g10 Code GmbH.
67
68 Permission is granted to copy, distribute and/or modify this document
69 under the terms of the GNU General Public License as published by the
70 Free Software Foundation; either version 2 of the License, or (at your
71 option) any later version. The text of the license can be found in the
72 section entitled ``Copying''.
73
74 @end ifnottex
75
76 @menu
77 * Overview::
78 * Authentication methods::
79 * Installation from Source::
80 * Configuration::
81 * Configuration Example::
82 * Testing::
83 * Notes on Applications::
84 * Copying::                     The GNU General Public License
85
86 @c @detailmenu
87 @c  --- The Detailed Node Listing ---
88 @c * Overview::                    Overview
89 @c * Building::                    Building Poldi
90 @c @end detailmenu
91
92 @end menu
93
94 @node Overview
95 @chapter Overview
96
97 Poldi is a PAM module implementing challenge/response based
98 authentication through the OpenPGP smartcard
99 (http://www.g10code.de/p-card.html).  It makes use of several GnuPG
100 components (Libgcrypt, Assuan, Scdaemon, Dirmngr) and currently supports two
101 authentication methods:
102
103 @table @asis
104 @item ``local-database'' authentication method
105
106 This method establishs the mapping between user accounts and
107 smartcards through a locally administered database.
108
109 @item ``X509'' authentication
110
111 This method uses the PKI infrastructure provided by Dirmngr for
112 validating certificates.  OpenPGP smartcards are associated with X509
113 certificates through the smartcard's ``url'' field; the user account
114 name to use for authentication is extracted from the certificate.
115 @end table
116
117 This manual is primarily intended for system administrators interested
118 in setting up authentication through PAM Poldi.
119
120 @node Authentication methods
121 @chapter Authentication methods
122
123 This chapter explains the supported authentication methods in detail.
124
125 @menu
126 * Local-database authentication::
127 * X509 authentication::
128 @end menu
129
130 @node Local-database authentication
131 @section Local-database authentication
132
133 The login process through local database authentication consists
134 essentially of three parts: looking up the smartcards key on the local
135 computer, figuring out the desired identity for the login and finally
136 doing challenge/response authentication against the local key.
137
138 Poldi maintains a database, which associates local user accounts with
139 smartcards (through their serial number).  There are little
140 restrictions in respect to the mapping of users and smartcards: one
141 smartcard can be associated with many users and one user can be
142 associated with many smartcards.
143
144 The public keys are stored in files in a subdirectory named
145 ``keys''. The files are named after the card serial numbers and must
146 contain the public key as a single S-Expression as it is printed out
147 by poldi-ctrl.
148
149 The mapping between keys and Unix accounts is to be established by
150 adding appropriate entries to the user database file named ``users''.
151 Such an entry is of the following form:
152
153 @example
154 <card serial number> <white space(s)> <account>.
155 @end example
156
157 @node X509 authentication
158 @section X509 authentication
159
160 With X509 authentication smartcards need to be associated with X509
161 certicates.  This mapping is to be established through the ``url''
162 field on the OpenPGP smartcard.  The url field is expected to hold
163 either a valid LDAP url (``ldap://...'') or a file url
164 (``file:///...'').  After a certificate has been successfuly looked
165 up, it is validated through Dirmngr and a challenge-response
166 authentication is triggered against the smartcard.  The mapping
167 between smartcards and local accounts is established through the list
168 of email addresses contained in the certificate.  Through the
169 configuration file, Poldi is informed about the ``X509 domain'' to
170 use.  This domain is used when looking through the list of email
171 addresses for the local username on the system. Note: semantics might
172 change.
173
174 To illustrate this with an example: lets assume a user is trying to
175 authenticate himself trough Poldi's X509 method.  Poldi looks up the
176 url field of the user's smartcard and retrieves his X509 certificate.
177 The certificate contains two e-mail addresses: ``<dude@@example.com>''
178 and ``<fry@@gnupg.org>''.  Since the administrator set the ``X509
179 domain'' to ``gnupg.org'' in Poldi's configuration file, Poldi will
180 pick out the address ``fry@@gnupg.org'' and (after succesful
181 challenge-response authentication) will let the user login as ``fry''.
182
183 @node Installation from Source
184 @chapter Installation from Source
185
186 Building and installing Poldi from source should be pretty
187 straightforward, since it uses the GNU autotools.  Build- and runtime
188 dependencies may vary with the enabled authentication methods.
189
190 Independent from enabled authentication methods, Poldi depends on
191 Libgpg-error, Libgcrypt, Libassuan, Scdaemon and of course Libpam.
192
193 The ``X509'' authentication method additionaly has a build-time
194 dependency on libksba and requires Dirmngr to be properly setup at
195 runtime.  The ``local database'' authentication method has no
196 additional requirements.
197
198 Details on the building procedure can be found in the file
199 ``INSTALL''.
200
201 At least one configure switch should be set:
202 @code{--with-pam-module-directory}, which specifies the installation
203 directory for PAM modules.  Alternatively one can copy the built PAM
204 module (named ``pam_poldi.so'') to the correct place manually.
205
206 For building the Poldi package, ``make'' needs to be invoked.
207
208 Installing Poldi works by invoking the ``install'' make target.  As
209 noted before, special care must be taken so that the PAM module ends up
210 in the correct place.
211
212 Poldi requires some directories beneath `SYSCONFDIR/poldi', which is
213 usually equal to `PREFIX/etc/poldi'. These directories can be created
214 manually or through the `install-conf-skeleton' make target.
215
216 @node Configuration
217 @chapter Configuration
218
219 Poldi can be configured through configuration files and through PAM
220 arguments.  All configuration files of Poldi are stored beneath
221 ``@code{sysconfdir}/poldi''.
222
223 Poldi's main configuration file is
224 ``@code{sysconfdir}/poldi/poldi.conf''.  The syntax of Poldi's
225 configuration file is identical to the one used by several other GnuPG
226 components; options and their values are written next to each other,
227 seperated by a whitespace - one such configuration item per line.
228
229 Poldi supports the following authentication method independent
230 options, which can be specified in the main configuration file and in
231 the PAM configuration files as arguments to the Poldi PAM module (with
232 standard doubledash notation).
233
234 @table @code
235 @item logfile FILENAME
236 Specify the file to use for log messages.
237 @item auth-method AUTH-METHOD
238 Specify the authentication method to use.  May be either ``localdb
239 or ``x509''.
240 @item debug
241 Enable debugging messages.
242 @end table
243
244 Further configuration depends on the authentication method to use.
245
246 @menu
247 * Configuration for ``local-database'' authentication::
248 * Configuration for ``X509'' authentication::
249 @end menu
250
251 @node Configuration for ``local-database'' authentication
252 @section Configuration for ``local-database'' authentication
253
254 For the local-database authentication method additional configuration
255 is required.  All local-database specific configuration files are
256 stored in the subdirectory ``localdb'':
257
258 @table @code
259 @item File: users
260 This file contains the mapping between smartcard serial numbers and
261 local usernames.  Syntax: this file consists of entries - one entry
262 per line.  Entries are of the form:
263 "<SERIALNO><WHITESPACES><USERNAME>\n" (without quotation marks and
264 without angle brackets.  Allowed whitespaces are spaces and tabs.
265 <SERIALNO> is the serial number of an OpenPGP smartcard as reported by
266 poldi-ctrl --print-serialno.  <USERNAME> is a valid username on the
267 system.  Comments are opened with "#" and terminated by a newline.
268
269 @item Directory: keys
270
271 This directory contains the "key database" for Poldis "local database"
272 authentication method.  When Poldi needs the key belonging to a given
273 smartcard serial number, it looks up a file in this directory whose
274 name is exactly the serial number.
275
276 Usually only the system administrator is able to modify this directory
277 and thus establish the mapping between smartcards and keys.  But it
278 might make sense for the administrator to make a file in this
279 directory writable for a ordinary user as well, since this would allow
280 that user to update his smartcard's key and adjust the mapping himself
281 without bothering the admin.
282 @end table
283
284
285 @node Configuration for ``X509'' authentication
286 @section Configuration for ``X509'' authentication
287
288 In case X509 authentication is enabled, Poldi tries to parse another
289 configuration file, namely ``poldi-x509.conf''.  The following
290 configuration options are supported for this configuration file:
291
292 @table @code
293 @item dirmngr-socket FILENAME
294 Specify the socket to be used for communication with Dirmngr.
295
296 @item x509-domain STRING
297 Specify the X509 domain, which is simply a suffix required for
298 recognizing email addresses contained in user certificates as
299 belonging to the system on which authentication happens.
300 @end table
301
302 @node Configuration Example
303 @chapter Configuration Example
304
305 @menu
306 * Example for ``local-database'' authentication::
307 * Example for ``X509'' authentication::
308 @end menu
309
310 @node Example for ``local-database'' authentication
311 @section Example for ``local-database'' authentication
312
313 Lets assume a new installation of Poldi into the root filesystem,
314 having configuration files stored beneath /etc/poldi. The user
315 ``moritz'', who got an OpenPGP card with the serial number
316 ``D2760001240101010001000006550000, would like to authenticate himself
317 through Poldi.
318
319 First, the system administrator has to associate the user moritz with
320 the card's serial number:
321
322 @example
323 $ echo "D2760001240101010001000006550000 moritz" >> /etc/poldi/localdb/users
324 @end example
325
326 Second, the system administrator needs to write the card's key into a
327 card-specific key file.  Therefore he inserts Moritz' smartcard and
328 executes:
329
330 @example
331 $ poldi-ctrl --print-key > /etc/poldi/localdb/keys/D2760001240101010001000006550000
332 @end example
333
334 The administrator wants to allow Moritz to update his card's key
335 himself; he/she types:
336
337 @example
338 $ chown moritz /etc/poldi/localdb/keys/D2760001240101010001000006550000
339 @end example
340
341 That's it.
342
343 @node Example for ``X509'' authentication
344 @section Example for ``X509'' authentication
345
346 Setting up X509 authentication is more complicated than setting up
347 localdb authentication, since more components are involved.  This
348 sections tries to explain the basic steps.
349
350 When using localdb authentication, all we need is a list of keys on
351 the system, against which the challenge-response authentication is
352 done.  For X509 authentication we need to:
353
354 @table @asis
355 @item ... create X509 certificates
356 one per smartcard, issued by a certificate authority trusted by Dirmngr
357 @item ... setup the smartcards
358 so that they ``point'' to ``their'' certificates
359 @item ... run Dirmngr
360 making it listen on a specific socket
361 @item ... setup Poldi
362 specifying Dirmngr's socket and the ``X509 domain'' in poldi-x509.conf.
363 @end table
364
365 Lets assume we don't have a certificate authority yet.  For the CA
366 administration one needs a CA program, like OpenSSL.  It can either be
367 used directly or through a GUI frontend like ``Tiny CA''.
368
369 FIXME: explain situation/goal (x509_domain).
370
371 Step 1: Create a CA.  I created my test CA with the following
372 settings:
373
374 @table @asis
375 @item Common Name: Fnord Inc CA
376 @item Country Name: DE
377 @item Organization Name: Fnord Inc
378 @item Organizational Unit: Testing
379 @end table
380
381 The other options required are rather self-explanitory.  After CA
382 creation, we need to generate a signing request.  For this,
383 gpgsm-gencert.sh can be used (after inserting the users smartcard and
384 running gpg-agent):
385
386 @example
387 $ gpgsm-gencert.sh
388 Key type
389  [1] RSA
390  [2] Existing key
391  [3] Direct from card
392 Your selection: 3
393 You selected: Direct from card
394 Card with S/N D2760001240101010001000006550000 found
395 gpg-agent uses OPENPGP.3 as ssh key
396 Select key 
397  [1] OPENPGP.1
398  [2] OPENPGP.2
399  [3] OPENPGP.3
400  [4] back
401 Your selection: 3
402 You selected: OPENPGP.3
403 Key usage
404  [1] sign, encrypt
405  [2] sign
406  [3] encrypt
407 Your selection: 2
408 You selected: sign
409 Name (DN)
410 > CN=Moritz Schulte
411 E-Mail addresses (end with an empty line)
412 > Moritz.Schulte@@rub.de
413 E-Mail addresses (end with an empty line)
414
415 DNS Names (optional; end with an empty line)
416
417 URIs (optional; end with an empty line)
418
419 Parameters for certificate request to create:
420      1  Key-Type: card:OPENPGP.3
421      2  Key-Length: 
422      3  Key-Usage: sign
423      4  Name-DN: CN=Moritz Schulte
424      5  Name-Email: Moritz.Schulte@@rub.de
425
426 Really create such a CSR?
427  [1] yes
428  [2] no
429 Your selection: 1
430 You selected: yes
431 gpgsm: certificate request created
432 -----BEGIN CERTIFICATE REQUEST-----
433 MIIBnjCCAQcCAQAwGTEXMBUGA1UEAxMOTW9yaXR6IFNjaHVsdGUwgaEwDQYJKoZI
434 hvcNAQEBBQADgY8AMIGLAoGBALjl58iz5T59otx5e6G2NMujUj949QAMLqYXL2Gw
435 bugmlkY8eDQ4Gd1S1fKBXCbGQrZ1D+M8mMdqjLInI4BK9DxBBq7X91YonuJdR1WS
436 6tSIYudMV0UoonbAyksB0zM2SatWz6roD8KgX8cPJbKgKlOmZ4VZGGa0GVayHaEE
437 fQuDAgUA6o2s+aBDMEEGCSqGSIb3DQEJDjE0MDIwIAYDVR0RBBkwF4EVTW9yaXR6
438 LlNjaHVsdGVAcnViLmRlMA4GA1UdDwEB/wQEAwIGwDANBgkqhkiG9w0BAQUFAAOB
439 gQCpRvQK2gV0rjFK4+H7/rBgUZvA5L89tz3vlWSgXwCVqTewgPMKYmFYXViGobti
440 c4laXQuGGqnCjmakbcs5/2Mt13bSTAaTOtfyzWZp+LwVtl8xwR9w/PbbsWyjKwnW
441 9H/jfXaKtyoLQgyUyK3cplPw0jW8bqC/t6zQcHe0YMYfPA==
442 -----END CERTIFICATE REQUEST-----
443
444 @end example
445
446 Import the new certificate signing request in your CA and sign it,
447 yielding a new client certificate.  A note on Tiny CA: the program
448 defaults FIXME mail address.
449
450 Export both, the CA certificate and the client certificate, in DER
451 format.  Export a certificate revocation list (CRL) for your CA in DER
452 format.
453
454 Step 2: Setup OpenPGP smartcard
455
456 The OpenPGP smartcard is not a ``real'' PKCS#XYZ (FIXME?) smartcard -
457 it cannot store X509 certificates.  So instead of ``uploading'' the
458 certificate to the smartcard, we write an URL to the card, through
459 which the complete certificate can be retrieved.  Simply fill the
460 smartcard's ``url'' field with either a ``ldap://'' or a ``file://''
461 URL, pointing to the certificate.  For LDAP urls to work, the
462 certificate must be stored on a LDAP server and Dirmngr must be
463 configured to use that LDAP server.  For testing, one can simply
464 specify ``file:///some/where/cert-exported-from-ca.crt''.  Editing the
465 card's data fields is to be done through GnuPG:
466
467 @example
468 $ gpg --card-edit # (or gpg2)
469 @end example
470
471 Step 3: Setup Dirmngr.
472
473 For debugging purposes it is usually a good idea to add:
474 @example
475 debug-all
476 log-file /some/where/dirmngr.log
477 @end example
478
479 to dirmngr.conf.
480
481 Drop the exported CA certificate in Dirmngr's ``trusted-certs''
482 directory.
483
484 Now, run Dirmngr:
485
486 @example
487 $ eval $(dirmngr --socket /some/where/dirmngr.S --daemon)
488 @end example
489
490 and inform it about the CRL:
491
492 @example
493 $ dirmngr-client --load-crl previously-saved-crl.der
494 @end example
495
496 Check Dirmngr's log file for any errors.
497
498 Step 4: Configure Poldi.
499
500 Obviously, in the main configuration file poldi.conf, we need:
501
502 @example
503 auth-method x509
504 @end example
505
506 Again, it's a very good idea to also add:
507
508 @example
509 debug
510 log-file /some/where/poldi.og
511 @end example
512
513 Add the following to ``poldi-x509.conf'':
514
515 @example
516 dirmngr-socket /some/where/dirmngr.S # the socket name previously specified
517 x509-domain example.com
518 @end example
519
520 Now, things should be ready for trying authentication.
521
522 @node Testing
523 @chapter Testing
524
525 Authentication through Poldi should be tested before activating the
526 module.  For this purpose, the Poldi package includes a simple program
527 named ``pam-test'', which is suitable for testing PAM authentication.
528
529 @menu
530 * The pam-test program::
531 @end menu
532
533 @node The pam-test program
534 @section The pam-test program
535
536 pam-test is a small program suitable for testing PAM authentication,
537 without any Poldi specific aspects.  Synopsis:
538
539 @example # FIXME
540 pam-test [options] <service name>
541 @end example
542
543 The program accepts the following options: FIXME.
544
545
546 @node Notes on Applications
547 @chapter Notes on Applications
548
549 Generally speaking, all applications containing a decent PAM
550 integration should work flawlessly in combination with Poldi.  Sadly,
551 there are applications out there, which do not use PAM correctly.
552 Therefore, they might work not too well in case they are configured to
553 use Poldi.
554
555 This chapter attempts to list the most common problems or useful hints
556 in respect to popular applications.
557
558 When applications still ask for e.g. a username although Poldi is
559 activated for that application, it might be the case that other
560 authentication modules, which trigger this kind of user interaction, are
561 configured to run prior to Poldi.
562
563 @menu
564 * login::
565 * su::
566 * gdm::
567 * xdm::
568 * kdm::
569 @end menu
570
571 @node login
572 @section login
573
574 The `login'-program contained in the `shadow'-package (>= v4.0.3) works
575 fine together with Poldi.
576
577 Usually login is launched by `getty', which might trigger user
578 interaction, which is not appropriate for use with Poldi (e.g., asking
579 for a username).  In this case, getty needs to be told to skip the task
580 of username querying.
581
582 The getty-program from the `util-linux'-package can be started with the
583 `-n' argument in order to not ask for a username.
584
585 @node su
586 @section su
587
588 The `su'-program contained in the `shadow'-package (>= v4.0.3) works
589 fine together with Poldi.
590
591 @node gdm
592 @section gdm
593
594 GDM contains two frontends, the `graphical greeter' and the `standard
595 greeter'.
596
597 At least the standard greeter can be used with Poldi just fine; the
598 graphical greeter obviously asks for usernames prior to triggering PAM
599 authentication.
600
601 @node xdm
602 @section xdm
603
604 XDM does ask for usernames prior to triggering PAM authentication, as
605 such it is not too suitable for use with Poldi.
606
607 @node kdm
608 @section kdm
609
610 KDM asks for username and password in it's default configuration,
611 instead of implementing PAM correctly.
612
613 @include gpl.texi
614
615 @bye