doc/invoke-danetool.texi

   1 @node danetool Invocation
   2 @section Invoking danetool
   3 @pindex danetool
   4 @cindex GnuTLS DANE tool
   5 @ignore
   6 #  -*- buffer-read-only: t -*- vi: set ro:
   7 #
   8 # DO NOT EDIT THIS FILE   (invoke-danetool.texi)
   9 #
  10 # It has been AutoGen-ed  October 12, 2012 at 09:27:38 AM by AutoGen 5.16
  11 # From the definitions    ../src/danetool-args.def
  12 # and the template file   agtexi-cmd.tpl
  13 @end ignore
  14
  15
  16 Tool generate DNS resource records for the DANE protocol.
  17
  18 This section was generated by @strong{AutoGen},
  19 using the @code{agtexi-cmd} template and the option descriptions for the @code{danetool} program.
  20 This software is released under the GNU General Public License, version 3 or later.
  21
  22
  23 @anchor{danetool usage}
  24 @subheading danetool help/usage (-h)
  25 @cindex danetool help
  26
  27 This is the automatically generated usage text for danetool.
  28 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  29 the usage text by passing it through a pager program.
  30 @code{more-help} is disabled on platforms without a working
  31 @code{fork(2)} function.  The @code{PAGER} environment variable is
  32 used to select the program, defaulting to @file{more}.  Both will exit
  33 with a status code of 0.
  34
  35 @exampleindent 0
  36 @example
  37 danetool - GnuTLS DANE tool - Ver. @@VERSION@@
  38 USAGE:  danetool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  39
  40    -d, --debug=num            Enable debugging.
  41                                 - It must be in the range:
  42                                   0 to 9999
  43    -V, --verbose              More verbose output
  44                                 - may appear multiple times
  45        --infile=file          Input file
  46                                 - file must pre-exist
  47        --outfile=str          Output file
  48        --load-pubkey=str      Loads a public key file
  49        --load-certificate=str Loads a certificate file
  50        --hash=str             Hash algorithm to use for signing.
  51        --inder                Use DER format for input certificates and private keys.
  52                                 - disabled as --no-inder
  53        --inraw                This is an alias for 'inder'
  54        --outder               Use DER format for output certificates and private keys
  55                                 - disabled as --no-outder
  56        --outraw               This is an alias for 'outder'
  57        --tlsa-rr              Print the DANE RR data on a certificate or public key
  58                                 - requires these options:
  59                                 host
  60        --host=str             Specify the hostname to be used in the DANE RR
  61        --proto=str            The protocol set for DANE data (tcp, udp etc.)
  62        --port=num             Specify the port number for the DANE data.
  63        --ca                   Whether the provided certificate or public key is a Certificate
  64 authority.
  65        --x509                 Use the hash of the X.509 certificate, rather than the public key.
  66        --local                The provided certificate or public key is a local entity.
  67    -v, --version[=arg]        Output version information and exit
  68    -h, --help                 Display extended usage information and exit
  69    -!, --more-help            Extended usage information passed thru pager
  70
  71 Options are specified by doubled hyphens and their name or by a single
  72 hyphen and the flag character.
  73
  74
  75
  76 Tool generate DNS resource records for the DANE protocol.
  77
  78 please send bug reports to:  bug-gnutls@@gnu.org
  79 @end example
  80 @exampleindent 4
  81
  82 @anchor{danetool debug}
  83 @subheading debug option (-d)
  84 @cindex danetool-debug
  85
  86 This is the ``enable debugging.'' option.
  87 This option takes an argument number.
  88 Specifies the debug level.
  89 @anchor{danetool load-pubkey}
  90 @subheading load-pubkey option
  91 @cindex danetool-load-pubkey
  92
  93 This is the ``loads a public key file'' option.
  94 This option takes an argument string.
  95 This can be either a file or a PKCS #11 URL
  96 @anchor{danetool load-certificate}
  97 @subheading load-certificate option
  98 @cindex danetool-load-certificate
  99
 100 This is the ``loads a certificate file'' option.
 101 This option takes an argument string.
 102 This can be either a file or a PKCS #11 URL
 103 @anchor{danetool hash}
 104 @subheading hash option
 105 @cindex danetool-hash
 106
 107 This is the ``hash algorithm to use for signing.'' option.
 108 This option takes an argument string.
 109 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
 110 @anchor{danetool inder}
 111 @subheading inder option
 112 @cindex danetool-inder
 113
 114 This is the ``use der format for input certificates and private keys.'' option.
 115 The input files will be assumed to be in DER or RAW format.
 116 Unlike options that in PEM input would allow multiple input data (e.g. multiple
 117 certificates), when reading in DER format a single data structure is read.
 118 @anchor{danetool inraw}
 119 @subheading inraw option
 120 @cindex danetool-inraw
 121
 122 This is an alias for the inder option,
 123 @pxref{danetool inder, the inder option documentation}.
 124
 125 @anchor{danetool outder}
 126 @subheading outder option
 127 @cindex danetool-outder
 128
 129 This is the ``use der format for output certificates and private keys'' option.
 130 The output will be in DER or RAW format.
 131 @anchor{danetool outraw}
 132 @subheading outraw option
 133 @cindex danetool-outraw
 134
 135 This is an alias for the outder option,
 136 @pxref{danetool outder, the outder option documentation}.
 137
 138 @anchor{danetool tlsa-rr}
 139 @subheading tlsa-rr option
 140 @cindex danetool-tlsa-rr
 141
 142 This is the ``print the dane rr data on a certificate or public key'' option.
 143
 144 @noindent
 145 This option has some usage constraints.  It:
 146 @itemize @bullet
 147 @item
 148 must appear in combination with the following options:
 149 host.
 150 @end itemize
 151
 152 This command prints the DANE RR data needed to enable DANE on a DNS server.
 153 @anchor{danetool host}
 154 @subheading host option
 155 @cindex danetool-host
 156
 157 This is the ``specify the hostname to be used in the dane rr'' option.
 158 This option takes an argument string @file{Hostname}.
 159 This command sets the hostname for the DANE RR.
 160 @anchor{danetool proto}
 161 @subheading proto option
 162 @cindex danetool-proto
 163
 164 This is the ``the protocol set for dane data (tcp, udp etc.)'' option.
 165 This option takes an argument string @file{Protocol}.
 166 This command specifies the protocol for the service set in the DANE data.
 167 @anchor{danetool ca}
 168 @subheading ca option
 169 @cindex danetool-ca
 170
 171 This is the ``whether the provided certificate or public key is a certificate authority.'' option.
 172 Marks the DANE RR as a CA certificate if specified.
 173 @anchor{danetool x509}
 174 @subheading x509 option
 175 @cindex danetool-x509
 176
 177 This is the ``use the hash of the x.509 certificate, rather than the public key.'' option.
 178 This option forces the generated record to contain the hash of the full X.509 certificate. By default only the hash of the public key is used.
 179 @anchor{danetool local}
 180 @subheading local option
 181 @cindex danetool-local
 182
 183 This is the ``the provided certificate or public key is a local entity.'' option.
 184 DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. Use this flag if this is a local (and possibly unsigned) entity.
 185 @anchor{danetool exit status}
 186 @subheading danetool exit status
 187
 188 One of the following exit values will be returned:
 189 @table @samp
 190 @item 0 (EXIT_SUCCESS)
 191 Successful program execution.
 192 @item 1 (EXIT_FAILURE)
 193 The operation failed or the command syntax was not valid.
 194 @end table
 195 @anchor{danetool See Also}
 196 @subheading danetool See Also
 197     p11tool (1)
 198
 199 @anchor{danetool Examples}
 200 @subheading danetool Examples
 201 @subheading DANE TLSA RR generation
 202
 203 To create a DANE TLSA resource record for a CA signed certificate use the following commands.
 204
 205 @example
 206 $ certtool --tlsa-rr --host www.example.com --load-certificate cert.pem
 207 @end example
 208
 209 For a self signed certificate use:
 210 @example
 211 $ certtool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 212   --local
 213 @end example
 214
 215 The latter is useful to add in your DNS entry even if your certificate is signed
 216 by a CA. That way even users who do not trust your CA will be able to verify your
 217 certificate using DANE.
 218
 219 In order to create a record for the signer of your certificate use:
 220 @example
 221 $ certtool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 222   --ca
 223 @end example
 224