1GPGSM(1)                     GNU Privacy Guard 2.3                    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 re‐
115              quest 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 se‐
131              cret 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  se‐
158              cret  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       --show-certs [files]
169              This command takes certificate files as input and prints  infor‐
170              mation  about them in the same format as --dump-cert does.  Each
171              file may either contain a single binary certificate  or  several
172              PEM  encoded  certificates.  If no files are given, the input is
173              taken from stdin.
174
175              Please note that the listing format may be changed in future re‐
176              leases  and  that  the option --with-colons has currently no ef‐
177              fect.
178
179
180
181       --keydb-clear-some-cert-flags
182              This is a debugging aid to reset certain flags in the key  data‐
183              base  which  are used to cache certain certificate statuses.  It
184              is especially useful if a bad CRL or a weird  running  OCSP  re‐
185              sponder  did accidentally revoke certificate.  There is no secu‐
186              rity issue with this command because gpgsm always make sure that
187              the  validity  of  a  certificate  is checked right before it is
188              used.
189
190
191       --delete-keys pattern
192              Delete the keys matching pattern.  Note that there is no command
193              to delete the secret part of the key directly.  In case you need
194              to do this, you should run the command gpgsm  --dump-secret-keys
195              KEYID  before  you delete the key, copy the string of hex-digits
196              in the ``keygrip'' line and delete the file consisting of  these
197              hex-digits  and the suffix .key from the ‘private-keys-v1.d’ di‐
198              rectory below our GnuPG home directory (usually ‘~/.gnupg’).
199
200
201       --export [pattern]
202              Export all certificates stored in the Keybox or those  specified
203              by the optional pattern. Those pattern consist of a list of user
204              ids (see: [how-to-specify-a-user-id]).  When used along with the
205              --armor  option  a  few informational lines are prepended before
206              each block.  There is one limitation: As there  is  no  commonly
207              agreed  upon way to pack more than one certificate into an ASN.1
208              structure, the binary export (i.e. without  using  armor)  works
209              only  for the export of one certificate.  Thus it is required to
210              specify  a  pattern  which  yields  exactly   one   certificate.
211              Ephemeral certificate are only exported if all pattern are given
212              as fingerprints or keygrips.
213
214
215       --export-secret-key-p12 key-id
216              Export the private key and the certificate identified by  key-id
217              using  the  PKCS#12 format.  When used with the --armor option a
218              few informational lines are prepended to the output.  Note, that
219              the PKCS#12 format is not very secure and proper transport secu‐
220              rity should be used to convey the exported key.   (See:  [option
221              --p12-charset].)
222
223
224       --export-secret-key-p8 key-id
225       --export-secret-key-raw key-id
226              Export  the  private key of the certificate identified by key-id
227              with any encryption stripped.  The ...-raw  command  exports  in
228              PKCS#1  format;  the  ...-p8  command  exports in PKCS#8 format.
229              When used with the --armor option a few informational lines  are
230              prepended to the output.  These commands are useful to prepare a
231              key for use on a TLS server.
232
233
234       --import [files]
235              Import the certificates from the PEM or binary encoded files  as
236              well  as  from  signed-only  messages.  This command may also be
237              used to import a secret key from a PKCS#12 file.
238
239
240       --learn-card
241              Read information about the private keys from the  smartcard  and
242              import  the  certificates from there.  This command utilizes the
243              gpg-agent and in turn the scdaemon.
244
245
246       --change-passphrase user_id
247       --passwd user_id
248              Change the passphrase of the private key belonging to  the  cer‐
249              tificate   specified   as  user_id.   Note,  that  changing  the
250              passphrase/PIN of a smartcard is not yet supported.
251
252

OPTIONS

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

HOW TO SPECIFY A USER ID

