1GPGSM(1)                     GNU Privacy Guard 2.2                    GPGSM(1)
2
3
4

NAME

6       gpgsm - CMS encryption and signing tool
7

SYNOPSIS

9       gpgsm [--homedir dir] [--options file] [options] command [args]
10
11
12

DESCRIPTION

14       gpgsm  is a tool similar to gpg to provide digital encryption and sign‐
15       ing services on X.509 certificates and the CMS protocol.  It is  mainly
16       used  as  a  backend for S/MIME mail processing.  gpgsm includes a full
17       featured certificate management and complies with all rules defined for
18       the German Sphinx project.
19
20
21
22
23

COMMANDS

25       Commands  are  not  distinguished from options except for the fact that
26       only one command is allowed.
27
28
29
30
31
32   Commands not specific to the function
33
34
35
36       --version
37              Print the program version and licensing information.  Note  that
38              you cannot abbreviate this command.
39
40
41       --help, -h
42              Print  a  usage message summarizing the most useful command-line
43              options.  Note that you cannot abbreviate this command.
44
45
46       --warranty
47              Print warranty information.  Note  that  you  cannot  abbreviate
48              this command.
49
50
51       --dump-options
52              Print  a  list of all available options and commands.  Note that
53              you cannot abbreviate this command.
54
55   Commands to select the type of operation
56
57
58
59       --encrypt
60              Perform an encryption.  The keys the data is encrypted  to  must
61              be set using the option --recipient.
62
63
64       --decrypt
65              Perform  a decryption; the type of input is automatically deter‐
66              mined.  It may either be in binary form or  PEM  encoded;  auto‐
67              matic determination of base-64 encoding is not done.
68
69
70       --sign Create a digital signature.  The key used is either the fist one
71              found in the keybox or those set with the --local-user option.
72
73
74       --verify
75              Check a signature file for validity.  Depending on the arguments
76              a detached signature may also be checked.
77
78
79       --server
80              Run in server mode and wait for commands on the stdin.
81
82
83       --call-dirmngr command [args]
84              Behave  as a Dirmngr client issuing the request command with the
85              optional list of args.  The output of  the  Dirmngr  is  printed
86              stdout.   Please  note that file names given as arguments should
87              have an absolute file name (i.e. commencing with /) because they
88              are  passed verbatim to the Dirmngr and the working directory of
89              the Dirmngr might not be the same as the  one  of  this  client.
90              Currently it is not possible to pass data via stdin to the Dirm‐
91              ngr.  command should not contain spaces.
92
93              This is command is required for certain maintaining tasks of the
94              dirmngr where a dirmngr must be able to call back to gpgsm.  See
95              the Dirmngr manual for details.
96
97
98       --call-protect-tool arguments
99              Certain maintenance operations are done by an  external  program
100              call gpg-protect-tool; this is usually not installed in a direc‐
101              tory listed in the PATH variable.  This command provides a  sim‐
102              ple  wrapper to access this tool.  arguments are passed verbatim
103              to this command; use '--help' to get a list of supported  opera‐
104              tions.
105
106
107
108   How to manage the certificates and keys
109
110
111
112       --generate-key
113       --gen-key
114              This  command  allows  the  creation  of  a  certificate signing
115              request or a self-signed certificate.  It is commonly used along
116              with  the --output option to save the created CSR or certificate
117              into a file.  If used with the --batch a parameter file is  used
118              to  create  the CSR or certificate and it is further possible to
119              create non-self-signed certificates.
120
121
122       --list-keys
123       -k     List all available certificates stored in the  local  key  data‐
124              base.   Note  that  the  displayed data might be reformatted for
125              better human readability and illegal characters are replaced  by
126              safe substitutes.
127
128
129       --list-secret-keys
130       -K     List  all  available  certificates  for  which a corresponding a
131              secret key is available.
132
133
134       --list-external-keys pattern
135              List certificates matching pattern  using  an  external  server.
136              This utilizes the dirmngr service.
137
138
139       --list-chain
140              Same  as  --list-keys  but  also  prints  all keys making up the
141              chain.
142
143
144
145       --dump-cert
146       --dump-keys
147              List all available certificates stored in the local key database
148              using a format useful mainly for debugging.
149
150
151       --dump-chain
152              Same  as  --dump-keys  but  also  prints  all keys making up the
153              chain.
154
155
156       --dump-secret-keys
157              List all available certificates  for  which  a  corresponding  a
158              secret  key is available using a format useful mainly for debug‐
159              ging.
160
161
162       --dump-external-keys pattern
163              List certificates matching pattern  using  an  external  server.
164              This  utilizes  the  dirmngr  service.   It uses a format useful
165              mainly for debugging.
166
167
168       --keydb-clear-some-cert-flags
169              This is a debugging aid to reset certain flags in the key  data‐
170              base  which  are used to cache certain certificate stati.  It is
171              especially useful if a bad CRL or a weird running OCSP responder
172              did accidentally revoke certificate.  There is no security issue
173              with this command because gpgsm always make sure that the valid‐
174              ity of a certificate is checked right before it is used.
175
176
177       --delete-keys pattern
178              Delete the keys matching pattern.  Note that there is no command
179              to delete the secret part of the key directly.  In case you need
180              to  do this, you should run the command gpgsm --dump-secret-keys
181              KEYID before you delete the key, copy the string  of  hex-digits
182              in  the ``keygrip'' line and delete the file consisting of these
183              hex-digits and the  suffix  .key  from  the  ‘private-keys-v1.d
184              directory below our GnuPG home directory (usually ‘~/.gnupg’).
185
186
187       --export [pattern]
188              Export  all certificates stored in the Keybox or those specified
189              by the optional pattern. Those pattern consist of a list of user
190              ids (see: [how-to-specify-a-user-id]).  When used along with the
191              --armor option a few informational lines  are  prepended  before
192              each  block.   There  is one limitation: As there is no commonly
193              agreed upon way to pack more than one certificate into an  ASN.1
194              structure,  the  binary  export (i.e. without using armor) works
195              only for the export of one certificate.  Thus it is required  to
196              specify   a   pattern  which  yields  exactly  one  certificate.
197              Ephemeral certificate are only exported if all pattern are given
198              as fingerprints or keygrips.
199
200
201       --export-secret-key-p12 key-id
202              Export  the private key and the certificate identified by key-id
203              using the PKCS#12 format.  When used with the --armor  option  a
204              few informational lines are prepended to the output.  Note, that
205              the PKCS#12 format is not very secure and proper transport secu‐
206              rity  should  be used to convey the exported key.  (See: [option
207              --p12-charset].)
208
209
210       --export-secret-key-p8 key-id
211       --export-secret-key-raw key-id
212              Export the private key of the certificate identified  by  key-id
213              with  any  encryption  stripped.  The ...-raw command exports in
214              PKCS#1 format; the ...-p8  command  exports  in  PKCS#8  format.
215              When  used with the --armor option a few informational lines are
216              prepended to the output.  These commands are useful to prepare a
217              key for use on a TLS server.
218
219
220       --import [files]
221              Import  the certificates from the PEM or binary encoded files as
222              well as from signed-only messages.  This  command  may  also  be
223              used to import a secret key from a PKCS#12 file.
224
225
226       --learn-card
227              Read  information  about the private keys from the smartcard and
228              import the certificates from there.  This command  utilizes  the
229              gpg-agent and in turn the scdaemon.
230
231
232       --change-passphrase user_id
233       --passwd user_id
234              Change  the  passphrase of the private key belonging to the cer‐
235              tificate  specified  as  user_id.   Note,  that   changing   the
236              passphrase/PIN of a smartcard is not yet supported.
237
238

