diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 511 |
1 files changed, 0 insertions, 511 deletions
diff --git a/README b/README deleted file mode 100644 index 5b4a69027..000000000 --- a/README +++ /dev/null @@ -1,511 +0,0 @@ - The GNU Privacy Guard 2 - ========================= - Version 1.9.x - - -GnuPG 1.9 is the future version of GnuPG; it is based on the gnupg-1.3 -code and the previous newpg package. It will eventually lead to a -GnuPG 2.0 release. Note that GnuPG 1.3 and 1.9 are not always in sync -and thus features and bug fixes done in 1.3 are not necessary -available in 1.9. - - -BUILD INSTRUCTIONS -================== - -GnuPG 1.9 depends on the following packages: - - libgpg-error (ftp://ftp.gnupg.org/gcrypt/alpha/libgpg-error/) - libgcrypt (ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/) - libassuan (ftp://ftp.gnupg.org/gcrypt/alpha/libassuan/) - libksba (ftp://ftp.gnupg.org/gcrypt/alpha/libksba/) - -You also need the pinentry package for most function of GnupG; however -it is not a build requirement. pinentry is available at -ftp://ftp.gnupg.org/gcrypt/pinentry/ . - -You should get the latest versions of course, the GnuPG configure -script complains if a version is not sufficient. - -After building and installing the above packages in the order as given -above, you may now continue with GnupG installation (you may also just -try to build GnuPG to see whether your already installed versions are -sufficient). - -As with all packages, you just have to do - - ./configure - make - make install - -(Before doing install you might need to become root.) - -If everything succeeds, you have a working GnuPG with support for -S/MIME and smartcards. Note that there is no binary gpg but a gpg2 so -that this package won't confict with a GnuPG 1.2 or1.3 -installation. gpg2 behaves just like gpg and it is possible to symlink -oto gpg if you want to use gpg 1.9. - -In case of problem please ask on [email protected] for advise. Note -that this release is only expected to build on GNU and *BSD systems. - -A texinfo manual named `gnupg.info' will get installed. Some commands -and options given below. See also the section `SMARTCARD INTRO'. - - -COMMANDS -======== - -gpgsm: ------- - ---learn-card - - Read information about the private keys from the smartcard and - import the certificates from there. - ---export - - Export all certificates stored in the Keybox or those specified on - the command line. When using --armor a few informational lines are - prepended before each block. - - -gpg2: ------ - ---card-status - - Show information pertaining smartcards implementing the OpenPGP - application. - ---change-pin - - Offers a menu to change the PIN of OpenPGP smartcards and to reset - the retry counters. - ---card-edit - - Offers a menu to change any data object on the card and to generate - the keys. - - -OPTIONS -======= - -gpgsm: ------- - ---include-certs <n> - - 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 <filename> - - 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 <path_to_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 <path_to_dirmgr_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 environment 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 <user_id> - - 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. Especially - a line tagged "grp" is 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 <path_to_pinentry_program> - - Specify the PINentry program. The default value is - "<prefix>/bin/pinentry" so you most likely want to specify it. - ---no-grab - - Tell 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. - - -scdaemon: --------- - ---ctapi-driver <libraryname> - - The default for Scdaemon is to use the PC/SC API currently provided - by libpcsclite.so. As an alternative the ctAPI can be used by - specify this option with the appropriate driver name - (e.g. libtowitoko.so). - ---reader-port <portname> - - This specifies the port of the chipcard reader. For PC/SC this is - currently ignored and the first PC/SC reader is used. For the - ctAPI, a number must be specified (the default is 32768 for the - first USB port). - ---disable-ccid - - Disable the integrated support for CCID compliant readers. This - allows to fall back to one of the other drivers even if the internal - CCID driver can handle the reader. Note, that CCID support is only - available if libusb was available at build time. - - -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'. - -gpg.conf-1.9.x - - Options for gpg; tried before gpg.conf - - -policies.txt - - A list of allowed CA policies. This file should give the - object identifiers of the policies line by line. Empty 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. - - -SOURCE FILES -============ - -Here is a list of directories with source files: - -jnlib/ utility functions -kbx/ keybox library -g10/ the gpg program here called gpg2 -sm/ the gpgsm program -agent/ the gpg-agent -scd/ the smartcard daemon -doc/ documentation - - - -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 <[email protected]> - - * 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. Note that you can't use the - string printed by "gpgsm --list-keys" because that one as been - reordered and modified for better readability; use --with-colons to - print the raw (but standard escaped) rfc2253 string - - Example: - - /CN=Heinrich 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. See note - above. - - 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. See note above. - - 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. - - gpgsm --import foo.p12 - -This require that the gpg-agent is running. - - -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 - - -SMARTCARD INTRO -=============== - -GPG, the OpenPGP part of GnuPG, supports the OpenPGP smartcard -(surprise!); see http://g10code.com/p-card.html. - -[Fixme: We need to explain this further] - - -GPGSM, the CMS (S/MIME) part of GnuPG, supports two kinds of -smartcards. The most flexible way is to use PKCS#15 compliant cards, -however you must have build GnuPG with support for the OpenSC library. -The build process automagically detects the presence of this library -and will include support for these cards. - -The other card we currently support is the Telesec NetKey card with -the NKS 2.0 card application. - -Before GPGSM can make use of a new card it must gather some -information, like the card's serial number, the public keys and the -certificates stored on the card. Thus for a new card you need to run -the command - - gpgsm --learn-card - -once. This is also a good test to see whether your card reader is -properly installed. See below in case of error. Once this has been -done you may use the keys stored on the card in the same way you use -keys stored on the disk. gpgsm automagically knows whether a card is -required and will pop up the pinentry to ask you to insert the -correct card. - -For selecting the driver, see the options of scdaemon. A useful -debugging flag is "--debug 2048" showing the communication between -scdaemon and the reader. - -[fixme: write more stuff] - - - - - |