~ubuntu-branches/ubuntu/saucy/gnupg2/saucy-updates : revision 15

1

This is gnupg.info, produced by makeinfo version 4.13 from gnupg.texi.

1

This is /home/wk/w/gnupg-stable/doc/gnupg.info, produced by makeinfo

2

version 4.13 from /home/wk/w/gnupg-stable/doc/gnupg.texi.

2

3

This is the `The GNU Privacy Guard Manual' (version 2.0.17,

4

January 2011).

4

This is the `The GNU Privacy Guard Manual' (version 2.0.19,

5

March 2012).

5

6

7

8

Foundation, Inc.

25

26

Using the GNU Privacy Guard

26

27

***************************

27

28

This is the `The GNU Privacy Guard Manual' (version 2.0.17,

29

January 2011).

29

This is the `The GNU Privacy Guard Manual' (version 2.0.19,

30

March 2012).

30

31

32

33

Foundation, Inc.

650

651

non-zero TTL overrides the global default as set by

651

652

`--default-cache-ttl-ssh'.

652

653

654

The only flag support is `confirm'. If this flag is found for a

655

key, each use of the key will pop up a pinentry to confirm the use

656

of that key. The flag is automatically set if a new key was

657

loaded into `gpg-agent' using the option `-c' of the `ssh-add'

658

command.

659

653

660

The keygrip may be prefixed with a `!' to disable an entry entry.

654

661

655

662

The following example lists exactly one key. Note that keys

657

664

reader are implicitly added to this list; i.e. there is no need to

658

665

list them.

659

666

660

# Key added on 2005-02-25 15:08:29

661

5A6592BF45DC73BD876874A28FD4639282E29B52 0

667

# Key added on: 2011-07-20 20:38:46

668

# Fingerprint: 5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81

669

34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm

662

670

663

671

`private-keys-v1.d/'

664

672

This is the directory where gpg-agent stores the private keys.

782

790

* Agent UPDATESTARTUPTTY:: Change the Standard Display

783

791

* Agent GETEVENTCOUNTER:: Get the Event Counters

784

792

* Agent GETINFO:: Return information about the process

793

* Agent OPTION:: Set options for the session

785

794

786

795

787

796

File: gnupg.info, Node: Agent PKDECRYPT, Next: Agent PKSIGN, Up: Agent Protocol

1205

1214

Incremented for changes of the card readers stati.

1206

1215

1207

1216

1208

File: gnupg.info, Node: Agent GETINFO, Prev: Agent GETEVENTCOUNTER, Up: Agent Protocol

1217

File: gnupg.info, Node: Agent GETINFO, Next: Agent OPTION, Prev: Agent GETEVENTCOUNTER, Up: Agent Protocol

1209

1218

1210

1219

2.6.14 Return information about the process

1211

1220

-------------------------------------------

1230

1239

returned.

1231

1240

1232

1241

1242

File: gnupg.info, Node: Agent OPTION, Prev: Agent GETINFO, Up: Agent Protocol

1243

1244

2.6.15 Set options for the session

1245

----------------------------------

1246

1247

Here is a list of session options which are not yet described with

1248

other commands. The general syntax for an Assuan option is:

1249

1250

OPTION KEY=VALUE

1251

1252

Supported KEYs are:

1253

1254

`agent-awareness'

1255

This may be used to tell gpg-agent of which gpg-agent version the

1256

client is aware of. gpg-agent uses this information to enable

1257

features which might break older clients.

1258

1259

`putenv'

1260

Change the session's environment to be used for the Pinentry.

1261

Valid values are:

1262

1263

`NAME'

1264

Delete envvar NAME

1265

1266

`NAME='

1267

Set envvar NAME to the empty string

1268

1269

`NAME=VALUE'

1270

Set envvar NAME to the string VALUE.

1271

1272

`use-cache-for-signing'

1273

See Assuan command `PKSIGN'.

1274

1275

`allow-pinentry-notify'

1276

This does not need any value. It is used to enable the

1277

PINENTRY_LAUNCHED inquiry.

1278

1279

1280

1233

1281

File: gnupg.info, Node: Invoking GPG, Next: Invoking GPGSM, Prev: Invoking GPG-AGENT, Up: Top

1234

1282

1235

1283

3 Invoking GPG

1255

1303

1256

1304

* Menu:

1257

1305

1258

* GPG Commands:: List of all commands.

1259

* GPG Options:: List of all options.

1260

* GPG Configuration:: Configuration files.

1261

* GPG Examples:: Some usage examples.

1306

* GPG Commands:: List of all commands.

1307

* GPG Options:: List of all options.

1308

* GPG Configuration:: Configuration files.

1309

* GPG Examples:: Some usage examples.

1262

1310

1263

1311

Developer information:

1312

* Unattended Usage of GPG:: Using `gpg' from other programs.

1264

1313

1265

1314

1266

1315

File: gnupg.info, Node: GPG Commands, Next: GPG Options, Up: Invoking GPG

1657

1706

1658

1707

uid `n'

1659

1708

Toggle selection of user ID or photographic user ID with

1660

index `n'. Use `*' to select all and `0' to deselect all.

1709

index `n'. Use `*' to select all and `0' to deselect all.

1661

1710

1662

1711

key `n'

1663

Toggle selection of subkey with index `n'. Use `*' to select

1664

all and `0' to deselect all.

1712

Toggle selection of subkey with index `n'. Use `*' to

1713

select all and `0' to deselect all.

1665

1714

1666

1715

sign

1667

1716

Make a signature on key of user `name' If the key is not yet

1668

1717

signed by the default user (or the users given with -u), the

1669

program displays the information of the key again, together

1670

with its fingerprint and asks whether it should be signed.

1671

This question is repeated for all users specified with -u.

1718

program displays the information of the key again, together

1719

with its fingerprint and asks whether it should be signed.

1720

This question is repeated for all users specified with -u.

1672

1721

1673

1722

lsign

1674

1723

Same as "sign" but the signature is marked as non-exportable

1675

and will therefore never be used by others. This may be used

1676

to make keys valid only in the local environment.

1724

and will therefore never be used by others. This may be

1725

used to make keys valid only in the local environment.

1677

1726

1678

1727

nrsign

1679

1728

Same as "sign" but the signature is marked as non-revocable

1680

and can therefore never be revoked.

1729

and can therefore never be revoked.

1681

1730

1682

1731

tsign

1683

1732

Make a trust signature. This is a signature that combines the

1684

notions of certification (like a regular signature), and

1685

trust (like the "trust" command). It is generally only useful

1686

in distinct communities or groups.

1733

notions of certification (like a regular signature), and

1734

trust (like the "trust" command). It is generally only

1735

useful in distinct communities or groups.

1687

1736

1688

1737

Note that "l" (for local / non-exportable), "nr" (for

1689

1738

non-revocable, and "t" (for trust) may be freely mixed and

1691

1740

1692

1741

delsig

1693

1742

Delete a signature. Note that it is not possible to retract a

1694

signature, once it has been send to the public (i.e. to a

1695

keyserver). In that case you better use `revsig'.

1743

signature, once it has been send to the public (i.e. to a

1744

keyserver). In that case you better use `revsig'.

1696

1745

1697

1746

revsig

1698

1747

Revoke a signature. For every signature which has been

1699

generated by one of the secret keys, GnuPG asks whether a

1700

revocation certificate should be generated.

1748

generated by one of the secret keys, GnuPG asks whether a

1749

revocation certificate should be generated.

1701

1750

1702

1751

check

1703

1752

Check the signatures on all selected user IDs.

1707

1756

1708

1757

addphoto

1709

1758

Create a photographic user ID. This will prompt for a JPEG

1710

file that will be embedded into the user ID. Note that a very

1711

large JPEG will make for a very large key. Also note that

1712

some programs will display your JPEG unchanged (GnuPG), and

1713

some programs will scale it to fit in a dialog box (PGP).

1759

file that will be embedded into the user ID. Note that a

1760

very large JPEG will make for a very large key. Also note

1761

that some programs will display your JPEG unchanged

1762

(GnuPG), and some programs will scale it to fit in a dialog

1763

box (PGP).

1714

1764

1715

1765

showphoto

1716

1766

Display the selected photographic user ID.

1717

1767

1718

1768

deluid

1719

1769

Delete a user ID or photographic user ID. Note that it is not

1720

possible to retract a user id, once it has been send to the

1721

public (i.e. to a keyserver). In that case you better use

1770

possible to retract a user id, once it has been send to the

1771

public (i.e. to a keyserver). In that case you better use

1722

1772

`revuid'.

1723

1773

1724

1774

revuid

1726

1776

1727

1777

primary

1728

1778

Flag the current user id as the primary one, removes the

1729

primary user id flag from all other user ids and sets the

1730

timestamp of all affected self-signatures one second ahead.

1731

Note that setting a photo user ID as primary makes it primary

1732

over other photo user IDs, and setting a regular user ID as

1733

primary makes it primary over other regular user IDs.

1779

primary user id flag from all other user ids and sets the

1780

timestamp of all affected self-signatures one second ahead.

1781

Note that setting a photo user ID as primary makes it

1782

primary over other photo user IDs, and setting a regular

1783

user ID as primary makes it primary over other regular user

1784

IDs.

1734

1785

1735

1786

keyserver

1736

1787

Set a preferred keyserver for the specified user ID(s). This

1737

allows other users to know where you prefer they get your key

1738

from. See `--keyserver-options honor-keyserver-url' for more

1739

on how this works. Setting a value of "none" removes an

1740

existing preferred keyserver.

1788

allows other users to know where you prefer they get your

1789

key from. See `--keyserver-options honor-keyserver-url' for

1790

more on how this works. Setting a value of "none" removes

1791

an existing preferred keyserver.

1741

1792

1742

1793

notation

1743

1794

Set a name=value notation for the specified user ID(s). See

1744

1795

`--cert-notation' for more on how this works. Setting a value

1745

of "none" removes all notations, setting a notation prefixed

1746

with a minus sign (-) removes that notation, and setting a

1747

notation name (without the =value) prefixed with a minus sign

1748

removes all notations with that name.

1796

of "none" removes all notations, setting a notation

1797

prefixed with a minus sign (-) removes that notation, and

1798

setting a notation name (without the =value) prefixed with

1799

a minus sign removes all notations with that name.

1749

1800

1750

1801

pref

1751

1802

List preferences from the selected user ID. This shows the

1752

actual preferences, without including any implied preferences.

1803

actual preferences, without including any implied

1804

preferences.

1753

1805

1754

1806

showpref

1755

1807

More verbose preferences listing for the selected user ID.

1756

This shows the preferences in effect by including the implied

1757

preferences of 3DES (cipher), SHA-1 (digest), and

1758

Uncompressed (compression) if they are not already included

1759

in the preference list. In addition, the preferred keyserver

1760

and signature notations (if any) are shown.

1808

This shows the preferences in effect by including the

1809

implied preferences of 3DES (cipher), SHA-1 (digest), and

1810

Uncompressed (compression) if they are not already included

1811

in the preference list. In addition, the preferred

1812

keyserver and signature notations (if any) are shown.

1761

1813

1762

1814

setpref `string'

1763

1815

Set the list of user ID preferences to `string' for all (or

1764

just the selected) user IDs. Calling setpref with no

1765