OPTIONS

240       GPGSM features a bunch of options to control the exact behaviour and to
241       change the default configuration.
242
243
244
245
246
247   How to change the configuration
248
249
250       These options are used to change  the  configuration  and  are  usually
251       found in the option file.
252
253
254
255
256       --options file
257              Reads  configuration  from file instead of from the default per-
258              user configuration file.   The  default  configuration  file  is
259              named  ‘gpgsm.conf’  and  expected  in  the  ‘.gnupg’  directory
260              directly below the home directory of the user.
261
262
263       --homedir dir
264              Set the name of the home directory to dir. If this option is not
265              used,  the  home  directory  defaults to ‘~/.gnupg’.  It is only
266              recognized when given on the command line.   It  also  overrides
267              any  home  directory  stated  through  the  environment variable
268GNUPGHOME’ or (on Windows systems) by  means  of  the  Registry
269              entry HKCU\Software\GNU\GnuPG:HomeDir.
270
271              On Windows systems it is possible to install GnuPG as a portable
272              application.  In this case only this command line option is con‐
273              sidered, all other ways to set a home directory are ignored.
274
275              To install GnuPG as a portable application under Windows, create
276              an empty file named ‘gpgconf.ctl’ in the same directory  as  the
277              tool  ‘gpgconf.exe’.   The root of the installation is then that
278              directory; or, if  ‘gpgconf.exe’  has  been  installed  directly
279              below  a  directory named ‘bin’, its parent directory.  You also
280              need to make sure that the following directories exist  and  are
281              writable:     ‘ROOT/home’     for    the    GnuPG    home    and
282ROOT/var/cache/gnupg’ for internal cache files.
283
284
285
286       -v
287
288       --verbose
289              Outputs additional information while running.  You can  increase
290              the  verbosity by giving several verbose commands to gpgsm, such
291              as '-vv'.
292
293
294       --policy-file filename
295              Change the default name of the policy file to filename.
296
297
298       --agent-program file
299              Specify an agent program to be used for secret  key  operations.
300              The  default value is determined by running the command gpgconf.
301              Note that the pipe symbol (|) is  used  for  a  regression  test
302              suite hack and may thus not be used in the file name.
303
304
305       --dirmngr-program file
306              Specify  a  dirmngr  program  to  be  used  for CRL checks.  The
307              default value is ‘/usr/bin/dirmngr’.
308
309
310       --prefer-system-dirmngr
311              This option is obsolete and ignored.
312
313
314       --disable-dirmngr
315              Entirely disable the use of the Dirmngr.
316
317
318       --no-autostart
319              Do not start the gpg-agent or the dirmngr if it has not yet been
320              started and its service is required.  This option is mostly use‐
321              ful on machines where the connection to gpg-agent has been redi‐
322              rected  to  another  machines.   If  dirmngr  is required on the
323              remote  machine,  it  may  be  started  manually  using  gpgconf
324              --launch dirmngr.
325
326
327       --no-secmem-warning
328              Do not print a warning when the so called "secure memory" cannot
329              be used.
330
331
332       --log-file file
333              When running in server mode, append all logging output to  file.
334              Use ‘socket://’ to log to socket.
335
336
337   Certificate related options
338
339
340
341
342       --enable-policy-checks
343       --disable-policy-checks
344              By default policy checks are enabled.  These options may be used
345              to change it.
346
347
348       --enable-crl-checks
349       --disable-crl-checks
350              By default the CRL checks are enabled and the DirMngr is used to
351              check for revoked certificates.  The disable option is most use‐
352              ful with an off-line network connection to suppress this check.
353
354
355       --enable-trusted-cert-crl-check
356       --disable-trusted-cert-crl-check
357              By default the CRL for trusted  root  certificates  are  checked
358              like for any other certificates.  This allows a CA to revoke its
359              own certificates voluntary without the need of putting all  ever
360              issued  certificates into a CRL.  The disable option may be used
361              to switch this extra check off.  Due to the caching done by  the
362              Dirmngr,  there  will  not  be  any noticeable performance gain.
363              Note, that this also disables possible OCSP checks  for  trusted
364              root  certificates.  A more specific way of disabling this check
365              is by adding the ``relax'' keyword to the root CA  line  of  the
366trustlist.txt
367
368
369
370       --force-crl-refresh
371              Tell the dirmngr to reload the CRL for each request.  For better
372              performance, the dirmngr will actually  optimize  this  by  sup‐
373              pressing the loading for short time intervals (e.g. 30 minutes).
374              This option is useful to make sure that a fresh CRL is available
375              for certificates hold in the keybox.  The suggested way of doing
376              this is by using it along with the option --with-validation  for
377              a key listing command.  This option should not be used in a con‐
378              figuration file.
379
380
381       --enable-ocsp
382       --disable-ocsp
383              By default OCSP checks are disabled.  The enable option  may  be
384              used  to enable OCSP checks via Dirmngr.  If CRL checks are also
385              enabled, CRLs will be used as a fallback if for some  reason  an
386              OCSP  request  will  not  succeed.  Note, that you have to allow
387              OCSP requests in Dirmngr's configuration  too  (option  --allow-
388              ocsp)  and  configure Dirmngr properly.  If you do not do so you
389              will get the error code 'Not supported'.
390
391
392       --auto-issuer-key-retrieve
393              If a required certificate is missing while validating the  chain
394              of  certificates,  try to load that certificate from an external
395              location.  This usually means that Dirmngr is employed to search
396              for  the  certificate.   Note that this option makes a "web bug"
397              like behavior possible.  LDAP server  operators  can  see  which
398              keys  you request, so by sending you a message signed by a brand
399              new key (which you naturally will not have on  your  local  key‐
400              box),  the  operator  can tell both your IP address and the time
401              when you verified the signature.
402
403
404
405
406       --validation-model name
407              This option changes the default validation model.  The only pos‐
408              sible  values  are "shell" (which is the default), "chain" which
409              forces the use of the chain model and "steed" for a new  simpli‐
410              fied  model.   The  chain model is also used if an option in the
411trustlist.txt’ or an attribute of the certificate requests  it.
412              However  the standard model (shell) is in that case always tried
413              first.
414
415
416       --ignore-cert-extension oid
417              Add oid to the list of ignored certificate extensions.  The  oid
418              is  expected  to be in dotted decimal form, like 2.5.29.3.  This
419              option may be used more than once.  Critical flagged certificate
420              extensions  matching  one of the OIDs in the list are treated as
421              if they are actually handled and thus the certificate  will  not
422              be  rejected  due  to  an  unknown critical extension.  Use this
423              option with care because extensions are usually flagged as crit‐
424              ical for a reason.
425
426
427   Input and Output
428
429
430
431       --armor
432       -a     Create PEM encoded output.  Default is binary output.
433
434
435       --base64
436              Create  Base-64  encoded  output;  i.e.  PEM  without the header
437              lines.
438
439
440       --assume-armor
441              Assume the input data is PEM encoded.  Default is to  autodetect
442              the encoding but this is may fail.
443
444
445       --assume-base64
446              Assume the input data is plain base-64 encoded.
447
448
449       --assume-binary
450              Assume the input data is binary encoded.
451
452
453
454       --p12-charset name
455              gpgsm  uses  the  UTF-8  encoding  when encoding passphrases for
456              PKCS#12 files.  This option may be used to force the  passphrase
457              to be encoded in the specified encoding name.  This is useful if
458              the application used to import the key uses a different encoding
459              and  thus  will not be able to import a file generated by gpgsm.
460              Commonly used values for name are Latin1 and CP850.   Note  that
461              gpgsm  itself  automagically  imports any file with a passphrase
462              encoded to the most commonly used encodings.
463
464
465
466       --default-key user_id
467              Use user_id as the standard key for signing.  This key  is  used
468              if  no  other key has been defined as a signing key.  Note, that
469              the first --local-users option also sets this key if it has  not
470              yet been set; however --default-key always overrides this.
471
472
473
474       --local-user user_id
475
476       -u user_id
477              Set  the  user(s)  to  be  used for signing.  The default is the
478              first secret key found in the database.
479
480
481
482       --recipient name
483       -r     Encrypt to the user id name.  There are several ways a  user  id
484              may be given (see: [how-to-specify-a-user-id]).
485
486
487
488       --output file
489       -o file
490              Write output to file.  The default is to write it to stdout.
491
492
493
494
495       --with-key-data
496              Displays extra information with the --list-keys commands.  Espe‐
497              cially a line tagged grp is printed which tells you the  keygrip
498              of  a  key.  This string is for example used as the file name of
499              the secret key.  Implies --with-colons.
500
501
502
503       --with-validation
504              When doing a key listing, do a full validation  check  for  each
505              key  and  print  the  result.   This is usually a slow operation
506              because it requires a CRL lookup and other operations.
507
508              When used along with --import, a validation of  the  certificate
509              to  import  is  done  and only imported if it succeeds the test.
510              Note that this does not affect an already available  certificate
511              in  the  DB.  This option is therefore useful to simply verify a
512              certificate.
513
514
515
516       --with-md5-fingerprint
517              For standard key listings, also print the MD5 fingerprint of the
518              certificate.
519
520
521       --with-keygrip
522              Include  the  keygrip  in  standard key listings.  Note that the
523              keygrip is always listed in --with-colons mode.
524
525
526       --with-secret
527              Include info about the presence of a secret key  in  public  key
528              listings done with --with-colons.
529
530
531   How to change how the CMS is created
532
533
534
535       --include-certs n
536              Using n of -2 includes all certificate except for the root cert,
537              -1 includes all certs, 0 does not include any certs, 1  includes
538              only  the  signers cert and all other positive values include up
539              to n certificates starting with the signer cert.  The default is
540              -2.
541
542
543       --cipher-algo oid
544              Use  the  cipher  algorithm with the ASN.1 object identifier oid
545              for encryption.  For  convenience  the  strings  3DES,  AES  and
546              AES256  may  be  used instead of their OIDs.  The default is AES
547              (2.16.840.1.101.3.4.1.2).
548
549
550       --digest-algo name
551              Use name as the message digest algorithm.   Usually  this  algo‐
552              rithm  is deduced from the respective signing certificate.  This
553              option forces the use of the given algorithm  and  may  lead  to
554              severe interoperability problems.
555
556
557   Doing things one usually do not want to do
558
559
560
561
562
563       --extra-digest-algo name
564              Sometimes  signatures are broken in that they announce a differ‐
565              ent digest algorithm than actually used.  gpgsm uses a  one-pass
566              data  processing  model  and thus needs to rely on the announced
567              digest algorithms to properly hash the data.   As  a  workaround
568              this  option  may  be  used  to tell gpgsm to also hash the data
569              using the algorithm name; this slows processing  down  a  little
570              bit but allows verification of such broken signatures.  If gpgsm
571              prints an error like ``digest algo 8 has not been enabled''  you
572              may want to try this option, with 'SHA256' for name.
573
574
575
576       --faked-system-time epoch
577              This  option is only useful for testing; it sets the system time
578              back or forth to epoch which is the number  of  seconds  elapsed
579              since the year 1970.  Alternatively epoch may be given as a full
580              ISO time string (e.g. "20070924T154812").
581
582
583       --with-ephemeral-keys
584              Include ephemeral flagged keys in the output  of  key  listings.
585              Note  that they are included anyway if the key specification for
586              a listing is given as fingerprint or keygrip.
587
588
589       --debug-level level
590              Select the debug level for investigating problems. level may  be
591              a numeric value or by a keyword:
592
593
594              none   No  debugging at all.  A value of less than 1 may be used
595                     instead of the keyword.
596
597              basic  Some basic debug messages.  A value between 1 and  2  may
598                     be used instead of the keyword.
599
600              advanced
601                     More verbose debug messages.  A value between 3 and 5 may
602                     be used instead of the keyword.
603
604              expert Even more detailed messages.  A value between 6 and 8 may
605                     be used instead of the keyword.
606
607              guru   All  of  the  debug messages you can get. A value greater
608                     than 8 may be used instead of the keyword.  The  creation
609                     of  hash  tracing files is only enabled if the keyword is
610                     used.
611
612       How these messages are mapped to the  actual  debugging  flags  is  not
613       specified  and may change with newer releases of this program. They are
614       however carefully selected to best aid in debugging.
615
616
617       --debug flags
618              This option is only useful for debugging and the  behaviour  may
619              change  at  any time without notice; using --debug-levels is the
620              preferred method to select the debug verbosity.  FLAGS  are  bit
621              encoded  and  may  be  given  in  usual  C-Syntax. The currently
622              defined bits are:
623
624
625              0 (1)  X.509 or OpenPGP protocol related data
626
627              1 (2)  values of big number integers
628
629              2 (4)  low level crypto operations
630
631              5 (32) memory allocation
632
633              6 (64) caching
634
635              7 (128)
636                     show memory statistics
637
638              9 (512)
639                     write hashed data to files named dbgmd-000*
640
641              10 (1024)
642                     trace Assuan protocol
643
644       Note, that all flags set  using  this  option  may  get  overridden  by
645       --debug-level.
646
647
648       --debug-all
649              Same as --debug=0xffffffff
650
651
652       --debug-allow-core-dump
653              Usually  gpgsm  tries to avoid dumping core by well written code
654              and by disabling core dumps for security reasons.  However, bugs
655              are  pretty  durable  beasts  and to squash them it is sometimes
656              useful to have a core dump.   This  option  enables  core  dumps
657              unless the Bad Thing happened before the option parsing.
658
659
660       --debug-no-chain-validation
661              This is actually not a debugging option but only useful as such.
662              It lets gpgsm bypass all certificate chain validation checks.
663
664
665       --debug-ignore-expiration
666              This is actually not a debugging option but only useful as such.
667              It  lets  gpgsm  ignore  all notAfter dates, this is used by the
668              regression tests.
669
670
671       --passphrase-fd n
672              Read the passphrase from file descriptor n. Only the first  line
673              will  be  read  from  file descriptor n. If you use 0 for n, the
674              passphrase will be read from STDIN. This can  only  be  used  if
675              only one passphrase is supplied.
676
677              Note that this passphrase is only used if the option --batch has
678              also been given.
679
680
681       --pinentry-mode mode
682              Set the pinentry mode to mode.  Allowed values for mode are:
683
684              default
685                     Use the default of the agent, which is ask.
686
687              ask    Force the use of the Pinentry.
688
689              cancel Emulate use of Pinentry's cancel button.
690
691              error  Return a Pinentry error (``No Pinentry'').
692
693              loopback
694                     Redirect Pinentry queries to the caller.   Note  that  in
695                     contrast to Pinentry the user is not prompted again if he
696                     enters a bad password.
697
698
699       --request-origin origin
700              Tell gpgsm to assume that the operation ultimately originated at
701              origin.   Depending  on  the  origin  certain  restrictions  are
702              applied and the Pinentry may include an extra note on  the  ori‐
703              gin.   Supported  values  for  origin  are:  local  which is the
704              default, remote to indicate a remote origin or  browser  for  an
705              operation requested by a web browser.
706
707
708       --no-common-certs-import
709              Suppress the import of common certificates on keybox creation.
710
711
712       All  the long options may also be given in the configuration file after
713       stripping off the two leading dashes.
714
715
716

