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

OPTIONS

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

HOW TO SPECIFY A USER ID

686       There  are  different ways to specify a user ID to GnuPG.  Some of them
687       are only valid for gpg others are only good for  gpgsm.   Here  is  the
688       entire list of ways to specify a key:
689
690
691
692       By key Id.
693              This  format  is  deduced  from the length of the string and its
694              content or 0x prefix. The key Id of an X.509 certificate are the
695              low  64  bits  of  its SHA-1 fingerprint.  The use of key Ids is
696              just a shortcut, for all automated  processing  the  fingerprint
697              should be used.
698
699              When  using gpg an exclamation mark (!) may be appended to force
700              using the specified primary or secondary key and not to try  and
701              calculate which primary or secondary key to use.
702
703              The last four lines of the example give the key ID in their long
704              form as internally used by the OpenPGP protocol. You can see the
705              long key ID using the option --with-colons.
706
707         234567C4
708         0F34E556E
709         01347A56A
710         0xAB123456
711
712         234AABBCC34567C4
713         0F323456784E56EAB
714         01AB3FED1347A5612
715         0x234AABBCC34567C4
716
717
718
719
720       By fingerprint.
721              This  format  is  deduced  from the length of the string and its
722              content or the 0x prefix.  Note, that only the 20  byte  version
723              fingerprint  is available with gpgsm (i.e. the SHA-1 hash of the
724              certificate).
725
726              When using gpg an exclamation mark (!) may be appended to  force
727              using  the specified primary or secondary key and not to try and
728              calculate which primary or secondary key to use.
729
730              The best way to specify a key Id is by  using  the  fingerprint.
731              This  avoids  any  ambiguities in case that there are duplicated
732              key IDs.
733
734         1234343434343434C434343434343434
735         123434343434343C3434343434343734349A3434
736         0E12343434343434343434EAB3484343434343434
737         0xE12343434343434343434EAB3484343434343434
738
739
740       (gpgsm also accepts colons between  each  pair  of  hexadecimal  digits
741       because  this  is the de-facto standard on how to present X.509 finger‐
742       prints.)
743
744
745       By exact match on OpenPGP user ID.
746              This is denoted by a leading equal sign. It does not make  sense
747              for X.509 certificates.
748
749         =Heinrich Heine <heinrichh@uni-duesseldorf.de>
750
751
752       By exact match on an email address.
753              This  is  indicated  by enclosing the email address in the usual
754              way with left and right angles.
755
756         <heinrichh@uni-duesseldorf.de>
757
758
759
760       By word match.
761              All words must match exactly (not case sensitive) but can appear
762              in  any  order in the user ID or a subjects name.  Words are any
763              sequences of letters, digits, the underscore and all  characters
764              with bit 7 set.
765
766         +Heinrich Heine duesseldorf
767
768
769       By exact match on the subject's DN.
770              This  is  indicated by a leading slash, directly followed by the
771              RFC-2253 encoded DN of the subject.  Note that you can't use the
772              string  printed  by "gpgsm --list-keys" because that one as been
773              reordered and modified for better readability; use --with-colons
774              to print the raw (but standard escaped) RFC-2253 string
775
776         /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
777
778
779       By exact match on the issuer's DN.
780              This is indicated by a leading hash mark, directly followed by a
781              slash and then directly followed by the rfc2253  encoded  DN  of
782              the  issuer.   This  should  return the Root cert of the issuer.
783              See note above.
784
785         #/CN=Root Cert,O=Poets,L=Paris,C=FR
786
787
788
789       By exact match on serial number and issuer's DN.
790              This is indicated by a hash mark, followed  by  the  hexadecimal
791              representation  of  the  serial number, then followed by a slash
792              and the RFC-2253 encoded DN of the issuer. See note above.
793
794         #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
795
796
797       By keygrip
798              This is indicated by an ampersand followed by the 40 hex  digits
799              of  a  keygrip.  gpgsm prints the keygrip when using the command
800              --dump-cert.  It does not yet work for OpenPGP keys.
801
802         &D75F22C3F86E355877348498CDC92BD21010A480
803
804
805
806       By substring match.
807              This is the default mode but applications may want to explicitly
808              indicate  this  by  putting the asterisk in front.  Match is not
809              case sensitive.
810
811         Heine
812         *Heine
813
814
815
816       Please note that we have reused the hash mark identifier which was used
817       in  old  GnuPG  versions to indicate the so called local-id.  It is not
818       anymore used and there should be  no  conflict  when  used  with  X.509
819       stuff.
820
821       Using the RFC-2253 format of DNs has the drawback that it is not possi‐
822       ble to map them back to the original encoding, however we don't have to
823       do this because our key database stores this encoding as meta data.
824
825
826
827
828
829

EXAMPLES

831         $ gpgsm -er goo@bar.net <plaintext >ciphertext
832
833
834
835

FILES

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

SEE ALSO

968       gpg2(1), gpg-agent(1)
969
970       The full documentation for this tool is maintained as a Texinfo manual.
971       If GnuPG and the info program are properly installed at your site,  the
972       command
973
974         info gnupg
975
976       should  give  you access to the complete manual including a menu struc‐
977       ture and an index.
978
979
980
981GnuPG 2.0.22                      2018-07-13                          GPGSM(1)
Impressum