arguments sets the preference list to the default (either

1766

built-in or set via `--default-preference-list'), and calling

1767

setpref with "none" as the argument sets an empty preference

1768

list. Use `gpg2 --version' to get a list of available

1769

algorithms. Note that while you can change the preferences on

1770

an attribute user ID (aka "photo ID"), GnuPG does not select

1771

keys via attribute user IDs so these preferences will not be

1772

used by GnuPG.

1816

just the selected) user IDs. Calling setpref with no

1817

arguments sets the preference list to the default (either

1818

built-in or set via `--default-preference-list'), and

1819

calling setpref with "none" as the argument sets an empty

1820

preference list. Use `gpg2 --version' to get a list of

1821

available algorithms. Note that while you can change the

1822

preferences on an attribute user ID (aka "photo ID"), GnuPG

1823

does not select keys via attribute user IDs so these

1824

preferences will not be used by GnuPG.

1773

1825

1774

1826

When setting preferences, you should list the algorithms in

1775

the order which you'd like to see them used by someone else

1776

when encrypting a message to your key. If you don't include

1777

3DES, it will be automatically added at the end. Note that

1778

there are many factors that go into choosing an algorithm

1779

(for example, your key may not be the only recipient), and so

1780

the remote OpenPGP application being used to send to you may

1781

or may not follow your exact chosen order for a given

1782

message. It will, however, only choose an algorithm that is

1783

present on the preference list of every recipient key. See

1784

also the INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section

1785

below.

1827

the order which you'd like to see them used by someone else

1828

when encrypting a message to your key. If you don't

1829

include 3DES, it will be automatically added at the end.

1830

Note that there are many factors that go into choosing an

1831

algorithm (for example, your key may not be the only

1832

recipient), and so the remote OpenPGP application being used

1833

to send to you may or may not follow your exact chosen

1834

order for a given message. It will, however, only choose

1835

an algorithm that is present on the preference list of

1836

every recipient key. See also the INTEROPERABILITY WITH

1837

OTHER OPENPGP PROGRAMS section below.

1786

1838

1787

1839

addkey

1788

1840

Add a subkey to this key.

1792

1844

1793

1845

keytocard

1794

1846

Transfer the selected secret subkey (or the primary key if no

1795

subkey has been selected) to a smartcard. The secret key in

1796

the keyring will be replaced by a stub if the key could be

1797

stored successfully on the card and you use the save command

1798

later. Only certain key types may be transferred to the card.

1799

A sub menu allows you to select on what card to store the

1800

key. Note that it is not possible to get that key back from

1801

the card - if the card gets broken your secret key will be

1802

lost unless you have a backup somewhere.

1847

subkey has been selected) to a smartcard. The secret key in

1848

the keyring will be replaced by a stub if the key could be

1849

stored successfully on the card and you use the save

1850

command later. Only certain key types may be transferred to

1851

the card. A sub menu allows you to select on what card to

1852

store the key. Note that it is not possible to get that key

1853

back from the card - if the card gets broken your secret

1854

key will be lost unless you have a backup somewhere.

1803

1855

1804

1856

bkuptocard `file'

1805

1857

Restore the given file to a card. This command may be used to

1806

restore a backup key (as generated during card

1807

initialization) to a new card. In almost all cases this will

1808

be the encryption key. You should use this command only with

1809

the corresponding public key and make sure that the file

1810

given as argument is indeed the backup to restore. You should

1811

then select 2 to restore as encryption key. You will first

1812

be asked to enter the passphrase of the backup key and then

1813

for the Admin PIN of the card.

1858

restore a backup key (as generated during card

1859

initialization) to a new card. In almost all cases this

1860

will be the encryption key. You should use this command

1861

only with the corresponding public key and make sure that the

1862

file given as argument is indeed the backup to restore. You

1863

should then select 2 to restore as encryption key. You

1864

will first be asked to enter the passphrase of the backup

1865

key and then for the Admin PIN of the card.

1814

1866

1815

1867

delkey

1816

1868

Remove a subkey (secondart key). Note that it is not possible

1817

to retract a subkey, once it has been send to the public

1818

(i.e. to a keyserver). In that case you better use `revkey'.

1869

to retract a subkey, once it has been send to the public

1870

(i.e. to a keyserver). In that case you better use

1871

`revkey'.

1819

1872

1820

1873

revkey

1821

1874

Revoke a subkey.

1822

1875

1823

1876

expire

1824

1877

Change the key or subkey expiration time. If a subkey is

1825

selected, the expiration time of this subkey will be changed.

1826

With no selection, the key expiration of the primary key is

1827

changed.

1878

selected, the expiration time of this subkey will be

1879

changed. With no selection, the key expiration of the

1880

primary key is changed.

1828

1881

1829

1882

trust

1830

1883

Change the owner trust value for the key. This updates the

1831

trust-db immediately and no save is required.

1884

trust-db immediately and no save is required.

1832

1885

1833

1886

disable

1834

1887

enable

1835

1888

Disable or enable an entire key. A disabled key can not

1836

normally be used for encryption.

1889

normally be used for encryption.

1837

1890

1838

1891

addrevoker

1839

1892

Add a designated revoker to the key. This takes one optional

1840

argument: "sensitive". If a designated revoker is marked as

1841

sensitive, it will not be exported by default (see

1893

argument: "sensitive". If a designated revoker is marked as

1894

sensitive, it will not be exported by default (see

1842

1895

export-options).

1843

1896

1844

1897

passwd

1849

1902

1850

1903

clean

1851

1904

Compact (by removing all signatures except the selfsig) any

1852

user ID that is no longer usable (e.g. revoked, or expired).

1853

Then, remove any signatures that are not usable by the trust

1854

calculations. Specifically, this removes any signature that

1855

does not validate, any signature that is superseded by a

1856

later signature, revoked signatures, and signatures issued by

1857

keys that are not present on the keyring.

1905

user ID that is no longer usable (e.g. revoked, or

1906

expired). Then, remove any signatures that are not usable

1907

by the trust calculations. Specifically, this removes any

1908

signature that does not validate, any signature that is

1909

superseded by a later signature, revoked signatures, and

1910

signatures issued by keys that are not present on the keyring.

1858

1911

1859

1912

minimize

1860

1913

Make the key as small as possible. This removes all

1861

signatures from each user ID except for the most recent

1914

signatures from each user ID except for the most recent

1862

1915

self-signature.

1863

1916

1864

1917

cross-certify

1865

1918

Add cross-certification signatures to signing subkeys that

1866

may not currently have them. Cross-certification signatures

1867

protect against a subtle attack against signing subkeys. See

1868

`--require-cross-certification'. All new keys generated have

1869

this signature by default, so this option is only useful to

1870

bring older keys up to date.

1919

may not currently have them. Cross-certification signatures

1920

protect against a subtle attack against signing subkeys. See

1921

`--require-cross-certification'. All new keys generated have

1922

this signature by default, so this option is only useful to

1923

bring older keys up to date.

1871

1924

1872

1925

save

1873

1926

Save all changes to the key rings and quit.

1874

1927

1875

1928

quit

1876

Quit the program without updating the key rings.

1877

1929

Quit the program without updating the key rings.

1878

1930

1879

1931

The listing shows you the key with its secondary keys and all user

1880

1932

ids. The primary user id is indicated by a dot, and selected keys

1887

1939

No ownertrust assigned / not yet calculated.

1888

1940

1889

1941

e

1890

Trust calculation has failed; probably due to an expired key.

1942

Trust calculation has failed; probably due to an expired

1943

key.

1891

1944

1892

1945

q

1893

1946

Not enough information for calculation.

1904

1957

u

1905

1958

Ultimately trusted.

1906

1959

1960

1907

1961

`--sign-key `name''

1908

1962

Signs a public key with your secret key. This is a shortcut

1909

1963

version of the subcommand "sign" from `--edit'.

2016

2070

are:

2017

2071

2018

2072

show-photos

2019

Causes `--list-keys', `--list-sigs', `--list-public-keys',

2020

and `--list-secret-keys' to display any photo IDs attached to

2021

the key. Defaults to no. See also `--photo-viewer'. Does

2022

not work with `--with-colons': see `--attribute-fd' for the

2023

appropriate way to get photo data for scripts and other

2024

frontends.

2073

Causes `--list-keys', `--list-sigs', `--list-public-keys',

2074

and `--list-secret-keys' to display any photo IDs attached

2075

to the key. Defaults to no. See also `--photo-viewer'.

2076

Does not work with `--with-colons': see `--attribute-fd'

2077

for the appropriate way to get photo data for scripts and

2078

other frontends.

2025

2079

2026

2080

show-policy-urls

2027

2081

Show policy URLs in the `--list-sigs' or `--check-sigs'

2031

2085

show-std-notations

2032

2086

show-user-notations

2033

2087

Show all, IETF standard, or user-defined signature notations

2034

in the `--list-sigs' or `--check-sigs' listings. Defaults to

2035

no.

2088

in the `--list-sigs' or `--check-sigs' listings. Defaults

2089

to no.

2036

2090

2037

2091

show-keyserver-urls

2038

2092

Show any preferred keyserver URL in the `--list-sigs' or

2040

2094

2041

2095

show-uid-validity

2042

2096

Display the calculated validity of user IDs during key

2043

listings. Defaults to no.

2097

listings. Defaults to no.

2044

2098

2045

2099

show-unusable-uids

2046

2100

Show revoked and expired user IDs in key listings. Defaults

2052

2106

2053

2107

show-keyring

2054

2108

Display the keyring name at the head of key listings to show

2055

which keyring a given key resides on. Defaults to no.

2109

which keyring a given key resides on. Defaults to no.

2056

2110

2057

2111

show-sig-expire

2058

2112

Show signature expiration dates (if any) during `--list-sigs'

2059

or `--check-sigs' listings. Defaults to no.

2113

or `--check-sigs' listings. Defaults to no.

2060

2114

2061

2115

show-sig-subpackets

2062

2116

Include signature subpackets in the key listing. This option

2063

can take an optional argument list of the subpackets to list.

2064

If no argument is passed, list all subpackets. Defaults to

2065

no. This option is only meaningful when using `--with-colons'

2066

along with `--list-sigs' or `--check-sigs'.

2117

can take an optional argument list of the subpackets to

2118

list. If no argument is passed, list all subpackets.

2119

Defaults to no. This option is only meaningful when using

2120

`--with-colons' along with `--list-sigs' or `--check-sigs'.

2121

2067

2122

2068

2123

`--verify-options `parameters''

2069

2124

This is a space or comma delimited string that gives options used

2072

2127

2073

2128

show-photos

2074

2129

Display any photo IDs present on the key that issued the

2075

signature. Defaults to no. See also `--photo-viewer'.

2130

signature. Defaults to no. See also `--photo-viewer'.

2076

2131

2077

2132

show-policy-urls

2078

2133

Show policy URLs in the signature being verified. Defaults to

2082

2137

show-std-notations

2083

2138

show-user-notations

2084

2139

Show all, IETF standard, or user-defined signature notations

2085

in the signature being verified. Defaults to IETF standard.

2140

in the signature being verified. Defaults to IETF standard.

2086

2141

2087

2142

show-keyserver-urls

2088

2143

Show any preferred keyserver URL in the signature being

2089

verified. Defaults to no.

2144

verified. Defaults to no.

2090

2145

2091

2146

