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              and  also  to avoid that new certificates introduce a web bug by
354              including a certificate specific CRL  DP.   The  disable  option
355              also  disables an issuer certificate lookup via the authorityIn‐
356              foAccess property of the certificate;  the  --enable-issuer-key-
357              retrieve can be used to make use of that property anyway.
358
359
360       --enable-trusted-cert-crl-check
361       --disable-trusted-cert-crl-check
362              By  default  the  CRL  for trusted root certificates are checked
363              like for any other certificates.  This allows a CA to revoke its
364              own  certificates voluntary without the need of putting all ever
365              issued certificates into a CRL.  The disable option may be  used
366              to  switch this extra check off.  Due to the caching done by the
367              Dirmngr, there will not  be  any  noticeable  performance  gain.
368              Note,  that  this also disables possible OCSP checks for trusted
369              root certificates.  A more specific way of disabling this  check
370              is  by  adding  the ``relax'' keyword to the root CA line of the
371trustlist.txt
372
373
374
375       --force-crl-refresh
376              Tell the dirmngr to reload the CRL for each request.  For better
377              performance,  the  dirmngr  will  actually optimize this by sup‐
378              pressing the loading for short time intervals (e.g. 30 minutes).
379              This option is useful to make sure that a fresh CRL is available
380              for certificates hold in the keybox.  The suggested way of doing
381              this  is by using it along with the option --with-validation for
382              a key listing command.  This option should not be used in a con‐
383              figuration file.
384
385
386       --enable-issuer-based-crl-check
387              Run  a CRL check even for certificates which do not have any CRL
388              distribution point.  This requires that a suitable  LDAP  server
389              has  been  configured  in  Dirmngr and that the CRL can be found
390              using the issuer.  This option reverts to what GnuPG did  up  to
391              version 2.2.20.  This option is in general not useful.
392
393
394       --enable-ocsp
395       --disable-ocsp
396              By  default  OCSP checks are disabled.  The enable option may be
397              used to enable OCSP checks via Dirmngr.  If CRL checks are  also
398              enabled,  CRLs  will be used as a fallback if for some reason an
399              OCSP request will not succeed.  Note, that  you  have  to  allow
400              OCSP  requests  in  Dirmngr's configuration too (option --allow-
401              ocsp) and configure Dirmngr properly.  If you do not do  so  you
402              will get the error code ‘Not supported’.
403
404
405       --auto-issuer-key-retrieve
406              If  a required certificate is missing while validating the chain
407              of certificates, try to load that certificate from  an  external
408              location.  This usually means that Dirmngr is employed to search
409              for the certificate.  Note that this option makes  a  "web  bug"
410              like  behavior  possible.   LDAP  server operators can see which
411              keys you request, so by sending you a message signed by a  brand
412              new  key  (which  you naturally will not have on your local key‐
413              box), the operator can tell both your IP address  and  the  time
414              when you verified the signature.
415
416
417
418
419       --validation-model name
420              This option changes the default validation model.  The only pos‐
421              sible values are "shell" (which is the default),  "chain"  which
422              forces  the use of the chain model and "steed" for a new simpli‐
423              fied model.  The chain model is also used if an  option  in  the
424trustlist.txt’  or an attribute of the certificate requests it.
425              However the standard model (shell) is in that case always  tried
426              first.
427
428
429       --ignore-cert-extension oid
430              Add  oid to the list of ignored certificate extensions.  The oid
431              is expected to be in dotted decimal form, like  2.5.29.3.   This
432              option may be used more than once.  Critical flagged certificate
433              extensions matching one of the OIDs in the list are  treated  as
434              if  they  are actually handled and thus the certificate will not
435              be rejected due to an  unknown  critical  extension.   Use  this
436              option with care because extensions are usually flagged as crit‐
437              ical for a reason.
438
439
440   Input and Output
441
442
443
444       --armor
445       -a     Create PEM encoded output.  Default is binary output.
446
447
448       --base64
449              Create Base-64 encoded  output;  i.e.  PEM  without  the  header
450              lines.
451
452
453       --assume-armor
454              Assume  the input data is PEM encoded.  Default is to autodetect
455              the encoding but this is may fail.
456
457
458       --assume-base64
459              Assume the input data is plain base-64 encoded.
460
461
462       --assume-binary
463              Assume the input data is binary encoded.
464
465
466
467       --p12-charset name
468              gpgsm uses the UTF-8  encoding  when  encoding  passphrases  for
469              PKCS#12  files.  This option may be used to force the passphrase
470              to be encoded in the specified encoding name.  This is useful if
471              the application used to import the key uses a different encoding
472              and thus will not be able to import a file generated  by  gpgsm.
473              Commonly  used  values for name are Latin1 and CP850.  Note that
474              gpgsm itself automagically imports any file  with  a  passphrase
475              encoded to the most commonly used encodings.
476
477
478
479       --default-key user_id
480              Use  user_id  as the standard key for signing.  This key is used
481              if no other key has been defined as a signing key.   Note,  that
482              the  first --local-users option also sets this key if it has not
483              yet been set; however --default-key always overrides this.
484
485
486
487       --local-user user_id
488
489       -u user_id
490              Set the user(s) to be used for  signing.   The  default  is  the
491              first secret key found in the database.
492
493
494
495       --recipient name
496       -r     Encrypt  to  the user id name.  There are several ways a user id
497              may be given (see: [how-to-specify-a-user-id]).
498
499
500
501       --output file
502       -o file
503              Write output to file.  The default is to write it to stdout.
504
505
506
507
508       --with-key-data
509              Displays extra information with the --list-keys commands.  Espe‐
510              cially  a line tagged grp is printed which tells you the keygrip
511              of a key.  This string is for example used as the file  name  of
512              the secret key.  Implies --with-colons.
513
514
515
516       --with-validation
517              When  doing  a  key listing, do a full validation check for each
518              key and print the result.  This  is  usually  a  slow  operation
519              because it requires a CRL lookup and other operations.
520
521              When  used  along with --import, a validation of the certificate
522              to import is done and only imported if  it  succeeds  the  test.
523              Note  that this does not affect an already available certificate
524              in the DB.  This option is therefore useful to simply  verify  a
525              certificate.
526
527
528
529       --with-md5-fingerprint
530              For standard key listings, also print the MD5 fingerprint of the
531              certificate.
532
533
534       --with-keygrip
535              Include the keygrip in standard key  listings.   Note  that  the
536              keygrip is always listed in --with-colons mode.
537
538
539       --with-secret
540              Include  info  about  the presence of a secret key in public key
541              listings done with --with-colons.
542
543
544   How to change how the CMS is created
545
546
547
548       --include-certs n
549              Using n of -2 includes all certificate except for the root cert,
550              -1  includes all certs, 0 does not include any certs, 1 includes
551              only the signers cert and all other positive values  include  up
552              to n certificates starting with the signer cert.  The default is
553              -2.
554
555
556       --cipher-algo oid
557              Use the cipher algorithm with the ASN.1  object  identifier  oid
558              for  encryption.   For  convenience  the  strings  3DES, AES and
559              AES256 may be used instead of their OIDs.  The  default  is  AES
560              (2.16.840.1.101.3.4.1.2).
561
562
563       --digest-algo name
564              Use  name  as  the message digest algorithm.  Usually this algo‐
565              rithm is deduced from the respective signing certificate.   This
566              option  forces  the  use  of the given algorithm and may lead to
567              severe interoperability problems.
568
569
570   Doing things one usually do not want to do
571
572
573
574
575
576       --extra-digest-algo name
577              Sometimes signatures are broken in that they announce a  differ‐
578              ent  digest algorithm than actually used.  gpgsm uses a one-pass
579              data processing model and thus needs to rely  on  the  announced
580              digest  algorithms  to  properly hash the data.  As a workaround
581              this option may be used to tell gpgsm  to  also  hash  the  data
582              using  the  algorithm  name; this slows processing down a little
583              bit but allows verification of such broken signatures.  If gpgsm
584              prints  an error like ``digest algo 8 has not been enabled'' you
585              may want to try this option, with ‘SHA256’ for name.
586
587
588
589       --faked-system-time epoch
590              This option is only useful for testing; it sets the system  time
591              back  or  forth  to epoch which is the number of seconds elapsed
592              since the year 1970.  Alternatively epoch may be given as a full
593              ISO time string (e.g. "20070924T154812").
594
595
596       --with-ephemeral-keys
597              Include  ephemeral  flagged  keys in the output of key listings.
598              Note that they are included anyway if the key specification  for
599              a listing is given as fingerprint or keygrip.
600
601
602       --debug-level level
603              Select  the debug level for investigating problems. level may be
604              a numeric value or by a keyword:
605
606
607              none   No debugging at all.  A value of less than 1 may be  used
608                     instead of the keyword.
609
610              basic  Some  basic  debug messages.  A value between 1 and 2 may
611                     be used instead of the keyword.
612
613              advanced
614                     More verbose debug messages.  A value between 3 and 5 may
615                     be used instead of the keyword.
616
617              expert Even more detailed messages.  A value between 6 and 8 may
618                     be used instead of the keyword.
619
620              guru   All of the debug messages you can get.  A  value  greater
621                     than  8 may be used instead of the keyword.  The creation
622                     of hash tracing files is only enabled if the  keyword  is
623                     used.
624
625       How  these  messages  are  mapped  to the actual debugging flags is not
626       specified and may change with newer releases of this program. They  are
627       however carefully selected to best aid in debugging.
628
629
630       --debug flags
631              This  option  is only useful for debugging and the behaviour may
632              change at any time without notice; using --debug-levels  is  the
633              preferred  method  to select the debug verbosity.  FLAGS are bit
634              encoded and may  be  given  in  usual  C-Syntax.  The  currently
635              defined bits are:
636
637
638              0 (1)  X.509 or OpenPGP protocol related data
639
640              1 (2)  values of big number integers
641
642              2 (4)  low level crypto operations
643
644              5 (32) memory allocation
645
646              6 (64) caching
647
648              7 (128)
649                     show memory statistics
650
651              9 (512)
652                     write hashed data to files named dbgmd-000*
653
654              10 (1024)
655                     trace Assuan protocol
656
657       Note,  that  all  flags  set  using  this  option may get overridden by
658       --debug-level.
659
660
661       --debug-all
662              Same as --debug=0xffffffff
663
664
665       --debug-allow-core-dump
666              Usually gpgsm tries to avoid dumping core by well  written  code
667              and by disabling core dumps for security reasons.  However, bugs
668              are pretty durable beasts and to squash  them  it  is  sometimes
669              useful  to  have  a  core  dump.  This option enables core dumps
670              unless the Bad Thing happened before the option parsing.
671
672
673       --debug-no-chain-validation
674              This is actually not a debugging option but only useful as such.
675              It lets gpgsm bypass all certificate chain validation checks.
676
677
678       --debug-ignore-expiration
679              This is actually not a debugging option but only useful as such.
680              It lets gpgsm ignore all notAfter dates, this  is  used  by  the
681              regression tests.
682
683
684       --passphrase-fd n
685              Read  the passphrase from file descriptor n. Only the first line
686              will be read from file descriptor n. If you use  0  for  n,  the
687              passphrase  will  be  read  from STDIN. This can only be used if
688              only one passphrase is supplied.
689
690              Note that this passphrase is only used if the option --batch has
691              also been given.
692
693
694       --pinentry-mode mode
695              Set the pinentry mode to mode.  Allowed values for mode are:
696
697              default
698                     Use the default of the agent, which is ask.
699
700              ask    Force the use of the Pinentry.
701
702              cancel Emulate use of Pinentry's cancel button.
703
704              error  Return a Pinentry error (``No Pinentry'').
705
706              loopback
707                     Redirect  Pinentry  queries  to the caller.  Note that in
708                     contrast to Pinentry the user is not prompted again if he
709                     enters a bad password.
710
711
712       --request-origin origin
713              Tell gpgsm to assume that the operation ultimately originated at
714              origin.   Depending  on  the  origin  certain  restrictions  are
715              applied  and  the Pinentry may include an extra note on the ori‐
716              gin.  Supported values  for  origin  are:  local  which  is  the
717              default,  remote  to  indicate a remote origin or browser for an
718              operation requested by a web browser.
719
720
721       --no-common-certs-import
722              Suppress the import of common certificates on keybox creation.
723
724
725       All the long options may also be given in the configuration file  after
726       stripping off the two leading dashes.
727
728
729

HOW TO SPECIFY A USER ID

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

EXAMPLES

879         $ gpgsm -er goo@bar.net <plaintext >ciphertext
880
881
882
883

FILES

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

SEE ALSO

1012       gpg2(1), gpg-agent(1)
1013
1014       The full documentation for this tool is maintained as a Texinfo manual.
1015       If GnuPG and the info program are properly installed at your site,  the
1016       command
1017
1018         info gnupg
1019
1020       should  give  you access to the complete manual including a menu struc‐
1021       ture and an index.
1022
1023
1024
1025GnuPG 2.2.25                      2020-11-23                          GPGSM(1)
Impressum