res_nsendsigned()--Send Authenticated Domain Query or Update

Syntax

 #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)

  Service Program Name: QSOSRV2

  Default Public Authority: *USE

  Threadsafe: Yes

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

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.
res_nsendsigned() calls res_ninit() if the res structure has not been initialized.
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.
res_nsendsigned() does not perform iterative queries and expects the name server to handle recursion.
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.
res_nsendsigned() will not use the local cache. It will always send the packet to the server.
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

API introduced: V5R1

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