File: gnupg.info,  Node: GPG Examples,  Next: Unattended Usage of GPG,  Prev: GPG Configuration,  Up: Invoking GPG

4.4 Examples
============

gpg -se -r 'Bob' 'file'
     sign and encrypt for user Bob

gpg -clear-sign 'file'
     make a cleartext signature

gpg -sb 'file'
     make a detached signature

gpg -u 0x12345678 -sb 'file'
     make a detached signature with the key 0x12345678

gpg -list-keys 'user_ID'
     show keys

gpg -fingerprint 'user_ID'
     show fingerprint

gpg -verify 'pgpfile'
gpg -verify 'sigfile' ['datafile']
     Verify the signature of the file but do not output the data unless
     requested.  The second form is used for detached signatures, where
     'sigfile' is the detached signature (either ASCII armored or
     binary) and 'datafile' are the signed data; if this is not given,
     the name of the file holding the signed data is constructed by
     cutting off the extension (".asc" or ".sig") of 'sigfile' or by
     asking the user for the filename.  If the option '--output' is also
     used the signed data is written to the file specified by that
     option; use '-' to write the signed data to stdout.

FILTER EXPRESSIONS
******************

The options '--import-filter' and '--export-filter' use expressions with
this syntax (square brackets indicate an optional part and curly braces
a repetition, white space between the elements are allowed):

       [lc] {[{flag}] PROPNAME op VALUE [lc]}

   The name of a property (PROPNAME) may only consist of letters, digits
and underscores.  The description for the filter type describes which
properties are defined.  If an undefined property is used it evaluates
to the empty string.  Unless otherwise noted, the VALUE must always be
given and may not be the empty string.  No quoting is defined for the
value, thus the value may not contain the strings '&&' or '||', which
are used as logical connection operators.  The flag '--' can be used to
remove this restriction.

   Numerical values are computed as long int; standard C notation
applies.  LC is the logical connection operator; either '&&' for a
conjunction or '||' for a disjunction.  A conjunction is assumed at the
begin of an expression.  Conjunctions have higher precedence than
disjunctions.  If VALUE starts with one of the characters used in any OP
a space after the OP is required.

The supported operators (OP) are:

=~
     Substring must match.

!~
     Substring must not match.

=
     The full string must match.

<>
     The full string must not match.

==
     The numerical value must match.

!=
     The numerical value must not match.

<=
     The numerical value of the field must be LE than the value.

<
     The numerical value of the field must be LT than the value.

>
     The numerical value of the field must be GT than the value.

>=
     The numerical value of the field must be GE than the value.

-le
     The string value of the field must be less or equal than the value.

-lt
     The string value of the field must be less than the value.

-gt
     The string value of the field must be greater than the value.

-ge
     The string value of the field must be greater or equal than the
     value.

-n
     True if value is not empty (no value allowed).

-z
     True if value is empty (no value allowed).

-t
     Alias for "PROPNAME != 0" (no value allowed).

-f
     Alias for "PROPNAME == 0" (no value allowed).

Values for FLAG must be space separated.  The supported flags are:

-
     VALUE spans to the end of the expression.
-c
     The string match in this part is done case-sensitive.
-t
     Leading and trailing spaces are not removed from VALUE.  The
     optional single space after OP is here required.

   The filter options concatenate several specifications for a filter of
the same type.  For example the four options in this example:

      --import-filter keep-uid="uid =~ Alfa"
      --import-filter keep-uid="&& uid !~ Test"
      --import-filter keep-uid="|| uid =~ Alpha"
      --import-filter keep-uid="uid !~ Test"

which is equivalent to

      --import-filter \
       keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"

   imports only the user ids of a key containing the strings "Alfa" or
"Alpha" but not the string "test".

RETURN VALUE
************

The program returns 0 if there are no severe errors, 1 if at least a
signature was bad, and other error codes for fatal errors.

   Note that signature verification requires exact knowledge of what has
been signed and by whom it has been signed.  Using only the return code
is thus not an appropriate way to verify a signature by a script.
Either make proper use or the status codes or use the 'gpgv' tool which
has been designed to make signature verification easy for scripts.

WARNINGS
********

Use a good password for your user account and make sure that all
security issues are always fixed on your machine.  Also employ diligent
physical protection to your machine.  Consider to use a good passphrase
as a last resort protection to your secret key in the case your machine
gets stolen.  It is important that your secret key is never leaked.
Using an easy to carry around token or smartcard with the secret key is
often a advisable.

   If you are going to verify detached signatures, make sure that the
program knows about it; either give both filenames on the command line
or use '-' to specify STDIN.

   For scripted or other unattended use of 'gpg' make sure to use the
machine-parseable interface and not the default interface which is
intended for direct use by humans.  The machine-parseable interface
provides a stable and well documented API independent of the locale or
future changes of 'gpg'.  To enable this interface use the options
'--with-colons' and '--status-fd'.  For certain operations the option
'--command-fd' may come handy too.  See this man page and the file
'DETAILS' for the specification of the interface.  Note that the GnuPG
"info" pages as well as the PDF version of the GnuPG manual features a
chapter on unattended use of GnuPG. As an alternative the library
'GPGME' can be used as a high-level abstraction on top of that
interface.

INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
********************************************

GnuPG tries to be a very flexible implementation of the OpenPGP
standard.  In particular, GnuPG implements many of the optional parts of
the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
compression algorithms.  It is important to be aware that not all
OpenPGP programs implement these optional algorithms and that by forcing
their use via the '--cipher-algo', '--digest-algo',
'--cert-digest-algo', or '--compress-algo' options in GnuPG, it is
possible to create a perfectly valid OpenPGP message, but one that
cannot be read by the intended recipient.

   There are dozens of variations of OpenPGP programs available, and
each supports a slightly different subset of these optional algorithms.
For example, until recently, no (unhacked) version of PGP supported the
BLOWFISH cipher algorithm.  A message using BLOWFISH simply could not be
read by a PGP user.  By default, GnuPG uses the standard OpenPGP
preferences system that will always do the right thing and create
messages that are usable by all recipients, regardless of which OpenPGP
program they use.  Only override this safe default if you really know
what you are doing.

   If you absolutely must override the safe default, or if the
preferences on a given key are invalid for some reason, you are far
better off using the '--pgp6', '--pgp7', or '--pgp8' options.  These
options are safe as they do not force any particular algorithms in
violation of OpenPGP, but rather reduce the available algorithms to a
"PGP-safe" list.

BUGS
****

On older systems this program should be installed as setuid(root).  This
is necessary to lock memory pages.  Locking memory pages prevents the
operating system from writing memory pages (which may contain
passphrases or other sensitive material) to disk.  If you get no warning
message about insecure memory your operating system supports locking
without being root.  The program drops root privileges as soon as locked
memory is allocated.

   Note also that some systems (especially laptops) have the ability to
"suspend to disk" (also known as "safe sleep" or "hibernate").  This
writes all memory to disk before going into a low power or even powered
off mode.  Unless measures are taken in the operating system to protect
the saved memory, passphrases or other sensitive material may be
recoverable from it later.

   Before you report a bug you should first search the mailing list
archives for similar problems and second check whether such a bug has
already been reported to our bug tracker at .