show-uid-validity

2092

2147

Display the calculated validity of the user IDs on the key

2093

that issued the signature. Defaults to no.

2148

that issued the signature. Defaults to no.

2094

2149

2095

2150

show-unusable-uids

2096

2151

Show revoked and expired user IDs during signature

2097

verification. Defaults to no.

2152

verification. Defaults to no.

2098

2153

2099

2154

show-primary-uid-only

2100

2155

Show only the primary user ID during signature verification.

2101

That is all the AKA lines as well as photo Ids are not shown

2102

with the signature verification status.

2156

That is all the AKA lines as well as photo Ids are not

2157

shown with the signature verification status.

2103

2158

2104

2159

pka-lookups

2105

2160

Enable PKA lookups to verify sender addresses. Note that PKA

2106

is based on DNS, and so enabling this option may disclose

2107

information on when and what signatures are verified or to

2108

whom data is encrypted. This is similar to the "web bug"

2109

described for the auto-key-retrieve feature.

2161

is based on DNS, and so enabling this option may disclose

2162

information on when and what signatures are verified or to

2163

whom data is encrypted. This is similar to the "web bug"

2164

described for the auto-key-retrieve feature.

2110

2165

2111

2166

pka-trust-increase

2112

2167

Raise the trust in a signature to full if the signature

2113

passes PKA validation. This option is only meaningful if

2168

passes PKA validation. This option is only meaningful if

2114

2169

pka-lookups is set.

2115

2170

2116

2171

`--enable-dsa2'

2194

2249

The Latin 2 set.

2195

2250

2196

2251

iso-8859-15

2197

This is currently an alias for the Latin 1 set.

2252

This is currently an alias for the Latin 1 set.

2198

2253

2199

2254

koi8-r

2200

2255

The usual Russian set (rfc1489).

2201

2256

2202

2257

utf-8

2203

Bypass all translations and assume that the OS uses native

2258

Bypass all translations and assume that the OS uses native

2204

2259

UTF-8 encoding.

2205

2260

2206

2261

`--utf8-strings'

2269

2324

pseudonymous user.

2270

2325

2271

2326

2 means you did casual verification of the key. For example, this

2272

could mean that you verified that the key fingerprint and checked

2273

the user ID on the key against a photo ID.

2327

could mean that you verified the key fingerprint and checked the

2328

user ID on the key against a photo ID.

2274

2329

2275

2330

3 means you did extensive verification of the key. For example,

2276

2331

this could mean that you verified the key fingerprint with the

2304

2359

2305

2360

pgp

2306

2361

This is the Web of Trust combined with trust signatures as

2307

used in PGP 5.x and later. This is the default trust model

2308

when creating a new trust database.

2362

used in PGP 5.x and later. This is the default trust model

2363

when creating a new trust database.

2309

2364

2310

2365

classic

2311

2366

This is the standard Web of Trust as used in PGP 2.x and

2313

2368

2314

2369

direct

2315

2370

Key validity is set directly by the user and not calculated

2316

via the Web of Trust.

2371

via the Web of Trust.

2317

2372

2318

2373

always

2319

2374

Skip key validation and assume that used keys are always fully

2320

trusted. You generally won't use this unless you are using

2321

some external validation scheme. This option also suppresses

2322

the "[uncertain]" tag printed with signature checks when

2323

there is no evidence that the user ID is bound to the key.

2375

trusted. You generally won't use this unless you are using

2376

some external validation scheme. This option also

2377

suppresses the "[uncertain]" tag printed with signature

2378

checks when there is no evidence that the user ID is bound

2379

to the key.

2324

2380

2325

2381

auto

2326

2382

Select the trust model depending on whatever the internal

2327

trust database says. This is the default model if such a

2328

database already exists.

2383

trust database says. This is the default model if such a

2384

database already exists.

2329

2385

2330

2386

`--auto-key-locate `parameters''

2331

2387

`--no-auto-key-locate'

2343

2399

2344

2400

ldap

2345

2401

Using DNS Service Discovery, check the domain in question for

2346

any LDAP keyservers to use. If this fails, attempt to locate

2347

the key using the PGP Universal method of checking

2402

any LDAP keyservers to use. If this fails, attempt to

2403

locate the key using the PGP Universal method of checking

2348

2404

`ldap://keys.(thedomain)'.

2349

2405

2350

2406

keyserver

2353

2409

2354

2410

keyserver-URL

2355

2411

In addition, a keyserver URL as used in the `--keyserver'

2356

option may be used here to query that particular keyserver.

2412

option may be used here to query that particular keyserver.

2357

2413

2358

2414

local

2359

2415

Locate the key using the local keyrings. This mechanism

2360

allows to select the order a local key lookup is done. Thus

2361

using `--auto-key-locate local' is identical to

2416

allows to select the order a local key lookup is done.

2417

Thus using `--auto-key-locate local' is identical to

2362

2418

`--no-auto-key-locate'.

2363

2419

2364

2420

nodefault

2365

2421

This flag disables the standard local key lookup, done before

2366

any of the mechanisms defined by the `--auto-key-locate' are

2367

tried. The position of this mechanism in the list does not

2368

matter. It is not required if `local' is also used.

2422

any of the mechanisms defined by the `--auto-key-locate'

2423

are tried. The position of this mechanism in the list does

2424

not matter. It is not required if `local' is also used.

2369

2425

2370

2426

2371

2427

`--keyid-format `short|0xshort|long|0xlong''

2372

2428

Select how to display key IDs. "short" is the traditional

2373

2429

8-character key ID. "long" is the more accurate (but less

2374

2430

convenient) 16-character key ID. Add an "0x" to either to include

2375

an "0x" at the beginning of the key ID, as in 0x99242560.

2431

an "0x" at the beginning of the key ID, as in 0x99242560. Note

2432

that this option is ignored if the option -with-colons is used.

2376

2433

2377

2434

`--keyserver `name''

2378

2435

Use `name' as your keyserver. This is the server that

2404

2461

2405

2462

include-revoked

2406

2463

When searching for a key with `--search-keys', include keys

2407

that are marked on the keyserver as revoked. Note that not

2408

all keyservers differentiate between revoked and unrevoked

2409

keys, and for such keyservers this option is meaningless.

2410

Note also that most keyservers do not have cryptographic

2411

verification of key revocations, and so turning this option

2464

that are marked on the keyserver as revoked. Note that not

2465

all keyservers differentiate between revoked and unrevoked

2466

keys, and for such keyservers this option is meaningless.

2467

Note also that most keyservers do not have cryptographic

2468

verification of key revocations, and so turning this option

2412

2469

off may result in skipping keys that are incorrectly marked

2413

2470

as revoked.

2414

2471

2415

2472

include-disabled

2416

2473

When searching for a key with `--search-keys', include keys

2417

that are marked on the keyserver as disabled. Note that this

2418

option is not used with HKP keyservers.

2474

that are marked on the keyserver as disabled. Note that

2475

this option is not used with HKP keyservers.

2419

2476

2420

2477

auto-key-retrieve

2421

2478

This option enables the automatic retrieving of keys from a

2422

keyserver when verifying signatures made by keys that are not

2423

on the local keyring.

2479

keyserver when verifying signatures made by keys that are

2480

not on the local keyring.

2424

2481

2425

2482

Note that this option makes a "web bug" like behavior

2426

possible. Keyserver operators can see which keys you

2427

request, so by sending you a message signed by a brand new

2428

key (which you naturally will not have on your local

2429

keyring), the operator can tell both your IP address and the

2430

time when you verified the signature.

2483

possible. Keyserver operators can see which keys you

2484

request, so by sending you a message signed by a brand new

2485

key (which you naturally will not have on your local

2486

keyring), the operator can tell both your IP address and

2487

the time when you verified the signature.

2431

2488

2432

2489

honor-keyserver-url

2433

2490

When using `--refresh-keys', if the key in question has a

2434

preferred keyserver URL, then use that preferred keyserver to

2435

refresh the key from. In addition, if auto-key-retrieve is

2436

set, and the signature being verified has a preferred

2437

keyserver URL, then use that preferred keyserver to fetch the

2438

key from. Defaults to yes.

2491

preferred keyserver URL, then use that preferred keyserver

2492

to refresh the key from. In addition, if auto-key-retrieve

2493

is set, and the signature being verified has a preferred

2494

keyserver URL, then use that preferred keyserver to fetch

2495

the key from. Defaults to yes.

2439

2496

2440

2497

honor-pka-record

2441

2498

If auto-key-retrieve is set, and the signature being verified

2442

has a PKA record, then use the PKA information to fetch the

2443

key. Defaults to yes.

2499

has a PKA record, then use the PKA information to fetch the

2500

key. Defaults to yes.

2444

2501

2445

2502

include-subkeys

2446

2503

When receiving a key, include subkeys as potential targets.

2447

Note that this option is not used with HKP keyservers, as

2448

they do not support retrieving keys by subkey id.

2504

Note that this option is not used with HKP keyservers, as

2505

they do not support retrieving keys by subkey id.

2449

2506

2450

2507

use-temp-files

2451

2508

On most Unix-like platforms, GnuPG communicates with the

2452

keyserver helper program via pipes, which is the most

2453

efficient method. This option forces GnuPG to use temporary

2454

