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

   1 TSIG                                 LOCAL                                TSIG
   2
   3 N\bNA\bAM\bME\bE
   4      n\bns\bs_\b_s\bsi\big\bgn\bn, n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp, n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt, n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by, n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp,
   5      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt, n\bns\bs_\b_f\bfi\bin\bnd\bd_\b_t\bts\bsi\big\bg - TSIG system
   6
   7 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   8      _\bi_\bn_\bt
   9      n\bns\bs_\b_s\bsi\big\bgn\bn(_\bu_\b__\bc_\bh_\ba_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\b*_\bm_\bs_\bg_\bl_\be_\bn, _\bi_\bn_\bt _\bm_\bs_\bg_\bs_\bi_\bz_\be, _\bi_\bn_\bt _\be_\br_\br_\bo_\br, _\bv_\bo_\bi_\bd _\b*_\bk,
  10              _\bc_\bo_\bn_\bs_\bt _\bu_\b__\bc_\bh_\ba_\br _\b*_\bq_\bu_\be_\br_\by_\bs_\bi_\bg, _\bi_\bn_\bt _\bq_\bu_\be_\br_\by_\bs_\bi_\bg_\bl_\be_\bn, _\bu_\b__\bc_\bh_\ba_\br _\b*_\bs_\bi_\bg,
  11              _\bi_\bn_\bt _\b*_\bs_\bi_\bg_\bl_\be_\bn, _\bt_\bi_\bm_\be_\b__\bt _\bi_\bn_\b__\bt_\bi_\bm_\be_\bs_\bi_\bg_\bn_\be_\bd);
  12
  13      _\bi_\bn_\bt
  14      n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp(_\bu_\b__\bc_\bh_\ba_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\b*_\bm_\bs_\bg_\bl_\be_\bn, _\bi_\bn_\bt _\bm_\bs_\bg_\bs_\bi_\bz_\be, _\bi_\bn_\bt _\be_\br_\br_\bo_\br,
  15              _\bn_\bs_\b__\bt_\bc_\bp_\b__\bt_\bs_\bi_\bg_\b__\bs_\bt_\ba_\bt_\be _\b*_\bs_\bt_\ba_\bt_\be, _\bi_\bn_\bt _\bd_\bo_\bn_\be);
  16
  17      _\bi_\bn_\bt
  18      n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt(_\bv_\bo_\bi_\bd _\b*_\bk, _\bc_\bo_\bn_\bs_\bt _\bu_\b__\bc_\bh_\ba_\br _\b*_\bq_\bu_\be_\br_\by_\bs_\bi_\bg, _\bi_\bn_\bt _\bq_\bu_\be_\br_\by_\bs_\bi_\bg_\bl_\be_\bn,
  19              _\bn_\bs_\b__\bt_\bc_\bp_\b__\bt_\bs_\bi_\bg_\b__\bs_\bt_\ba_\bt_\be _\b*_\bs_\bt_\ba_\bt_\be);
  20
  21      _\bi_\bn_\bt
  22      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by(_\bu_\b__\bc_\bh_\ba_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\b*_\bm_\bs_\bg_\bl_\be_\bn, _\bv_\bo_\bi_\bd _\b*_\bk, _\bc_\bo_\bn_\bs_\bt _\bu_\b__\bc_\bh_\ba_\br _\b*_\bq_\bu_\be_\br_\by_\bs_\bi_\bg,
  23              _\bi_\bn_\bt _\bq_\bu_\be_\br_\by_\bs_\bi_\bg_\bl_\be_\bn, _\bu_\b__\bc_\bh_\ba_\br _\b*_\bs_\bi_\bg, _\bi_\bn_\bt _\b*_\bs_\bi_\bg_\bl_\be_\bn, _\bt_\bi_\bm_\be_\b__\bt _\bi_\bn_\b__\bt_\bi_\bm_\be_\bs_\bi_\bg_\bn_\be_\bd,
  24              _\bi_\bn_\bt _\bn_\bo_\bs_\bt_\br_\bi_\bp);
  25
  26      _\bi_\bn_\bt
  27      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp(_\bu_\b__\bc_\bh_\ba_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\b*_\bm_\bs_\bg_\bl_\be_\bn, _\bn_\bs_\b__\bt_\bc_\bp_\b__\bt_\bs_\bi_\bg_\b__\bs_\bt_\ba_\bt_\be _\b*_\bs_\bt_\ba_\bt_\be,
  28              _\bi_\bn_\bt _\br_\be_\bq_\bu_\bi_\br_\be_\bd);
  29
  30      _\bi_\bn_\bt
  31      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt(_\bv_\bo_\bi_\bd _\b*_\bk, _\bc_\bo_\bn_\bs_\bt _\bu_\b__\bc_\bh_\ba_\br _\b*_\bq_\bu_\be_\br_\by_\bs_\bi_\bg, _\bi_\bn_\bt _\bq_\bu_\be_\br_\by_\bs_\bi_\bg_\bl_\be_\bn,
  32              _\bn_\bs_\b__\bt_\bc_\bp_\b__\bt_\bs_\bi_\bg_\b__\bs_\bt_\ba_\bt_\be _\b*_\bs_\bt_\ba_\bt_\be);
  33
  34      _\bu_\b__\bc_\bh_\ba_\br _\b*
  35      n\bns\bs_\b_f\bfi\bin\bnd\bd_\b_t\bts\bsi\big\bg(_\bu_\b__\bc_\bh_\ba_\br _\b*_\bm_\bs_\bg, _\bu_\b__\bc_\bh_\ba_\br _\b*_\be_\bo_\bm);
  36
  37 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  38      The TSIG routines are used to implement transaction/request security of
  39      DNS messages.
  40
  41      n\bns\bs_\b_s\bsi\big\bgn\bn() and n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by() are the basic routines.  n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp() and
  42      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp() are used to sign/verify TCP messages that may be split
  43      into multiple packets, such as zone transfers, and n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt(),
  44      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt() initialize the state structure necessary for TCP
  45      operations.  n\bns\bs_\b_f\bfi\bin\bnd\bd_\b_t\bts\bsi\big\bg() locates the TSIG record in a message, if one
  46      is present.
  47
  48      n\bns\bs_\b_s\bsi\big\bgn\bn()
  49            msg            the incoming DNS message, which will be modified
  50            msglen         the length of the DNS message, on input and output
  51            msgsize        the size of the buffer containing the DNS message on
  52                           input
  53            error          the value to be placed in the TSIG error field
  54            key            the (DST_KEY *) to sign the data
  55            querysig       for a response, the signature contained in the query
  56            querysiglen    the length of the query signature
  57            sig            a buffer to be filled with the generated signature
  58            siglen         the length of the signature buffer on input, the
  59                           signature length on output
  60
  61      n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp()
  62            msg            the incoming DNS message, which will be modified
  63            msglen         the length of the DNS message, on input and output
  64            msgsize        the size of the buffer containing the DNS message on
  65                           input
  66            error          the value to be placed in the TSIG error field
  67            state          the state of the operation
  68            done           non-zero value signifies that this is the last
  69                           packet
  70
  71      n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt()
  72            k              the (DST_KEY *) to sign the data
  73            querysig       for a response, the signature contained in the query
  74            querysiglen    the length of the query signature
  75            state          the state of the operation, which this initializes
  76
  77      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by()
  78            msg            the incoming DNS message, which will be modified
  79            msglen         the length of the DNS message, on input and output
  80            key            the (DST_KEY *) to sign the data
  81            querysig       for a response, the signature contained in the query
  82            querysiglen    the length of the query signature
  83            sig            a buffer to be filled with the signature contained
  84            siglen         the length of the signature buffer on input, the
  85                           signature length on output
  86            nostrip        non-zero value means that the TSIG is left intact
  87
  88      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp()
  89            msg            the incoming DNS message, which will be modified
  90            msglen         the length of the DNS message, on input and output
  91            state          the state of the operation
  92            required       non-zero value signifies that a TSIG record must be
  93                           present at this step
  94
  95      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp_\b_i\bin\bni\bit\bt()
  96            k              the (DST_KEY *) to verify the data
  97            querysig       for a response, the signature contained in the query
  98            querysiglen    the length of the query signature
  99            state          the state of the operation, which this initializes
 100
 101      n\bns\bs_\b_f\bfi\bin\bnd\bd_\b_t\bts\bsi\big\bg()
 102            msg            the incoming DNS message
 103            msglen         the length of the DNS message
 104
 105 R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS
 106      n\bns\bs_\b_f\bfi\bin\bnd\bd_\b_t\bts\bsi\big\bg() returns a pointer to the TSIG record if one is found, and
 107      NULL otherwise.
 108
 109      All other routines return 0 on success, modifying arguments when neces‐
 110      sary.
 111
 112      n\bns\bs_\b_s\bsi\big\bgn\bn() and n\bns\bs_\b_s\bsi\big\bgn\bn_\b_t\btc\bcp\bp() return the following errors:
 113            (-1)                    bad input data
 114            (-ns_r_badkey)          The key was invalid, or the signing failed
 115            NS_TSIG_ERROR_NO_SPACE  the message buffer is too small.
 116
 117      n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by() and n\bns\bs_\b_v\bve\ber\bri\bif\bfy\by_\b_t\btc\bcp\bp() return the following errors:
 118            (-1)                    bad input data
 119            NS_TSIG_ERROR_FORMERR   The message is malformed
 120            NS_TSIG_ERROR_NO_TSIG   The message does not contain a TSIG record
 121            NS_TSIG_ERROR_ID_MISMATCH
 122                                    The TSIG original ID field does not match
 123                                    the message ID
 124            (-ns_r_badkey)          Verification failed due to an invalid key
 125            (-ns_r_badsig)          Verification failed due to an invalid sig‐
 126                                    nature
 127            (-ns_r_badtime)         Verification failed due to an invalid
 128                                    timestamp
 129            ns_r_badkey             Verification succeeded but the message had
 130                                    an error of BADKEY
 131            ns_r_badsig             Verification succeeded but the message had
 132                                    an error of BADSIG
 133            ns_r_badtime            Verification succeeded but the message had
 134                                    an error of BADTIME
 135
 136 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
 137      resolver(3).
 138
 139 A\bAU\bUT\bTH\bHO\bOR\bRS\bS
 140      Brian Wellington, TISLabs at Network Associates
 141
 142 4th Berkeley Distribution       January 1, 1996      4th Berkeley Distribution