search..
No manual entry for -- in section 1
GPGSM(1)		     GNU Privacy Guard 2.4		       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 signing
       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  Ger-
       man 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 to 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; automatic
	      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 std-
	      out.   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.   Cur-
	      rently  it is not possible to pass data via stdin to the Dirmngr.
	      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 simple
	      wrapper to access this tool.  arguments are  passed  verbatim  to
	      this command; use `--help' to get a list of supported operations.

   How to manage the certificates and keys

       --generate-key
       --gen-key
	      This command allows the creation of a certificate signing request
	      or a self-signed certificate.  It is commonly used along with the
	      --output	option	to  save  the created CSR or certificate into a
	      file.  If used with the --batch a parameter file is used to  cre-
	      ate  the	CSR or certificate and it is further possible to create
	      non-self-signed certificates.

       --list-keys
       -k     List all available certificates stored in the local key database.
	      Note that the displayed data might be reformatted for better  hu-
	      man  readability and illegal characters are replaced by safe sub-
	      stitutes.

       --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 debugging.

       --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.

       --show-certs [files]
	      This command takes certificate files as input and prints informa-
	      tion about them in the same format  as  --dump-cert  does.   Each
	      file  may	 either	 contain a single binary certificate or several
	      PEM encoded certificates.	 If no files are given,	 the  input  is
	      taken from stdin.

	      Please  note that the listing format may be changed in future re-
	      leases and that the option --with-colons has currently no effect.

       --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 statuses.  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' directory
	      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
	      using the PKCS#12 format.	 When used with the  --armor  option  a
	      few  informational lines are prepended to the output.  Note, that
	      the PKCS#12 format is not very secure and proper transport  secu-
	      rity  should  be	used to convey the exported key.  (See: [option
	      --p12-charset].)

       --export-secret-key-p8 key-id
       --export-secret-key-raw key-id
	      Export the private key of the certificate	 identified  by	 key-id
	      with  any	 encryption  stripped.	 The ...-raw command exports in
	      PKCS#1 format; the ...-p8 command exports in PKCS#8 format.  When
	      used with the  --armor  option  a	 few  informational  lines  are
	      prepended	 to the output.	 These commands are useful to prepare a
	      key for use on a TLS server.

       --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.

       --change-passphrase user_id
       --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 directly be-
	      low 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 rec-
	      ognized  when  given  on the command line.  It also overrides any
	      home  directory	stated	 through   the	 environment   variable
	      `GNUPGHOME'  or (on Windows systems) by means of the Registry en-
	      try HKCU\Software\GNU\GnuPG:HomeDir.

	      On Windows systems it is possible to install GnuPG as a  portable
	      application.   In this case only this command line option is con-
	      sidered, all other ways to set a home directory are ignored.

       -v

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

       --keyserver string
	      This is a deprecated option.  It was used to add an  LDAP	 server
	      to   use	for  X.509  certificate	 and  CRL  lookup.   The  alias
	      --ldapserver existed from version 2.2.28 to 2.2.33 and  2.3.2  to
	      2.3.4 but is now entirely ignored.

	      LDAP servers must be given in the configuration for dirmngr.

       --policy-file filename
	      Change  the default name of the policy file to filename.	The de-
	      fault name is `policies.txt'.

       --agent-program file
	      Specify an agent program to be used for  secret  key  operations.
	      The  default  value is determined by running the command gpgconf.
	      Note that the pipe symbol (|) is used for a regression test suite
	      hack and may thus not be used in the file name.

       --dirmngr-program file
	      Specify a dirmngr program to be used for CRL checks.  The default
	      value is `/usr/bin/dirmngr'.

       --prefer-system-dirmngr
	      This option is obsolete and ignored.

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

       --no-autostart
	      Do not start the gpg-agent or the dirmngr if it has not yet  been
	      started  and its service is required.  This option is mostly use-
	      ful on machines where the connection to gpg-agent has been  redi-
	      rected to another machines.  If dirmngr is required on the remote
	      machine,	it may be started manually using gpgconf --launch dirm-
	      ngr.

       --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.
	      Use `socket://' to log to socket.

       --log-time
	      Prefix all log output with a timestamp even if  no  log  file  is
	      used.

   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
	      and  also	 to  avoid that new certificates introduce a web bug by
	      including a certificate specific CRL DP.	The disable option also
	      disables an issuer certificate lookup via the authorityInfoAccess
	      property of the certificate; the --enable-issuer-key-retrieve can
	      be used to make use of that property anyway.

       --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 is-
	      sued 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 suppress-
	      ing  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  configura-
	      tion file.

       --enable-issuer-based-crl-check
	      Run  a  CRL check even for certificates which do not have any CRL
	      distribution point.  This requires that a	 suitable  LDAP	 server
	      has  been configured in Dirmngr and that the CRL can be found us-
	      ing the issuer.  This option reverts to what GnuPG did up to ver-
	      sion 2.2.20.  This option is in general not useful.

       --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 keybox), the
	      operator can tell both your IP address and the time when you ver-
	      ified the signature.  Note that if CRL checking is  not  disabled
	      issuer certificates are retrieved in any case using the caIssuers
	      authorityInfoAccess method.

       --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 option
	      with care because extensions are usually flagged as critical  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.

       --input-size-hint n
	      This option can be used to tell GPGSM the size of the input  data
	      in  bytes.   n  must be a positive base-10 number.  It is used by
	      the --status-fd line ``PROGRESS'' to provide a  value  for  ``to-
	      tal'' if that is not available by other means.

       --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 en-
	      coded 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.  Implies --with-colons.

       --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 because
	      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 certifi-
	      cate.

       --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 key-
	      grip is always listed in --with-colons mode.

       --with-secret
	      Include  info  about  the	 presence of a secret key in public key
	      listings done with --with-colons.

       --no-pretty-dn
	      By default gpgsm prints distinguished names (DNs) like the Issuer
	      or Subject in a more readable format (e.g. using a  well	defined
	      order of the parts).  However, this format can't be used as input
	      strings.	 This option reverts printing to standard RFC-2253 for-
	      mat and thus avoids the need to use --dump-cert or  --with-colons
	      to get the ``real'' name.

   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 algorithm
	      is deduced from the respective signing certificate.  This	 option
	      forces  the use of the given algorithm and may lead to severe in-
	      teroperability problems.

   Doing things one usually do not want to do

       --chuid uid
	      Change the current user to uid which may either be a number or  a
	      name.   This  can	 be used from the root account to run gpgsm for
	      another user.  If uid is not the current UID a standard  PATH  is
	      set  and	the  envvar GNUPGHOME is unset.	 To override the latter
	      the option --homedir can be used.	 This option has only an effect
	      when used on the command line.  This option has currently no  ef-
	      fect at all on Windows.

       --extra-digest-algo name
	      Sometimes signatures are broken in that they announce a different
	      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 op-
	      tion may be used to tell gpgsm to also hash the  data  using  the
	      algorithm	 name;	this slows processing down a little bit but al-
	      lows verification of such broken signatures.  If gpgsm prints  an
	      error like ``digest algo 8 has not been enabled'' you may want to
	      try this option, with `SHA256' for name.

       --compliance string
	      Set  the	compliance  mode.   Valid  values  are shown when using
	      "help" for string.

       --min-rsa-length n
	      This option adjusts the compliance mode "de-vs" for stricter  key
	      size  requirements.   For	 example, a value of 3000 turns rsa2048
	      and dsa2048 keys into non-VS-NfD compliant keys.

       --require-compliance
	      To check that data has been encrypted according to the  rules  of
	      the  current  compliance mode, a gpgsm user needs to evaluate the
	      status lines.  This is  allows  frontends	 to  handle  compliance
	      check  in a more flexible way.  However, for scripted use the re-
	      quired evaluation of the status-line requires quite some	effort;
	      this  option  can	 be  used  instead  to make sure that the gpgsm
	      process exits with a failure if the compliance rules are not ful-
	      filled.  Note that this option has currently an  effect  only  in
	      "de-vs" mode.

       --assert-signer fpr_or_file
	      This option checks whether at least one valid signature on a file
	      has  been	 made with the specified key.  The key is either speci-
	      fied as a fingerprint or a file listing fingerprints.   The  fin-
	      gerprint	must be given or listed in compact format (no colons or
	      spaces in between).  As of now only SHA-1	 fingerprints  are  al-
	      lowed.   This option can be given multiple times and each finger-
	      print is checked against the signing key as well	as  the	 corre-
	      sponding	primary	 key.	If  fpr_or_file specifies a file, empty
	      lines are ignored as well as all lines starting with a hash sign.
	      With this option gpgsm is guaranteed to return with an exit  code
	      of  0  if and only if a signature has been encountered, is valid,
	      and the key matches one of the fingerprints given by this option.

       --always-trust
	      Force encryption to the specified certificates without any  vali-
	      dation  of  the  certificate chain.  The only requirement is that
	      the certificate is capable of encryption.	 Note that this	 option
	      is ineffective if --require-compliance is used.

       --ignore-cert-with-oid oid
	      Add  oid to the list of OIDs to be checked while reading certifi-
	      cates from smartcards. The oid is expected to be in dotted  deci-
	      mal form, like 2.5.29.3.	This option may be used more than once.
	      As of now certificates with an extended key usage matching one of
	      those  OIDs  are	ignored during a --learn-card operation and not
	      imported.	 This option can help to keep the  local  key  database
	      clear of unneeded certificates stored on smartcards.

       --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.

       --compatibility-flags flags
	      Set  compatibility  flags to work around problems due to non-com-
	      pliant certificates or data.  The flags are given as a comma sep-
	      arated list of flag names and are OR-ed  together.   The	special
	      flag  "none" clears the list and allows one to start over with an
	      empty list.  To get a list  of  available	 flags	the  sole  word
	      "help" can be used.

       --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 spec-
       ified  and may change with newer releases of this program. They are how-
       ever carefully selected to best aid in debugging.

       --debug flags
	      Set debug flags.	All flags are or-ed and flags may be given in C
	      syntax (e.g. 0x0042) or as a comma separated list of flag	 names.
	      To  get  a list of all supported flags the single word "help" can
	      be used. This option is only useful for debugging and the	 behav-
	      ior may change at any time without notice.

	      Note,  that all flags set using this option may get overridden by
	      --debug-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 use-
	      ful to have a core dump.	This option enables core  dumps	 unless
	      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.

       --passphrase-fd n
	      Read the passphrase from file descriptor n. Only the  first  line
	      will  be	read  from  file  descriptor n. If you use 0 for n, the
	      passphrase will be read from STDIN. This can only be used if only
	      one passphrase is supplied.

	      Note that this passphrase is only used if the option --batch  has
	      also been given.

       --pinentry-mode mode
	      Set the pinentry mode to mode.  Allowed values for mode are:

	      default
		     Use the default of the agent, which is ask.

	      ask    Force the use of the Pinentry.

	      cancel Emulate use of Pinentry's cancel button.

	      error  Return a Pinentry error (``No Pinentry'').

	      loopback
		     Redirect  Pinentry	 queries  to  the caller.  Note that in
		     contrast to Pinentry the user is not prompted again if  he
		     enters a bad password.

       --request-origin origin
	      Tell  gpgsm to assume that the operation ultimately originated at
	      origin.  Depending on the origin certain restrictions are applied
	      and the Pinentry may include an extra note on the	 origin.   Sup-
	      ported  values for origin are: local which is the default, remote
	      to indicate a remote origin or browser for an operation requested
	      by a web browser.

       --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 con-
	      tent 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 con-
	      tent  or the 0x prefix.  Note, that only the 20 byte version fin-
	      gerprint is available with gpgsm (i.e. the SHA-1 hash of the cer-
	      tificate).

	      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.	 gpg  also  allows the use of the space separated SHA-1 finger-
       print as printed by the key listing commands.

       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 partial match on an email address.
	      This is indicated by prefixing the search string with an @.  This
	      uses a substring search but considers only the mail address (i.e.
	      inside the angle brackets).

	 @heinrichh

       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 has been re-
	      ordered 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 RFC-2253	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.

	 &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

       . and + prefixes
	      These prefixes are reserved for looking up mails anchored at  the
	      end and for a word search mode.  They are not yet implemented and
	      using them is undefined.

	      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
	      possible	to  map	 them back to the original encoding, however we
	      don't have to do this because our key database stores this encod-
	      ing 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 de-
	      fault name may be changed on the command line (see: [gpgsm-option
	      --options]).  You should backup this file.

       common.conf
	      This is an optional configuration file read by gpgsm on  startup.
	      It  may  contain	options	 pertaining to all components of GnuPG.
	      Its current main use is for the "use-keyboxd" option.

       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  certificate  will
	      print only a warning; certificates with policies marked as criti-
	      cal and not listed in this file will fail the signature verifica-
	      tion.  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 legacy method to mark root certificates as usable for
	      qualified certificates.  Qualified certificates  are  capable  of
	      creating	legally binding signatures in the same way as handwrit-
	      ten signatures.  The modern method to mark such root certificates
	      is to use the "qual" flag in the system  trustlist.txt;  see  the
	      gpg-agent man page for details.

	      Comments	int his file 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 characters, 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  pur-
	      poses.

	      Note that even if a certificate is listed in this file, this does
	      not mean that the certificate is trusted; in general the certifi-
	      cates   listed   in   this   file	 need  to  be  listed  also  in
	      `trustlist.txt'. This is	a  global  file	 an  installed	in  the
	      sysconf directory (e.g.  `/etc/gnupg/qualified.txt').

	      Every  time  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 sig-
	      nature represents a legally  binding  (``qualified'')  signature.
	      When  creating  a	 signature  using  such	 a certificate an extra
	      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  ver-
	      sions  use  filenames like `help.LL.txt' with LL denoting the lo-
	      cale.  GnuPG comes with a set of predefined  help	 files	in  the
	      data  directory  (e.g.  `/usr/share/gnupg/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  in-
	      stalled `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 concatenation
	      of PEM encoded X.509 certificates.  This global file is installed
	      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 the current home directory (see:  [option  --homedir]).
       Only gpgsm may modify these files.

       pubring.kbx
	      This a database file storing the certificates as well as meta in-
	      formation.   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 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
       gpg(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 structure
       and an index.

GnuPG 2.4.7			   2024-11-22			       GPGSM(1)