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 71The TSIG routines are used to implement transaction/request security of 72DNS messages. 73.Pp 74.Fn ns_sign 75and 76.Fn ns_verify 77are the basic routines. 78.Fn ns_sign_tcp 79and 80.Fn ns_verify_tcp 81are used to sign/verify TCP messages that may be split into multiple packets, 82such as zone transfers, and 83.Fn ns_sign_tcp_init , 84.Fn ns_verify_tcp_init 85initialize the state structure necessary for TCP operations. 86.Fn ns_find_tsig 87locates 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 92the incoming DNS message, which will be modified 93.It Dv msglen 94the length of the DNS message, on input and output 95.It Dv msgsize 96the size of the buffer containing the DNS message on input 97.It Dv error 98the value to be placed in the TSIG error field 99.It Dv key 100the (DST_KEY *) to sign the data 101.It Dv querysig 102for a response, the signature contained in the query 103.It Dv querysiglen 104the length of the query signature 105.It Dv sig 106a buffer to be filled with the generated signature 107.It Dv siglen 108the 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 114the incoming DNS message, which will be modified 115.It Dv msglen 116the length of the DNS message, on input and output 117.It Dv msgsize 118the size of the buffer containing the DNS message on input 119.It Dv error 120the value to be placed in the TSIG error field 121.It Dv state 122the state of the operation 123.It Dv done 124non-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 130the (DST_KEY *) to sign the data 131.It Dv querysig 132for a response, the signature contained in the query 133.It Dv querysiglen 134the length of the query signature 135.It Dv state 136the 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 142the incoming DNS message, which will be modified 143.It Dv msglen 144the length of the DNS message, on input and output 145.It Dv key 146the (DST_KEY *) to sign the data 147.It Dv querysig 148for a response, the signature contained in the query 149.It Dv querysiglen 150the length of the query signature 151.It Dv sig 152a buffer to be filled with the signature contained 153.It Dv siglen 154the length of the signature buffer on input, the signature length on output 155.It Dv nostrip 156non-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 162the incoming DNS message, which will be modified 163.It Dv msglen 164the length of the DNS message, on input and output 165.It Dv state 166the state of the operation 167.It Dv required 168non-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 174the (DST_KEY *) to verify the data 175.It Dv querysig 176for a response, the signature contained in the query 177.It Dv querysiglen 178the length of the query signature 179.It Dv state 180the 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 186the incoming DNS message 187.It Dv msglen 188the length of the DNS message 189.El 190.Sh RETURN VALUES 191.Fn ns_find_tsig 192returns a pointer to the TSIG record if one is found, and NULL otherwise. 193.Pp 194All other routines return 0 on success, modifying arguments when necessary. 195.Pp 196.Fn ns_sign 197and 198.Fn ns_sign_tcp 199return the following errors: 200.Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent 201.It Dv (-1) 202bad input data 203.It Dv (-ns_r_badkey) 204The key was invalid, or the signing failed 205.It Dv NS_TSIG_ERROR_NO_SPACE 206the message buffer is too small. 207.El 208.Pp 209.Fn ns_verify 210and 211.Fn ns_verify_tcp 212return the following errors: 213.Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent 214.It Dv (-1) 215bad input data 216.It Dv NS_TSIG_ERROR_FORMERR 217The message is malformed 218.It Dv NS_TSIG_ERROR_NO_TSIG 219The message does not contain a TSIG record 220.It Dv NS_TSIG_ERROR_ID_MISMATCH 221The TSIG original ID field does not match the message ID 222.It Dv (-ns_r_badkey) 223Verification failed due to an invalid key 224.It Dv (-ns_r_badsig) 225Verification failed due to an invalid signature 226.It Dv (-ns_r_badtime) 227Verification failed due to an invalid timestamp 228.It Dv ns_r_badkey 229Verification succeeded but the message had an error of BADKEY 230.It Dv ns_r_badsig 231Verification succeeded but the message had an error of BADSIG 232.It Dv ns_r_badtime 233Verification succeeded but the message had an error of BADTIME 234.El 235.Pp 236.Sh SEE ALSO 237.Xr resolver 3 . 238.Sh AUTHORS 239Brian Wellington, TISLabs at Network Associates 240.\" .Sh BUGS 241