security-and-privacy/gnupg
security-and-privacy
/
gnupg
mirror of git://git.gnupg.org/gnupg.git
1
0
Fork 0
Code Releases Activity
gnupg/README

373 lines
9.9 KiB
Plaintext
Raw Blame History

NewPG is a temporary protect to work on GnuPG extensions. It will be
merged into the regular GnuPG sources for a GnuPG 2.0 release.
jnlib/ utility functions
assuan/ assuan protocol library
kbx/ keybox library
sm/ the gpgsm program
agent/ the gpg-agent
scd/ the smartcard daemon
Libksba and Libgcrypt are required to build it.
Assuan and Keybox are both 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 <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 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 <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. 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 <path_to_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 <heinrichh@uni-duesseldorf.de>
* Exact match on an email address.
This is indicated by enclosing the email address in the usual way
with left and right angles
Example:
<heinrichh@uni-duesseldorf.de>
* 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.
gpg-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 <passphrase>" -
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.
gpg-protect-tool --p12-export foo.key >foo.p12
View Git Blame Copy Permalink