external/bsd/libbind/dist/doc/tsig.man3

   1 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (c) 1995-1999 by Internet Software Consortium
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  14 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" Id: tsig.man3,v 1.2 2009/01/21 00:12:34 each Exp
  17 .\"
  18 .Dd January 1, 1996
  19 .Os BSD 4
  20 .Dt TSIG
  21 .Sh NAME
  22 .Nm ns_sign ,
  23 .Nm ns_sign_tcp ,
  24 .Nm ns_sign_tcp_init ,
  25 .Nm ns_verify ,
  26 .Nm ns_verify_tcp ,
  27 .Nm ns_verify_tcp_init ,
  28 .Nm ns_find_tsig
  29 .Nd TSIG system
  30 .Sh SYNOPSIS
  31 .Ft int
  32 .Fo ns_sign
  33 .Fa "u_char *msg"
  34 .Fa "int *msglen"
  35 .Fa "int msgsize"
  36 .Fa "int error"
  37 .Fa "void *k"
  38 .Fa "const u_char *querysig"
  39 .Fa "int querysiglen"
  40 .Fa "u_char *sig"
  41 .Fa "int *siglen"
  42 .Fa "time_t in_timesigned"
  43 .Fc
  44 .Ft int
  45 .Fn ns_sign_tcp "u_char *msg" "int *msglen" "int msgsize" "int error" \
  46     "ns_tcp_tsig_state *state" "int done"
  47 .Ft int
  48 .Fn ns_sign_tcp_init "void *k" "const u_char *querysig" "int querysiglen" \
  49     "ns_tcp_tsig_state *state"
  50 .Ft int
  51 .Fo ns_verify
  52 .Fa "u_char *msg"
  53 .Fa "int *msglen"
  54 .Fa "void *k"
  55 .Fa "const u_char *querysig"
  56 .Fa "int querysiglen"
  57 .Fa "u_char *sig"
  58 .Fa "int *siglen"
  59 .Fa "time_t in_timesigned"
  60 .Fa "int nostrip"
  61 .Fc
  62 .Ft int
  63 .Fn ns_verify_tcp "u_char *msg" "int *msglen" "ns_tcp_tsig_state *state" \
  64     "int required"
  65 .Ft int
  66 .Fn ns_verify_tcp_init "void *k" "const u_char *querysig" "int querysiglen" \
  67     "ns_tcp_tsig_state *state"
  68 .Ft u_char *
  69 .Fn ns_find_tsig "u_char *msg" "u_char *eom"
  70 .Sh DESCRIPTION
  71 The TSIG routines are used to implement transaction/request security of
  72 DNS messages.
  73 .Pp
  74 .Fn ns_sign
  75 and
  76 .Fn ns_verify
  77 are the basic routines.
  78 .Fn ns_sign_tcp
  79 and
  80 .Fn ns_verify_tcp
  81 are used to sign/verify TCP messages that may be split into multiple packets,
  82 such as zone transfers, and
  83 .Fn ns_sign_tcp_init ,
  84 .Fn ns_verify_tcp_init
  85 initialize the state structure necessary for TCP operations.
  86 .Fn ns_find_tsig
  87 locates the TSIG record in a message, if one is present.
  88 .Pp
  89 .Fn ns_sign
  90 .Bl -tag -width "in_timesigned" -compact -offset indent
  91 .It Dv msg
  92 the incoming DNS message, which will be modified
  93 .It Dv msglen
  94 the length of the DNS message, on input and output
  95 .It Dv msgsize
  96 the size of the buffer containing the DNS message on input
  97 .It Dv error
  98 the value to be placed in the TSIG error field
  99 .It Dv key
 100 the (DST_KEY *) to sign the data
 101 .It Dv querysig
 102 for a response, the signature contained in the query
 103 .It Dv querysiglen
 104 the length of the query signature
 105 .It Dv sig
 106 a buffer to be filled with the generated signature
 107 .It Dv siglen
 108 the length of the signature buffer on input, the signature length on output
 109 .El
 110 .Pp
 111 .Fn ns_sign_tcp
 112 .Bl -tag -width "in_timesigned" -compact -offset indent
 113 .It Dv msg
 114 the incoming DNS message, which will be modified
 115 .It Dv msglen
 116 the length of the DNS message, on input and output
 117 .It Dv msgsize
 118 the size of the buffer containing the DNS message on input
 119 .It Dv error
 120 the value to be placed in the TSIG error field
 121 .It Dv state
 122 the state of the operation
 123 .It Dv done
 124 non-zero value signifies that this is the last packet
 125 .El
 126 .Pp
 127 .Fn ns_sign_tcp_init
 128 .Bl -tag -width "in_timesigned" -compact -offset indent
 129 .It Dv k
 130 the (DST_KEY *) to sign the data
 131 .It Dv querysig
 132 for a response, the signature contained in the query
 133 .It Dv querysiglen
 134 the length of the query signature
 135 .It Dv state
 136 the state of the operation, which this initializes
 137 .El
 138 .Pp
 139 .Fn ns_verify
 140 .Bl -tag -width "in_timesigned" -compact -offset indent
 141 .It Dv msg
 142 the incoming DNS message, which will be modified
 143 .It Dv msglen
 144 the length of the DNS message, on input and output
 145 .It Dv key
 146 the (DST_KEY *) to sign the data
 147 .It Dv querysig
 148 for a response, the signature contained in the query
 149 .It Dv querysiglen
 150 the length of the query signature
 151 .It Dv sig
 152 a buffer to be filled with the signature contained
 153 .It Dv siglen
 154 the length of the signature buffer on input, the signature length on output
 155 .It Dv nostrip
 156 non-zero value means that the TSIG is left intact
 157 .El
 158 .Pp
 159 .Fn ns_verify_tcp
 160 .Bl -tag -width "in_timesigned" -compact -offset indent
 161 .It Dv msg
 162 the incoming DNS message, which will be modified
 163 .It Dv msglen
 164 the length of the DNS message, on input and output
 165 .It Dv state
 166 the state of the operation
 167 .It Dv required
 168 non-zero value signifies that a TSIG record must be present at this step
 169 .El
 170 .Pp
 171 .Fn ns_verify_tcp_init
 172 .Bl -tag -width "in_timesigned" -compact -offset indent
 173 .It Dv k
 174 the (DST_KEY *) to verify the data
 175 .It Dv querysig
 176 for a response, the signature contained in the query
 177 .It Dv querysiglen
 178 the length of the query signature
 179 .It Dv state
 180 the state of the operation, which this initializes
 181 .El
 182 .Pp
 183 .Fn ns_find_tsig
 184 .Bl -tag -width "in_timesigned" -compact -offset indent
 185 .It Dv msg
 186 the incoming DNS message
 187 .It Dv msglen
 188 the length of the DNS message
 189 .El
 190 .Sh RETURN VALUES
 191 .Fn ns_find_tsig
 192 returns a pointer to the TSIG record if one is found, and NULL otherwise.
 193 .Pp
 194 All other routines return 0 on success, modifying arguments when necessary.
 195 .Pp
 196 .Fn ns_sign
 197 and
 198 .Fn ns_sign_tcp
 199 return the following errors:
 200 .Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent
 201 .It Dv (-1)
 202 bad input data
 203 .It Dv (-ns_r_badkey)
 204 The key was invalid, or the signing failed
 205 .It Dv NS_TSIG_ERROR_NO_SPACE
 206 the message buffer is too small.
 207 .El
 208 .Pp
 209 .Fn ns_verify
 210 and
 211 .Fn ns_verify_tcp
 212 return the following errors:
 213 .Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent
 214 .It Dv (-1)
 215 bad input data
 216 .It Dv NS_TSIG_ERROR_FORMERR
 217 The message is malformed
 218 .It Dv NS_TSIG_ERROR_NO_TSIG
 219 The message does not contain a TSIG record
 220 .It Dv NS_TSIG_ERROR_ID_MISMATCH
 221 The TSIG original ID field does not match the message ID
 222 .It Dv (-ns_r_badkey)
 223 Verification failed due to an invalid key
 224 .It Dv (-ns_r_badsig)
 225 Verification failed due to an invalid signature
 226 .It Dv (-ns_r_badtime)
 227 Verification failed due to an invalid timestamp
 228 .It Dv ns_r_badkey
 229 Verification succeeded but the message had an error of BADKEY
 230 .It Dv ns_r_badsig
 231 Verification succeeded but the message had an error of BADSIG
 232 .It Dv ns_r_badtime
 233 Verification succeeded but the message had an error of BADTIME
 234 .El
 235 .Pp
 236 .Sh SEE ALSO
 237 .Xr resolver 3 .
 238 .Sh AUTHORS
 239 Brian Wellington, TISLabs at Network Associates
 240 .\" .Sh BUGS