HOW TO SPECIFY A USER ID

718       There are different ways to specify a user ID to GnuPG.  Some  of  them
719       are  only  valid  for  gpg others are only good for gpgsm.  Here is the
720       entire list of ways to specify a key:
721
722
723
724       By key Id.
725              This format is deduced from the length of  the  string  and  its
726              content or 0x prefix. The key Id of an X.509 certificate are the
727              low 64 bits of its SHA-1 fingerprint.  The use  of  key  Ids  is
728              just  a  shortcut,  for all automated processing the fingerprint
729              should be used.
730
731              When using gpg an exclamation mark (!) may be appended to  force
732              using  the specified primary or secondary key and not to try and
733              calculate which primary or secondary key to use.
734
735              The last four lines of the example give the key ID in their long
736              form as internally used by the OpenPGP protocol. You can see the
737              long key ID using the option --with-colons.
738
739         234567C4
740         0F34E556E
741         01347A56A
742         0xAB123456
743
744         234AABBCC34567C4
745         0F323456784E56EAB
746         01AB3FED1347A5612
747         0x234AABBCC34567C4
748
749
750
751
752       By fingerprint.
753              This format is deduced from the length of  the  string  and  its
754              content  or  the 0x prefix.  Note, that only the 20 byte version
755              fingerprint is available with gpgsm (i.e. the SHA-1 hash of  the
756              certificate).
757
758              When  using gpg an exclamation mark (!) may be appended to force
759              using the specified primary or secondary key and not to try  and
760              calculate which primary or secondary key to use.
761
762              The  best  way  to specify a key Id is by using the fingerprint.
763              This avoids any ambiguities in case that  there  are  duplicated
764              key IDs.
765
766         1234343434343434C434343434343434
767         123434343434343C3434343434343734349A3434
768         0E12343434343434343434EAB3484343434343434
769         0xE12343434343434343434EAB3484343434343434
770
771
772       gpgsm  also  accepts  colons  between  each  pair of hexadecimal digits
773       because this is the de-facto standard on how to present  X.509  finger‐
774       prints.   gpg  also allows the use of the space separated SHA-1 finger‐
775       print as printed by the key listing commands.
776
777
778       By exact match on OpenPGP user ID.
779              This is denoted by a leading equal sign. It does not make  sense
780              for X.509 certificates.
781
782         =Heinrich Heine <heinrichh@uni-duesseldorf.de>
783
784
785       By exact match on an email address.
786              This  is  indicated  by enclosing the email address in the usual
787              way with left and right angles.
788
789         <heinrichh@uni-duesseldorf.de>
790
791
792
793       By partial match on an email address.
794              This is indicated by prefixing the  search  string  with  an  @.
795              This uses a substring search but considers only the mail address
796              (i.e. inside the angle brackets).
797
798         @heinrichh
799
800
801       By exact match on the subject's DN.
802              This is indicated by a leading slash, directly followed  by  the
803              RFC-2253 encoded DN of the subject.  Note that you can't use the
804              string printed by gpgsm --list-keys because that  one  has  been
805              reordered and modified for better readability; use --with-colons
806              to print the raw (but standard escaped) RFC-2253 string.
807
808         /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
809
810
811       By exact match on the issuer's DN.
812              This is indicated by a leading hash mark, directly followed by a
813              slash  and  then directly followed by the RFC-2253 encoded DN of
814              the issuer.  This should return the Root  cert  of  the  issuer.
815              See note above.
816
817         #/CN=Root Cert,O=Poets,L=Paris,C=FR
818
819
820
821       By exact match on serial number and issuer's DN.
822              This  is  indicated  by a hash mark, followed by the hexadecimal
823              representation of the serial number, then followed  by  a  slash
824              and the RFC-2253 encoded DN of the issuer. See note above.
825
826         #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
827
828
829       By keygrip.
830              This  is indicated by an ampersand followed by the 40 hex digits
831              of a keygrip.  gpgsm prints the keygrip when using  the  command
832              --dump-cert.  It does not yet work for OpenPGP keys.
833
834         &D75F22C3F86E355877348498CDC92BD21010A480
835
836
837
838       By substring match.
839              This is the default mode but applications may want to explicitly
840              indicate this by putting the asterisk in front.   Match  is  not
841              case sensitive.
842
843         Heine
844         *Heine
845
846
847       . and + prefixes
848              These prefixes are reserved for looking up mails anchored at the
849              end and for a word search mode.  They are  not  yet  implemented
850              and using them is undefined.
851
852
853              Please  note  that we have reused the hash mark identifier which
854              was used in old GnuPG versions to indicate the so called  local-
855              id.  It is not anymore used and there should be no conflict when
856              used with X.509 stuff.
857
858              Using the RFC-2253 format of DNs has the drawback that it is not
859              possible  to  map them back to the original encoding, however we
860              don't have to do this  because  our  key  database  stores  this
861              encoding as meta data.
862
863
864
865
866
867

