res_nsendsigned()--Send Authenticated Domain Query or Update

 #include <sys/types.h>
 #include <netinet/in.h>
 #include <arpa/nameser.h>
 #include <resolv.h>

 int res_nsendsigned(state* res,
              const unsigned char *query_buffer,  
              int  query_buffer_length,
              ns_tsig_key * key,
              unsigned char *answer_buffer,
              int  answer_buffer_length)

The res_nsendsigned() function is similar to res_nsend() but it uses the specified key to create a transaction signature (TSIG) to sign the query or update packet and to authenticate the response.

Parameters

res

(Input) The pointer to the state structure.

query_buffer

(Input) The pointer to the query or update message.

query_buffer_length

(Input) The length of query_buffer.

key

(Input) The pointer to the key to use for authentication. This key must exist on the name server.

answer_buffer

(Output) The pointer to where the response is stored.

answer_buffer_length

(Input) The size of the answer_buffer.

Authorities

No authorization is required.

Return Value

res_nsendsigned() returns an integer. Possible values are:

• n (successful), where n is the actual size of the answer returned.
  
  
• -1 (unsuccessful)
  
  
• -ns_r_badkey (unsuccessful) The key was invalid or the signing failed.
  
  
• NS_TSIG_ERROR_NO_SPACE (unsuccessful) The message buffer was too small to add the TSIG.

Error Conditions

When the res_nsendsigned() function fails, res_nsendsigned() can set errno to one of the following:

[ECONNREFUSED]

Not able to connect to a server.

[ECONVERT]

Either the input packet could not be translated to ASCII or the answer received could not be translated to the coded character set identifier (CCSID) currently in effect for the job.

[EFAULT]

The system detected a pointer that was invalid while attempting to access an input pointer.

[EINVAL]

One of the following reasons:

• An invalid length or NULL pointer was passed to res_nsendsigned()

• The res appears to be initialized but the reserved field is not set to zeros.

Note: No attempt is made to initialize the res structure if it was initialized previous to the res_nsendsigned() being issued.

[EMSGSIZE]

The message buffer was too small to add the TSIG. The return value was NS_TSIG_ERROR_NO_SPACE.

[ENOTTY]

The message or reply couldn't be verified. See extended_error in the res structure:

NS_TSIG_ERROR_FORMERR

The message is malformed.

NS_TSIG_ERROR_NO_TSIG

The message does not contain a TSIG record.

NS_TSIG_ERROR_ID_MISMATCH

The TSIG original ID field does not match the message ID.

(-ns_r_badkey)

Verification failed due to an invalid key.

(-ns_r_badsig)

Verification failed due to an invalid signature.

(-ns_r_badtime)

Verification failed due to an invalid timestamp.

ns_r_badkey

Verification succeeded but the message had an error (rcode) of ns_r_badkey.

ns_r_badsig

Verification succeeded but the message had an error (rcode) of ns_r_badsig.

ns_r_badtime

Verification succeeded but the message had an error (rcode) of ns_r_badtime.

[ETIMEDOUT]

A timeout received from a connected server.

When the res_nsearch() function fails, h_errno (defined in <netdb.h>) can also be set to one of the following:

HOST_NOT_FOUND

Either the input packet could not be translated to ASCII or the answer received could not be translated to the coded character set identifier (CCSID) currently in effect for the job.

NO_RECOVERY

An invalid length or NULL pointer was passed to res_nsendsigned() or the res could not be initialized properly.

Notes:

• No attempt is made to initialize the res structure if it was initialized previous to the res_nsendsigned() being issued.
  
  
• There are numerous other values that errno can be set to by the sockets functions that res_nsendsigned() calls. The above values are the only values that res_nsendsigned() can specifically set. Refer to other sockets functions for the other values. errno is always set in an error condition, but h_errno is not necessarily set.

  After receiving an error reply packet, res_nsendsigned() will set the extended_error field in the state structure to the last reply return code from the DNS server. See <arpa/nameser.h> for all possible values of ns_rcode.

Usage Notes

1. res_nsendsigned() sends the query or update to the local name server and handles all timeouts and retries. The response packet is stored in answer_buffer.
   
   
2. res_nsendsigned() calls res_ninit() if the res structure has not been initialized.
   
   
3. res_nsendsigned() uses the UDP protocol, except for the following cases in which it uses TCP to send the packet.
   
   • If the RES_USEVC or RES_STAYOPEN bits are set in the options field of the res structure.
     
     
   • If the configuration from Change TCP/IP Domain (CHGTCPDMN) specifies that the server protocol is TCP.
     
     
   • If the truncation bit is set in the packet header on the response from a UDP packet, and RES_IGNTC is not set in the res structure.
   
   
4. res_nsendsigned() does not perform iterative queries and expects the name server to handle recursion.
   
   
5. res_nsendsigned() assumes that the data passed to it is EBCDIC and is in the default coded character set identifier (CCSID) currently in effect for the job. It translates the data from the default CCSID currently in effect for the job to ASCII (CCSID 819) before the data is sent out to a name server. The response that it receives from the name server is returned in the default CCSID currently in effect for the job.
   
   
6. res_nsendsigned() will not use the local cache. It will always send the packet to the server.
   
   
7. When using TSIG, it is important that the QUTCOFFSET system value is set correctly for the local time zone. The resolver system and name server timestamps must be within 5 minutes of each other (adjusted by the UTC offset) or the authentication will fail with ns_r_badtime.

Related Information

• hstrerror()--Retrieve Resolver Error Message
  
  
• res_nclose()--Close Socket and Reset res Structure
  
  
• res_findzonecut()--Find the Enclosing Zone and Servers
  
  
• res_hostalias()--Retrieve the host alias
  
  
• res_ninit()--Initialize res Structure
  
  
• res_nmkquery()--Place Domain Query in Buffer
  
  
• res_nmkupdate()--Construct an Update Packet
  
  
• res_nquery()--Send Domain Query
  
  
• res_nsearch()--Search for Domain Name
  
  
• res_nsend()--Send Buffered Domain Query
  
  
• res_nupdate()--Build and Send Dynamic Updates
  
  
• res_xlate()--Translate DNS Packets

[ Back to top | UNIX-Type APIs | APIs by category ]