tkey.h revision 135446 
1/*
2 * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2001  Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and 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
18/* $Id: tkey.h,v 1.18.206.1 2004/03/06 08:14:00 marka Exp $ */
19
20#ifndef DNS_TKEY_H
21#define DNS_TKEY_H 1
22
23#include <isc/lang.h>
24
25#include <dns/types.h>
26
27#include <dst/dst.h>
28
29ISC_LANG_BEGINDECLS
30
31/* Key agreement modes */
32#define DNS_TKEYMODE_SERVERASSIGNED		1
33#define DNS_TKEYMODE_DIFFIEHELLMAN		2
34#define DNS_TKEYMODE_GSSAPI			3
35#define DNS_TKEYMODE_RESOLVERASSIGNED		4
36#define DNS_TKEYMODE_DELETE			5
37
38struct dns_tkeyctx {
39	dst_key_t *dhkey;
40	dns_name_t *domain;
41	void *gsscred;
42	isc_mem_t *mctx;
43	isc_entropy_t *ectx;
44};
45
46isc_result_t
47dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx, dns_tkeyctx_t **tctxp);
48/*
49 *	Create an empty TKEY context.
50 *
51 * 	Requires:
52 *		'mctx' is not NULL
53 *		'tctx' is not NULL
54 *		'*tctx' is NULL
55 *
56 *	Returns
57 *		ISC_R_SUCCESS
58 *		ISC_R_NOMEMORY
59 *		return codes from dns_name_fromtext()
60 */
61
62void
63dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp);
64/*
65 *      Frees all data associated with the TKEY context
66 *
67 * 	Requires:
68 *		'tctx' is not NULL
69 *		'*tctx' is not NULL
70 */
71
72isc_result_t
73dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx,
74		      dns_tsig_keyring_t *ring);
75/*
76 *	Processes a query containing a TKEY record, adding or deleting TSIG
77 *	keys if necessary, and modifies the message to contain the response.
78 *
79 *	Requires:
80 *		'msg' is a valid message
81 *		'tctx' is a valid TKEY context
82 *		'ring' is a valid TSIG keyring
83 *
84 *	Returns
85 *		ISC_R_SUCCESS	msg was updated (the TKEY operation succeeded,
86 *				or msg now includes a TKEY with an error set)
87 *		DNS_R_FORMERR	the packet was malformed (missing a TKEY
88 *				or KEY).
89 *		other		An error occurred while processing the message
90 */
91
92isc_result_t
93dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name,
94		      dns_name_t *algorithm, isc_buffer_t *nonce,
95		      isc_uint32_t lifetime);
96/*
97 *	Builds a query containing a TKEY that will generate a shared
98 *	secret using a Diffie-Hellman key exchange.  The shared key
99 *	will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME
100 *	is supported), and will be named either 'name',
101 *	'name' + server chosen domain, or random data + server chosen domain
102 *	if 'name' == dns_rootname.  If nonce is not NULL, it supplies
103 *	random data used in the shared secret computation.  The key is
104 *	requested to have the specified lifetime (in seconds)
105 *
106 *
107 *	Requires:
108 *		'msg' is a valid message
109 *		'key' is a valid Diffie Hellman dst key
110 *		'name' is a valid name
111 *		'algorithm' is a valid name
112 *
113 *	Returns:
114 *		ISC_R_SUCCESS	msg was successfully updated to include the
115 *				query to be sent
116 *		other		an error occurred while building the message
117 */
118
119isc_result_t
120dns_tkey_buildgssquery(dns_message_t *msg, dns_name_t *name,
121		       dns_name_t *gname, void *cred,
122		       isc_uint32_t lifetime, void **context);
123/*
124 * XXX
125 */
126
127isc_result_t
128dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key);
129/*
130 *	Builds a query containing a TKEY record that will delete the
131 *	specified shared secret from the server.
132 *
133 *	Requires:
134 *		'msg' is a valid message
135 *		'key' is a valid TSIG key
136 *
137 *	Returns:
138 *		ISC_R_SUCCESS	msg was successfully updated to include the
139 *				query to be sent
140 *		other		an error occurred while building the message
141 */
142
143isc_result_t
144dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg,
145                           dst_key_t *key, isc_buffer_t *nonce,
146			   dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
147/*
148 *	Processes a response to a query containing a TKEY that was
149 *	designed to generate a shared secret using a Diffie-Hellman key
150 *	exchange.  If the query was successful, a new shared key
151 *	is created and added to the list of shared keys.
152 *
153 *	Requires:
154 *		'qmsg' is a valid message (the query)
155 *		'rmsg' is a valid message (the response)
156 *		'key' is a valid Diffie Hellman dst key
157 *		'outkey' is either NULL or a pointer to NULL
158 *		'ring' is a valid keyring or NULL
159 *
160 *	Returns:
161 *		ISC_R_SUCCESS	the shared key was successfully added
162 *		ISC_R_NOTFOUND	an error occurred while looking for a
163 *				component of the query or response
164 */
165
166isc_result_t
167dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg,
168			    dns_name_t *gname, void *cred, void **context,
169			    dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
170/*
171 * XXX
172 */
173
174isc_result_t
175dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg,
176			       dns_tsig_keyring_t *ring);
177/*
178 *	Processes a response to a query containing a TKEY that was
179 *	designed to delete a shared secret.  If the query was successful,
180 *	the shared key is deleted from the list of shared keys.
181 *
182 *	Requires:
183 *		'qmsg' is a valid message (the query)
184 *		'rmsg' is a valid message (the response)
185 *		'ring' is not NULL
186 *
187 *	Returns:
188 *		ISC_R_SUCCESS	the shared key was successfully deleted
189 *		ISC_R_NOTFOUND	an error occurred while looking for a
190 *				component of the query or response
191 */
192
193
194ISC_LANG_ENDDECLS
195
196#endif /* DNS_TKEY_H */
197