From 9ec1437772d84ccaf32fd1bdde170e7667bc54b7 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Sat, 11 Sep 2004 14:50:35 +0000 Subject: Some more new files --- doc/Notes | 242 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 doc/Notes (limited to 'doc/Notes') diff --git a/doc/Notes b/doc/Notes new file mode 100644 index 000000000..4a990776e --- /dev/null +++ b/doc/Notes @@ -0,0 +1,242 @@ +> * How to mark a CA certificate as trusted. + +There are two ways: + + 1. Let gpg-agent do this for you. Since version 1.9.9 you need to + add the option --allow-mark-trusted gpg-agent.conf or when + invoking gpg-agent. Everytime gpgsm notices an untrusted root + certificate gpg-agent will pop up a dialog to ask whether this + certificate should be trusted. This is similar to whatmost + browsers do. + + The disadvantage of this method and the reason why + --allow-mark-trusted is required is that the list of trusted root + certificates will grow, because almost all user will just hit + "yes, I trust" and "yes, I verified the fingerprint" without + understanding that this is a very serious decision. + + 2. Use your editor. Edit the file ~/.gnupg/trustlist.txt and add + the fingerprints of the trusted root certificates. There are + comments on the top explaining the simple format. The current + CVS version allows for colons in the fingerprint, so you can + easily cut and paste it from whereever you know that this is the + correct fingerprint. + +An example for an entry in the trustlist.txt is: + + # CN=PCA-1-Verwaltung,O=PKI-1-Verwaltung,C=de + 3EEE3D8BB7F0FE5C9F5804A3A7E51BCE98209DF9 S + +This is in fact one that probably made its way into the file using the +first method. As usual a # indicates a comment. The trailing S means +that this is to be used for (X.509). + +It is not possible to trust intermediate CA certificates; gpgsm always +checks the entire chain of certificates. + +> * How to import a key and bind it to some certificate already +> imported. Alternatively, import key and certificate together, from +> a pkcs12 blob, or pkcs8 + certificate blobs, or whatever. +> Alternatively, don't import the key at all, but specify location of +> key using a parameter when signing. + +You always need to import the key; there is something similar to a +keyring (here called a keybox: ~/.gnupg/pubring.kbx). + +Importing a key either from a binary or ascii armored (PEM) certificate +file or from a cert-only signature file is done using + + gpg --import FILE + +or + + gpg --import < FILE + +In general you should first import the root certificates and then down +to the end user certificate. You may put all into one file and gpgsm +will do the right thing in this case independend of the order. + +While verifying a signature, all included certificates are +automagically imported. + +To import from a pkcs#12 file you may use the same command; if a +private key is contained in that file, you will be asked for the +transport passphrases as well as for the new passphrase used to +protect it in gpg-agent's private key storage +(~/.gnupg/private-keys-v1.d/). Note that the pkcs#12 support is very +basic but sufficient for certificates exported from Mozilla, OpenSSL +and MS Outlook. + +Background info on private keys: + +If you want to look at the private key you first need to know the name +of the keyfile. Run the command "gpgsm -K --with-key-data [KEYID]" and +you get an output like: + + crs::1024:1:CF8[..]6D:20040105T184908:2006[...]:09::CN=ZS[....]::esES: + fpr:::::::::3B50BF2BDAF2[...]1AE6796D:::2812[...]508F21F065E65E44: + grp:::::::::C92DB9CFD588ADE846BE3AC4E7A2E1B11A4A2ADB: + uid:::::::::CN=Werner Koch,OU=test,O=g10 Code,C=de:: + uid::::::::::: + +This should be familar to advanced gpg-users; see doc/DETAILS in gpg +1.3 (CVS HEAD) for a description of the records. The value in the +"grp" tagged record is the so called keygrip and you should find a +file ~/.gnupg/private-keys-v1.d/C92DB9CFD588ADE846BE3AC4E7A2E1B11A4A2ADB.key +with the private and public key in an S-expression like format. The +gpg-protect-tool may be used to display it in a human readable format: + + $ gpgsm --call-protect-tool ~/.gnupg/private-keys-v1.d/C9[...]B.key + (protected-private-key + (rsa + (n #00C16B6E807C47BB[...]10487#) + (e #010001#) + (protected openpgp-s2k3-sha1-aes-cbc + ( + (sha1 "Hvü9Qt^Ç" "96") + #2B17DC766AEA2568EE0C688E18F9757E#) + #65A4FF9F30750A1300[...]7#) + ) + ) + +The current CVS version of gpgsm has a command --dump-keys which lists +more details of a key including the keygrip so you don't need to use +the colon format if you want to manually debug things. + + $ gpgsm --dump-keys + Serial number: 01 + Issuer: CN=Trust Anchor,O=Test Certificates,C=US + Subject: CN=Trust Anchor,O=Test Certificates,C=US + sha1_fpr: 66:8A:47:56:A2:DC:88:FF:DA:B8:95:E1:3C:63:37:55:5F:0A:F7:BF + md5_fpr: 03:01:3B:BB:EC:6C:5D:48:88:4C:95:63:99:84:ED:C0 + keygrip: 6A082B3063F6DA6D68B2994AB11B4328FD6206D2 + notBefore: 2001-04-19 14:57:20 + notAfter: 2011-04-19 14:57:20 + hashAlgo: 1.2.840.113549.1.1.5 (sha1WithRSAEncryption) + keyType: 1024 bit RSA + authKeyId: [none] + keyUsage: certSign crlSign + extKeyUsage: [none] + policies: [none] + chainLength: unlimited + crlDP: [none] + authInfo: [none] + subjInfo: [none] + extn: 2.5.29.14 (subjectKeyIdentifier) [22 octets] + +> * How to import a CRL + +CRLs are managed by the dirmngr which is a separate package. The idea +is to eventaully turn it into a system daemon, so that on a multi-user +machine CRLs are handled more efficiently. As of now the dirmngr +needs service from gpgsm thus it is best to call it through gpgsm: + + gpgsm --call-dirmngr LOAD /absolute/filename/to/a/CRL/file + +See the dirmngr README and manual for further details. + +If you don't want to check CRLs, use the option --diable-crl-checks +with gpgsm. + +> I'm trying to replace the S/MIME support in OpenSSL with gpgsm for the +> MUA Gnus. + +Great; I'd love it. + +> Perhaps I shouldn't be using gpgsm directly? gpgme didn't seem to +> have a command line front end. + +For Gnus it makes sense to use gpgsm directly. Enhancing pgg to +support gpgsm should not be that hard. Things you need to take care +off are: Warn if GPG_AGENT_INFO has not been set, because this will +call gpg-agent for each operation and obviously does not cache the +passphrase them. If GPG_AGENT_INFO has been set, also disable the +passphrase code for gpg and pass --use-agent to gpg - this way gpg +benefits from the passphrase caching and the pinentry. + +You may want to look at gpgconf (tools/README.gpgconf) to provide a +customization interface for gpgsm, gpg-agent and dirmngr. + + +Module Overview +================ + +gpgsm + libgpg-error + libgcrypt + libksba + libassuan [statically linked] + [Standard system libraries] + +gpg-agent + libgpg-error + libgcrypt + libassuan [statically linked] + libpth [system library] + [Standard system libraries] + +scdaemon + libgpg-error + libgcrypt + libksba + libassuan [statically linked] + libusb [system library, optional] + libopensc [system library, optional] + [For reader access libpcsclite or a CT-API library may be + linked at runtime (controllable by scdaemon.conf)] + [Standard system libraries] + +gpg-protect-tool + libgpg-error + libgcrypt + [Standard system libraries] + +dirmngr + libgpg-error + libgcrypt + libksba + libassuan [statically linked] + libldap [system libary] + liblber [system libary] + libsasl [system libary, required by libldap] + libdb2 [system libary, required by libsasl] + libcrypt [system libary, required by libsasl - OOPS] + libpam [system libary, required by libsasl] + [Standard system libraries] + +pinentry-curses + libncurses + [Standard system libraries] + [Independent Assuan code is source included] + +pinentry-gtk + libncurses + [GTK+ and X libraries] + [Standard system libraries] + [Independent Assuan code is source included] + +pinentry-qt + libncurses + [QT and X libraries] + [Standard system libraries] + [Independent Assuan code is source included] + +gpgme + [Standard system libraries] + [gpgsm is required at runtime] + [Independent Assuan code is source included] + +libgpg-error + [none] + +libgcrypt + libgpg-error + +libksba + libgpg-error + +libassuan + [none] + + + -- cgit From 4604ae8e99dfdc91d2af76d7336cd4a4d6da2722 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Wed, 29 Sep 2004 11:04:30 +0000 Subject: Changed license of the manual stuff to GPL. * gnupg.texi (Top): New menu item Helper Tools. * tools.texi (Helper Tools): New. * Makefile.am (gnupg_TEXINFOS): Add tools.texi. --- doc/ChangeLog | 9 +++++++ doc/Makefile.am | 4 +-- doc/Notes | 3 +++ doc/gnupg.texi | 26 ++++++------------- doc/gpg-agent.texi | 2 +- doc/tools.texi | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 96 insertions(+), 22 deletions(-) create mode 100644 doc/tools.texi (limited to 'doc/Notes') diff --git a/doc/ChangeLog b/doc/ChangeLog index 79a8c9532..d7015bd85 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,12 @@ +2004-09-29 Werner Koch + + Changed license of the manual stuff to GPL. + + * gnupg.texi (Top): New menu item Helper Tools. + + * tools.texi (Helper Tools): New. + * Makefile.am (gnupg_TEXINFOS): Add tools.texi. + 2004-08-05 Werner Koch * scdaemon.texi (Card applications): New section. diff --git a/doc/Makefile.am b/doc/Makefile.am index 9dc917de4..3ac312049 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,8 +21,8 @@ info_TEXINFOS = gnupg.texi gnupg_TEXINFOS = \ - gpgsm.texi gpg-agent.texi scdaemon.texi assuan.texi\ - debugging.texi glossary.texi contrib.texi gpl.texi fdl.texi + gpgsm.texi gpg-agent.texi scdaemon.texi assuan.texi tools.texi \ + debugging.texi glossary.texi contrib.texi gpl.texi DISTCLEANFILES = gnupg.tmp gnupg.ops diff --git a/doc/Notes b/doc/Notes index 4a990776e..3598bc7a7 100644 --- a/doc/Notes +++ b/doc/Notes @@ -1,3 +1,6 @@ + +Add an infor page for watchgnupg. + > * How to mark a CA certificate as trusted. There are two ways: diff --git a/doc/gnupg.texi b/doc/gnupg.texi index 0beb97e69..ec82fe425 100644 --- a/doc/gnupg.texi +++ b/doc/gnupg.texi @@ -5,26 +5,14 @@ @include version.texi @macro copyrightnotice -Copyright @copyright{} 2002 Free Software Foundation, Inc. +Copyright @copyright{} 2002, 2004 Free Software Foundation, Inc. @end macro @macro permissionnotice Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License'', the Front-Cover -texts being (a) (see below), and with the Back-Cover Texts being (b) -(see below). A copy of the license is included in the section entitled -``GNU Free Documentation License''. - -(a) The FSF's Front-Cover Text is: - - A GNU Manual - -(b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU - software. Copies published by the Free Software Foundation raise - funds for GNU development. +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2 of the License, or (at your +option) any later version. The text of the license can be found in the +section entitled ``Copying''. @end macro @@ -126,10 +114,10 @@ Developer information Miscellaneous +* Helper Tools:: Description of small helper tools * Debugging:: How to solve problems * Copying:: GNU General Public License says how you can copy and share GnuPG -* GNU Free Documentation License:: How you can copy and share this manual. * Contributors:: People who have contributed to GnuPG. Indices @@ -145,10 +133,10 @@ Indices @include assuan.texi +@include tools.texi @include debugging.texi @include gpl.texi -@include fdl.texi @include contrib.texi diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index 460cca45a..ab28eeb7d 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -282,7 +282,7 @@ command. @opindex ttyname @opindex ttytype @opindex lc-type -@opindex lc-messa +@opindex lc-messages These options are used with the server mode to pass localization information. diff --git a/doc/tools.texi b/doc/tools.texi new file mode 100644 index 000000000..d04b01277 --- /dev/null +++ b/doc/tools.texi @@ -0,0 +1,74 @@ +@c Copyright (C) 2004 Free Software Foundation, Inc. +@c This is part of the GnuPG manual. +@c For copying conditions, see the file GnuPG.texi. + +@node Helper Tools +@chapter Helper Tools + +GnuPG comes with a couple of smaller tools: + +@menu +* watchgnupg:: Read logs from a socket. +* addgnupghome:: Create .gnupg home directories +@end menu + + +@node watchgnupg +@section Read logs from a socket + +Most of the main utilities are able to write there log files to a +Unix Domain socket if configured that way. watchgnupg is a simple +listener for such a socket. It ameliorates the output with a time +stamp and makes sure that long lines are not interspersed with log +output from other utilities. + +@noindent +watchgnupg is commonly invoked as + +@samp{watchgnupg --force ~/.gnupg/S.log} + +@noindent +This starts it on the current terminal for listening on the socket +@file{~/.gnupg/S.log}. + +@noindent +watchgnupg understands these options: + +@table @gnupgtabopt + +@item --force +@opindex force +Delete an already existing socket file. + +@item --verbose +@opindex verbose +Enable extra informational output. + +@item --version +@opindex version +print version of the program and exit + +@item --help +@opindex help +Display a brief help page and exit + +@end table + + + +@node addgnupghome +@section Create .gnupg home directories + +If GnuPG is installed on a system with existing user accounts, it is +sometimes required to populate the GnuPG home directory with existing +files. Especially a @file{trustlist.txt} and a keybox with some +initial certificates are often desired. This scripts help to do this +by copying all files from @file{/etc/skel/.gnupg} to the home +directories of the accounts given on the command line. It takes care +not to overwrite existing GnuPG home directories. + +@noindent +addgnupghome is invoked by root as: + +@samp{addgnupghome account1 account2 ... accountn} + -- cgit