Next: Unattended Usage, Previous: Configuration files, Up: Invoking GPG [Contents][Index]

### 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.

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 beensigned. 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 https://bugs.gnupg.org.

Next: Unattended Usage, Previous: Configuration files, Up: Invoking GPG [Contents][Index]