doc/invoke-danetool.texi

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