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 29, 2012 at 07:37:13 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        --inder                Use DER format for input certificates and private keys.
  52                                 - disabled as --no-inder
  53        --inraw                This is an alias for 'inder'
  54        --tlsa-rr              Print the DANE RR data on a certificate or public key
  55                                 - requires these options:
  56                                 host
  57        --host=str             Specify the hostname to be used in the DANE RR
  58        --proto=str            The protocol set for DANE data (tcp, udp etc.)
  59        --port=num             Specify the port number for the DANE data.
  60        --ca                   Whether the provided certificate or public key is a Certificate
  61 authority.
  62        --x509                 Use the hash of the X.509 certificate, rather than the public key.
  63        --local                The provided certificate or public key is a local entity.
  64    -v, --version[=arg]        Output version information and exit
  65    -h, --help                 Display extended usage information and exit
  66    -!, --more-help            Extended usage information passed thru pager
  67
  68 Options are specified by doubled hyphens and their name or by a single
  69 hyphen and the flag character.
  70
  71
  72
  73 Tool generate DNS resource records for the DANE protocol.
  74
  75 please send bug reports to:  bug-gnutls@@gnu.org
  76 @end example
  77 @exampleindent 4
  78
  79 @anchor{danetool debug}
  80 @subheading debug option (-d)
  81 @cindex danetool-debug
  82
  83 This is the ``enable debugging.'' option.
  84 This option takes an argument number.
  85 Specifies the debug level.
  86 @anchor{danetool load-pubkey}
  87 @subheading load-pubkey option
  88 @cindex danetool-load-pubkey
  89
  90 This is the ``loads a public key file'' option.
  91 This option takes an argument string.
  92 This can be either a file or a PKCS #11 URL
  93 @anchor{danetool load-certificate}
  94 @subheading load-certificate option
  95 @cindex danetool-load-certificate
  96
  97 This is the ``loads a certificate file'' option.
  98 This option takes an argument string.
  99 This can be either a file or a PKCS #11 URL
 100 @anchor{danetool hash}
 101 @subheading hash option
 102 @cindex danetool-hash
 103
 104 This is the ``hash algorithm to use for signing.'' option.
 105 This option takes an argument string.
 106 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
 107 @anchor{danetool inder}
 108 @subheading inder option
 109 @cindex danetool-inder
 110
 111 This is the ``use der format for input certificates and private keys.'' option.
 112 The input files will be assumed to be in DER or RAW format.
 113 Unlike options that in PEM input would allow multiple input data (e.g. multiple
 114 certificates), when reading in DER format a single data structure is read.
 115 @anchor{danetool inraw}
 116 @subheading inraw option
 117 @cindex danetool-inraw
 118
 119 This is an alias for the inder option,
 120 @pxref{danetool inder, the inder option documentation}.
 121
 122 @anchor{danetool tlsa-rr}
 123 @subheading tlsa-rr option
 124 @cindex danetool-tlsa-rr
 125
 126 This is the ``print the dane rr data on a certificate or public key'' option.
 127
 128 @noindent
 129 This option has some usage constraints.  It:
 130 @itemize @bullet
 131 @item
 132 must appear in combination with the following options:
 133 host.
 134 @end itemize
 135
 136 This command prints the DANE RR data needed to enable DANE on a DNS server.
 137 @anchor{danetool host}
 138 @subheading host option
 139 @cindex danetool-host
 140
 141 This is the ``specify the hostname to be used in the dane rr'' option.
 142 This option takes an argument string @file{Hostname}.
 143 This command sets the hostname for the DANE RR.
 144 @anchor{danetool proto}
 145 @subheading proto option
 146 @cindex danetool-proto
 147
 148 This is the ``the protocol set for dane data (tcp, udp etc.)'' option.
 149 This option takes an argument string @file{Protocol}.
 150 This command specifies the protocol for the service set in the DANE data.
 151 @anchor{danetool ca}
 152 @subheading ca option
 153 @cindex danetool-ca
 154
 155 This is the ``whether the provided certificate or public key is a certificate authority.'' option.
 156 Marks the DANE RR as a CA certificate if specified.
 157 @anchor{danetool x509}
 158 @subheading x509 option
 159 @cindex danetool-x509
 160
 161 This is the ``use the hash of the x.509 certificate, rather than the public key.'' option.
 162 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.
 163 @anchor{danetool local}
 164 @subheading local option
 165 @cindex danetool-local
 166
 167 This is the ``the provided certificate or public key is a local entity.'' option.
 168 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.
 169 @anchor{danetool exit status}
 170 @subheading danetool exit status
 171
 172 One of the following exit values will be returned:
 173 @table @samp
 174 @item 0 (EXIT_SUCCESS)
 175 Successful program execution.
 176 @item 1 (EXIT_FAILURE)
 177 The operation failed or the command syntax was not valid.
 178 @end table
 179 @anchor{danetool See Also}
 180 @subheading danetool See Also
 181     p11tool (1)
 182
 183 @anchor{danetool Examples}
 184 @subheading danetool Examples
 185 @subheading DANE TLSA RR generation
 186
 187 To create a DANE TLSA resource record for a CA signed certificate use the following commands.
 188
 189 @example
 190 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem
 191 @end example
 192
 193 For a self signed certificate use:
 194 @example
 195 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 196   --local
 197 @end example
 198
 199 The latter is useful to add in your DNS entry even if your certificate is signed
 200 by a CA. That way even users who do not trust your CA will be able to verify your
 201 certificate using DANE.
 202
 203 In order to create a record for the signer of your certificate use:
 204 @example
 205 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
 206   --ca
 207 @end example
 208
 209 To read a server's DANE TLSA entry, using the dig tool, use:
 210 @example
 211 $ dig +short TYPE52 _443._tcp.www.example.com
 212 @end example
 213