Tutorial for gpgsm?
wk at gnupg.org
Tue Sep 7 09:49:25 CEST 2004
On Fri, 03 Sep 2004 17:05:20 +0200, Simon Josefsson said:
> * 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
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
An example for an entry in the trustlist.txt is:
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
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
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:
uid:::::::::CN=Werner Koch,OU=test,O=g10 Code,C=de::
uid:::::::::<wk at g10code.de>::
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
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
(sha1 "Hvü9Qt^Ç" "96")
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
notBefore: 2001-04-19 14:57:20
notAfter: 2011-04-19 14:57:20
hashAlgo: 1.2.840.113522.214.171.124 (sha1WithRSAEncryption)
keyType: 1024 bit RSA
keyUsage: certSign crlSign
extn: 126.96.36.199 (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
> 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.
More information about the Gnupg-users