EXAMPLES

869         $ gpgsm -er goo@bar.net <plaintext >ciphertext
870
871
872
873

FILES

875       There  are  a  few  configuration  files  to control certain aspects of
876       gpgsm's operation. Unless noted, they are expected in the current  home
877       directory (see: [option --homedir]).
878
879
880
881       gpgsm.conf
882              This  is  the  standard  configuration  file  read  by  gpgsm on
883              startup.  It may contain any valid long option; the leading  two
884              dashes may not be entered and the option may not be abbreviated.
885              This default name may be  changed  on  the  command  line  (see:
886              [gpgsm-option --options]).  You should backup this file.
887
888
889
890       policies.txt
891              This  is  a  list of allowed CA policies.  This file should list
892              the object identifiers of the  policies  line  by  line.   Empty
893              lines and lines starting with a hash mark are ignored.  Policies
894              missing in this file and not marked as critical in the  certifi‐
895              cate  will  print  only  a  warning;  certificates with policies
896              marked as critical and not listed in this  file  will  fail  the
897              signature verification.  You should backup this file.
898
899              For example, to allow only the policy 2.289.9.9, the file should
900              look like this:
901
902                # Allowed policies
903                2.289.9.9
904
905
906       qualified.txt
907              This is the list of root certificates used  for  qualified  cer‐
908              tificates.  They are defined as certificates capable of creating
909              legally binding signatures in the same way as handwritten signa‐
910              tures  are.  Comments start with a hash mark and empty lines are
911              ignored.  Lines do have a length limit but this is not a serious
912              limitation  as the format of the entries is fixed and checked by
913              gpgsm: A non-comment line starts with optional whitespace,  fol‐
914              lowed by exactly 40 hex characters, white space and a lowercased
915              2 letter country code.  Additional  data  delimited  with  by  a
916              white  space is current ignored but might late be used for other
917              purposes.
918
919              Note that even if a certificate is listed  in  this  file,  this
920              does  not  mean  that the certificate is trusted; in general the
921              certificates listed in this file  need  to  be  listed  also  in
922trustlist.txt’.
923
924              This  is  a global file an installed in the data directory (e.g.
925/usr/share/gnupg/qualified.txt’).  GnuPG  installs  a  suitable
926              file  with root certificates as used in Germany.  As new Root-CA
927              certificates may be issued over time, these entries may need  to
928              be  updated; new distributions of this software should come with
929              an updated list but it is still the responsibility of the Admin‐
930              istrator to check that this list is correct.
931
932              Every  time gpgsm uses a certificate for signing or verification
933              this file will be consulted to  check  whether  the  certificate
934              under  question  has ultimately been issued by one of these CAs.
935              If this is the case the user will be informed that the  verified
936              signature  represents  a  legally binding (``qualified'') signa‐
937              ture.  When creating a signature using  such  a  certificate  an
938              extra  prompt will be issued to let the user confirm that such a
939              legally binding signature shall really be created.
940
941              Because this software has not yet been  approved  for  use  with
942              such certificates, appropriate notices will be shown to indicate
943              this fact.
944
945
946       help.txt
947              This is plain text file with a few help entries used with pinen‐
948              try  as  well  as  a large list of help items for gpg and gpgsm.
949              The standard file has English help texts; to  install  localized
950              versions  use  filenames like ‘help.LL.txt’ with LL denoting the
951              locale.  GnuPG comes with a set of predefined help files in  the
952              data  directory  (e.g. ‘/usr/share/gnupg/gnupg/help.de.txt’) and
953              allows overriding of any help item by help files stored  in  the
954              system  configuration directory (e.g. ‘/etc/gnupg/help.de.txt’).
955              For a reference of  the  help  file's  syntax,  please  see  the
956              installed ‘help.txt’ file.
957
958
959
960       com-certs.pem
961              This  file  is a collection of common certificates used to popu‐
962              lated a  newly  created  ‘pubring.kbx’.   An  administrator  may
963              replace this file with a custom one.  The format is a concatena‐
964              tion of PEM encoded X.509 certificates.   This  global  file  is
965              installed  in  the  data  directory (e.g. ‘/usr/share/gnupg/com-
966              certs.pem’).
967
968
969       Note that on larger installations, it is useful to put predefined files
970       into  the  directory  ‘/etc/skel/.gnupg/’  so  that newly created users
971       start up with a working configuration.   For  existing  users  a  small
972       helper script is provided to create these files (see: [addgnupghome]).
973
974       For  internal  purposes  gpgsm creates and maintains a few other files;
975       they all live in the current home directory (see: [option  --homedir]).
976       Only gpgsm may modify these files.
977
978
979
980       pubring.kbx
981              This  a  database  file storing the certificates as well as meta
982              information.  For debugging purposes the  tool  kbxutil  may  be
983              used  to  show  the internal structure of this file.  You should
984              backup this file.
985
986
987       random_seed
988              This content of this file is used to maintain the internal state
989              of  the  random  number  generator across invocations.  The same
990              file is used by other programs of this software too.
991
992
993       S.gpg-agent
994              If this file exists gpgsm will first  try  to  connect  to  this
995              socket  for  accessing gpg-agent before starting a new gpg-agent
996              instance.  Under Windows this socket  (which  in  reality  be  a
997              plain file describing a regular TCP listening port) is the stan‐
998              dard way of connecting the gpg-agent.
999
1000

SEE ALSO

1002       gpg2(1), gpg-agent(1)
1003
1004       The full documentation for this tool is maintained as a Texinfo manual.
1005       If  GnuPG and the info program are properly installed at your site, the
1006       command
1007
1008         info gnupg
1009
1010       should give you access to the complete manual including a  menu  struc‐
1011       ture and an index.
1012
1013
1014
1015GnuPG 2.2.9                       2018-06-12                          GPGSM(1)
Impressum