Replaced remaining references to http:///www.gnupg.org by https:
[gnupg-doc.git] / web / aegypten / development.org
1 #+TITLE: GnuPG - Project Ägypten - Development
2 #+STARTUP: showall
3 #+SETUPFILE: "../share/setup.inc"
4
5 * Project Ägypten: Development
6
7 [[file:index.org][Home]] | [[file:tech.org][Technology]] | [[file:who.org][Who]] | [[file:time.org][Schedule]] | Development |
8 [[file:pr.org][Public Relations]] | [[file:glossary.org][Glossary]]
9
10
11 ** Infrastructure
12
13 -  CVS:
14    See below for detailed instructions.
15 -  Bug-Tracking:
16
17    [[http://intevation.de/roundup/aegypten/][Ägypten Issue Tracker]]
18     (previously we used an
19    [[http://intevation.de/rt/webrt?q_queue=aegypten][RT-based issues
20    tracker for Ägypten]]. Please report new bugs only into the new
21    Roundup-based one.)
22
23    [[http://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&product=kmail&component=encryption&component=general&component=IMAP&component=kmailcvt&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_severity=critical&bug_severity=grave&bug_severity=major&bug_severity=crash&bug_severity=normal&bug_severity=minor&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=][KMail:
24    Open Bugs]] (report KMail related bugs here)
25
26 -  Ägypten Mailing Lists:
27
28    Technical coordination is discussed at:
29    [[http://lists.gnupg.org/mailman/listinfo/gpa-dev][gpa-dev]]
30     This is also the list for the project Gnu Privacy Assistance (GPA)
31    and the tool Gnu Privacy Assistant (gpa).
32
33    Commits to Ägypten CVS:
34    [[http://lists.gnupg.org/mailman/listinfo/aegypten-commits][aegypten-commits]]
35
36 -  Other Mailing Lists:
37
38    KMail development:
39    [[http://mail.kde.org/mailman/listinfo/kmail][kmail]]
40     There you won't find a link to the archive, it is here:
41    [[http://lists.kde.org/?l=kmail][kmail mailing list archive]]
42
43    GnuPG development:
44    [[http://lists.gnupg.org/mailman/listinfo/gnupg-devel][gnupg-devel]]
45
46 ** How to test an Ägypten-enabled KMail or Mutt?
47
48 Please also note that the development is in flux and CVS instructions
49 might not be entirely up-to-date. Please report any problem to our
50 mailing list.
51
52 If you apply tar-balls or CVS, take care to use consistent prefixes for
53 your system. Use "make ; su -c 'make install'" instead of "make install"
54 if the prefixes points to a place you have no write-access for.
55
56 If you only interested in KMail and OpenPGP you might want to read the
57 KMail Howto: [[http://kmail.kde.org/kmail-pgpmime-howto.html][Using OpenPGP and PGP/MIME with KMail]].
58
59 *You should create and use a test user first* if you apply any version
60 that are not marked as stable releases in order to keep your private
61 mail and configuration safe.
62
63 *** Prerequisits for installing
64
65 These tools are required for the Ägypten features. They should already
66 be installed on your system or be readily available as binary package
67 for simple installation. Install them before you start any building of
68 other Ägypten packages.
69
70 -  [[https://www.gnupg.org][GnuPG]] >= 1.2.2
71
72 *** Building Ägypten for KDE 3.1 and Mutt 1.5
73
74 You need at least KDE 3.1.0 plus corresponding devel-packages installed.
75 The packages described below are in fact the official KDE 3.1 tar-balls.
76
77 You need the following tar-balls (this combination is confirmed to
78 compile, but watch out for newer versions):
79
80 *Note:* The KDE 3.1 series requires GpgME 0.3 generation. GpgME >= 0.4.0
81 will not form a working Ägypten in conjunction with KDE 3.1. However,
82 KDE 3.2 will require the GpgME 0.4 generation.
83
84 *Security issue:* It is very important to apply the patch for kdenetwork
85 as listed below. This patch has been rejected by the KDE team as not
86 security relevant, but in fact not applying it, you have to stay with
87 the old crypto-backend which is unmaintained reguarding security fixes.
88  Also, if you upgrade from KDE 3.1.x to KDE 3.1.5 you should apply the
89 patch. If you don't you should not update the crypto-backend since the
90 updated one will not work without the patch applied.
91  The patch is in CVS KDE\_3\_1\_BRANCH already, so once there is a KDE
92 3.1.6 all is OK again.
93
94 For KMail:
95
96 [[ftp://ftp.trolltech.com/qt/source/qt-x11-free-3.1.2.tar.bz2][qt-x11-free-3.1.2.tar.bz2]]
97 (14MB)
98
99 [[ftp://ftp.kde.org/pub/kde/stable/3.1.5/src/arts-1.1.5.tar.bz2][arts-1.1.5.tar.bz2]]
100 (1MB)
101
102 [[ftp://ftp.kde.org/pub/kde/stable/3.1.5/src/kdelibs-3.1.5.tar.bz2][kdelibs-3.1.5.tar.bz2]]
103 (11MB)
104
105 [[ftp://ftp.kde.org/pub/kde/stable/3.1.5/src/kdebase-3.1.5.tar.bz2][kdebase-3.1.5.tar.bz2]]
106 (16MB)
107
108 [[ftp://ftp.kde.org/pub/kde/stable/3.1.5/src/kdenetwork-3.1.5.tar.bz2][kdenetwork-3.1.5.tar.bz2]]
109 (5MB)
110
111 [[ftp://ftp.kde.org/pub/kde/stable/3.1.5/src/kdepim-3.1.5.tar.bz2][kdepim-3.1.5.tar.bz2]]
112 (3.3MB)
113   
114  For Mutt:
115
116 [[ftp://ftp.gnupg.org/gcrypt/alpha/aegypten/mutts-1.5.0-gpgme-030408.tar.gz][mutts-1.5.0-gpgme-030408.tar.gz]]
117 (1.4MB)
118   
119  For any Ägypten-enabled mail user agent:
120
121 [[ftp://ftp.gnupg.org/gcrypt/alpha/libgpg-error/libgpg-error-0.6.tar.gz][libgpg-error-0.6.tar.gz]]
122 (400KB)
123
124 [[ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/libgcrypt-1.1.91.tar.gz][libgcrypt-1.1.91.tar.gz]]
125 (900KB)
126
127 [[ftp://ftp.gnupg.org/gcrypt/alpha/libksba/libksba-0.9.1.tar.gz][libksba-0.9.1.tar.gz]]
128 (500KB)
129
130 [[ftp://ftp.gnupg.org/gcrypt/alpha/aegypten/opensc-0.7.0wk1.tar.gz][opensc-0.7.0wk1.tar.gz]]
131 (700KB, optional for smartcard support)
132
133 [[ftp://ftp.gnupg.org/gcrypt/alpha/libassuan/libassuan-0.6.2.tar.gz][libassuan-0.6.2.tar.gz]]
134 (300KB)
135
136 [[ftp://ftp.gnupg.org/gcrypt/alpha/gnupg/gnupg-1.9.3.tar.gz][gnupg-1.9.3.tar.gz]]
137 (1.2MB)
138
139 [[ftp://ftp.gnupg.org/gcrypt/gpgme/gpgme-0.3.16.tar.gz][gpgme-0.3.16.tar.gz]]
140 (700KB)
141
142 [[ftp://ftp.gnupg.org/gcrypt/alpha/cryptplug/cryptplug-0.3.16.tar.gz][cryptplug-0.3.16.tar.gz]]
143 (250KB)
144
145 [[ftp://ftp.gnupg.org/gcrypt/alpha/dirmngr/dirmngr-0.5.1.tar.gz][dirmngr-0.5.1.tar.gz]]
146 (200KB)
147
148 [[ftp://ftp.gnupg.org/gcrypt/pinentry/pinentry-0.7.0.tar.gz][pinentry-0.7.0.tar.gz]]
149 (300KB)
150
151 The build process looks like this:
152
153 1. *[KMail]*
154     cd /local-vol1/aegypten/compile
155     tar xvjf ../source/qt-x11-free-3.1.2.tar.bz2
156     cd qt-x11-free-3.1.2
157     export QTDIR=$PWD
158     ./configure -prefix /usr/local/aegypten -thread
159     make install
160 2. *[KMail]*
161     export QTDIR=/usr/local/aegypten
162     export KDEDIR=/usr/local/aegypten
163     export LD\_LIBRARY\_PATH=$KDEDIR/lib:$QTDIR/lib
164     export PATH=$KDEDIR/bin:$PATH
165     (be sure to execute this later always before running parts of the
166    aegypten installation)
167 3. *[KMail]*
168     untar, configure with e.g. --prefix=/usr/local/aegypten, make and
169    install:
170     arts-1.1.5
171     kdelibs-3.1.5
172     kdebase-3.1.5
173     kdenetwork-3.1.5 (before compiling, apply
174    [[https://intevation.de/roundup/aegypten/file5/bug_18_fix.patch][this
175    patch]] in directory kdenetwork: patch -p0 < bug\_18\_fix.patch)
176     kdepim-3.1.5
177 4. *[Any MUA]*
178     untar, configure with e.g. --prefix=/usr/local/aegypten, make and
179    install:
180     libgpg-error-0.6
181     libassuan-0.6.2
182     libgcrypt-1.1.91
183     libksba-0.9.1
184     opensc-0.7.0wk1 (optional for smartcard support)
185     gnupg-1.9.3 (does not interfere with any gnupg < 1.9.0)
186     gpgme-0.3.16
187     cryptplug-0.3.16
188     dirmngr-0.5.1
189     pinentry-0.7.0
190 5. *[Mutt]*
191     export PATH=/usr/local/aegypten/bin:$PATH
192     (be sure to execute this later always before running parts of the
193    aegypten installation)
194     untar, configure with e.g. --prefix=/usr/local/aegypten, make and
195    install:
196     mutts-1.5.0-gpgme-030408 (you might have to change some file
197    ownership manually for installing)
198
199 *** Building Ägypten for KDE 3.2
200
201 It should be possible to use Ägypten1 with KDE 3.2 by just following the
202 rules as for KDE 3.1 and simple exchanging the KDE pachages accordingly.
203 Reports on success/failure/hints are welcome.
204
205 Please see the [[../aegypten2/index.html][Ägypten2 project page]] on how
206 to gain the new and extended features of the Ägypten2 project which
207 bases its work on KDE 3.2.
208
209 *** Prerequisits for using OpenPGP or S/MIME
210
211 1. Specify pinentry program (use pinentry-gtk, pinentry-qt or
212    pinentry-curses):
213
214    In file ~/.gnupg/gpg-agent.conf add:
215
216    no-grab
217     pinentry-program /some/where/bin/pinentry-qt
218     default-cache-ttl 600
219
220 2. Make sure gpg-agent is started before KMail and GnuPG:
221
222    This can be done manually in the same shell as you start KMail from:
223     eval "$(gpg-agent --daemon)"
224
225    The usual way to run the agent is from the `~/.xsession' file:
226     eval `gpg-agent --daemon`
227
228    If you don't use an X server, you can also put this into your regular
229    startup file `~/.profile' or `.bash\_profile'.
230
231    However, you should take that you don't have multiple instances of
232    gpg-agent running.
233
234 3. Configure KMail:
235    In the Cryptography section, add the Plug-In
236    /some/where/lib/cryptplug/gpgme-smime.so for S/MIME and/or
237    /some/where/lib/cryptplug/gpgme-openpgp.so for OpenPGP. Activate your
238    preferred one.
239
240 *** Using S/MIME
241
242 Follow these steps (you may skip the key generation if you just want to
243 verify signed messages or send encrypted ones) to perform the first
244 S/MIME activities (please note again that development is in flux and
245 things may change; this list is also incomplete: let us know where you
246 need more hints):
247
248 1. Configure GpgSM:
249    In file ~/.gnupg/gpgsm.conf add:
250     agent-program /some/where/bin/gpg-agent # not needed if in search
251    path
252     dirmngr-program /some/where/bin/dirmngr # not needed if in search
253    path
254     #disable-crl-checks # uncomment if you think it is appropriate
255     #disable-policy-checks # uncomment if you think it is appropriate
256 2. Create a smime certificate request (don't use this one for any real
257    security purpose!)
258     Note: [[#howto_import_external_certs][Below]] is a HowTo on
259    importing other external created certificates.
260    cat <<\EOF > ~/tmp/script.assuan
261     INPUT FD=4
262     OUTPUT FD=5 --armor
263     GENKEY
264     BYE
265     EOF
266     cat <<\EOF > ~/tmp/parms.txt
267     key-type: rsa
268     key-length: 1024
269     key-usage: sign, encrypt
270     name-dn: C=de,O=MyOrg,OU=Testlab,CN=Joe Tester
271     name-email: joe@nowher.org
272     EOF
273     gpgsm --server <~/tmp/script.assuan 4<~/tmp/parms.txt
274    5>~/tmp/out.pem
275 3. You can now sign this key by a certificate authority (CA).
276
277    Either you send the certificate request to an official CA or you can
278    set up your own CA with OpenSSL for this (the following is an excerpt
279    of the [[http://www.post1.com/home/ngps/m2/howto.ca.html][HOWTO:
280    Creating your own CA with OpenSSL by Pheng Siong Ng]] ):
281
282    #[install OpenSSL]
283     mkdir ~/CA
284     cd ~/CA
285     locate CA.pl # copy the file to .
286     locate openssl.cnf # copy the file to .
287     ./CA.pl -newca # answer the questions
288
289    Now you have a working CA and can sign certificate requests. Since
290    OpenSSL can't handle email in the correct way, you have to add the
291    line
292     subjectAltName=email:copy,email:joe@nowher.org
293     to the file ~/CA/openssl.cnf. Then execute
294     export SSLEAY\_CONFIG="-config $HOME/CA/openssl.cnf"
295
296    Finally execute the certification process:
297     cp ~/tmp/out.pem newreq.pem
298     ./CA.pl -sign # enter password of CA and confirm certification
299
300 4. Import the signed certificate:
301    gpgsm --import ~/CA/demoCA/cacert.pem # to have the cert of the CA
302     gpgsm --import ~/CA/newcert.pem
303
304 Now send yourself a s/mime signed email. If it does not work, contact us
305 on gpa-dev.
306
307 *** Using OpenPGP
308
309 1. Create your OpenPGP key-pair
310    Please make yourself familiar with GnuPG if you don't know how to do
311    this. Probably gpg is already installed on your system.
312 2. Configure KMail: Specify your OpenPGP identity.
313 3. Add to your ~/.gnupg/gpg.conf:
314    use-agent
315
316 Now you should be able to perform signature verification, decryption,
317 encryption, signing based on OpenPGP.
318
319 *** Using Smartcards
320
321 The Ägypten project uses
322
323 -  TeleSec NetKey Card
324 -  Towitoko ChipDrive micro USB (preferred) and V24
325
326 These devices are confirmed to work. Others may as well (please report).
327
328 **** Configuring OpenSC
329
330 You must install an opensc.conf file in {prefix}/etc; an example is
331 included in opensc-0.6.1-wk-20020415/etc/. We are using the pcsc
332 framework.
333
334 **** Configuring Smartcard reader
335
336 What's to be done is very dependent on your system.
337
338 USB: read [[http://www.linux-usb.org/][http://www.linux-usb.org/]] on
339 how to get your USB drive connected.
340
341 This example shows what was done on a Debian GNU/Linux Woody, Kernel
342 2.4.18 - the above link should be your prime source on learning how to
343 enable your USB device!):
344
345 #+BEGIN_EXAMPLE
346     mknod ttyUSB0 c 188 0 # if device does not already exist
347     mount -t usbdevfs none /proc/bus/usb # if this does not already exist
348     apt-get install libtowitoko2
349     modprobe usb-uhci # to switch on usb, if not already done
350     modprobe pl2303 # for the Towitoko Chipcard reader
351     apt-get install usbview # use this tool to check for devices
352     /etc/init.d/pcscd restart # might be necessary after connecting the device
353 #+END_EXAMPLE
354
355 V24: Just install libtowitoko2 and configure the proper serial port.
356
357 **** Preparing a pkcs15 card
358
359 *Note:* It may happen that you make the card unusable - it is also
360 likely that this happens due to bugs or instrallation problems. We have
361 been lucky so far in that we have only one file on one card which is not
362 deletable anymore.
363
364 1. Create a new test certificate and a key using OpenSSL (see above).
365 2. Insert the Netkey card and fire up opensc-explorer. Do this at the
366    opensc-explorer command line (we assume that it is a fresh card with
367    a 6 byte NullPIN):
368
369    #+BEGIN_EXAMPLE
370        change CHV0 00:00:00:00:00:00  "admin0"
371        get 2F00 saved-2F00
372        del 2F00
373        quit
374    #+END_EXAMPLE
375
376    We need to delete the GDO file because the record length used is too
377    short for our application. Note the new SO (Security Officer)
378    password ("admin0") somewhere.
379
380 3. Initialize the card:
381
382    pkcs15-init -C
383
384    You are asked for 2 PINs and PUKs; use at least 6 characaters. The
385    PUKs are not yet used, the SO password serves for this.
386
387 4. Write a certificate to the card:
388    pkcs15-init -X /somewhere/my\_cert.pem
389 5. Write a secret key to the card
390
391    pkcs15-init -S /somewhere/my\_private\_key.pem
392
393    You are asked for the PEM password which is used to protect the ket
394    in the PEM file and for CHV2, where you enter the password/PIN set in
395    step 2.
396
397    Note, you will see an error message - don't care about this.
398
399 6. Check that everything is fine:
400
401    $ pkcs15-tool --list-pins
402
403    After some garbage you should get:
404
405    #+BEGIN_EXAMPLE
406        Card has 2 PIN code(s).
407
408        PIN [Authentication PIN]
409                Com. Flags: 0x13
410                Auth ID   : 01
411                Flags     : [0x03], case-sensitive, local
412                Length    : 6..16
413                Pad char  : 0x00
414                Reference : 128
415                Type      : 2
416                Path      : 3F005015
417
418        PIN [Non-repudiation PIN]
419                Com. Flags: 0x13
420                Auth ID   : 02
421                Flags     : [0x03], case-sensitive, local
422                Length    : 6..16
423                Pad char  : 0x00
424                Reference : 129
425                Type      : 2
426                Path      : 3F005015
427    #+END_EXAMPLE
428
429    pkcs15-tool -c
430
431    #+BEGIN_EXAMPLE
432        Card has 1 certificate(s).
433
434        X.509 Certificate [Authentication Certificate]
435                 Flags    : 0
436                 Authority: no
437                 Path     : 3F0050159001
438                 ID       : 45
439    #+END_EXAMPLE
440
441    pkcs15-tool -k
442
443    #+BEGIN_EXAMPLE
444        Card has 1 private key(s).
445
446        Private RSA Key [Authentication Key]
447                Com. Flags  : 0
448                Usage       : [0x4], sign
449                Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract,local
450                ModLength   : 1024
451                Key ref     : 0
452                Native      : no
453                Path        : 3F0050155001
454                Auth ID     : 01
455                ID          : 45
456    #+END_EXAMPLE
457
458 You may want to erase the PKCS15 structure in case of (very likely)
459 problems; you can use this script:
460
461 #+BEGIN_EXAMPLE
462     opensc-explorer <<EOF
463     cd 5015
464     del 9001
465     del 5002
466     del 5001
467     del 4404
468     del 4402
469     del 4401
470     del 5032
471     del 5031
472     del 0011
473     del 0001
474     cd ..
475     del 5015
476     EOF
477 #+END_EXAMPLE
478
479 If you want to play with the PIN files created under the 5015 DF, you
480 should now that you have to use CHV128 and CHV129 with the
481 opensc-explorer commands "ver" and "change".
482
483 **** Using a pkcs15 prepared card
484
485 1. Specify scdaemon program:
486    In file ~/.gnupg/gpg-agent.conf add:
487     scdaemon-program /some/where/bin/scdaemon
488 2. Register the card with gpgsm:
489    gpgsm --learn-card
490 3. Now you can use this card e.g. to create a signature:
491
492    gpgsm -sbvu 'user\_id\_of\_new\_cert' plain >plain.sig
493
494    (if you did not had a secret key before, the card's user id is now
495    the default)
496
497    The PIN entry dialog should pop up and ask you for the Smartcard
498    Authentication PIN. (It is what you entered as CHV0 if you created
499    the pkcs15 bar-bones yourself).
500
501    There will also be a popup window to ask you to insert the card if
502    you did remove it from the reader or you are using a different one.
503
504 *** HowTo import externally generated keys and certificates into GpgSM
505
506 (written by Matthias Welwarsky)
507
508 Let's assume you have an S/MIME certificate, probably a personal
509 freemail certificate from Thawte or some other Certification Authority.
510 Thawte offers X509 S/MIME certificates via a web interface, you cannot
511 have gpgsm generate the Certificate Request and thus the private key,
512 your browser will do that. So the problem is, after the certificate got
513 issued, you have in inside you browser while you need it in GPGSM.
514
515 "Where's the problem?" you might say. "I can always export my
516 certificate as a PKCS#12 certificate bundle and import it into GPGSM."
517
518 That's true, but it's a bit more difficult. While GPGSM has an import
519 feature for PKCS#12 encoded secret keys, it is limited:
520
521 1. GPGSM cannot import the complete PKCS#12 bundle, ONLY the secret key
522  2. The Key must not be encrypted.
523
524 You need to import the secret key, the certificate, and the issuers
525 certificate. Unfortunately, there seems to be no GPGSM-Only solution,
526 but you can get along with a little help from OpenSSL :-)
527
528 Here's a step-by-step HOWTO that I used to get my Thawte certificate
529 into GPGSM:
530
531 1. Export the Certificate from your browser.
532
533 You probably have Mozilla, konqueror currently lacks support for
534 generating certificate requests. The browser will ask you to specifiy an
535 Export Password, be sure to remember it for the rest of the procedure,
536 and store the certificate into a file "certbundle.p12".
537
538 2. Use OpenSSL to extract the key from the bundle.
539
540 GPGSM currently seems to be unable to handle the complete bundle in one
541 go. You need to extract the pieces yourself. This can be done with the
542 following OpenSSL calls:
543
544 First, you must convert the bundle from PKCS#12 into PEM format:
545
546 bash$ openssl pkcs12 -in certbundle.p12 -out certbundle.pem -nodes
547
548 OpenSSL will ask you for the Export Password, that's the password you
549 used in your Browser to export the password.
550
551 Then, extract the key from the bundle and export it, again in PKCS#12
552 format
553
554 bash$ openssl pkcs12 -in certbundle.pem -export -out certkey.p12
555 -nocerts \ -nodes
556
557 Again, OpenSSL will ask you for an Export Password, just use the same as
558 in the previous step. Now you have your secret key ready for import into
559 GPGSM:
560
561 bash$ gpgsm --call-protect-tool --p12-import --store certkey.p12
562
563 3. Import the Issuers certificate and your own certificate
564
565 Now that you have imported your secret key successfully, you need to
566 import the issuers certificate, too. To obtain this certificate, you may
567 have to browse to the issuers website and download it, but Thawte for
568 example stores their certificate in the bundle you get when you request
569 the certificate. You can then extract it from the file certbundle.pem
570 you generated in the first step, simply with a text viewer. My preferred
571 way is to display the file in vi, then mark the issuer certificate with
572 the mouse and copy it into a shell, where before I typed in:
573
574 bash$ gpgsm --import
575
576 This will import the issuers certificate. Once you have successfully
577 completed this step, do the same with your own certificate.
578
579 If GPGSM did not spit out any error messages, you have now successfully
580 imported your freemail certificate and use your favourite,
581 Aegypten-enabled mailer to send and receive S/MIME messages with your
582 own certificates.
583
584 You can check with "gpgsm --list-secret-keys". If your freemail
585 certificate shows up, you're ready to go.
586
587 ** Discussion
588
589 The following links intend to collect discussions around technological
590 decisions and plannings the Ägypten project is or will be involved in
591 one way or another.
592
593 *** KMail integration
594
595 The integeration of gpg-based S/MIME and OpenPGP support as part of the
596 Ägypten project involves a tough time line as well as a framework to
597 support other (non-KDE) MUAs.
598
599 It is intended to bring these two aspects in line with the KDE
600 development plans as good as possible. Essentially this means to reduce
601 those parts that will live only a short time to suffice the Ägypten
602 needs and that will be abandoned/substituted later on once the KDE
603 framework is further developed.
604
605 Some KDE activities in the same or related fields as Ägypten:
606
607 -  [[http://lists.kde.org/?l=kmail&m=100456988004152&w=2][Ideas for
608    KMime design]] (in the kmail list archive)
609 -  work is also going on on a
610    [[http://lists.kde.org/?l=kmail&m=100454574428861&w=2][kssl based
611    S/MIME "plugin"]] (in the kmail list archive)
612
613 *** Mutt integration
614
615 A special tar-ball of an Ägypten-enabled Mutt is available from the
616 ftp.gnupg.org site (see description above).
617
618 Apart from Ägypten, there is another
619 [[http://elmy.myip.org/mutt/smime.html][Mutt patch for S/MIME]]
620 available. This one is based on OpenSSL.
621
622 *** LDAP enabled KAddressbook
623
624 The LDAP functionality will allow the user to search for information by
625 typing (part of) a name in a textfield, the application will then query
626 the LDAP server and show the user a list of matches. The user can then
627 choose to add individual addresses to her local addressbook.
628
629 The addressbook application "KAddressbook" has been chosen to be
630 enhanced with LDAP functionality because it uses the most modern and
631 actively developed addressbook backend in KDE -- libkabc. The
632 development of the alternative libkab has officially been discontinued.
633
634 *** How to deal with certificates and LDAP
635
636 **** Background
637
638 An LDAP server can in principle have an smime-certificate attached to an
639 entry for a person. This entry usually also has the email address as
640 attribute. Important is that we can have several matching email
641 addresses for one person string or email address. To identify one
642 certificate we can use the fingerprint.
643
644 In principle the certificate should have the information that make it
645 possible to find the distribution point for the CRLs of the CA. Thus in
646 theory one would not have to speficy the DNS and port number of the ldap
647 server for the CLRs. So one would be fine once having a valid cert and
648 the trust path certs. In practice we might try ldap servers we have
649 tried for the certs too if in search for the CLR of a specific cert.
650
651 **** Kaddressbook's relation to Kmail
652
653 One design idea is that kaddressbook should not directly deal with
654 certificates, because it would then depend on gpgme for most of its
655 actions. Thus KAddressbook is only interested in the persons and their
656 email address attribute when quering an ldap server.
657
658 It just gives the email address and optional additional hints to KMail.
659 KMail then has to decide if it wants to use crypto and what crypto. If
660 KMail goes for s/mime encryption it has to care to find a certificate
661 for this email address. Now KMail (maybe in cooperation with the
662 certmanager) will call the crypto backend to search for a suitable
663 certificate. The cryptobackend will search external ldap-servers when
664 told so by KMail.
665
666 **** Why we need the fingerprint to be saved as hint in KAddressbook
667
668 From the background section it is clear that KMail might be presented
669 with a number of certificates for a single email address. This selection
670 would have to be done each time by the user, if we do not remember the
671 fingerprint of the prefered certificate. The right place to save this
672 hint is the KAddressbook as far as I can see it.
673
674 **** Drawback: Two lists of ldap Servers to query
675
676 There is a drawback that KAddressbook and dirmngr (which is the part of
677 the crypt backend actually asking the ldap servers) both have their list
678 of ldap servers to ask. Currently we think this is unavoidable if we
679 don't want to make things even more complicated. Theoretically we could
680 sync the KDE and crypto-backend preferences somehow, but this would
681 indeed make things more complicated.
682
683 All in all it seems that we need an GUI interface to the dirmngr list
684 separated from the KDE/KAddressbook ldap server configuration GUI.
685
686 **** Conclusion for implementation
687
688 We need a way for KMail or the certmanager to give hint data to
689 KAddressbook that KAddressbook can give back. Especially this hint data
690 should include "use smime" and "use the cert with this fingerprint:
691 xxx".
692
693 KMail or the certmanager has to the right search functions of gpgme if
694 it does not find a suitable certificate.
695
696 We need a configuration GUI to modify the dirmngr configuration for the
697 ldap servers to be searched for the certs.
698
699 *** Smartcards
700
701 **** Brief Intro
702
703 ICC or Smartcards are tiny (in todays terms) regular computers with an
704 OS using an EEPROM instead of a harddisk, with just one serial I/O, a
705 simple standardized command set and ACL protected files. Filenames are
706 16 bit values, you have diretories (called DFs) of up to 4 levels and
707 regular files (EFs) which may come in a transparent form, record
708 structured or circular structured. There are select read and write file
709 commands, commands to verify PINs, where the PIN is stored in a file on
710 the CARD with an ACL set to NO-READ. The cards required for Ägypten need
711 also have cryptograpic operations like encrypt, generate MAC, sign and
712 verify.
713
714 The chip is usually based on the 8051 but enhanced with a crypto
715 accelarator. If you detach the chip from the plastic card, you will
716 notice that the actual chip is on the backside of the golden contacts,
717 The contacts are used to supply the card with the power volatge, the
718 clock and the serial data.
719
720 **** SCdaemon
721
722 Reasons why SCdaemon:
723
724 -  It is a module which can be used by independent applications, e.g.
725    programs that only like to see whether smart card is inserted or just
726    need to access the non-secret information.
727 -  Bugs in this one don't progagate to gpg-agent. Strong encapsulation
728    due to the process barrier.
729 -  There is no need to link X.509 code into gpg-agent. Only needed in
730    the SCdaemon -> less dependencies. This is the only module which
731    needs to be aware of the SC backend OpenSC. More stability of the
732    system; a crash here does not affect gpg-agent and gpg-agent can
733    restart the scdaemon.
734 -  Easier maintenance and development.
735
736 **** User Interface for Smartcards
737
738 Some thoughts on the UI requirements for cards:
739
740 Preparation of cards (intitalization of the card's filesystem) should be
741 done by an external utility because we might need to display a lot of
742 error messages etc. A command line tool is more suitable for this.
743
744 Note that average users don't need this because they can purchase
745 suitable initialized cards. If there will be a need for a more user
746 friendly interface, someone else might setup such a project.
747
748 For storing the key on a card, a bootable OS is the desired solution.
749 But we should be able to do it within our environment after displaying
750 suitable warnings. To do this we need a checkbox (defaults to false) in
751 the key generation dialog. Everyting else is done by utilizing the
752 pinentry.
753
754 The most common interaction with SC happens after a user plugs in a
755 card. The SCdaemon might detect this but therefore it must have been
756 started already. So the better way is to tell gpgsm to look for a card -
757 KDE may provide a notifications service to start this program whenever
758 the state of a card readwer changes, but this not within the scope of
759 the Ägypten project.
760
761 In most cases gpg-agent/SCdaemon will notice that the card has already
762 been used and therefore the access to the card is transparent. However,
763 for new and unknown cards we need to ask the user what to do. To
764 separate this from the UI, we like to also use the pinentry. After a
765 user plugs in a card she won't be too surprised to see a pop up window,
766 asking some questions about the card ("Hey, this is a new card - what do
767 you want me to do with it?"). The user might answer, he does not know in
768 which case the dialog disapears but will pop up every time the card is
769 plugged in again. The other possible answer is "yes, I want to use a
770 secret key from this card" after which gpg-agent asks for the PIN to
771 verify that she is a legitimate user and registers the card in her
772 secret-key database on the disk.
773
774 If the use of a secret key is any time later needed, gpg-agent will look
775 through its secret key DB and use the key stored on the disk or (if
776 there is a flag that the key is on a SC) ask the user to insert the
777 appropriate card.
778
779 So the changes to the UI are really minimal by only requiring one
780 checkbox.
781
782 There is still the question open on howto un-regsiter a key from the DB
783 after it has expired or is not anymore accessible.
784
785 **** Smartcard access modules
786
787 The Ägypten project will use [[http://www.opensc.org/][OpenSC]] to
788 incorporate Smartcards. [[http://www.linuxnet.com/middle.html][PCSC Lite
789 of the MUSCLE project]] will be used to establish principle
790 functionality. Afterwards, PCSC lite will be replaced by a new
791 implementation. The primary reason is that the current license of PCSC
792 is not compliant with the Ägypten project goals for licenses (GPL). A
793 further advantage of OpenSC is the working pkcs-15 code and the clear
794 origin of the code.
795
796 An alternative for OpenSC was
797 [[http://www.franken.de/crypt/scez.html][SCEZ]], but here also the
798 license (old BSD with advertisement clause in current tar-balls) made us
799 prefer the LGPL licensed OpenSC. However, SCEZ the current development
800 version is now dual licensed under the new BSD and LGPL .
801
802 Links:
803
804 [[http://www.ioc.ee/atsc/faq.html][A Frequently Asked Questions list
805 (FAQ) for alt.technology.smartcards]] (outdated but still useful)
806  [[http://www.opensc.org/][OpenSC - SmartCard library with support for
807 PKCS#15 compatible cards]] (License: LGPL)
808  [[http://www.franken.de/crypt/scez.html][SCEZ - Smart Card Library]]
809 (License: old BSD)
810  [[http://www.linuxnet.com/middle.html][MUSCLE: Latest Stable PC/SC]]
811  [[http://smartsign.sourceforge.net/][Smartsign]] (GPL)
812  [[http://www.libchipcard.de/][Libchipcard]] (LGPL)
813
814 [[http://www.accu.org/bookreviews/public/reviews/s/s000027.htm][Smart
815 Card Handbook by W Rankl & W Effing (Book Review)]] This book s also
816 available in German by Hanser
817 ([[http://www.hanser.de/weitere_infos/1999/3-446-21115-2.htm][Handbuch
818 der Chipkarten, 3. Auflage, ISBN 3-44621115-2]]).
819
820 ** Other related projects and interesting stuff
821
822 [[http://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt][X.509 Style
823 Guide]] by Peter Gutmann
824
825 [[http://www.getronicsgov.com/hot/sfl_home.htm][S/MIME Freeware Library
826 (SFL)]] (Free Software status not clear, partly GPL)
827
828 [[http://www.post1.com/home/ngps/m2/howto.smime.html][HOWTO: Programming
829 S/MIME in Python with M2Crypto]]
830
831 [[http://csrc.nist.gov/pki/testing/x509paths.html][X.509 Path Validation
832 Test Suite]] Conformance tests for relying parties that validate X.509
833 certification paths at the National Institute of Standards and
834 Technology.
835
836 [[%20http://www.direct-to-linux.com/TUTORIALS/LinuxTutorialLDAP.html][Linux
837 LDAP Tutorial: Deploying OpenLDAP - Directory Installation and
838 configuration (V1.2 / 2.0)]]
839
840 [[http://www.web2ldap.de/][WWW gateway to LDAP server]]
841
842 [[http://www.openssl.org][OpenSSL]] Contains a Free Software CA
843 implementation.
844
845 [[http://www.pyca.de/][pyCA - X.509 CA]] Software for running a
846 X.509/PKIX certificate authority (uses OpenSSL)
847
848 [[http://gpkcs11.sourceforge.net/][gpkcs11]] cryptographic token access
849 for Unix
850
851 [[http://cryp.to/librfc822/][RFC822 Address Parser Library]]
852
853 #+HTML:<!--disable-copyright-footer-->