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 v1.2.3