Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GPGSM(1)		       GNU Privacy Guard		      GPGSM(1)

NAME
       gpgsm - CMS encryption and signing tool

SYNOPSIS
       gpgsm [--homedir	dir] [--options	file] [options]	command	[args]

DESCRIPTION
       gpgsm  is a tool	similar	to gpg to provide digital encryption and sign-
       ing services on X.509 certificates and the CMS protocol.	 It is	mainly
       used  as	 a  backend for	S/MIME mail processing.	 gpgsm includes	a full
       featured	certificate management and complies with all rules defined for
       the German Sphinx project.

COMMANDS
       Commands	 are  not  distinguished from options except for the fact that
       only one	command	is allowed.

   Commands not	specific to the	function

       --version
	      Print the	program	version	and licensing information.  Note  that
	      you cannot abbreviate this command.

       --help, -h
	      Print  a	usage message summarizing the most useful command-line
	      options.	Note that you cannot abbreviate	this command.

       --warranty
	      Print warranty information.  Note	 that  you  cannot  abbreviate
	      this command.

       --dump-options
	      Print  a	list of	all available options and commands.  Note that
	      you cannot abbreviate this command.

   Commands to select the type of operation

       --encrypt
	      Perform an encryption.  The keys the data	is encrypted too  must
	      be set using the option --recipient.

       --decrypt
	      Perform  a decryption; the type of input is automatically	deter-
	      mined.  It may either be in binary form or  PEM  encoded;	 auto-
	      matic determination of base-64 encoding is not done.

       --sign Create a digital signature.  The key used	is either the fist one
	      found in the keybox or those set with the	--local-user option.

       --verify
	      Check a signature	file for validity.  Depending on the arguments
	      a	detached signature may also be checked.

       --server
	      Run in server mode and wait for commands on the stdin.

       --call-dirmngr command [args]
	      Behave  as a Dirmngr client issuing the request command with the
	      optional list of args.  The output of  the  Dirmngr  is  printed
	      stdout.	Please	note that file names given as arguments	should
	      have an absolute file name (i.e. commencing with / because  they
	      are  passed verbatim to the Dirmngr and the working directory of
	      the Dirmngr might	not be the same	as the	one  of	 this  client.
	      Currently	it is not possible to pass data	via stdin to the Dirm-
	      ngr.  command should not contain spaces.

	      This is command is required for certain maintaining tasks	of the
	      dirmngr where a dirmngr must be able to call back	to gpgsm.  See
	      the Dirmngr manual for details.

       --call-protect-tool arguments
	      Certain maintenance operations are done by an  external  program
	      call gpg-protect-tool; this is usually not installed in a	direc-
	      tory listed in the PATH variable.	 This command provides a  sim-
	      ple  wrapper to access this tool.	 arguments are passed verbatim
	      to this command; use '--help' to get a list of supported	opera-
	      tions.

   How to manage the certificates and keys

       --gen-key
	      -This  command  allows the creation of a certificate signing re-
	      quest.  It -is commonly used along with the --output  option  to
	      save  the	 -created CSR into a file.  If used with the --batch a
	      parameter	-file is used to create	the CSR.

       --list-keys

       -k     List all available certificates stored in	the  local  key	 data-
	      base.   Note  that  the  displayed data might be reformatted for
	      better human readability and illegal characters are replaced  by
	      safe substitutes.

       --list-secret-keys

       -K     List  all	available certificates for which a corresponding a se-
	      cret key is available.

       --list-external-keys pattern
	      List certificates	matching pattern  using	 an  external  server.
	      This utilizes the	dirmngr	service.

       --list-chain
	      Same  as	--list-keys  but  also	prints	all keys making	up the
	      chain.

       --dump-cert

       --dump-keys
	      List all available certificates stored in	the local key database
	      using a format useful mainly for debugging.

       --dump-chain
	      Same  as	--dump-keys  but  also	prints	all keys making	up the
	      chain.

       --dump-secret-keys
	      List all available certificates for which	a corresponding	a  se-
	      cret  key	 is  available using a format useful mainly for	debug-
	      ging.

       --dump-external-keys pattern
	      List certificates	matching pattern  using	 an  external  server.
	      This  utilizes  the  dirmngr  service.   It uses a format	useful
	      mainly for debugging.

       --keydb-clear-some-cert-flags
	      This is a	debugging aid to reset certain flags in	the key	 data-
	      base  which  are used to cache certain certificate stati.	 It is
	      especially useful	if a bad CRL or	a weird	running	OCSP responder
	      did accidentally revoke certificate.  There is no	security issue
	      with this	command	because	gpgsm always make sure that the	valid-
	      ity of a certificate is checked right before it is used.

       --delete-keys pattern
	      Delete the keys matching pattern.	 Note that there is no command
	      to delete	the secret part	of the key directly.  In case you need
	      to  do this, you should run the command gpgsm --dump-secret-keys
	      KEYID before you delete the key, copy the	string	of  hex-digits
	      in  the ``keygrip'' line and delete the file consisting of these
	      hex-digits and the suffix	.key from the `private-keys-v1.d'  di-
	      rectory below our	GnuPG home directory (usually `~/.gnupg').

       --export	[pattern]
	      Export  all certificates stored in the Keybox or those specified
	      by the optional pattern. Those pattern consist of	a list of user
	      ids (see:	[how-to-specify-a-user-id]).  When used	along with the
	      --armor option a few informational lines	are  prepended	before
	      each  block.   There  is one limitation: As there	is no commonly
	      agreed upon way to pack more than	one certificate	into an	 ASN.1
	      structure,  the  binary  export (i.e. without using armor) works
	      only for the export of one certificate.  Thus it is required  to
	      specify	a   pattern  which  yields  exactly  one  certificate.
	      Ephemeral	certificate are	only exported if all pattern are given
	      as fingerprints or keygrips.

       --export-secret-key-p12 key-id
	      Export  the private key and the certificate identified by	key-id
	      in a PKCS#12 format. When	used with the --armor option a few in-
	      formational  lines  are prepended	to the output.	Note, that the
	      PKCS#12 format is	not very secure	and this command is only  pro-
	      vided  if	 there	is  no	other way to exchange the private key.
	      (see: [option --p12-charset])

       --import	[files]
	      Import the certificates from the PEM or binary encoded files  as
	      well  as	from  signed-only  messages.  This command may also be
	      used to import a secret key from a PKCS#12 file.

       --learn-card
	      Read information about the private keys from the	smartcard  and
	      import  the  certificates	from there.  This command utilizes the
	      gpg-agent	and in turn the	scdaemon.

       --passwd	user_id
	      Change the passphrase of the private key belonging to  the  cer-
	      tificate	 specified   as	 user_id.   Note,  that	 changing  the
	      passphrase/PIN of	a smartcard is not yet supported.

OPTIONS
       GPGSM features a	bunch of options to control the	exact behaviour	and to
       change the default configuration.

   How to change the configuration

       These  options  are  used  to  change the configuration and are usually
       found in	the option file.

       --options file
	      Reads configuration from file instead of from the	 default  per-
	      user  configuration  file.   The	default	 configuration file is
	      named `gpgsm.conf' and expected in the  `.gnupg'	directory  di-
	      rectly below the home directory of the user.

       --homedir dir
	      Set the name of the home directory to dir. If this option	is not
	      used, the	home directory defaults	to  `~/.gnupg'.	  It  is  only
	      recognized  when	given  on the command line.  It	also overrides
	      any home	directory  stated  through  the	 environment  variable
	      `GNUPGHOME'  or  (on W32 systems)	by means of the	Registry entry
	      HKCU\Software\GNU\GnuPG:HomeDir.

       -v

       --verbose
	      Outputs additional information while running.  You can  increase
	      the  verbosity by	giving several verbose commands	to gpgsm, such
	      as '-vv'.

       --policy-file filename
	      Change the default name of the policy file to filename.

       --agent-program file
	      Specify an agent program to be used for secret  key  operations.
	      The  default  value  is the `/usr/local/bin/gpg-agent'.  This is
	      only  used  as  a	 fallback  when	  the	environment   variable
	      GPG_AGENT_INFO  is  not  set  or	a running agent	cannot be con-
	      nected.

       --dirmngr-program file
	      Specify a	dirmngr	program	to be used for CRL  checks.   The  de-
	      fault  value  is	`/usr/sbin/dirmngr'.   This  is	only used as a
	      fallback when the	environment variable DIRMNGR_INFO is  not  set
	      or a running dirmngr cannot be connected.

       --prefer-system-dirmngr
	      If a system wide dirmngr is running in daemon mode, first	try to
	      connect to this one.  Fallback to	a pipe based  server  if  this
	      does not work.  Under Windows this option	is ignored because the
	      system dirmngr is	always used.

       --disable-dirmngr
	      Entirely disable the use of the Dirmngr.

       --no-secmem-warning
	      Do not print a warning when the so called	"secure	memory"	cannot
	      be used.

       --log-file file
	      When running in server mode, append all logging output to	file.

   Certificate related options

       --enable-policy-checks

       --disable-policy-checks
	      By default policy	checks are enabled.  These options may be used
	      to change	it.

       --enable-crl-checks

       --disable-crl-checks
	      By default the CRL checks	are enabled and	the DirMngr is used to
	      check for	revoked	certificates.  The disable option is most use-
	      ful with an off-line network connection to suppress this check.

       --enable-trusted-cert-crl-check

       --disable-trusted-cert-crl-check
	      By default the CRL for trusted  root  certificates  are  checked
	      like for any other certificates.	This allows a CA to revoke its
	      own certificates voluntary without the need of putting all  ever
	      issued  certificates into	a CRL.	The disable option may be used
	      to switch	this extra check off.  Due to the caching done by  the
	      Dirmngr,	there  will  not  be  any noticeable performance gain.
	      Note, that this also disables possible OCSP checks  for  trusted
	      root  certificates.  A more specific way of disabling this check
	      is by adding the ``relax'' keyword to the	root CA	 line  of  the
	      `trustlist.txt'

       --force-crl-refresh
	      Tell the dirmngr to reload the CRL for each request.  For	better
	      performance, the dirmngr will actually  optimize	this  by  sup-
	      pressing the loading for short time intervals (e.g. 30 minutes).
	      This option is useful to make sure that a	fresh CRL is available
	      for certificates hold in the keybox.  The	suggested way of doing
	      this is by using it along	with the option	--with-validation  for
	      a	key listing command.  This option should not be	used in	a con-
	      figuration file.

       --enable-ocsp

       --disable-ocsp
	      By default OCSP checks are disabled.  The	enable option  may  be
	      used  to enable OCSP checks via Dirmngr.	If CRL checks are also
	      enabled, CRLs will be used as a fallback if for some  reason  an
	      OCSP  request  will  not	succeed.  Note,	that you have to allow
	      OCSP requests in Dirmngr's configuration	too  (option  --allow-
	      ocsp)  and  configure Dirmngr properly.  If you do not do	so you
	      will get the error code 'Not supported'.

       --auto-issuer-key-retrieve
	      If a required certificate	is missing while validating the	 chain
	      of  certificates,	 try to	load that certificate from an external
	      location.	 This usually means that Dirmngr is employed to	search
	      for  the	certificate.   Note that this option makes a "web bug"
	      like behavior possible.  LDAP server  operators  can  see	 which
	      keys  you	request, so by sending you a message signed by a brand
	      new key (which you naturally will	not have on  your  local  key-
	      box),  the  operator  can	tell both your IP address and the time
	      when you verified	the signature.

       --validation-model name
	      This option changes the default validation model.	 The only pos-
	      sible  values  are "shell" (which	is the default), "chain" which
	      forces the use of	the chain model	and "steed" for	a new  simpli-
	      fied  model.   The  chain	model is also used if an option	in the
	      `trustlist.txt' or an attribute of the certificate requests  it.
	      However  the standard model (shell) is in	that case always tried
	      first.

       --ignore-cert-extension oid
	      Add oid to the list of ignored certificate extensions.  The  oid
	      is  expected  to be in dotted decimal form, like 2.5.29.3.  This
	      option may be used more than once.  Critical flagged certificate
	      extensions  matching  one	of the OIDs in the list	are treated as
	      if they are actually handled and thus the	certificate  will  not
	      be  rejected due to an unknown critical extension.  Use this op-
	      tion with	care because extensions	are usually flagged as	criti-
	      cal for a	reason.

   Input and Output

       --armor

       -a     Create PEM encoded output.  Default is binary output.

       --base64
	      Create  Base-64  encoded	output;	 i.e.  PEM  without the	header
	      lines.

       --assume-armor
	      Assume the input data is PEM encoded.  Default is	to  autodetect
	      the encoding but this is may fail.

       --assume-base64
	      Assume the input data is plain base-64 encoded.

       --assume-binary
	      Assume the input data is binary encoded.

       --p12-charset name
	      gpgsm  uses  the	UTF-8  encoding	 when encoding passphrases for
	      PKCS#12 files.  This option may be used to force the  passphrase
	      to be encoded in the specified encoding name.  This is useful if
	      the application used to import the key uses a different encoding
	      and  thus	 will not be able to import a file generated by	gpgsm.
	      Commonly used values for name are	Latin1 and CP850.   Note  that
	      gpgsm  itself  automagically  imports any	file with a passphrase
	      encoded to the most commonly used	encodings.

       --default-key user_id
	      Use user_id as the standard key for signing.  This key  is  used
	      if  no  other key	has been defined as a signing key.  Note, that
	      the first	--local-users option also sets this key	if it has  not
	      yet been set; however --default-key always overrides this.

       --local-user user_id

       -u user_id
	      Set  the	user(s)	 to  be	 used for signing.  The	default	is the
	      first secret key found in	the database.

       --recipient name

       -r     Encrypt to the user id name.  There are several ways a  user  id
	      may be given (see: [how-to-specify-a-user-id]).

       --output	file

       -o file
	      Write output to file.  The default is to write it	to stdout.

       --with-key-data
	      Displays extra information with the --list-keys commands.	 Espe-
	      cially a line tagged grp is printed which	tells you the  keygrip
	      of  a  key.  This	string is for example used as the file name of
	      the secret key.

       --with-validation
	      When doing a key listing,	do a full validation  check  for  each
	      key  and print the result.  This is usually a slow operation be-
	      cause it requires	a CRL lookup and other operations.

	      When used	along with --import, a validation of  the  certificate
	      to  import  is  done  and	only imported if it succeeds the test.
	      Note that	this does not affect an	already	available  certificate
	      in  the  DB.  This option	is therefore useful to simply verify a
	      certificate.

       --with-md5-fingerprint
	      For standard key listings, also print the	MD5 fingerprint	of the
	      certificate.

       --with-keygrip
	      Include  the  keygrip  in	 standard key listings.	 Note that the
	      keygrip is always	listed in --with-colons	mode.

   How to change how the CMS is	created.

       --include-certs n
	      Using n of -2 includes all certificate except for	the root cert,
	      -1  includes all certs, 0	does not include any certs, 1 includes
	      only the signers cert and	all other positive values  include  up
	      to n certificates	starting with the signer cert.	The default is
	      -2.

       --cipher-algo oid
	      Use the cipher algorithm with the	ASN.1  object  identifier  oid
	      for  encryption.	 For  convenience  the	strings	 3DES, AES and
	      AES256 may be used instead of their OIDs.	 The  default  is  AES
	      (2.16.840.1.101.3.4.1.2).

       --digest-algo name
	      Use  name	 as  the message digest	algorithm.  Usually this algo-
	      rithm is deduced from the	respective signing certificate.	  This
	      option forces the	use of the given algorithm and may lead	to se-
	      vere interoperability problems.

   Doing things	one usually do not want	to do.

       --extra-digest-algo name
	      Sometimes	signatures are broken in that they announce a  differ-
	      ent  digest algorithm than actually used.	 gpgsm uses a one-pass
	      data processing model and	thus needs to rely  on	the  announced
	      digest  algorithms  to  properly hash the	data.  As a workaround
	      this option may be used to tell gpg to also hash the data	 using
	      the  algorithm name; this	slows processing down a	little bit but
	      allows to	verify such broken signatures.	If gpgsm prints	an er-
	      ror  like	``digest algo 8	has not	been enabled'' you may want to
	      try this option, with 'SHA256' for name.

       --faked-system-time epoch
	      This option is only useful for testing; it sets the system  time
	      back  or	forth  to epoch	which is the number of seconds elapsed
	      since the	year 1970.  Alternatively epoch	may be given as	a full
	      ISO time string (e.g. "20070924T154812").

       --with-ephemeral-keys
	      Include  ephemeral  flagged  keys	in the output of key listings.
	      Note that	they are included anyway if the	key specification  for
	      a	listing	is given as fingerprint	or keygrip.

       --debug-level level
	      Select  the debug	level for investigating	problems. level	may be
	      a	numeric	value or by a keyword:

	      none   No	debugging at all.  A value of less than	1 may be  used
		     instead of	the keyword.

	      basic  Some  basic  debug	messages.  A value between 1 and 2 may
		     be	used instead of	the keyword.

	      advanced
		     More verbose debug	messages.  A value between 3 and 5 may
		     be	used instead of	the keyword.

	      expert Even more detailed	messages.  A value between 6 and 8 may
		     be	used instead of	the keyword.

	      guru   All of the	debug messages you can get.  A	value  greater
		     than  8 may be used instead of the	keyword.  The creation
		     of	hash tracing files is only enabled if the  keyword  is
		     used.

       How  these  messages  are  mapped  to the actual	debugging flags	is not
       specified and may change	with newer releases of this program. They  are
       however carefully selected to best aid in debugging.

       --debug flags
	      This  option  is only useful for debugging and the behaviour may
	      change at	any time without notice; using --debug-levels  is  the
	      preferred	 method	 to select the debug verbosity.	 FLAGS are bit
	      encoded and may be given in usual	C-Syntax.  The	currently  de-
	      fined bits are:

	      0	(1)  X.509 or OpenPGP protocol related data

	      1	(2)  values of big number integers

	      2	(4)  low level crypto operations

	      5	(32) memory allocation

	      6	(64) caching

	      7	(128)
		     show memory statistics.

	      9	(512)
		     write hashed data to files	named dbgmd-000*

	      10 (1024)
		     trace Assuan protocol

       Note,  that all flags set using this option may get overridden by --de-
       bug-level.

       --debug-all
	      Same as --debug=0xffffffff

       --debug-allow-core-dump
	      Usually gpgsm tries to avoid dumping core	by well	 written  code
	      and by disabling core dumps for security reasons.	 However, bugs
	      are pretty durable beasts	and to squash  them  it	 is  sometimes
	      useful  to have a	core dump.  This option	enables	core dumps un-
	      less the Bad Thing happened before the option parsing.

       --debug-no-chain-validation
	      This is actually not a debugging option but only useful as such.
	      It lets gpgsm bypass all certificate chain validation checks.

       --debug-ignore-expiration
	      This is actually not a debugging option but only useful as such.
	      It lets gpgsm ignore all notAfter	dates, this is used by the re-
	      gression tests.

       --fixed-passphrase string
	      Supply  the passphrase string to the gpg-protect-tool.  This op-
	      tion is only useful for the regression tests included with  this
	      package  and  may	 be revised or removed at any time without no-
	      tice.

       --no-common-certs-import
	      Suppress the import of common certificates on keybox creation.

	      All the long options may also be given in	the configuration file
	      after stripping off the two leading dashes.

HOW TO SPECIFY A USER ID
       There  are  different ways to specify a user ID to GnuPG.  Some of them
       are only	valid for gpg others are only good for gpgsm.  Here is the en-
       tire list of ways to specify a key:

       By key Id.
	      This  format  is	deduced	 from the length of the	string and its
	      content or 0x prefix. The	key Id of an X.509 certificate are the
	      low  64  bits  of	 its SHA-1 fingerprint.	 The use of key	Ids is
	      just a shortcut, for all automated  processing  the  fingerprint
	      should be	used.

	      When  using gpg an exclamation mark (!) may be appended to force
	      using the	specified primary or secondary key and not to try  and
	      calculate	which primary or secondary key to use.

	      The last four lines of the example give the key ID in their long
	      form as internally used by the OpenPGP protocol. You can see the
	      long key ID using	the option --with-colons.

	 234567C4
	 0F34E556E
	 01347A56A
	 0xAB123456

	 234AABBCC34567C4
	 0F323456784E56EAB
	 01AB3FED1347A5612
	 0x234AABBCC34567C4

       By fingerprint.
	      This  format  is	deduced	 from the length of the	string and its
	      content or the 0x	prefix.	 Note, that only the 20	 byte  version
	      fingerprint  is available	with gpgsm (i.e. the SHA-1 hash	of the
	      certificate).

	      When using gpg an	exclamation mark (!) may be appended to	 force
	      using  the specified primary or secondary	key and	not to try and
	      calculate	which primary or secondary key to use.

	      The best way to specify a	key Id is by  using  the  fingerprint.
	      This  avoids  any	 ambiguities in	case that there	are duplicated
	      key IDs.

	 1234343434343434C434343434343434
	 123434343434343C3434343434343734349A3434
	 0E12343434343434343434EAB3484343434343434
	 0xE12343434343434343434EAB3484343434343434

       (gpgsm also accepts colons between each pair of hexadecimal digits  be-
       cause  this  is	the  de-facto standard on how to present X.509 finger-
       prints.)

       By exact	match on OpenPGP user ID.
	      This is denoted by a leading equal sign. It does not make	 sense
	      for X.509	certificates.

	 =Heinrich Heine <heinrichh@uni-duesseldorf.de>

       By exact	match on an email address.
	      This  is	indicated  by enclosing	the email address in the usual
	      way with left and	right angles.

	 <heinrichh@uni-duesseldorf.de>

       By word match.
	      All words	must match exactly (not	case sensitive)	but can	appear
	      in  any  order in	the user ID or a subjects name.	 Words are any
	      sequences	of letters, digits, the	underscore and all  characters
	      with bit 7 set.

	 +Heinrich Heine duesseldorf

       By exact	match on the subject's DN.
	      This  is	indicated by a leading slash, directly followed	by the
	      RFC-2253 encoded DN of the subject.  Note	that you can't use the
	      string  printed  by "gpgsm --list-keys" because that one as been
	      reordered	and modified for better	readability; use --with-colons
	      to print the raw (but standard escaped) RFC-2253 string

	 /CN=Heinrich Heine,O=Poets,L=Paris,C=FR

       By exact	match on the issuer's DN.
	      This is indicated	by a leading hash mark,	directly followed by a
	      slash and	then directly followed by the rfc2253  encoded	DN  of
	      the  issuer.   This  should  return the Root cert	of the issuer.
	      See note above.

	 #/CN=Root Cert,O=Poets,L=Paris,C=FR

       By exact	match on serial	number and issuer's DN.
	      This is indicated	by a hash mark,	followed  by  the  hexadecimal
	      representation  of  the  serial number, then followed by a slash
	      and the RFC-2253 encoded DN of the issuer. See note above.

	 #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR

       By keygrip
	      This is indicated	by an ampersand	followed by the	40 hex	digits
	      of  a  keygrip.  gpgsm prints the	keygrip	when using the command
	      --dump-cert.  It does not	yet work for OpenPGP keys.

	 &D75F22C3F86E355877348498CDC92BD21010A480

       By substring match.
	      This is the default mode but applications	may want to explicitly
	      indicate	this  by  putting the asterisk in front.  Match	is not
	      case sensitive.

	 Heine
	 *Heine

       Please note that	we have	reused the hash	mark identifier	which was used
       in  old	GnuPG  versions	to indicate the	so called local-id.  It	is not
       anymore used and	there should be	 no  conflict  when  used  with	 X.509
       stuff.

       Using the RFC-2253 format of DNs	has the	drawback that it is not	possi-
       ble to map them back to the original encoding, however we don't have to
       do this because our key database	stores this encoding as	meta data.

EXAMPLES
	 $ gpgsm -er goo@bar.net <plaintext >ciphertext

FILES
       There  are  a  few  configuration  files	 to control certain aspects of
       gpgsm's operation. Unless noted,	they are expected in the current  home
       directory (see: [option --homedir]).

       gpgsm.conf
	      This  is	the  standard  configuration  file  read  by  gpgsm on
	      startup.	It may contain any valid long option; the leading  two
	      dashes may not be	entered	and the	option may not be abbreviated.
	      This default name	may be	changed	 on  the  command  line	 (see:
	      [gpgsm-option --options]).  You should backup this file.

       policies.txt
	      This  is	a  list	of allowed CA policies.	 This file should list
	      the object identifiers of	the  policies  line  by	 line.	 Empty
	      lines and	lines starting with a hash mark	are ignored.  Policies
	      missing in this file and not marked as critical in the  certifi-
	      cate  will  print	 only  a  warning;  certificates with policies
	      marked as	critical and not listed	in this	 file  will  fail  the
	      signature	verification.  You should backup this file.

	      For example, to allow only the policy 2.289.9.9, the file	should
	      look like	this:

		# Allowed policies
		2.289.9.9

       qualified.txt
	      This is the list of root certificates used  for  qualified  cer-
	      tificates.  They are defined as certificates capable of creating
	      legally binding signatures in the	same way as handwritten	signa-
	      tures  are.  Comments start with a hash mark and empty lines are
	      ignored.	Lines do have a	length limit but this is not a serious
	      limitation  as the format	of the entries is fixed	and checked by
	      gpgsm: A non-comment line	starts with optional whitespace,  fol-
	      lowed  by	exactly	40 hex character, white	space and a lowercased
	      2	letter country code.  Additional  data	delimited  with	 by  a
	      white  space is current ignored but might	late be	used for other
	      purposes.

	      Note that	even if	a certificate is listed	 in  this  file,  this
	      does  not	 mean  that the	certificate is trusted;	in general the
	      certificates listed in this file	need  to  be  listed  also  in
	      `trustlist.txt'.

	      This  is	a global file an installed in the data directory (e.g.
	      `/usr/share/gnupg/qualified.txt').  GnuPG	 installs  a  suitable
	      file  with root certificates as used in Germany.	As new Root-CA
	      certificates may be issued over time, these entries may need  to
	      be  updated; new distributions of	this software should come with
	      an updated list but it is	still the responsibility of the	Admin-
	      istrator to check	that this list is correct.

	      Everytime	 gpgsm	uses a certificate for signing or verification
	      this file	will be	consulted to check whether the certificate un-
	      der question has ultimately been issued by one of	these CAs.  If
	      this is the case the user	will be	 informed  that	 the  verified
	      signature	 represents  a	legally	binding	(``qualified'')	signa-
	      ture.  When creating a signature using such a certificate	an ex-
	      tra  prompt  will	 be issued to let the user confirm that	such a
	      legally binding signature	shall really be	created.

	      Because this software has	not yet	been  approved	for  use  with
	      such certificates, appropriate notices will be shown to indicate
	      this fact.

       help.txt
	      This is plain text file with a few help entries used with	pinen-
	      try  as  well  as	 a large list of help items for	gpg and	gpgsm.
	      The standard file	has English help texts;	to  install  localized
	      versions	use  filenames like `help.LL.txt' with LL denoting the
	      locale.  GnuPG comes with	a set of predefined help files in  the
	      data  directory (e.g. `/usr/share/gnupg/help.de.txt') and	allows
	      overriding of any	help item by help files	stored in  the	system
	      configuration  directory (e.g. `/etc/gnupg/help.de.txt').	 For a
	      reference	of the help file's syntax, please  see	the  installed
	      `help.txt' file.

       com-certs.pem
	      This  file  is a collection of common certificates used to popu-
	      lated a newly created `pubring.kbx'.  An administrator  may  re-
	      place  this  file	with a custom one.  The	format is a concatena-
	      tion of PEM encoded X.509	certificates.  This global file	is in-
	      stalled  in  the	data  directory	 (e.g.	`/usr/share/gnupg/com-
	      certs.pem').

       Note that on larger installations, it is	useful to put predefined files
       into  the  directory  `/etc/skel/.gnupg/'  so  that newly created users
       start up	with a working configuration.	For  existing  users  a	 small
       helper script is	provided to create these files (see: [addgnupghome]).

       For  internal  purposes	gpgsm creates and maintains a few other	files;
       they all	live in	in the current home directory  (see:  [option  --home-
       dir]).  Only gpgsm may modify these files.

       pubring.kbx
	      This  a  database	 file storing the certificates as well as meta
	      information.  For	debugging purposes the	tool  kbxutil  may  be
	      used  to	show  the internal structure of	this file.  You	should
	      backup this file.

       random_seed
	      This content of this file	is used	to maintain the	internal state
	      of  the  random  number  generator across	invocations.  The same
	      file is used by other programs of	this software too.

       S.gpg-agent
	      If   this	  file	 exists	  and	the    environment    variable
	      `GPG_AGENT_INFO'	is not set, gpgsm will first try to connect to
	      this socket for accessing	gpg-agent before starting a  new  gpg-
	      agent  instance.	Under Windows this socket (which in reality be
	      a	plain file describing a	regular	TCP  listening	port)  is  the
	      standard way of connecting the gpg-agent.

SEE ALSO
       gpg2(1),	gpg-agent(1)

       The full	documentation for this tool is maintained as a Texinfo manual.
       If GnuPG	and the	info program are properly installed at your site,  the
       command

	 info gnupg

       should  give  you access	to the complete	manual including a menu	struc-
       ture and	an index.

GnuPG 2.0.30			  2017-07-08			      GPGSM(1)

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OPTIONS | HOW TO SPECIFY A USER ID | EXAMPLES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gpgsm&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help