788       There  are  different ways to specify a user ID to GnuPG.  Some of them
789       are only valid for gpg others are only good for gpgsm.  Here is the en‐
790       tire list of ways to specify a key:
791
792
793
794       By key Id.
795              This  format  is  deduced  from the length of the string and its
796              content or 0x prefix. The key Id of an X.509 certificate are the
797              low  64  bits  of  its SHA-1 fingerprint.  The use of key Ids is
798              just a shortcut, for all automated  processing  the  fingerprint
799              should be used.
800
801              When  using gpg an exclamation mark (!) may be appended to force
802              using the specified primary or secondary key and not to try  and
803              calculate which primary or secondary key to use.
804
805              The last four lines of the example give the key ID in their long
806              form as internally used by the OpenPGP protocol. You can see the
807              long key ID using the option --with-colons.
808
809         234567C4
810         0F34E556E
811         01347A56A
812         0xAB123456
813
814         234AABBCC34567C4
815         0F323456784E56EAB
816         01AB3FED1347A5612
817         0x234AABBCC34567C4
818
819
820
821
822       By fingerprint.
823              This  format  is  deduced  from the length of the string and its
824              content or the 0x prefix.  Note, that only the 20  byte  version
825              fingerprint  is available with gpgsm (i.e. the SHA-1 hash of the
826              certificate).
827
828              When using gpg an exclamation mark (!) may be appended to  force
829              using  the specified primary or secondary key and not to try and
830              calculate which primary or secondary key to use.
831
832              The best way to specify a key Id is by  using  the  fingerprint.
833              This  avoids  any  ambiguities in case that there are duplicated
834              key IDs.
835
836         1234343434343434C434343434343434
837         123434343434343C3434343434343734349A3434
838         0E12343434343434343434EAB3484343434343434
839         0xE12343434343434343434EAB3484343434343434
840
841
842       gpgsm also accepts colons between each pair of hexadecimal  digits  be‐
843       cause  this  is  the  de-facto standard on how to present X.509 finger‐
844       prints.  gpg also allows the use of the space separated  SHA-1  finger‐
845       print as printed by the key listing commands.
846
847
848       By exact match on OpenPGP user ID.
849              This  is denoted by a leading equal sign. It does not make sense
850              for X.509 certificates.
851
852         =Heinrich Heine <heinrichh@uni-duesseldorf.de>
853
854
855       By exact match on an email address.
856              This is indicated by enclosing the email address  in  the  usual
857              way with left and right angles.
858
859         <heinrichh@uni-duesseldorf.de>
860
861
862
863       By partial match on an email address.
864              This  is  indicated  by  prefixing  the search string with an @.
865              This uses a substring search but considers only the mail address
866              (i.e. inside the angle brackets).
867
868         @heinrichh
869
870
871       By exact match on the subject's DN.
872              This  is  indicated by a leading slash, directly followed by the
873              RFC-2253 encoded DN of the subject.  Note that you can't use the
874              string  printed  by  gpgsm --list-keys because that one has been
875              reordered and modified for better readability; use --with-colons
876              to print the raw (but standard escaped) RFC-2253 string.
877
878         /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
879
880
881       By exact match on the issuer's DN.
882              This is indicated by a leading hash mark, directly followed by a
883              slash and then directly followed by the RFC-2253 encoded  DN  of
884              the  issuer.   This  should  return the Root cert of the issuer.
885              See note above.
886
887         #/CN=Root Cert,O=Poets,L=Paris,C=FR
888
889
890
891       By exact match on serial number and issuer's DN.
892              This is indicated by a hash mark, followed  by  the  hexadecimal
893              representation  of  the  serial number, then followed by a slash
894              and the RFC-2253 encoded DN of the issuer. See note above.
895
896         #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
897
898
899       By keygrip.
900              This is indicated by an ampersand followed by the 40 hex  digits
901              of  a  keygrip.  gpgsm prints the keygrip when using the command
902              --dump-cert.
903
904         &D75F22C3F86E355877348498CDC92BD21010A480
905
906
907
908       By substring match.
909              This is the default mode but applications may want to explicitly
910              indicate  this  by  putting the asterisk in front.  Match is not
911              case sensitive.
912
913         Heine
914         *Heine
915
916
917       . and + prefixes
918              These prefixes are reserved for looking up mails anchored at the
919              end  and  for  a word search mode.  They are not yet implemented
920              and using them is undefined.
921
922
923              Please note that we have reused the hash mark  identifier  which
924              was  used in old GnuPG versions to indicate the so called local-
925              id.  It is not anymore used and there should be no conflict when
926              used with X.509 stuff.
927
928              Using the RFC-2253 format of DNs has the drawback that it is not
929              possible to map them back to the original encoding,  however  we
930              don't  have  to do this because our key database stores this en‐
931              coding as meta data.
932
933
934

EXAMPLES

936         $ gpgsm -er goo@bar.net <plaintext >ciphertext
937
938
939
940

FILES

