doc/invoke-danetool.texi

   1 @node danetool Invocation
   2 @subsection Invoking danetool
   3 @pindex danetool
   4 @ignore
   5 #  -*- buffer-read-only: t -*- vi: set ro:
   6 #
   7 # DO NOT EDIT THIS FILE   (invoke-danetool.texi)
   8 #
   9 # It has been AutoGen-ed
  10 # From the definitions    ../src/danetool-args.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15 Tool to generate and check DNS resource records for the DANE protocol.
  16
  17 This section was generated by @strong{AutoGen},
  18 using the @code{agtexi-cmd} template and the option descriptions for the @code{danetool} program.
  19 This software is released under the GNU General Public License, version 3 or later.
  20
  21
  22 @anchor{danetool usage}
  23 @subsubheading danetool help/usage (@option{--help})
  24 @cindex danetool help
  25
  26 This is the automatically generated usage text for danetool.
  27
  28 The text printed is the same whether selected with the @code{help} option
  29 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  30 the usage text by passing it through a pager program.
  31 @code{more-help} is disabled on platforms without a working
  32 @code{fork(2)} function.  The @code{PAGER} environment variable is
  33 used to select the program, defaulting to @file{more}.  Both will exit
  34 with a status code of 0.
  35
  36 @exampleindent 0
  37 @example
  38 danetool - GnuTLS DANE tool
  39 Usage:  danetool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  40
  41    -d, --debug=num            Enable debugging
  42                                 - it must be in the range:
  43                                   0 to 9999
  44    -V, --verbose              More verbose output
  45                                 - may appear multiple times
  46        --infile=file          Input file
  47                                 - file must pre-exist
  48        --outfile=str          Output file
  49        --load-pubkey=str      Loads a public key file
  50        --load-certificate=str Loads a certificate file
  51        --dlv=str              Sets a DLV file
  52        --hash=str             Hash algorithm to use for signing
  53        --check=str            Check a host's DANE TLSA entry
  54        --check-ee             Check only the end-entity's certificate
  55        --check-ca             Check only the CA's certificate
  56        --tlsa-rr              Print the DANE RR data on a certificate or public key
  57                                 - requires the option 'host'
  58        --host=str             Specify the hostname to be used in the DANE RR
  59        --proto=str            The protocol set for DANE data (tcp, udp etc.)
  60        --port=num             Specify the port number for the DANE data
  61        --app-proto=str        an alias for the 'starttls-proto' option
  62        --starttls-proto=str   The application protocol to be used to obtain the server's certificate
  63 (https, ftp, smtp, imap, ldap, xmpp)
  64        --ca                   Whether the provided certificate or public key is a Certificate
  65 Authority
  66        --x509                 Use the hash of the X.509 certificate, rather than the public key
  67        --local                an alias for the 'domain' option
  68                                 - enabled by default
  69        --domain               The provided certificate or public key is issued by the local domain
  70                                 - disabled as '--no-domain'
  71                                 - enabled by default
  72        --local-dns            Use the local DNS server for DNSSEC resolving
  73                                 - disabled as '--no-local-dns'
  74        --insecure             Do not verify any DNSSEC signature
  75        --inder                Use DER format for input certificates and private keys
  76                                 - disabled as '--no-inder'
  77        --inraw                an alias for the 'inder' option
  78        --print-raw            Print the received DANE data in raw format
  79                                 - disabled as '--no-print-raw'
  80        --quiet                Suppress several informational messages
  81    -v, --version[=arg]        output version information and exit
  82    -h, --help                 display extended usage information and exit
  83    -!, --more-help            extended usage information passed thru pager
  84
  85 Options are specified by doubled hyphens and their name or by a single
  86 hyphen and the flag character.
  87
  88 Tool to generate and check DNS resource records for the DANE protocol.
  89
  90 @end example
  91 @exampleindent 4
  92
  93 @anchor{danetool debug}
  94 @subsubheading debug option (-d)
  95
  96 This is the ``enable debugging'' option.
  97 This option takes a number argument.
  98 Specifies the debug level.
  99 @anchor{danetool load-pubkey}
 100 @subsubheading load-pubkey option
 101
 102 This is the ``loads a public key file'' option.
 103 This option takes a string argument.
 104 This can be either a file or a PKCS #11 URL
 105 @anchor{danetool load-certificate}
 106 @subsubheading load-certificate option
 107
 108 This is the ``loads a certificate file'' option.
 109 This option takes a string argument.
 110 This can be either a file or a PKCS #11 URL
 111 @anchor{danetool dlv}
 112 @subsubheading dlv option
 113
 114 This is the ``sets a dlv file'' option.
 115 This option takes a string argument.
 116 This sets a DLV file to be used for DNSSEC verification.
 117 @anchor{danetool hash}
 118 @subsubheading hash option
 119
 120 This is the ``hash algorithm to use for signing'' option.
 121 This option takes a string argument.
 122 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
 123 @anchor{danetool check}
 124 @subsubheading check option
 125
 126 This is the ``check a host's dane tlsa entry'' option.
 127 This option takes a string argument.
 128 Obtains the DANE TLSA entry from the given hostname and prints information. Note that the actual certificate of the host can be provided using --load-certificate, otherwise danetool will connect to the server to obtain it. The exit code on verification success will be zero.
 129 @anchor{danetool check-ee}
 130 @subsubheading check-ee option
 131
 132 This is the ``check only the end-entity's certificate'' option.
 133 Checks the end-entity's certificate only. Trust anchors or CAs are not considered.
 134 @anchor{danetool check-ca}
 135 @subsubheading check-ca option
 136
 137 This is the ``check only the ca's certificate'' option.
 138 Checks the trust anchor's and CA's certificate only. End-entities are not considered.
 139 @anchor{danetool tlsa-rr}
 140 @subsubheading tlsa-rr option
 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 @subsubheading host option
 155
 156 This is the ``specify the hostname to be used in the dane rr'' option.
 157 This option takes a string argument @file{Hostname}.
 158 This command sets the hostname for the DANE RR.
 159 @anchor{danetool proto}
 160 @subsubheading proto option
 161
 162 This is the ``the protocol set for dane data (tcp, udp etc.)'' option.
 163 This option takes a string argument @file{Protocol}.
 164 This command specifies the protocol for the service set in the DANE data.
 165 @anchor{danetool app-proto}
 166 @subsubheading app-proto option
 167
 168 This is an alias for the @code{starttls-proto} option,
 169 @pxref{danetool starttls-proto, the starttls-proto option documentation}.
 170
 171 @anchor{danetool starttls-proto}
 172 @subsubheading starttls-proto option
 173
 174 This is the ``the application protocol to be used to obtain the server's certificate (https, ftp, smtp, imap, ldap, xmpp)'' option.
 175 This option takes a string argument.
 176 When the server's certificate isn't provided danetool will connect to the server to obtain the certificate. In that case it is required to known the protocol to talk with the server prior to initiating the TLS handshake.
 177 @anchor{danetool ca}
 178 @subsubheading ca option
 179
 180 This is the ``whether the provided certificate or public key is a certificate authority'' option.
 181 Marks the DANE RR as a CA certificate if specified.
 182 @anchor{danetool x509}
 183 @subsubheading x509 option
 184
 185 This is the ``use the hash of the x.509 certificate, rather than the public key'' option.
 186 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.
 187 @anchor{danetool local}
 188 @subsubheading local option
 189
 190 This is an alias for the @code{domain} option,
 191 @pxref{danetool domain, the domain option documentation}.
 192
 193 @anchor{danetool domain}
 194 @subsubheading domain option
 195
 196 This is the ``the provided certificate or public key is issued by the local domain'' option.
 197
 198 @noindent
 199 This option has some usage constraints.  It:
 200 @itemize @bullet
 201 @item
 202 can be disabled with --no-domain.
 203 @item
 204 It is enabled by default.
 205 @end itemize
 206
 207 DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. This flag indicates that this is a domain-issued certificate, meaning that there could be no CA involved.
 208 @anchor{danetool local-dns}
 209 @subsubheading local-dns option
 210
 211 This is the ``use the local dns server for dnssec resolving'' option.
 212
 213 @noindent
 214 This option has some usage constraints.  It:
 215 @itemize @bullet
 216 @item
 217 can be disabled with --no-local-dns.
 218 @end itemize
 219
 220 This option will use the local DNS server for DNSSEC.
 221 This is disabled by default due to many servers not allowing DNSSEC.
 222 @anchor{danetool insecure}
 223 @subsubheading insecure option
 224
 225 This is the ``do not verify any dnssec signature'' option.
 226 Ignores any DNSSEC signature verification results.
 227 @anchor{danetool inder}
 228 @subsubheading inder option
 229
 230 This is the ``use der format for input certificates and private keys'' option.
 231
 232 @noindent
 233 This option has some usage constraints.  It:
 234 @itemize @bullet
 235 @item
 236 can be disabled with --no-inder.
 237 @end itemize
 238
 239 The input files will be assumed to be in DER or RAW format.
 240 Unlike options that in PEM input would allow multiple input data (e.g. multiple
 241 certificates), when reading in DER format a single data structure is read.
 242 @anchor{danetool inraw}
 243 @subsubheading inraw option
 244
 245 This is an alias for the @code{inder} option,
 246 @pxref{danetool inder, the inder option documentation}.
 247
 248 @anchor{danetool print-raw}
 249 @subsubheading print-raw option
 250
 251 This is the ``print the received dane data in raw format'' option.
 252
 253 @noindent
 254 This option has some usage constraints.  It:
 255 @itemize @bullet
 256 @item
 257 can be disabled with --no-print-raw.
 258 @end itemize
 259
 260 This option will print the received DANE data.
 261 @anchor{danetool quiet}
 262 @subsubheading quiet option
 263
 264 This is the ``suppress several informational messages'' option.
 265 In that case on the exit code can be used as an indication of verification success
 266 @anchor{danetool exit status}
 267 @subsubheading danetool exit status
 268
 269 One of the following exit values will be returned:
 270 @table @samp
 271 @item 0 (EXIT_SUCCESS)
 272 Successful program execution.
 273 @item 1 (EXIT_FAILURE)
 274 The operation failed or the command syntax was not valid.
 275 @end table
 276 @anchor{danetool See Also}
 277 @subsubheading danetool See Also
 278     certtool (1)
 279 @anchor{danetool Examples}
 280 @subsubheading danetool Examples
 281 @subsubheading DANE TLSA RR generation
 282
 283 To create a DANE TLSA resource record for a certificate (or public key)
 284 that was issued localy and may or may not be signed by a CA use the following command.
 285 @example
 286 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem
 287 @end example
 288
 289 To create a DANE TLSA resource record for a CA signed certificate, which will
 290 be marked as such use the following command.
 291 @example
 292 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 293   --no-domain
 294 @end example
 295
 296 The former is useful to add in your DNS entry even if your certificate is signed
 297 by a CA. That way even users who do not trust your CA will be able to verify your
 298 certificate using DANE.
 299
 300 In order to create a record for the CA signer of your certificate use the following.
 301 @example
 302 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 303   --ca --no-domain
 304 @end example
 305
 306 To read a server's DANE TLSA entry, use:
 307 @example
 308 $ danetool --check www.example.com --proto tcp --port 443
 309 @end example
 310
 311 To verify a server's DANE TLSA entry, use:
 312 @example
 313 $ danetool --check www.example.com --proto tcp --port 443 --load-certificate chain.pem
 314 @end example