Provided by: gpgsm_2.0.22-3ubuntu1_amd64 bug


       gpgsm - CMS encryption and signing tool


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


       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 German Sphinx project.


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

   Commands not specific to the function

              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.

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

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

   Commands to select the type of operation

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

              Perform a decryption; the type of input is automatically determined.  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.

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

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

              -This command allows the  creation  of  a  certificate  signing  request.   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.  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
              create the CSR or certificate and it is further possible to create  non-self-signed


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


       -K     List  all  available  certificates  for  which  a  corresponding  a  secret  key is

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

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


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

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

              List all available certificates for which a corresponding a secret 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.

              This is a debugging aid to reset certain flags in the key database 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 validity
              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 in a PKCS#12
              format. When using along with the --armor option  a  few  informational  lines  are
              prepended to the output.  Note, that the PKCS#12 format is not very secure and this
              command is only provided 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.

              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

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


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

   How to change the configuration

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

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


              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

       --dirmngr-program file
              Specify  a  dirmngr  program  to  be  used  for  CRL  checks.  The default 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.

              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.

              Entirely disable the use of the Dirmngr.

              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


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


              By  default the CRL checks are enabled and the DirMngr is used to check for revoked
              certificates.   The  disable  option  is  most  useful  with  an  off-line  network
              connection to suppress this 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  suppressing 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 configuration file.


              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

              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 verified the signature.

       --validation-model name
              This option changes the default validation model.  The  only  possible  values  are
              "shell" (which is the default), "chain" which forces the use of the chain model and
              "steed" for a new simplified 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  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


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

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

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

              Assume the input data is plain base-64 encoded.

              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:

       --output file

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

              Displays extra information with the --list-keys commands.  Especially 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.

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

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

              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 3DES (1.2.840.113549.3.7).

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

   Doing things one usually do not want to do.

       --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 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 error 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").

              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

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

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

                     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
              defined 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 --debug-level.

              Same as --debug=0xffffffff

              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 unless the Bad Thing happened before the option parsing.

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

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

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

              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.


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



       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.


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

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

         =Heinrich Heine <>

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


       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.


       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.


       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 encoding as meta data.


         $ gpgsm -er <plaintext >ciphertext


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

              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.

              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
              critical and not listed in this file will fail  the  signature  verification.   You
              should backup this file.

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

                # Allowed policies

              This  is  the  list of root certificates used for qualified certificates.  They are
              defined as certificates capable of creating legally binding signatures in the  same
              way as handwritten signatures 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, followed 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
              Administrator 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  under  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'')  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.

              This  is  plain  text  file with a few help entries used with pinentry 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/’) and allows overriding of any help
              item  by  help  files  stored  in  the   system   configuration   directory   (e.g.
              ‘/etc/gnupg/’).   For  a reference of the help file's syntax, please see
              the installed ‘help.txt’ file.

              This file is a collection of common certificates used to populated a newly  created
              ‘pubring.kbx’.   An  administrator  may  replace  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:

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

              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.

              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.

              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


       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 structure and an index.