files to communicate. On some platforms (such as Win32 and

2509

keyserver helper program via pipes, which is the most

2510

efficient method. This option forces GnuPG to use temporary

2511

files to communicate. On some platforms (such as Win32 and

2455

2512

RISC OS), this option is always enabled.

2456

2513

2457

2514

keep-temp-files

2458

2515

If using `use-temp-files', do not delete the temp files after

2459

using them. This option is useful to learn the keyserver

2460

communication protocol by reading the temporary files.

2516

using them. This option is useful to learn the keyserver

2517

communication protocol by reading the temporary files.

2461

2518

2462

2519

verbose

2463

2520

Tell the keyserver helper program to be more verbose. This

2464

option can be repeated multiple times to increase the

2521

option can be repeated multiple times to increase the

2465

2522

verbosity level.

2466

2523

2467

2524

timeout

2468

2525

Tell the keyserver helper program how long (in seconds) to

2469

try and perform a keyserver action before giving up. Note

2470

that performing multiple actions at the same time uses this

2471

timeout value per action. For example, when retrieving

2472

multiple keys via `--recv-keys', the timeout applies

2526

try and perform a keyserver action before giving up. Note

2527

that performing multiple actions at the same time uses this

2528

timeout value per action. For example, when retrieving

2529

multiple keys via `--recv-keys', the timeout applies

2473

2530

separately to each key retrieval, and not to the

2474

2531

`--recv-keys' command as a whole. Defaults to 30 seconds.

2475

2532

2476

2533

http-proxy=`value'

2477

2534

Set the proxy to use for HTTP and HKP keyservers. This

2478

overrides the "http_proxy" environment variable, if any.

2535

overrides the "http_proxy" environment variable, if any.

2479

2536

2480

2537

max-cert-size

2481

2538

When retrieving a key via DNS CERT, only accept keys up to

2482

this size. Defaults to 16384 bytes.

2539

this size. Defaults to 16384 bytes.

2483

2540

2484

2541

debug

2485

2542

Turn on debug output in the keyserver helper program. Note

2486

that the details of debug output depends on which keyserver

2487

helper program is being used, and in turn, on any libraries

2488

that the keyserver helper program uses internally (libcurl,

2543

that the details of debug output depends on which keyserver

2544

helper program is being used, and in turn, on any libraries

2545

that the keyserver helper program uses internally (libcurl,

2489

2546

openldap, etc).

2490

2547

2491

2548

check-cert

2492

2549

Enable certificate checking if the keyserver presents one

2493

(for hkps or ldaps). Defaults to on.

2550

(for hkps or ldaps). Defaults to on.

2494

2551

2495

2552

ca-cert-file

2496

2553

Provide a certificate store to override the system default.

2497

Only necessary if check-cert is enabled, and the keyserver is

2498

using a certificate that is not present in a system default

2499

certificate list.

2554

Only necessary if check-cert is enabled, and the keyserver

2555

is using a certificate that is not present in a system

2556

default certificate list.

2500

2557

2501

2558

Note that depending on the SSL library that the keyserver

2502

helper is built with, this may actually be a directory or a

2559

helper is built with, this may actually be a directory or a

2503

2560

file.

2504

2561

2505

2562

`--completes-needed `n''

2759

2816

2760

2817

import-local-sigs

2761

2818

Allow importing key signatures marked as "local". This is not

2762

generally useful unless a shared keyring scheme is being used.

2763

Defaults to no.

2819

generally useful unless a shared keyring scheme is being

2820

used. Defaults to no.

2764

2821

2765

2822

repair-pks-subkey-bug

2766

2823

During import, attempt to repair the damage caused by the PKS

2767

keyserver bug (pre version 0.9.6) that mangles keys with

2768

multiple subkeys. Note that this cannot completely repair the

2769

damaged key as some crucial data is removed by the keyserver,

2770

but it does at least give you back one subkey. Defaults to no

2771

for regular `--import' and to yes for keyserver `--recv-keys'.

2824

keyserver bug (pre version 0.9.6) that mangles keys with

2825

multiple subkeys. Note that this cannot completely repair

2826

the damaged key as some crucial data is removed by the

2827

keyserver, but it does at least give you back one subkey.

2828

Defaults to no for regular `--import' and to yes for

2829

keyserver `--recv-keys'.

2772

2830

2773

2831

merge-only

2774

2832

During import, allow key updates to existing keys, but do not

2775

allow any new keys to be imported. Defaults to no.

2833

allow any new keys to be imported. Defaults to no.

2776

2834

2777

2835

import-clean

2778

2836

After import, compact (remove all signatures except the

2779

2837

self-signature) any user IDs from the new key that are not

2780

usable. Then, remove any signatures from the new key that

2781

are not usable. This includes signatures that were issued by

2782

keys that are not present on the keyring. This option is the

2783

same as running the `--edit-key' command "clean" after

2838

usable. Then, remove any signatures from the new key that

2839

are not usable. This includes signatures that were issued

2840

by keys that are not present on the keyring. This option is

2841

the same as running the `--edit-key' command "clean" after

2784

2842

import. Defaults to no.

2785

2843

2786

2844

import-minimal

2787

2845

Import the smallest key possible. This removes all signatures

2788

except the most recent self-signature on each user ID. This

2789

option is the same as running the `--edit-key' command

2790

"minimize" after import. Defaults to no.

2846

except the most recent self-signature on each user ID. This

2847

option is the same as running the `--edit-key' command

2848

"minimize" after import. Defaults to no.

2791

2849

2792

2850

`--export-options `parameters''

2793

2851

This is a space or comma delimited string that gives options for

2796

2854

2797

2855

export-local-sigs

2798

2856

Allow exporting key signatures marked as "local". This is not

2799

generally useful unless a shared keyring scheme is being used.

2800

Defaults to no.

2857

generally useful unless a shared keyring scheme is being

2858

used. Defaults to no.

2801

2859

2802

2860

export-attributes

2803

2861

Include attribute user IDs (photo IDs) while exporting. This

2804

is useful to export keys if they are going to be used by an

2805

OpenPGP program that does not accept attribute user IDs.

2862

is useful to export keys if they are going to be used by an

2863

OpenPGP program that does not accept attribute user IDs.

2806

2864

Defaults to yes.

2807

2865

2808

2866

export-sensitive-revkeys

2811

2869

2812

2870

export-reset-subkey-passwd

2813

2871

When using the `--export-secret-subkeys' command, this option

2814

resets the passphrases for all exported subkeys to empty.

2815

This is useful when the exported subkey is to be used on an

2816

unattended machine where a passphrase doesn't necessarily

2872

resets the passphrases for all exported subkeys to empty.

2873

This is useful when the exported subkey is to be used on an

2874

unattended machine where a passphrase doesn't necessarily

2817

2875

make sense. Defaults to no.

2818

2876

2819

2877

export-clean

2820

2878

Compact (remove all signatures from) user IDs on the key being

2821

exported if the user IDs are not usable. Also, do not export

2822

any signatures that are not usable. This includes signatures

2823

that were issued by keys that are not present on the keyring.

2824

This option is the same as running the `--edit-key' command

2825

"clean" before export except that the local copy of the key

2826

is not modified. Defaults to no.

2879

exported if the user IDs are not usable. Also, do not export

2880

any signatures that are not usable. This includes

2881

signatures that were issued by keys that are not present on

2882

the keyring. This option is the same as running the

2883

`--edit-key' command "clean" before export except that the

2884

local copy of the key is not modified. Defaults to no.

2827

2885

2828

2886

export-minimal

2829

2887

Export the smallest key possible. This removes all signatures

2830

except the most recent self-signature on each user ID. This

2831

option is the same as running the `--edit-key' command

2832

"minimize" before export except that the local copy of the

2888

except the most recent self-signature on each user ID. This

2889

option is the same as running the `--edit-key' command

2890

"minimize" before export except that the local copy of the

2833

2891

key is not modified. Defaults to no.

2834

2892

2835

2893

`--with-colons'

2943

3001

2944

3002

`--s2k-count `n''

2945

3003

Specify how many times the passphrase mangling is repeated. This

2946

value may range between 1024 and 65011712 inclusive, and the

2947

default is 65536. Note that not all values in the 1024-65011712

2948

range are legal and if an illegal value is selected, GnuPG will

2949

round up to the nearest legal value. This option is only

2950

meaningful if `--s2k-mode' is 3.

3004

value may range between 1024 and 65011712 inclusive. The default

3005

is inquired from gpg-agent. Note that not all values in the

3006

1024-65011712 range are legal and if an illegal value is selected,

3007

GnuPG will round up to the nearest legal value. This option is

3008

only meaningful if `--s2k-mode' is 3.

2951

3009

2952

3010

2953

3011

3.2.5 Compliance options

3049

3107

3050

3108

`none'

3051

3109

No debugging at all. A value of less than 1 may be used

3052

instead of the keyword.

3110

instead of the keyword.

3053

3111

3054

3112

`basic'

3055

3113

Some basic debug messages. A value between 1 and 2 may be

3056

used instead of the keyword.

3114

used instead of the keyword.

3057

3115

3058

3116

`advanced'

3059

3117

More verbose debug messages. A value between 3 and 5 may be

3060

used instead of the keyword.

3118

used instead of the keyword.

3061

3119

3062

3120

`expert'

3063

3121

Even more detailed messages. A value between 6 and 8 may be

3064

used instead of the keyword.

3122

used instead of the keyword.

3065

3123

3066

3124

`guru'

3067

3125

All of the debug messages you can get. A value greater than 8

3068

may be used instead of the keyword. The creation of hash

3069

tracing files is only enabled if the keyword is used.

3126

may be used instead of the keyword. The creation of hash

3127

tracing files is only enabled if the keyword is used.

3070

3128

3071

3129

How these messages are mapped to the actual debugging flags is not

3072

3130

specified and may change with newer releases of this program. They

3349

3407

`--ignore-valid-from'

3350

3408

GnuPG normally does not select and use subkeys created in the

3351

3409

future. This option allows the use of such keys and thus exhibits

3352

the pre-1.0.7 behaviour. You should not use this option unless you

3410

the pre-1.0.7 behaviour. You should not use this option unless

3353

3411

there is some clock problem. See also `--ignore-time-conflict' for

3354

3412

timestamp issues with signatures.

3355

3413

3556

3614

directory (*note option --homedir::).

3557

3615

3558

3616

`gpg.conf'

3559

This is the standard configuration file read by `gpg2' on startup.

3560

It may contain any valid long option; the leading two dashes may

3561

not be entered and the option may not be abbreviated. This default

3562

name may be changed on the command line (*note option --options::).

3563

You should backup this file.

3617

This is the standard configuration file read by `gpg2' on

3618

startup. It may contain any valid long option; the leading two

3619

dashes may not be entered and the option may not be abbreviated.

3620

This default name may be changed on the command line (*note

3621

option --options::). You should backup this file.

3564

3622

3565

3623

3566

3624

Note that on larger installations, it is useful to put predefined

3586

3644

3587

3645

`~/.gnupg/trustdb.gpg'

3588

3646

The trust database. There is no need to backup this file; it is

3589

better to backup the ownertrust values (*note option

3647

better to backup the ownertrust values (*note option

3590

3648

--export-ownertrust::).

3591

3649

3592

3650

`~/.gnupg/trustdb.gpg.lock'

3611

3669

If set directory used instead of "~/.gnupg".

3612

3670

3613

3671

GPG_AGENT_INFO

3614

Used to locate the gpg-agent. The value consists of 3 colon

3615

delimited fields: The first is the path to the Unix Domain Socket,

3616

the second the PID of the gpg-agent and the protocol version which

3617

should be set to 1. When starting the gpg-agent as described in

3618

its documentation, this variable is set to the correct value. The

3619

option `--gpg-agent-info' can be used to override it.

3672

Used to locate the gpg-agent. The value consists of 3 colon

3673

delimited fields: The first is the path to the Unix Domain

3674

Socket, the second the PID of the gpg-agent and the protocol

3675

version which should be set to 1. When starting the gpg-agent as

3676

described in its documentation, this variable is set to the correct

3677

value. The option `--gpg-agent-info' can be used to override it.

3620

3678

3621

3679

PINENTRY_USER_DATA

3622

3680

This value is passed via gpg-agent to pinentry. It is useful to

3623

convey extra information to a custom pinentry.

3681

convey extra information to a custom pinentry.

3624

3682

3625

3683

COLUMNS

3626

3684

LINES

3628

3686

3629

3687

LANGUAGE

3630

3688

Apart from its use by GNU, it is used in the W32 version to

3631

override the language selection done through the Registry. If

3632

used and set to a valid and available language name (LANGID), the

3633

file with the translation is loaded from

3634

`GPGDIR/gnupg.nls/LANGID.mo'. Here GPGDIR is the directory out of

3635

which the gpg binary has been loaded. If it can't be loaded the

3636

Registry is tried and as last resort the native Windows locale

3637

system is used.

3689

override the language selection done through the Registry. If

3690

used and set to a valid and available language name (LANGID),

3691

the file with the translation is loaded from

3692

3693

`GPGDIR/gnupg.nls/LANGID.mo'. Here GPGDIR is the directory out

3694

of which the gpg binary has been loaded. If it can't be loaded

3695

the Registry is tried and as last resort the native Windows

3696

locale system is used.

3638

3697

3639

3698

3640

3699

3641

File: gnupg.info, Node: GPG Examples, Prev: GPG Configuration, Up: Invoking GPG

3700

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

3642

3701

3643

3702

3.4 Examples

3644

3703

============

3746

3805

already been reported to our bug tracker at http://bugs.gnupg.org .

3747

3806

3748

3807

3808

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

3809

3810

3.5 Unattended Usage

3811

====================

3812

3813

`gpg' is often used as a backend engine by other software. To help

3814

with this a machine interface has been defined to have an unambiguous

3815

way to do this. The options `--status-fd' and `--batch' are almost

3816

always required for this.

3817

3818

* Menu:

3819

3820

* Unattended GPG key generation:: Unattended key generation

3821

3822

3823

File: gnupg.info, Node: Unattended GPG key generation, Up: Unattended Usage of GPG

3824

3825

3.6 Unattended key generation

3826

=============================

3827

3828

The command `--gen-key' may be used along with the option `--batch' for

3829

unattended key generation. The parameters are either read from stdin

3830

or given as a file on the command line. The format of the parameter

3831

file is as follows:

3832

3833

* Text only, line length is limited to about 1000 characters.

3834

3835

* UTF-8 encoding must be used to specify non-ASCII characters.

3836

3837

* Empty lines are ignored.

3838

3839

* Leading and trailing while space is ignored.

3840

3841

* A hash sign as the first non white space character indicates a

3842

comment line.

3843

3844

* Control statements are indicated by a leading percent sign, the

3845

arguments are separated by white space from the keyword.

3846

3847

* Parameters are specified by a keyword, followed by a colon.

3848

Arguments are separated by white space.

3849

3850

* The first parameter must be `Key-Type'; control statements may be

3851

placed anywhere.

3852

3853

* The order of the parameters does not matter except for `Key-Type'

3854

which must be the first parameter. The parameters are only used

3855

for the generated keyblock (primary and subkeys); parameters

3856

from previous sets are not used. Some syntactically checks may

3857

be performed.

3858

3859

* Key generation takes place when either the end of the parameter

3860

file is reached, the next `Key-Type' parameter is encountered or

3861

at the control statement `%commit' is encountered.

3862

3863

Control statements:

3864

3865

%echo TEXT

3866

Print TEXT as diagnostic.

3867

3868

%dry-run

3869

Suppress actual key generation (useful for syntax checking).

3870

3871

%commit

3872

Perform the key generation. Note that an implicit commit is done

3873

at the next Key-Type parameter.

3874

3875

%pubring FILENAME

3876

%secring FILENAME

3877

Do not write the key to the default or commandline given keyring

3878

but to FILENAME. This must be given before the first commit to

3879

take place, duplicate specification of the same filename is

3880

ignored, the last filename before a commit is used. The filename

3881

is used until a new filename is used (at commit points) and all

3882

keys are written to that file. If a new filename is given, this

3883

file is created (and overwrites an existing one). For GnuPG

3884

versions prior to 2.1, both control statements must be given. For

3885

GnuPG 2.1 and later `%secring' is a no-op.

3886

3887

%ask-passphrase

3888

%no-ask-passphrase

3889

Enable (or disable) a mode where the command `passphrase' is

3890

ignored and instead the usual passphrase dialog is used. This does

3891

not make sense for batch key generation; however the unattended key

3892

generation feature is also used by GUIs and this feature

3893

relinquishes the GUI from implementing its own passphrase entry

3894

code. These are global control statements and affect all future

3895

key genrations.

3896

3897

%no-protection

3898

Since GnuPG version 2.1 it is not anymore possible to specify a

3899

passphrase for unattended key generation. The passphrase command

3900

is simply ignored and `%ask-passpharse' is thus implicitly enabled.

3901

Using this option allows the creation of keys without any

3902

passphrase protection. This option is mainly intended for

3903

regression tests.

3904

3905

%transient-key

3906

If given the keys are created using a faster and a somewhat less

3907

secure random number generator. This option may be used for keys

3908

which are only used for a short time and do not require full

3909

cryptographic strength. It takes only effect if used together with

3910

the control statement `%no-protection'.

3911

3912

3913

General Parameters:

3914

3915

Key-Type: ALGO

3916

Starts a new parameter block by giving the type of the primary

3917

key. The algorithm must be capable of signing. This is a required

3918

parameter. ALGO may either be an OpenPGP algorithm number or a

3919

string with the algorithm name. The special value `default' may

3920

be used for ALGO to create the default key type; in this case a

3921

`Key-Usage' shall not be given and `default' also be used for

3922

`Subkey-Type'.

3923

3924

Key-Length: NBITS

3925

The requested length of the generated key in bits. The default is

3926

returned by running the command `gpg2 --gpgconf-list'.

3927

3928

Key-Grip: HEXSTRING

3929

This is optional and used to generate a CSR or certificate for an

3930

already existing key. Key-Length will be ignored when given.

3931

3932

Key-Usage: USAGE-LIST

3933

Space or comma delimited list of key usages. Allowed values are

3934

`encrypt', `sign', and `auth'. This is used to generate the key

3935

flags. Please make sure that the algorithm is capable of this

3936

usage. Note that OpenPGP requires that all primary keys are

3937

capable of certification, so no matter what usage is given here,

3938

the `cert' flag will be on. If no `Key-Usage' is specified and

3939

the `Key-Type' is not `default', all allowed usages for that

3940

particular algorithm are used; if it is not given but `default' is

3941

used the usage will be `sign'.

3942

3943

Subkey-Type: ALGO

3944

This generates a secondary key (subkey). Currently only one subkey

3945

can be handled. See also `Key-Type' above.

3946

3947

Subkey-Length: NBITS

3948

Length of the secondary key (subkey) in bits. The default is

3949

returned by running the command `gpg2 --gpgconf-list'".

3950

3951

Subkey-Usage: USAGE-LIST

3952

Key usage lists for a subkey; similar to `Key-Usage'.

3953

3954

Passphrase: STRING

3955

If you want to specify a passphrase for the secret key, enter it

3956

here. Default is not to use any passphrase.

3957

3958

Name-Real: NAME

3959

Name-Comment: COMMENT

3960

Name-Email: EMAIL

3961

The three parts of a user name. Remember to use UTF-8 encoding

3962

here. If you don't give any of them, no user ID is created.

3963

3964

Expire-Date: ISO-DATE|(NUMBER[d|w|m|y])

3965

Set the expiration date for the key (and the subkey). It may

3966

either be entered in ISO date format (2000-08-15) or as number of

3967

days, weeks, month or years. The special notation "seconds=N" is

3968

also allowed to directly give an Epoch value. Without a letter

3969

days are assumed. Note that there is no check done on the

3970

overflow of the type used by OpenPGP for timestamps. Thus you

3971

better make sure that the given value make sense. Although

3972

OpenPGP works with time intervals, GnuPG uses an absolute value

3973

internally and thus the last year we can represent is 2105.

3974

3975

Ceation-Date: ISO-DATE

3976

Set the creation date of the key as stored in the key information

3977

and which is also part of the fingerprint calculation. Either a

3978

date like "1986-04-26" or a full timestamp like "19860426T042640"

3979

may be used. The time is considered to be UTC. If it is not

3980

given the current time is used.

3981

3982

Preferences: STRING

3983

Set the cipher, hash, and compression preference values for this

3984

key. This expects the same type of string as the sub-command

3985

`setpref' in the `--edit-key' menu.

3986

3987

Revoker: ALGO:FPR [sensitive]

3988

Add a designated revoker to the generated key. Algo is the public

3989

key algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)

