Add an info page for watchgnupg. > * 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. Every time 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 wherever 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 independent 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 familiar 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 library] liblber [system library] libsasl [system library, required by libldap] libdb2 [system library, required by libsasl] libcrypt [system library, required by libsasl - OOPS] libpam [system library, 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]