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