/*
* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, you can obtain one at https://mozilla.org/MPL/2.0/.
*
* See the COPYRIGHT file distributed with this work for additional
* information regarding copyright ownership.
*/
#ifndef DNS_TKEY_H
#define DNS_TKEY_H 1
/*! \file dns/tkey.h */
#include <inttypes.h>
#include <stdbool.h>
#include <isc/lang.h>
#include <dns/types.h>
#include <dst/dst.h>
#include <dst/gssapi.h>
ISC_LANG_BEGINDECLS
/* Key agreement modes */
#define DNS_TKEYMODE_SERVERASSIGNED 1
#define DNS_TKEYMODE_DIFFIEHELLMAN 2
#define DNS_TKEYMODE_GSSAPI 3
#define DNS_TKEYMODE_RESOLVERASSIGNED 4
#define DNS_TKEYMODE_DELETE 5
struct dns_tkeyctx {
dst_key_t *dhkey;
dns_name_t *domain;
dns_gss_cred_id_t gsscred;
isc_mem_t *mctx;
char *gssapi_keytab;
};
isc_result_t
dns_tkeyctx_create(isc_mem_t *mctx, dns_tkeyctx_t **tctxp);
/*%<
* Create an empty TKEY context.
*
* Requires:
*\li 'mctx' is not NULL
*\li 'tctx' is not NULL
*\li '*tctx' is NULL
*
* Returns
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOMEMORY
*\li return codes from dns_name_fromtext()
*/
void
dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp);
/*%<
* Frees all data associated with the TKEY context
*
* Requires:
*\li 'tctx' is not NULL
*\li '*tctx' is not NULL
*/
isc_result_t
dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx,
dns_tsig_keyring_t *ring);
/*%<
* Processes a query containing a TKEY record, adding or deleting TSIG
* keys if necessary, and modifies the message to contain the response.
*
* Requires:
*\li 'msg' is a valid message
*\li 'tctx' is a valid TKEY context
*\li 'ring' is a valid TSIG keyring
*
* Returns
*\li #ISC_R_SUCCESS msg was updated (the TKEY operation succeeded,
* or msg now includes a TKEY with an error set)
* DNS_R_FORMERR the packet was malformed (missing a TKEY
* or KEY).
*\li other An error occurred while processing the message
*/
isc_result_t
dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key,
const dns_name_t *name, const dns_name_t *algorithm,
isc_buffer_t *nonce, uint32_t lifetime);
/*%<
* Builds a query containing a TKEY that will generate a shared
* secret using a Diffie-Hellman key exchange. The shared key
* will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME
* is supported), and will be named either 'name',
* 'name' + server chosen domain, or random data + server chosen domain
* if 'name' == dns_rootname. If nonce is not NULL, it supplies
* random data used in the shared secret computation. The key is
* requested to have the specified lifetime (in seconds)
*
*
* Requires:
*\li 'msg' is a valid message
*\li 'key' is a valid Diffie Hellman dst key
*\li 'name' is a valid name
*\li 'algorithm' is a valid name
*
* Returns:
*\li #ISC_R_SUCCESS msg was successfully updated to include the
* query to be sent
*\li other an error occurred while building the message
*/
isc_result_t
dns_tkey_buildgssquery(dns_message_t *msg, const dns_name_t *name,
const dns_name_t *gname, isc_buffer_t *intoken,
uint32_t lifetime, dns_gss_ctx_id_t *context, bool win2k,
isc_mem_t *mctx, char **err_message);
/*%<
* Builds a query containing a TKEY that will generate a GSSAPI context.
* The key is requested to have the specified lifetime (in seconds).
*
* Requires:
*\li 'msg' is a valid message
*\li 'name' is a valid name
*\li 'gname' is a valid name
*\li 'context' is a pointer to a valid gss_ctx_id_t
* (which may have the value GSS_C_NO_CONTEXT)
*\li 'win2k' when true says to turn on some hacks to work
* with the non-standard GSS-TSIG of Windows 2000
*
* Returns:
*\li ISC_R_SUCCESS msg was successfully updated to include the
* query to be sent
*\li other an error occurred while building the message
*\li *err_message optional error message
*/
isc_result_t
dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key);
/*%<
* Builds a query containing a TKEY record that will delete the
* specified shared secret from the server.
*
* Requires:
*\li 'msg' is a valid message
*\li 'key' is a valid TSIG key
*
* Returns:
*\li #ISC_R_SUCCESS msg was successfully updated to include the
* query to be sent
*\li other an error occurred while building the message
*/
isc_result_t
dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg,
dst_key_t *key, isc_buffer_t *nonce,
dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
/*%<
* Processes a response to a query containing a TKEY that was
* designed to generate a shared secret using a Diffie-Hellman key
* exchange. If the query was successful, a new shared key
* is created and added to the list of shared keys.
*
* Requires:
*\li 'qmsg' is a valid message (the query)
*\li 'rmsg' is a valid message (the response)
*\li 'key' is a valid Diffie Hellman dst key
*\li 'outkey' is either NULL or a pointer to NULL
*\li 'ring' is a valid keyring or NULL
*
* Returns:
*\li #ISC_R_SUCCESS the shared key was successfully added
*\li #ISC_R_NOTFOUND an error occurred while looking for a
* component of the query or response
*/
isc_result_t
dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg,
const dns_name_t *gname, dns_gss_ctx_id_t *context,
isc_buffer_t *outtoken, dns_tsigkey_t **outkey,
dns_tsig_keyring_t *ring, char **err_message);
/*%<
* XXX
*/
isc_result_t
dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg,
dns_tsig_keyring_t *ring);
/*%<
* Processes a response to a query containing a TKEY that was
* designed to delete a shared secret. If the query was successful,
* the shared key is deleted from the list of shared keys.
*
* Requires:
*\li 'qmsg' is a valid message (the query)
*\li 'rmsg' is a valid message (the response)
*\li 'ring' is not NULL
*
* Returns:
*\li #ISC_R_SUCCESS the shared key was successfully deleted
*\li #ISC_R_NOTFOUND an error occurred while looking for a
* component of the query or response
*/
isc_result_t
dns_tkey_gssnegotiate(dns_message_t *qmsg, dns_message_t *rmsg,
const dns_name_t *server, dns_gss_ctx_id_t *context,
dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring,
bool win2k, char **err_message);
/*
* Client side negotiation of GSS-TSIG. Process the response
* to a TKEY, and establish a TSIG key if negotiation was successful.
* Build a response to the input TKEY message. Can take multiple
* calls to successfully establish the context.
*
* Requires:
* 'qmsg' is a valid message, the original TKEY request;
* it will be filled with the new message to send
* 'rmsg' is a valid message, the incoming TKEY message
* 'server' is the server name
* 'context' is the input context handle
* 'outkey' receives the established key, if non-NULL;
* if non-NULL must point to NULL
* 'ring' is the keyring in which to establish the key,
* or NULL
* 'win2k' when true says to turn on some hacks to work
* with the non-standard GSS-TSIG of Windows 2000
*
* Returns:
* ISC_R_SUCCESS context was successfully established
* ISC_R_NOTFOUND couldn't find a needed part of the query
* or response
* DNS_R_CONTINUE additional context negotiation is required;
* send the new qmsg to the server
*/
ISC_LANG_ENDDECLS
#endif /* DNS_TKEY_H */