3990

FPR is the fingerprint of the designated revoker. The optional

3991

`sensitive' flag marks the designated revoker as sensitive

3992

information. Only v4 keys may be designated revokers.

3993

3994

Keyserver: STRING

3995

This is an optional parameter that specifies the preferred

3996

keyserver URL for the key.

3997

3998

Handle: STRING

3999

This is an optional parameter only used with the status lines

4000

KEY_CREATED and KEY_NOT_CREATED. STRING may be up to 100

4001

characters and should not contain spaces. It is useful for batch

4002

key generation to associate a key parameter block with a status

4003

line.

4004

4005

4006

Here is an example on how to create a key:

4007

$ cat >foo <<EOF

4008

%echo Generating a basic OpenPGP key

4009

Key-Type: DSA

4010

Key-Length: 1024

4011

Subkey-Type: ELG-E

4012

Subkey-Length: 1024

4013

Name-Real: Joe Tester

4014

Name-Comment: with stupid passphrase

4015

Name-Email: joe@foo.bar

4016

Expire-Date: 0

4017

Passphrase: abc

4018

%pubring foo.pub

4019

%secring foo.sec

4020

# Do a commit here, so that we can later print "done" :-)

4021

%commit

4022

%echo done

4023

EOF

4024

$ gpg2 --batch --gen-key foo

4025

[...]

4026

$ gpg2 --no-default-keyring --secret-keyring ./foo.sec \

4027

--keyring ./foo.pub --list-secret-keys

4028

/home/wk/work/gnupg-stable/scratch/foo.sec

4029

------------------------------------------

4030

sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>

4031

ssb 1024g/8F70E2C0 2000-03-09

4032

4033

If you want to create a key with the default algorithms you would use

4034

these parameters:

4035

%echo Generating a default key

4036

Key-Type: default

4037

Subkey-Type: default

4038

Name-Real: Joe Tester

4039

Name-Comment: with stupid passphrase

4040

Name-Email: joe@foo.bar

4041

Expire-Date: 0

4042

Passphrase: abc

4043

%pubring foo.pub

4044

%secring foo.sec

4045

# Do a commit here, so that we can later print "done" :-)

4046

%commit

4047

%echo done

4048

4049

3749

4050

File: gnupg.info, Node: Invoking GPGSM, Next: Invoking SCDAEMON, Prev: Invoking GPG, Up: Top

3750

4051

3751

4052

4 Invoking GPGSM

3862

4163

---------------------------------------------

3863

4164

3864

4165

`--gen-key'

3865

This command allows the creation of a certificate signing request.

3866

It is commonly used along with the `--output' option to save the

3867

created CSR into a file. If used with the `--batch' a parameter

3868

file is used to create the CSR.

4166

-This command allows the creation of a certificate signing

4167

request. It -is commonly used along with the `--output' option to

4168

save the -created CSR into a file. If used with the `--batch' a

4169

parameter -file is used to create the CSR.

3869

4170

3870

4171

`--list-keys'

3871

4172

`-k'

3972

4273

* Certificate Options:: Certificate related options.

3973

4274

* Input and Output:: Input and Output.

3974

4275

* CMS Options:: How to change how the CMS is created.

3975

* Esoteric Options:: Doing things one usually don't want to do.

4276

* Esoteric Options:: Doing things one usually do not want to do.

3976

4277

3977

4278

3978

4279

File: gnupg.info, Node: Configuration Options, Next: Certificate Options, Up: GPGSM Options

4011

4312

Specify an agent program to be used for secret key operations. The

4012

4313

default value is the `/usr/local/bin/gpg-agent'. This is only used

4013

4314

as a fallback when the environment variable `GPG_AGENT_INFO' is not

4014

set or a running agent can't be connected.

4315

set or a running agent cannot be connected.

4015

4316

4016

4317

`--dirmngr-program FILE'

4017

4318

Specify a dirmngr program to be used for CRL checks. The default

4018

4319

value is `/usr/sbin/dirmngr'. This is only used as a fallback

