diff --git a/README b/README index b0b23c5f6..7aea069b3 100644 --- a/README +++ b/README @@ -1,371 +1,372 @@ GnuPG 1.9 is a temporary protect to work on GnuPG extensions. It will eventually lead to a GnuPG 2.0 release. jnlib/ utility functions kbx/ keybox library sm/ the gpgsm program agent/ the gpg-agent scd/ the smartcard daemon -Libassuan, Libksba and Libgcrypt are required to build it. +You need the libgpg-error package. Libassuan, Libksba and Libgcrypt +are also required to build it. Keybox is designed to be source include-able. A texinfo manual `gnupg.info' will get installed. Some commands and options given below. COMMANDS ======== gpgsm: ------ --learn-card Read tinformation about the private keys from the smartcard and import the certificates from there. --export Export all certificates storein the Keybox or those specified on the commandline. When using --armor a few informational lines are prepended before each block. OPTIONS ======= gpgsm: ------ --include-certs Using N of -2 includes all certificate except for the Root cert, -1 includes all certs, 0 does not include any certs, 1 includes only the signers cert (this is the default) and all other positives values include up to N certs starting with the signer cert. --policy-file Chnage the deault name of the policy file --enable-policy-checks --disable-policy-checks By default policy checks are enabled. These options may be used to change it. --enable-crl-checks --disable-crl-checks By default the CRL checks are enabled and the DirMngr is used to check for revoked certificates. The disable option is most useful with a off-line connection to suppres this check. --agent-program Specify an agent program to be used for secret key operations. The default value is "../agent/gpg-agent". This is only used as a fallback when the envrionment varaibale GPG_AGENT_INFO is not set or a running agent can't be connected. --dirmngr-program Specify a dirmngr program to be used for CRL checks. The default value is "/usr/sbin/dirmngr". This is only used as a fallback when the envrionment varaibale DIRMNGR_INFO is not set or a running dirmngr can't be connected. --no-secmem-warning Don't print the warning "no secure memory" --armor Create PEM ecoded output. Default is binary output. --base64 Create Base-64 encoded output; i.e. PEM without the header lines. --assume-armor Assume the input data is PEM encoded. Default is to autodetect the encoding but this is may fail. --assume-base64 Assume the input data is plain base-64 encoded. --assume-binary Assume the input data is binary encoded. --server Run in server mode. This is used by GPGME to control gpgsm. See the assuan specification regarding gpgsm about the used protocol. Some options are ignored in server mode. --local-user Set the user to be used for signing. The default is the first secret key found in the database. --with-key-data Displays extra information with the --list-keys commands. Especiall a line tagged "grp" si printed which tells you the keygrip of a key. This is string is for example used as the filename of the secret key. gpg-agent: --------- --pinentry-program Specify the PINentry program. The default value is "../../pinentry/kpinentry/kpinentry" so you most likely want to specify it. --no-grab Tel the pinentry not to grab keybourd and mouse. You most likely want to give this option during testing and development to avoid lockups in case of bugs. FILES ===== The default home directory is ~/.gnupg. It can be changed by either the --homedir option or by seting the environment variable GNUPGHOME. This is a list of files usually found in this directory: gpgsm.conf Options for gpgsm. Options are the same as the command line options but don't enter the leading dashes and give arguments without an equal sign. Blank lines and lines starting with a hash mark as the first non whitye space character are ignored. gpg-agent.conf Options for gpg-agent scdaemon.conf Options for scdaemon. dirmngr.conf Options for the DirMngr which is not part of this package and the option file wilol most likely be moved to /etc gpg.conf Options for gpg. Note that old versions of gpg use the filename `options' instead of `gpg.conf'. policies.txt A list of allowed CA policies. This file should give the object identifiers of the policies line by line. emptry lines and lines startung with a hash mark are ignored. ++++++++++ 2.289.9.9 ++++++++++ trustlist.txt A list of trusted certificates usually maintained by gpg-agent. It can however be edited manually. The file will be created automagically with some explaining comments. random_seed Used internally for keeping the state of the RNG over invocations. pubring.kbx The database file with the certificates. pubring.gpg The database file with the OpenPGP public keys. This will eventually be merged with pubring.kbx secring.gpg The database file with the OpenPGP secret keys. This will be removed when gpg is changed to make use of the gpg-agent. private-keys-v1.d/ Directory holding the private keys maintained by gpg-agent. For detailed info see agent/keyformat.txt. Note that there is a helper tool gpg-protect-tool which may be used to protect or unprotect keys. This is however nothing a user should care about. How to specify a user ID ======================== Due to the way X.509 certificates are made up we need a few new ways to specify a certificate (aka key in OpenPGP). In addition to the ways a user ID can be specified with gpg, I have implemented 3 new modes for gpgsm, here is the entire list of ways to specify a key: * By keyID. This format is deducded from the length of the string and its content or "0x" prefix. For use with OpenPGP a exclamation mark may be appended to force use of the specified (sub)key. As with v34 OpenPGP keys, the keyID of an X509 certificate are the low 64 bits of the SHA-1 fingerprint. The use of keyIDs is just a shortcut, for all automated processing the fingerprint should be used. Examples: 234567C4 0F34E556E 01347A56A 0xAB123456 234AABBCC34567C4 0F323456784E56EAB 01AB3FED1347A5612 0x234AABBCC34567C4 * By fingerprint This is format is deduced from the length of the string and its content or "0x" prefix. Note, that only the 20 byte fingerprint is used with GPGSM (SHA-1 hash of the certificate). For use with OpenPGP a exclamation mark may be appended to force use of the specified (sub)key. Examples: 1234343434343434C434343434343434 123434343434343C3434343434343734349A3434 0E12343434343434343434EAB3484343434343434 0xE12343434343434343434EAB3484343434343434 * Exact match on OpenPGP user ID This is denoted by a leading equal sign. It does not make much sense for X.509. Example: =Heinrich Heine * Exact match on an email address. This is indicated by enclosing the email address in the usual way with left and right angles Example: * Word match All words must match exactly (not case sensitive) but can appear in any order in the user ID or a subjects name. Words are any sequences of letters, digits, the underscore and all characters with bit 7 set. Example: +Heinrich Heine duesseldorf * [NEW] Exact match by subject's DN This is indicated by a leading slash, directly followed by the rfc2253 encoded DN of the subject. Example: /CN=Henrich Heine,O=Poets,L=Paris,C=FR * [NEW] Excact match by issuer's DN This is indicated by a leading hash mark, directly followed by a slash and then directly followed by the rfc2253 encoded DN of the issuer. This should return the Root cert of the issuer Example: #/CN=Root Cert,O=Poets,L=Paris,C=FR * [NEW] Exact match by serial number and subject's DN This is indicated by a hash mark, followed by the hexadecmal representation of the serial number, the followed by a slahs and the RFC2253 encoded DN of the issuer. Example: #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR * Substring match By case insensitive substring matching. This is the default mode but applications may want to explicitly indicate this by putting the asterisk in front. Example: Heine *Heine Please note that we have reused the hash mark indentifier which was used in old GnuPG versions to indicate the so called local-id. It is not anymore used and there should be no conflict when used with X.509 stuff. Using the rfc2253 format of DNs has the drawback that it is not possible to map them back to the original encoding, however we don't have to do this, because our key database stores this encoding as meta data. Some of the search modes are not yet implemented ;-) How to import a private key =========================== There is some limited support to import a private key from a PKCS-12 file. Note, that this does only import the private key and not any certificates available in that file. gpgsm --call-protect-tool --p12-import --store foo.p12 This require that the gpg-agent is running, alternative you may give the passphrase on the commandline using the option "-P " - however this is in general not a good idea. If that key already exists, the protect-tool refuses to store it unless you use the option "--force". How to export a private key =========================== There is also limited support to export a private key in PKCS-12 format. However the certificate is not stored and there is no MAC applied. gpgsm --call-protect-tool --p12-export foo.key >foo.p12 diff --git a/TODO b/TODO index 9b277aa5e..bd23ba6c0 100644 --- a/TODO +++ b/TODO @@ -1,73 +1,73 @@ -*- outline -*- * src/base64 ** Make parsing more robust Currently we don't cope with overlong lines in the best way. * sm/call-agent.c ** The protocol uses an incomplete S-expression We should always use valid S-Exp and not just parts. ** Some code should go into import.c ** When we allow concurrent service request in gpgsm, we might want to have an agent context for each service request (i.e. Assuan context). * sm/certreqgen.c ** Improve error reporting ** Do some basic checks on the supplied DNs * sm/certchain.c ** When a certificate chain was sucessfully verified, make ephemeral certs used in this chain permanent. ** figure out how to auto retrieve a key by serialno+issuer. Dirmngr is currently not able to parse more than the CN. * sm/decrypt.c ** replace leading zero in integer hack by a cleaner solution * sm/sign.c ** Don't hardcode the use of RSA. * sm/gpgsm.c ** Support --output ** mark all unimplemented commands and options. * sm/keydb.c ** Check file permissions ** Write a keybox header and check for that magic value. ** Check that all error code mapping is done. ** Remove the inter-module dependencies between gpgsm and keybox - +** Add an source_of_key field * agent/command.c ** Make sure that secure memory is used where appropriate * agent/pkdecrypt.c, agent/pksign.c ** Don't use stdio to return results. * agent/protect-tool.c ** Export and import certificates along with the secret key. ** Make it more comfortable; i.e. copy files to the correct place. * Move pkcs-1 encoding into libgcrypt. * Use a MAC to protect some files. * sm/export.c ** Return an error code or a status info per user ID. * ALL ** Return IMPORT_OK status.