1GPGSM(1) GNU Privacy Guard GPGSM(1)
2
3
4
6 gpgsm - CMS encryption and signing tool
7
9 gpgsm [--homedir dir] [--options file] [options] command [args]
10
11
12
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
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
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
272 ‘GNUPGHOME’ 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
360 ‘trustlist.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
405 ‘trustlist.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
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
831 $ gpgsm -er goo@bar.net <plaintext >ciphertext
832
833
834
835
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
884 ‘trustlist.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
918 ‘help.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
957 ‘GPG_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
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)