4019

4320

when the environment variable `DIRMNGR_INFO' is not set or a

4020

running dirmngr can't be connected.

4321

running dirmngr cannot be connected.

4021

4322

4022

4323

`--prefer-system-dirmngr'

4023

4324

If a system wide `dirmngr' is running in daemon mode, first try to

4029

4330

Entirely disable the use of the Dirmngr.

4030

4331

4031

4332

`--no-secmem-warning'

4032

Don't print a warning when the so called "secure memory" can't be

4033

used.

4333

Do not print a warning when the so called "secure memory" cannot

4334

be used.

4034

4335

4035

4336

`--log-file FILE'

4036

4337

When running in server mode, append all logging output to FILE.

4060

4361

certificates voluntary without the need of putting all ever issued

4061

4362

certificates into a CRL. The disable option may be used to switch

4062

4363

this extra check off. Due to the caching done by the Dirmngr,

4063

there won't be any noticeable performance gain. Note, that this

4064

also disables possible OCSP checks for trusted root certificates.

4065

A more specific way of disabling this check is by adding the

4066

"relax" keyword to the root CA line of the `trustlist.txt'

4364

there will not be any noticeable performance gain. Note, that

4365

this also disables possible OCSP checks for trusted root

4366

certificates. A more specific way of disabling this check is by

4367

adding the "relax" keyword to the root CA line of the

4368

`trustlist.txt'

4067

4369

4068

4370

`--force-crl-refresh'

4069

4371

Tell the dirmngr to reload the CRL for each request. For better

4077

4379

4078

4380

`--enable-ocsp'

4079

4381

`--disable-ocsp'

4080

Be default OCSP checks are disabled. The enable option may be

4382

By default OCSP checks are disabled. The enable option may be

4081

4383

used to enable OCSP checks via Dirmngr. If CRL checks are also

4082

4384

enabled, CRLs will be used as a fallback if for some reason an

4083

OCSP request won't succeed. Note, that you have to allow OCSP

4084

requests in Dirmngr's configuration too (option `--allow-ocsp' and

4085

configure dirmngr properly. If you don't do so you will get the

4086

error code `Not supported'.

4385

OCSP request will not succeed. Note, that you have to allow OCSP

4386

requests in Dirmngr's configuration too (option `--allow-ocsp')

4387

and configure Dirmngr properly. If you do not do so you will get

4388

the error code `Not supported'.

4087

4389

4088

4390

`--auto-issuer-key-retrieve'

4089

4391

If a required certificate is missing while validating the chain of

4098

4400

4099

4401

`--validation-model NAME'

4100

4402

This option changes the default validation model. The only

4101

possible values are "shell" (which is the default) and "chain"

4102

which forces the use of the chain model. The chain model is also

4103

used if an option in the `trustlist.txt' or an attribute of the

4104

certificate requests it. However the standard model (shell) is in

4105

that case always tried first.

4403

possible values are "shell" (which is the default), "chain" which

4404

forces the use of the chain model and "steed" for a new simplified

4405

model. The chain model is also used if an option in the

4406

`trustlist.txt' or an attribute of the certificate requests it.

4407

However the standard model (shell) is in that case always tried

4408

first.

4106

4409

4107

4410

`--ignore-cert-extension OID'

4108

4411

Add OID to the list of ignored certificate extensions. The OID is

4109

4412

expected to be in dotted decimal form, like `2.5.29.3'. This

4110

4413

option may be used more than once. Critical flagged certificate

4111

4414

extensions matching one of the OIDs in the list are treated as if

4112

they are actually handled and thus the certificate won't be

4415

they are actually handled and thus the certificate will not be

4113

4416

rejected due to an unknown critical extension. Use this option

4114

4417

with care because extensions are usually flagged as critical for a

4115

4418

reason.

4143

4446

PKCS#12 files. This option may be used to force the passphrase to

4144

4447

be encoded in the specified encoding NAME. This is useful if the

4145

4448

application used to import the key uses a different encoding and

4146

thus won't be able to import a file generated by `gpgsm'. Commonly

4147

used values for NAME are `Latin1' and `CP850'. Note that `gpgsm'

4148

itself automagically imports any file with a passphrase encoded to

4149

the most commonly used encodings.

4449

thus will not be able to import a file generated by `gpgsm'.

4450

Commonly used values for NAME are `Latin1' and `CP850'. Note that

4451

`gpgsm' itself automagically imports any file with a passphrase

4452

encoded to the most commonly used encodings.

4150

4453

4151

4454

`--default-key USER_ID'

4152

4455

Use USER_ID as the standard key for signing. This key is used if

4223

4526

4224

4527

File: gnupg.info, Node: Esoteric Options, Prev: CMS Options, Up: GPGSM Options

4225

4528

4226

4.2.5 Doing things one usually don't want to do.

4227

------------------------------------------------

4529

4.2.5 Doing things one usually do not want to do.

4530

-------------------------------------------------

4228

4531

4229

4532

`--extra-digest-algo NAME'

4230

4533

Sometimes signatures are broken in that they announce a different

4430

4733

a newly created `pubring.kbx'. An administrator may replace this

4431

4734

file with a custom one. The format is a concatenation of PEM

4432

4735

encoded X.509 certificates. This global file is installed in the

4433

