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

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