942       There are a few configuration  files  to  control  certain  aspects  of
943       gpgsm's  operation. Unless noted, they are expected in the current home
944       directory (see: [option --homedir]).
945
946
947
948       gpgsm.conf
949              This is  the  standard  configuration  file  read  by  gpgsm  on
950              startup.   It may contain any valid long option; the leading two
951              dashes may not be entered and the option may not be abbreviated.
952              This  default  name  may  be  changed  on the command line (see:
953              [gpgsm-option --options]).  You should backup this file.
954
955
956       common.conf
957              This is an optional configuration file read by gpgsm on startup.
958              It  may  contain  options pertaining to all components of GnuPG.
959              Its current main use is for the "use-keyboxd" option.
960
961
962       policies.txt
963              This is a list of allowed CA policies.  This  file  should  list
964              the  object  identifiers  of  the  policies line by line.  Empty
965              lines and lines starting with a hash mark are ignored.  Policies
966              missing  in this file and not marked as critical in the certifi‐
967              cate will print  only  a  warning;  certificates  with  policies
968              marked  as  critical  and  not listed in this file will fail the
969              signature verification.  You should backup this file.
970
971              For example, to allow only the policy 2.289.9.9, the file should
972              look like this:
973
974                # Allowed policies
975                2.289.9.9
976
977
978       qualified.txt
979              This  is  the  list of root certificates used for qualified cer‐
980              tificates.  They are defined as certificates capable of creating
981              legally binding signatures in the same way as handwritten signa‐
982              tures are.  Comments start with a hash mark and empty lines  are
983              ignored.  Lines do have a length limit but this is not a serious
984              limitation as the format of the entries is fixed and checked  by
985              gpgsm:  A non-comment line starts with optional whitespace, fol‐
986              lowed by exactly 40 hex characters, white space and a lowercased
987              2  letter  country  code.   Additional  data delimited with by a
988              white space is current ignored but might late be used for  other
989              purposes.
990
991              Note  that  even  if  a certificate is listed in this file, this
992              does not mean that the certificate is trusted;  in  general  the
993              certificates  listed  in  this  file  need  to be listed also in
994trustlist.txt’. This is a  global  file  an  installed  in  the
995              sysconf directory (e.g.  ‘/etc/gnupg/qualified.txt’).
996
997              Every  time gpgsm uses a certificate for signing or verification
998              this file will be consulted to check whether the certificate un‐
999              der question has ultimately been issued by one of these CAs.  If
1000              this is the case the user will be  informed  that  the  verified
1001              signature  represents  a  legally binding (``qualified'') signa‐
1002              ture.  When creating a signature using such a certificate an ex‐
1003              tra  prompt  will  be issued to let the user confirm that such a
1004              legally binding signature shall really be created.
1005
1006              Because this software has not yet been  approved  for  use  with
1007              such certificates, appropriate notices will be shown to indicate
1008              this fact.
1009
1010
1011       help.txt
1012              This is plain text file with a few help entries used with pinen‐
1013              try  as  well  as  a large list of help items for gpg and gpgsm.
1014              The standard file has English help texts; to  install  localized
1015              versions  use  filenames like ‘help.LL.txt’ with LL denoting the
1016              locale.  GnuPG comes with a set of predefined help files in  the
1017              data  directory  (e.g. ‘/usr/share/gnupg/gnupg/help.de.txt’) and
1018              allows overriding of any help item by help files stored  in  the
1019              system  configuration directory (e.g. ‘/etc/gnupg/help.de.txt’).
1020              For a reference of the help file's syntax, please  see  the  in‐
1021              stalled ‘help.txt’ file.
1022
1023
1024
1025       com-certs.pem
1026              This  file  is a collection of common certificates used to popu‐
1027              lated a newly created ‘pubring.kbx’.  An administrator  may  re‐
1028              place  this  file with a custom one.  The format is a concatena‐
1029              tion of PEM encoded X.509 certificates.  This global file is in‐
1030              stalled  in  the  data  directory  (e.g.  ‘/usr/share/gnupg/com-
1031              certs.pem’).
1032
1033
1034       Note that on larger installations, it is useful to put predefined files
1035       into  the  directory  ‘/etc/skel/.gnupg/’  so  that newly created users
1036       start up with a working configuration.   For  existing  users  a  small
1037       helper script is provided to create these files (see: [addgnupghome]).
1038
1039       For  internal  purposes  gpgsm creates and maintains a few other files;
1040       they all live in the current home directory (see: [option  --homedir]).
1041       Only gpgsm may modify these files.
1042
1043
1044
1045       pubring.kbx
1046              This  a  database  file storing the certificates as well as meta
1047              information.  For debugging purposes the  tool  kbxutil  may  be
1048              used  to  show  the internal structure of this file.  You should
1049              backup this file.
1050
1051
1052       random_seed
1053              This content of this file is used to maintain the internal state
1054              of  the  random  number  generator across invocations.  The same
1055              file is used by other programs of this software too.
1056
1057
1058       S.gpg-agent
1059              If this file exists gpgsm will first  try  to  connect  to  this
1060              socket  for  accessing gpg-agent before starting a new gpg-agent
1061              instance.  Under Windows this socket  (which  in  reality  be  a
1062              plain file describing a regular TCP listening port) is the stan‐
1063              dard way of connecting the gpg-agent.
1064
1065

SEE ALSO

1067       gpg2(1), gpg-agent(1)
1068
1069       The full documentation for this tool is maintained as a Texinfo manual.
1070       If  GnuPG and the info program are properly installed at your site, the
1071       command
1072
1073         info gnupg
1074
1075       should give you access to the complete manual including a  menu  struc‐
1076       ture and an index.
1077
1078
1079
1080GnuPG 2.4.0                       2022-12-16                          GPGSM(1)
Impressum