data directory (e.g. `/usr/share/gnupg/qualified.txt').

4736

data directory (e.g. `/usr/share/gnupg/com-certs.pem').

4434

4737

4435

4738

4436

4739

Note that on larger installations, it is useful to put predefined

4485

4788

* Menu:

4486

4789

4487

4790

* Automated signature checking:: Automated signature checking.

4791

* CSR and certificate creation:: CSR and certificate creation.

4488

4792

4489

4793

4490

4794

File: gnupg.info, Node: Automated signature checking, Up: Unattended Usage

4526

4830

``GOODSIG', `VALIDSIG' `TRUST_NEVER''

4527

4831

4528

4832

Error verifying a signature

4529

For some reason the signature could not be verified, i.e. it can't

4530

be decided whether the signature is valid or invalid. A common

4531

reason for this is a missing certificate.

4833

For some reason the signature could not be verified, i.e. it

4834

cannot be decided whether the signature is valid or invalid. A

4835

common reason for this is a missing certificate.

4836

4837

4838

4839

File: gnupg.info, Node: CSR and certificate creation, Up: Unattended Usage

4840

4841

4.7 CSR and certificate creation

4842

================================

4843

4844

*Please notice*: The immediate creation of certificates is only

4845

supported by GnuPG version 2.1 or later. With a 2.0 version you may

4846

only create a CSR.

4847

4848

The command `--gen-key' may be used along with the option `--batch' to

4849

either create a certificate signing request (CSR) or an X.509

4850

certificate. The is controlled by a parameter file; the format of this

4851

file is as follows:

4852

4853

* Text only, line length is limited to about 1000 characters.

4854

4855

* UTF-8 encoding must be used to specify non-ASCII characters.

4856

4857

* Empty lines are ignored.

4858

4859

* Leading and trailing while space is ignored.

4860

4861

* A hash sign as the first non white space character indicates a

4862

comment line.

4863

4864

* Control statements are indicated by a leading percent sign, the

4865

arguments are separated by white space from the keyword.

4866

4867

* Parameters are specified by a keyword, followed by a colon.

4868

Arguments are separated by white space.

4869

4870

* The first parameter must be `Key-Type', control statements may be

4871

placed anywhere.

4872

4873

* The order of the parameters does not matter except for `Key-Type'

4874

which must be the first parameter. The parameters are only used

4875

for the generated CSR/certificate; parameters from previous sets

4876

are not used. Some syntactically checks may be performed.

4877

4878

* Key generation takes place when either the end of the parameter

4879

file is reached, the next `Key-Type' parameter is encountered or

4880

at the control statement `%commit' is encountered.

4881

4882

Control statements:

4883

4884

%echo TEXT

4885

Print TEXT as diagnostic.

4886

4887

%dry-run

4888

Suppress actual key generation (useful for syntax checking).

4889

4890

%commit

4891

Perform the key generation. Note that an implicit commit is done

4892

at the next Key-Type parameter.

4893

4894

4895

General Parameters:

4896

4897

Key-Type: ALGO

4898

Starts a new parameter block by giving the type of the primary

4899

key. The algorithm must be capable of signing. This is a required

4900

parameter. The only supported value for ALGO is `rsa'.

4901

4902

Key-Length: NBITS

4903

The requested length of a generated key in bits. Defaults to 2048.

4904

4905

Key-Grip: HEXSTRING

4906

This is optional and used to generate a CSR or certificatet for an

4907

already existing key. Key-Length will be ignored when given.

4908

4909

Key-Usage: USAGE-LIST

4910

Space or comma delimited list of key usage, allowed values are

4911

`encrypt', `sign' and `cert'. This is used to generate the

4912

keyUsage extension. Please make sure that the algorithm is

4913

capable of this usage. Default is to allow encrypt and sign.

4914

4915

Name-DN: SUBJECT-NAME

4916

This is the Distinguished Name (DN) of the subject in RFC-2253

4917

format.

4918

4919

Name-Email: STRING

4920

This is an email address for the altSubjectName. This parameter is

4921

optional but may occur several times to add several email

4922

addresses to a certificate.

4923

4924

Name-DNS: STRING

4925

The is an DNS name for the altSubjectName. This parameter is

4926

optional but may occur several times to add several DNS names to a

4927

certificate.

4928

4929

Name-URI: STRING

4930

This is an URI for the altSubjectName. This parameter is optional

4931

but may occur several times to add several URIs to a certificate.

4932

4933

Additional parameters used to create a certificate (in contrast to a

4934

certificate signing request):

4935

4936

Serial: SN

4937

If this parameter is given an X.509 certificate will be generated.

4938

SN is expected to be a hex string representing an unsigned integer

4939

of arbitary length. The special value `random' can be used to

4940

create a 64 bit random serial number.

4941

4942

Issuer-DN: ISSUER-NAME

4943

This is the DN name of the issuer in rfc2253 format. If it is not

4944

set it will default to the subject DN and a special GnuPG

4945

extension will be included in the certificate to mark it as a

4946

standalone certificate.

4947

4948

Creation-Date: ISO-DATE

4949

Not-Before: ISO-DATE

4950

Set the notBefore date of the certificate. Either a date like

4951

`1986-04-26' or `1986-04-26 12:00' or a standard ISO timestamp

4952

like `19860426T042640' may be used. The time is considered to be

4953

UTC. If it is not given the current date is used.

4954

4955

Expire-Date: ISO-DATE

4956

Not-After: ISO-DATE

4957

Set the notAfter date of the certificate. Either a date like

4958

`2063-04-05' or `2063-04-05 17:00' or a standard ISO timestamp

4959

like `20630405T170000' may be used. The time is considered to be

4960

UTC. If it is not given a default value in the not too far future

4961

is used.

4962

4963

Signing-Key: KEYGRIP

4964

This gives the keygrip of the key used to sign the certificate.

4965

If it is not given a self-signed certificate will be created. For

4966

compatibility with future versions, it is suggested to prefix the

4967

keygrip with a `&'.

4968

4969

Hash-Algo: HASH-ALGO

4970

Use HASH-ALGO for this CSR or certificate. The supported hash

4971

algorithms are: `sha1', `sha256', `sha384' and `sha512'; they may

4972

also be specified with uppercase letters. The default is `sha1'.

4532

4973

4533

4974

4534

4975

4535

4976

File: gnupg.info, Node: GPGSM Protocol, Prev: Unattended Usage, Up: Invoking GPGSM

4536

4977

4537

4.7 The Protocol the Server Mode Uses.

4978

4.8 The Protocol the Server Mode Uses.

4538

4979

======================================

4539

4980

4540

4981

Description of the protocol used to access `GPGSM'. `GPGSM' does

4564

5005

4565

5006

File: gnupg.info, Node: GPGSM ENCRYPT, Next: GPGSM DECRYPT, Up: GPGSM Protocol

4566

5007

4567

4.7.1 Encrypting a Message

5008

4.8.1 Encrypting a Message

4568

5009

--------------------------

4569

5010

4570

5011

Before encryption can be done the recipient must be set using the

4576

5017

representation of the key; the server may accept any other way of

4577

5018

specification. If this is a valid and trusted recipient the server

4578

5019

does respond with OK, otherwise the return is an ERR with the reason why

4579

the recipient can't be used, the encryption will then not be done for

5020

the recipient cannot be used, the encryption will then not be done for

4580

5021

this recipient. If the policy is not to encrypt at all if not all

4581

5022

recipients are valid, the client has to take care of this. All

4582

5023

`RECIPIENT' commands are cumulative until a `RESET' or an successful

4616

5057

ciphertext to the file descriptor set with the `OUTPUT' command, take

4617

5058

the recipients from all the recipients set so far. If this command

4618

5059

fails the clients should try to delete all output currently done or

4619

otherwise mark it as invalid. `GPGSM' does ensure that there won't be

4620

any security problem with leftover data on the output in this case.

5060

otherwise mark it as invalid. `GPGSM' does ensure that there will not

5061

be any security problem with leftover data on the output in this case.

4621

5062

4622

5063

This command should in general not fail, as all necessary checks have

4623

5064

been done while setting the recipients. The input and output pipes are

4626

5067

4627

5068

File: gnupg.info, Node: GPGSM DECRYPT, Next: GPGSM SIGN, Prev: GPGSM ENCRYPT, Up: GPGSM Protocol

4628

5069

4629

4.7.2 Decrypting a message

5070

4.8.2 Decrypting a message

4630

5071

--------------------------

4631

5072

4632

5073

Input and output FDs are set the same way as in encryption, but `INPUT'

4648

5089

4649

5090

File: gnupg.info, Node: GPGSM SIGN, Next: GPGSM VERIFY, Prev: GPGSM DECRYPT, Up: GPGSM Protocol

4650

5091

4651

4.7.3 Signing a Message

5092

4.8.3 Signing a Message

4652

5093

-----------------------

4653

5094

4654

5095

Signing is usually done with these commands:

4677

5118

to the signer's key. USERID should be the internal representation

4678

5119

of the key; the server may accept any other way of specification. If

4679

5120

this is a valid and trusted recipient the server does respond with OK,

4680

otherwise the return is an ERR with the reason why the key can't be

5121

otherwise the return is an ERR with the reason why the key cannot be

4681

5122

used, the signature will then not be created using this key. If the

4682

5123

policy is not to sign at all if not all keys are valid, the client has

4683

5124

to take care of this. All `SIGNER' commands are cumulative until a

4687

5128

4688

5129

File: gnupg.info, Node: GPGSM VERIFY, Next: GPGSM GENKEY, Prev: GPGSM SIGN, Up: GPGSM Protocol

4689

5130

4690

4.7.4 Verifying a Message

5131

4.8.4 Verifying a Message

4691

5132

-------------------------

4692

5133

4693

5134

To verify a mesage the command:

4703

5144

4704

5145

File: gnupg.info, Node: GPGSM GENKEY, Next: GPGSM LISTKEYS, Prev: GPGSM VERIFY, Up: GPGSM Protocol

4705

5146

4706

4.7.5 Generating a Key

5147

4.8.5 Generating a Key

4707

5148

----------------------

4708

5149

4709

5150

This is used to generate a new keypair, store the secret part in the

4731

5172

4732

5173

File: gnupg.info, Node: GPGSM LISTKEYS, Next: GPGSM EXPORT, Prev: GPGSM GENKEY, Up: GPGSM Protocol

4733

5174

4734

4.7.6 List available keys

5175

4.8.6 List available keys

4735

5176

-------------------------

4736

5177

4737

5178

To list the keys in the internal database or using an external key

4770

5211

4771

5212

File: gnupg.info, Node: GPGSM EXPORT, Next: GPGSM IMPORT, Prev: GPGSM LISTKEYS, Up: GPGSM Protocol

4772

5213

4773

4.7.7 Export certificates

5214

4.8.7 Export certificates

4774

5215

-------------------------

4775

5216

4776

5217

To export certificate from the internal key database the command:

4794

5235

4795

5236

File: gnupg.info, Node: GPGSM IMPORT, Next: GPGSM DELETE, Prev: GPGSM EXPORT, Up: GPGSM Protocol

4796

5237

4797

4.7.8 Import certificates

5238

4.8.8 Import certificates

4798

5239

-------------------------

4799

5240

4800

5241

To import certificates into the internal key database, the command

4814

5255

4815

5256

File: gnupg.info, Node: GPGSM DELETE, Next: GPGSM GETINFO, Prev: GPGSM IMPORT, Up: GPGSM Protocol

4816

5257

4817

4.7.9 Delete certificates

5258

4.8.9 Delete certificates

4818

5259

-------------------------

4819

5260

4820

5261

To delete a certificate the command

4831

5272

4832

5273

File: gnupg.info, Node: GPGSM GETINFO, Prev: GPGSM DELETE, Up: GPGSM Protocol

4833

5274

4834

4.7.10 Return information about the process

5275

4.8.10 Return information about the process

4835

5276

-------------------------------------------

4836

5277

4837

5278

This is a multipurpose function to return a variety of information.

4995

5436

write hashed data to files named `dbgmd-000*'

4996

5437

4997

5438

`10 (1024)'

4998

trace Assuan protocol

5439

trace Assuan protocol. See also option

5440

`--debug-assuan-log-cats'.

4999

5441

5000

5442

`11 (2048)'

5001

5443

trace APDU I/O to the card. This may reveal sensitive data.

5002

5444

5445

`12 (4096)'

5446

trace some card reader related function calls.

5447

5003

5448

`--debug-all'

5004

5449

Same as `--debug=0xffffffff'

5005

5450

5026

5471

`--debug-log-tid'

5027

5472

This option appends a thread ID to the PID in the log output.

5028

5473

5474

`--debug-assuan-log-cats CATS'

5475

Changes the active Libassuan logging categories to CATS. The

5476

value for CATS is an unsigned integer given in usual C-Syntax. A

5477

value of of 0 switches to a default category. If this option is

5478

not used the categories are taken from the environment variable

5479

`ASSUAN_DEBUG'. Note that this option has only an effect if the

5480

Assuan debug flag has also been with the option `--debug'. For a

5481

list of categories see the Libassuan manual.

5482

5029

5483

`--no-detach'

5030

5484

Don't detach the process from the console. This is mainly useful

5031

5485

for debugging.

5112

5566

* DINSIG Card:: The DINSIG card application

5113

5567

* PKCS#15 Card:: The PKCS#15 card application

5114

5568

* Geldkarte Card:: The Geldkarte application

5569

* Undefined Card:: The Undefined stub application

5115

5570

5116

5571

5117

5572

File: gnupg.info, Node: OpenPGP Card, Next: NKS Card, Up: Card applications

5157

5612

`gpgsm'.

5158

5613

5159

5614

5160

File: gnupg.info, Node: Geldkarte Card, Prev: PKCS#15 Card, Up: Card applications

5615

File: gnupg.info, Node: Geldkarte Card, Next: Undefined Card, Prev: PKCS#15 Card, Up: Card applications

5161

5616

5162

5617

5.3.5 The Geldkarte card application "geldkarte"

5163

5618

------------------------------------------------

5167

5622

comes with almost all German banking cards.

5168

5623

5169

5624

5625

File: gnupg.info, Node: Undefined Card, Prev: Geldkarte Card, Up: Card applications

5626

5627

5.3.6 The Undefined card application "undefined"

5628

------------------------------------------------

5629

5630

This is a stub application to allow the use of the APDU command even if

5631

no supported application is found on the card. This application is not

5632

used automatically but must be explicitly requested using the SERIALNO

5633

command.

5634

5635

5170

5636

File: gnupg.info, Node: Scdaemon Configuration, Next: Scdaemon Examples, Prev: Card applications, Up: Invoking SCDAEMON

5171

5637

5172

5638

5.4 Configuration files

5902

6368

is given, check that file instead.

5903

6369

5904

6370

`--reload [COMPONENT]'

5905

Reload all or the given component. This is basically the sam as

6371

Reload all or the given component. This is basically the same as

5906

6372

sending a SIGHUP to the component. Components which don't support

5907

6373

reloading are ignored.

5908

6374

6375

`--kill [COMPONENT]'

6376

Kill the given component. Components which support killing are

6377

gpg-agent and scdaemon. Components which don't support reloading

6378

are ignored. Note that as of now reload and kill have the same

6379

effect for scdaemon.

6380

5909

6381

5910

6382

The following options may be used:

5911

6383

6832

7304

`/end'

6833

7305

These commands provide a way for executing loops. All lines

6834

7306

between the `while' and the corresponding `end' are executed as

6835

long as the evaluation of CONDITION yields a non-zero value. The

6836

evaluation is done by passing CONDITION to the `strtol' function.

6837

Example:

7307

long as the evaluation of CONDITION yields a non-zero value or is

7308

the string `true' or `yes'. The evaluation is done by passing

7309

CONDITION to the `strtol' function. Example:

6838

7310

6839

7311

/subst

6840

7312

/let i 3

6843

7315

/let i ${- $i 1}

6844

7316

/end

6845

7317

7318

`/if CONDITION'

7319

`/end'

7320

These commands provide a way for conditional execution. All lines

7321

between the `if' and the corresponding `end' are executed only if

7322

the evaluation of CONDITION yields a non-zero value or is the

7323

string `true' or `yes'. The evaluation is done by passing

7324

CONDITION to the `strtol' function.

7325

6846

7326

`/run FILE'

6847

7327

Run commands from FILE.

6848

7328

7270

7750

delete the file then. You may export the file again at any time as long

7271

7751

as it is available in GnuPG's private key database.

7272

7752

7273

7274

File: gnupg.info, Node: System Notes, Next: Debugging, Prev: Howtos, Up: Top

7275

7276

9 Notes pertaining to certain OSes.

7277

***********************************

7278

7279

GnuPG has been developed on GNU/Linux systems and is know to work on

7280

almost all Free OSes. All modern POSIX systems should be supported

7281

right now, however there are probably a lot of smaller glitches we need

7282

to fix first. The major problem areas are:

7283

7284

* For logging to sockets and other internal operations the

7285

`fopencookie' function (`funopen' under *BSD) is used. This is a

7286

very convenient function which makes it possible to create outputs

7287

in a structures and easy maintainable way. The drawback however

7288

is that most proprietary OSes don't support this function. At

7289

g10 Code we have looked into several ways on how to overcome this

7290

limitation but no sufficiently easy and maintainable way has been

7291

found. Porting _glibc_ to a general POSIX system is of course an

7292

option and would make writing portable software much easier; this

7293

it has not yet been done and the system administrator would need

7294

to cope with the GNU specific admin things in addition to the

7295

generic ones of his system.

7296

7297

We have now settled to use explicit stdio wrappers with a

7298

functionality similar to funopen. Although the code for this has

7299

already been written (_libestream_), we have not yet changed GnuPG

7300

to use it.

7301

7302

This means that on systems not supporting either `funopen' or

7303

`fopencookie', logging to a socket won't work, prompts are not

7304

formatted as pretty as they should be and `gpgsm''s `LISTKEYS'

7305

Assuan command does not work.

7306

7307

* We are planning to use file descriptor passing for interprocess

7308

communication. This will allow us save a lot of resources and

7309

improve performance of certain operations a lot. Systems not

7310

supporting this won't gain these benefits but we try to keep them

7311

working the standard way as it is done today.

7312

7313

* We require more or less full POSIX compatibility. This has been

7314

around for 15 years now and thus we don't believe it makes sense to

7315

support non POSIX systems anymore. Well, we of course the usual

7316

workarounds for near POSIX systems well be applied.

7317

7318

There is one exception of this rule: Systems based the Microsoft

7319

Windows API (called here _W32_) will be supported to some extend.

7320

7321

7322

* Menu:

7323

7324

* W32 Notes:: Microsoft Windows Notes

7325

7326

7327

File: gnupg.info, Node: W32 Notes, Up: System Notes

7328

7329

9.1 Microsoft Windows Notes

7330

===========================

7331

7332

Current limitations are:

7333

7334

* `gpgconf' does not create backup files, so in case of trouble your

7335

configuration file might get lost.

7336

7337

* `watchgnupg' is not available. Logging to sockets is not possible.

7338

7339

* The periodical smartcard status checking done by `scdaemon' is not

7340

yet supported.

7341

7342

7343

7344

File: gnupg.info, Node: Debugging, Next: Copying, Prev: System Notes, Up: Top

7345

7346

10 How to solve problems

7347

************************

7348

7349

Everyone knows that software often does not do what it should do and

7350

thus there is a need to track down problems. We call this debugging in

7351

a reminiscent to the moth jamming a relay in a Mark II box back in 1947.

7352

7353

Most of the problems a merely configuration and user problems but

7354

nevertheless there are the most annoying ones and responsible for many

7355

gray hairs. We try to give some guidelines here on how to identify and

7356

solve the problem at hand.

7357

7358

* Menu:

7359

7360

* Debugging Tools:: Description of some useful tools.

7361

* Debugging Hints:: Various hints on debugging.

7362

* Common Problems:: Commonly seen problems.

7363

* Architecture Details:: How the whole thing works internally.

7364

7365

7366

File: gnupg.info, Node: Debugging Tools, Next: Debugging Hints, Up: Debugging

7367

7368

10.1 Debugging Tools

7369

====================

7370

7371

The GnuPG distribution comes with a couple of tools, useful to help find

7372

and solving problems.

7373

7374

* Menu:

7375

7376

* kbxutil:: Scrutinizing a keybox file.

7377

7378

7379

File: gnupg.info, Node: kbxutil, Up: Debugging Tools

7380

7381

10.1.1 Scrutinizing a keybox file

7382

---------------------------------

7383

7384

A keybox is a file format used to store public keys along with meta

7385

information and indices. The commonly used one is the file

7386

`pubring.kbx' in the `.gnupg' directory. It contains all X.509

7387

certificates as well as OpenPGP keys(1) .

7388

7389

When called the standard way, e.g.:

7390

7391

`kbxutil ~/.gnupg/pubring.kbx'

7392

7393

it lists all records (called blobs) with there meta-information in a

7394

human readable format.

7395

7396

To see statistics on the keybox in question, run it using

7397

7398

`kbxutil --stats ~/.gnupg/pubring.kbx'

7399

7400

and you get an output like:

7401

7402

Total number of blobs: 99

7403

header: 1

7404

empty: 0

7405

openpgp: 0

7406

x509: 98

7407

non flagged: 81

7408

secret flagged: 0

7409

ephemeral flagged: 17

7410

7411

In this example you see that the keybox does not have any OpenPGP

7412

keys but contains 98 X.509 certificates and a total of 17 keys or

7413

certificates are flagged as ephemeral, meaning that they are only

7414

temporary stored (cached) in the keybox and won't get listed using the

7415

usual commands provided by `gpgsm' or `gpg'. 81 certificates are stored

7416

in a standard way and directly available from `gpgsm'.

7417

7418

To find duplicated certificates and keyblocks in a keybox file (this

7419

should not occur but sometimes things go wrong), run it using

7420

7421

`kbxutil --find-dups ~/.gnupg/pubring.kbx'

7422

7423

---------- Footnotes ----------

7424

7425

(1) Well, OpenPGP keys are not implemented, `gpg' still used the

7426

keyring file `pubring.gpg'

7427

7428

7429

File: gnupg.info, Node: Debugging Hints, Next: Common Problems, Prev: Debugging Tools, Up: Debugging

7430

7431

10.2 Various hints on debugging.

7432

================================

7433

7434

* How to find the IP address of a keyserver

7435

7436

If a round robin URL of is used for a keyserver (e.g.

7437

subkeys.gnupg.org); it is not easy to see what server is actually

7438

used. Using the keyserver debug option as in

7439

7440

gpg --keyserver-options debug=1 -v --refresh-key 1E42B367

7441

7442

is thus often helpful. Note that the actual output depends on the

7443

backend and may change from release to release.

7444

7445

7446

7447

File: gnupg.info, Node: Common Problems, Next: Architecture Details, Prev: Debugging Hints, Up: Debugging

7448

7449

10.3 Commonly Seen Problems

7450

===========================

7451

7452

* Error code `Not supported' from Dirmngr

7453

7454

Most likely the option `enable-ocsp' is active for gpgsm but

7455

Dirmngr's OCSP feature has not been enabled using `allow-ocsp' in

7456

`dirmngr.conf'.

7457

7458

* The Curses based Pinentry does not work

7459

7460

The far most common reason for this is that the environment

7461

variable `GPG_TTY' has not been set correctly. Make sure that it

7462

has been set to a real tty devce and not just to `/dev/tty'; i.e.

7463

`GPG_TTY=tty' is plainly wrong; what you want is `GPG_TTY=`tty`'

7464

-- note the back ticks. Also make sure that this environment

7465

variable gets exported, that is you should follow up the setting

7466

with an `export GPG_TTY' (assuming a Bourne style shell). Even for

7467

GUI based Pinentries; you should have set `GPG_TTY'. See the

7468

section on installing the `gpg-agent' on how to do it.

7469

7470

* SSH hangs while a popping up pinentry was expected

7471

7472

SSH has no way to tell the gpg-agent what terminal or X display it

7473

is running on. So when remotely logging into a box where a

7474

gpg-agent with SSH support is running, the pinentry will get

7475

popped up on whatever display the gpg-agent has been started. To

7476

solve this problem you may issue the command

7477

7478

echo UPDATESTARTUPTTY | gpg-connect-agent

7479

7480

and the next pinentry will pop up on your display or screen.

7481

However, you need to kill the running pinentry first because only

7482

one pinentry may be running at once. If you plan to use ssh on a

7483

new display you should issue the above command before invoking ssh

7484

or any other service making use of ssh.

7485

7486

* Exporting a secret key without a certificate

7487

7488

I may happen that you have created a certificate request using

7489

`gpgsm' but not yet received and imported the certificate from the

7490

CA. However, you want to export the secret key to another machine

7491

right now to import the certificate over there then. You can do

7492

this with a little trick but it requires that you know the

7493

approximate time you created the signing request. By running the

7494

command

7495

7496

ls -ltr ~/.gnupg/private-keys-v1.d

7497

7498

you get a listing of all private keys under control of `gpg-agent'.

7499

Pick the key which best matches the creation time and run the

7500

command

7501

7502

/usr/local/libexec/gpg-protect-tool --p12-export ~/.gnupg/private-keys-v1.d/FOO >FOO.p12

7503

7504

(Please adjust the path to `gpg-protect-tool' to the appropriate

7505

location). FOO is the name of the key file you picked (it should

7506

have the suffix `.key'). A Pinentry box will pop up and ask you

7507

for the current passphrase of the key and a new passphrase to

7508

protect it in the pkcs#12 file.

7509

7510

To import the created file on the machine you use this command:

7511

7512

/usr/local/libexec/gpg-protect-tool --p12-import --store FOO.p12

7513

7514

You will be asked for the pkcs#12 passphrase and a new passphrase

7515

to protect the imported private key at its new location.

7516

7517

Note that there is no easy way to match existing certificates with

7518

stored private keys because some private keys are used for Secure

7519

Shell or other purposes and don't have a corresponding certificate.

7520

7521

* A root certificate does not verify

7522

7523

A common problem is that the root certificate misses the required

7524

basicConstraints attribute and thus `gpgsm' rejects this

7525

certificate. An error message indicating "no value" is a sign for

7526

such a certificate. You may use the `relax' flag in

7527

`trustlist.txt' to accept the certificate anyway. Note that the

7528

fingerprint and this flag may only be added manually to

7529

`trustlist.txt'.

7530

7531

* Error message: "digest algorithm N has not been enabled"

7532

7533

The signature is broken. You may try the option

7534

`--extra-digest-algo SHA256' to workaround the problem. The

7535

number N is the internal algorithm identifier; for example 8

7536

refers to SHA-256.

7537

7538

* The Windows version does not work under Wine

7539

7540

When running the W32 version of `gpg' under Wine you may get an

7541

error messages like:

7542

7543

gpg: fatal: WriteConsole failed: Access denied

7544

7545

The solution is to use the command `wineconsole'.

7546

7547

Some operations like gen-key really want to talk to the console

7548

directly for increased security (for example to prevent the

7549

passphrase from appearing on the screen). So, you should use

7550

`wineconsole' instead of `wine', which will launch a windows

7551

console that implements those additional features.

7552

7553

* Why does GPG's -search-key list weird keys?

7554

7555

For performance reasons the keyservers do not check the keys the

7556

same way `gpg' does. It may happen that the listing of keys

7557

available on the keyservers shows keys with wrong user IDs or with

7558

user Ids from other keys. If you try to import this key, the bad

7559

keys or bad user ids won't get imported, though. This is a bit

7560

unfortunate but we can't do anything about it without actually

7561

downloading the keys.

7562

7563

7564

7565

File: gnupg.info, Node: Architecture Details, Prev: Common Problems, Up: Debugging

7566

7567

10.4 How the whole thing works internally.

7568

==========================================

7569

7570

* Menu:

7571

7572

* GnuPG-1 and GnuPG-2:: Relationship between the two branches.

7573

7574

7575

File: gnupg.info, Node: GnuPG-1 and GnuPG-2, Up: Architecture Details

7576

7577

10.4.1 Relationship between the two branches.

7578

---------------------------------------------

7579

7580

Here is a little picture showing how the components work together:

7581

7582

[image src="gnupg-card-architecture.png"]

7583

7584

Lets try to explain it:

7585

7586

TO BE DONE.

7587