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  November  1, 2012 at 07:51:08 PM 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        --check=str            Check DANE TLSA entry.
  52        --local-dns            Use the local DNS server for DNSSEC resolving.
  53                                 - disabled as --no-local-dns
  54        --inder                Use DER format for input certificates and private keys.
  55                                 - disabled as --no-inder
  56        --inraw                This is an alias for 'inder'
  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 check}
 111 @subheading check option
 112 @cindex danetool-check
 113
 114 This is the ``check dane tlsa entry.'' option.
 115 This option takes an argument string.
 116 Obtains the DANE TLSA entry from the given hostname and prints information.
 117 @anchor{danetool local-dns}
 118 @subheading local-dns option
 119 @cindex danetool-local-dns
 120
 121 This is the ``use the local dns server for dnssec resolving.'' option.
 122 This option will use the local DNS server for DNSSEC.
 123 This is disabled by default due to many servers not allowing DNSSEC.
 124 @anchor{danetool inder}
 125 @subheading inder option
 126 @cindex danetool-inder
 127
 128 This is the ``use der format for input certificates and private keys.'' option.
 129 The input files will be assumed to be in DER or RAW format.
 130 Unlike options that in PEM input would allow multiple input data (e.g. multiple
 131 certificates), when reading in DER format a single data structure is read.
 132 @anchor{danetool inraw}
 133 @subheading inraw option
 134 @cindex danetool-inraw
 135
 136 This is an alias for the inder option,
 137 @pxref{danetool inder, the inder option documentation}.
 138
 139 @anchor{danetool tlsa-rr}
 140 @subheading tlsa-rr option
 141 @cindex danetool-tlsa-rr
 142
 143 This is the ``print the dane rr data on a certificate or public key'' option.
 144
 145 @noindent
 146 This option has some usage constraints.  It:
 147 @itemize @bullet
 148 @item
 149 must appear in combination with the following options:
 150 host.
 151 @end itemize
 152
 153 This command prints the DANE RR data needed to enable DANE on a DNS server.
 154 @anchor{danetool host}
 155 @subheading host option
 156 @cindex danetool-host
 157
 158 This is the ``specify the hostname to be used in the dane rr'' option.
 159 This option takes an argument string @file{Hostname}.
 160 This command sets the hostname for the DANE RR.
 161 @anchor{danetool proto}
 162 @subheading proto option
 163 @cindex danetool-proto
 164
 165 This is the ``the protocol set for dane data (tcp, udp etc.)'' option.
 166 This option takes an argument string @file{Protocol}.
 167 This command specifies the protocol for the service set in the DANE data.
 168 @anchor{danetool ca}
 169 @subheading ca option
 170 @cindex danetool-ca
 171
 172 This is the ``whether the provided certificate or public key is a certificate authority.'' option.
 173 Marks the DANE RR as a CA certificate if specified.
 174 @anchor{danetool x509}
 175 @subheading x509 option
 176 @cindex danetool-x509
 177
 178 This is the ``use the hash of the x.509 certificate, rather than the public key.'' option.
 179 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.
 180 @anchor{danetool local}
 181 @subheading local option
 182 @cindex danetool-local
 183
 184 This is the ``the provided certificate or public key is a local entity.'' option.
 185 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.
 186 @anchor{danetool exit status}
 187 @subheading danetool exit status
 188
 189 One of the following exit values will be returned:
 190 @table @samp
 191 @item 0 (EXIT_SUCCESS)
 192 Successful program execution.
 193 @item 1 (EXIT_FAILURE)
 194 The operation failed or the command syntax was not valid.
 195 @end table
 196 @anchor{danetool See Also}
 197 @subheading danetool See Also
 198     p11tool (1)
 199
 200 @anchor{danetool Examples}
 201 @subheading danetool Examples
 202 @subheading DANE TLSA RR generation
 203
 204 To create a DANE TLSA resource record for a CA signed certificate use the following commands.
 205
 206 @example
 207 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem
 208 @end example
 209
 210 For a self signed certificate use:
 211 @example
 212 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 213   --local
 214 @end example
 215
 216 The latter is useful to add in your DNS entry even if your certificate is signed
 217 by a CA. That way even users who do not trust your CA will be able to verify your
 218 certificate using DANE.
 219
 220 In order to create a record for the signer of your certificate use:
 221 @example
 222 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 223   --ca
 224 @end example
 225
 226 To read a server's DANE TLSA entry, use:
 227 @example
 228 $ danetool --check www.example.com --proto tcp --port 443
 229 @end example
 230
 231 To verify a server's DANE TLSA entry, use:
 232 @example
 233 $ danetool --check www.example.com --proto tcp --port 443 --load-certificate chain.pem
 234 @end example
 235