[thirdparty/dhcp.git] / omapip / omapi.3

.\"	omapi.3
.\"
.\" Copyright (c) 2000-2001 Internet Software Consortium.
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of The Internet Software Consortium nor the names
.\"    of its contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" This software has been written for the Internet Software Consortium
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
.\" To learn more about the Internet Software Consortium, see
.\" ``http://www.isc.org/''.  To learn more about Vixie Enterprises,
.\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
.\" ``http://www.nominum.com''.
.TH omapi 3
.SH NAME
OMAPI - Object Management Application Programming Interface
.SH DESCRIPTION
.PP
OMAPI is an programming layer designed for controlling remote
applications, and for querying them for their state. It is currently
used by the ISC DHCP server and this outline addresses the parts of
OMAPI appropriate to the clients of DHCP server. It does this by also
describing the use of a thin API layered on top of OMAPI called
'dhcpctl'
.PP
OMAPI uses TCP/IP as the transport for server communication, and
security can be imposed by having the client and server
cryptographically sign messages using a shared secret.
.PP
dhcpctl works by presenting the client with handles to objects that
act as surrogates for the real objects in the server. For example a
client will create a handle for a lease object, and will request the
server to fill the lease handle's state. The client application can
then pull details such as the lease expiration time from the lease
handle. 
.PP
Modifications can be made to the server state by creating handles to
new objects, or by modifying attributes of handles to existing
objects, and then instructing the server to update itself according to
the changes made.
.SH USAGE
.PP
The client application must always call dhcpctl_initialize() before
making calls to any other dhcpctl functions. This initializes 
various internal data structures. 
.PP
To create the connection to the server the client must use
dhcpctl_connect() function. As well as making the physical connection
it will also set up the connection data structures to do
authentication on each message, if that is required.
.PP
All the dhcpctl functions return an integer value of type
isc_result_t. A successful call will yield a result of
ISC_R_SUCCESS. If the call fails for a reason local to the client
(e.g. insufficient local memory, or invalid arguments to the call)
then the return value of the dhcpctl function will show that. If the
call succeeds but the server couldn't process the request the error
value from the server is returned through another way, shown below.
.PP
The easiest way to understand dhcpctl is to see it in action. The
following program is fully functional, but almost all error checking
has been removed to make is shorter and easier to understand. This
program will query the server running on the localhost for the details
of the lease for IP address 10.0.0.101. It will then print out the time
the lease ends.
.PP
.nf
		#include <stdarg.h>
		#include <sys/time.h>
		#include <sys/socket.h>
		#include <stdio.h>
		#include <netinet/in.h>

		#include <isc/result.h>
		#include <dhcpctl/dhcpctl.h>

		int main (int argc, char **argv) {
			dhcpctl_data_string ipaddrstring = NULL;
			dhcpctl_data_string value = NULL;
.fi
.PP
All modifications of handles and all accesses of handle data happen
via dhcpctl_data_string objects.
.PP
.nf
			dhcpctl_handle connection = NULL;
			dhcpctl_handle lease = NULL;
			isc_result_t waitstatus;
			struct in_addr convaddr;
			time_t thetime;

			dhcpctl_initialize ();
.fi
.PP
Required first step.
.PP
.nf
			dhcpctl_connect (&connection, "127.0.0.1",
					 7911, 0);
.fi
.PP
Sets up the connection to the server. The server normally listens on
port 7911 unless configured to do otherwise.
.PP
.nf
			dhcpctl_new_object (&lease, connection,
					    "lease");
.fi
.PP
Here we create a handle to a lease. This call just sets up local data
structure. The server hasn't yet made any association between the
client's data structure and any lease it has.
.PP
.nf
			memset (&ipaddrstring, 0, sizeof
				ipaddrstring);

			inet_pton(AF_INET, "10.0.0.101",
				  &convaddr);

			omapi_data_string_new (&ipaddrstring,
					       4, MDL);
.fi
.PP
Create a new data string to storing in the handle.
.PP
.nf
			memcpy(ipaddrstring->value, &convaddr.s_addr, 4);

			dhcpctl_set_value (lease, ipaddrstring,
					   "ip-address");
.fi
.PP
We're setting the ip-address attribute of the lease handle to the
given address. We've not set any other attributes so when the server
makes the association the ip address will be all it uses to look up
the lease in its tables.
.PP
.nf
			dhcpctl_open_object (lease, connection, 0);
.fi
.PP
Here we prime the connection with the request to look up the lease in
the server and fill up the local handle with the attributes the server
will send over in its answer.
.PP
.nf
			dhcpctl_wait_for_completion (lease,
						     &waitstatus);
.fi
.PP
This call causes the message to get sent to the server (the message to
look up the lease and send back the attribute values in the
answer). The value in the variable waitstatus when the function
returns will be the result from the server. If the message could
not be processed properly by the server then the error will be
reflected here.
.PP
.nf
			if (waitstatus != ISC_R_SUCCESS) {
				/* server not authoritative */
				exit (0);
			}

			dhcpctl_data_string_dereference(&ipaddrstring,
							MDL);
.fi
.PP
Clean-up memory we no longer need.
.PP
.nf
			dhcpctl_get_value (&value, lease, "ends");
.fi
.PP
Get the attribute named ``ends'' from the lease handle. This is a
4-byte integer of the time (in unix epoch seconds) that the lease
will expire.
.PP
.nf
	
			memcpy(&thetime, value->value, value->len);
			dhcpctl_data_string_dereference(&value, MDL);

			fprintf (stdout, "ending time is %s",
				 ctime(&thetime));
		}

.fi
.SH AUTHENTICATION
If the server demands authenticated connections then before opening
the connection the user must call dhcpctl_new_authenticator.
.PP
.nf
		dhcpctl_handle authenticator = NULL;
		const char *keyname = "a-key-name";
		const char *algorithm = "hmac-md5";
		const char *secret = "a-shared-secret";

		dhcpctl_new_authenticator (&authenticator, 
                                           keyname,
                                           algorithm,
                                           secret,
					   strlen(secret) + 1);
.fi
.PP
The keyname, algorithm and secret must all match what is specified in
the server's dhcpd.conf file:
.PP
.nf
		key "a-key-name" {
			algorithm hmac-md5;
			secret "a-shared-secret";
		};

		# Set the omapi-key value to use
		# authenticated connections
		omapi-key "a-key-name";
.fi
.PP
The authenticator handle that is created by the call to
dhcpctl_new_authenticator must be given as the last (the 4th) argument
to the call to dhcpctl_connect(). All messages will then be signed
with the given secret string using the specified algorithm.
.SH SEE ALSO
dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
.SH AUTHOR
.B omapi
was created by Ted Lemon of Nominum, Inc.  Information about Nominum
and support contracts for DHCP and BIND can be found at
.B http://www.nominum.com.   This documentation was written by James
Brister of Nominum, Inc.
Commit	Line	Data
d758ad8c TL	1	.\" omapi.3
	2	.\"
	3	.\" Copyright (c) 2000-2001 Internet Software Consortium.
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\"
	8	.\" 1. Redistributions of source code must retain the above copyright
	9	.\" notice, this list of conditions and the following disclaimer.
	10	.\" 2. Redistributions in binary form must reproduce the above copyright
	11	.\" notice, this list of conditions and the following disclaimer in the
	12	.\" documentation and/or other materials provided with the distribution.
	13	.\" 3. Neither the name of The Internet Software Consortium nor the names
	14	.\" of its contributors may be used to endorse or promote products derived
	15	.\" from this software without specific prior written permission.
	16	.\"
	17	.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
	18	.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
	19	.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
	20	.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	21	.\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
	22	.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	23	.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	24	.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
	25	.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
	26	.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
	27	.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
	28	.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	29	.\" SUCH DAMAGE.
	30	.\"
	31	.\" This software has been written for the Internet Software Consortium
	32	.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
	33	.\" To learn more about the Internet Software Consortium, see
	34	.\" ``http://www.isc.org/''. To learn more about Vixie Enterprises,
	35	.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
	36	.\" ``http://www.nominum.com''.
	37	.TH omapi 3
	38	.SH NAME
	39	OMAPI - Object Management Application Programming Interface
	40	.SH DESCRIPTION
	41	.PP
	42	OMAPI is an programming layer designed for controlling remote
	43	applications, and for querying them for their state. It is currently
	44	used by the ISC DHCP server and this outline addresses the parts of
	45	OMAPI appropriate to the clients of DHCP server. It does this by also
	46	describing the use of a thin API layered on top of OMAPI called
	47	'dhcpctl'
	48	.PP
	49	OMAPI uses TCP/IP as the transport for server communication, and
	50	security can be imposed by having the client and server
	51	cryptographically sign messages using a shared secret.
	52	.PP
	53	dhcpctl works by presenting the client with handles to objects that
	54	act as surrogates for the real objects in the server. For example a
	55	client will create a handle for a lease object, and will request the
	56	server to fill the lease handle's state. The client application can
	57	then pull details such as the lease expiration time from the lease
	58	handle.
	59	.PP
	60	Modifications can be made to the server state by creating handles to
	61	new objects, or by modifying attributes of handles to existing
	62	objects, and then instructing the server to update itself according to
	63	the changes made.
	64	.SH USAGE
65	.PP
66	The client application must always call dhcpctl_initialize() before
67	making calls to any other dhcpctl functions. This initializes
68	various internal data structures.
69	.PP
70	To create the connection to the server the client must use
71	dhcpctl_connect() function. As well as making the physical connection
72	it will also set up the connection data structures to do
73	authentication on each message, if that is required.
74	.PP
75	All the dhcpctl functions return an integer value of type
76	isc_result_t. A successful call will yield a result of
77	ISC_R_SUCCESS. If the call fails for a reason local to the client
78	(e.g. insufficient local memory, or invalid arguments to the call)
79	then the return value of the dhcpctl function will show that. If the
80	call succeeds but the server couldn't process the request the error
81	value from the server is returned through another way, shown below.
82	.PP
83	The easiest way to understand dhcpctl is to see it in action. The
84	following program is fully functional, but almost all error checking
85	has been removed to make is shorter and easier to understand. This
86	program will query the server running on the localhost for the details
87	of the lease for IP address 10.0.0.101. It will then print out the time
88	the lease ends.
89	.PP
90	.nf
dc6d4b5a BC	91	#include <stdarg.h>
	92	#include <sys/time.h>
	93	#include <sys/socket.h>
	94	#include <stdio.h>
	95	#include <netinet/in.h>
	96
	97	#include <isc/result.h>
	98	#include <dhcpctl/dhcpctl.h>
	99
	100	int main (int argc, char **argv) {
	101	dhcpctl_data_string ipaddrstring = NULL;
	102	dhcpctl_data_string value = NULL;
d758ad8c TL	103	.fi
	104	.PP
	105	All modifications of handles and all accesses of handle data happen
	106	via dhcpctl_data_string objects.
	107	.PP
	108	.nf
dc6d4b5a BC	109	dhcpctl_handle connection = NULL;
	110	dhcpctl_handle lease = NULL;
	111	isc_result_t waitstatus;
	112	struct in_addr convaddr;
	113	time_t thetime;
	114
	115	dhcpctl_initialize ();
d758ad8c TL	116	.fi
	117	.PP
	118	Required first step.
	119	.PP
	120	.nf
dc6d4b5a BC	121	dhcpctl_connect (&connection, "127.0.0.1",
dc6d4b5a BC	122	7911, 0);
d758ad8c TL	123	.fi
	124	.PP
	125	Sets up the connection to the server. The server normally listens on
	126	port 7911 unless configured to do otherwise.
	127	.PP
	128	.nf
dc6d4b5a BC	129	dhcpctl_new_object (&lease, connection,
dc6d4b5a BC	130	"lease");
d758ad8c TL	131	.fi
	132	.PP
	133	Here we create a handle to a lease. This call just sets up local data
	134	structure. The server hasn't yet made any association between the
	135	client's data structure and any lease it has.
	136	.PP
	137	.nf
dc6d4b5a BC	138	memset (&ipaddrstring, 0, sizeof
	139	ipaddrstring);
	140
	141	inet_pton(AF_INET, "10.0.0.101",
	142	&convaddr);
	143
	144	omapi_data_string_new (&ipaddrstring,
	145	4, MDL);
d758ad8c TL	146	.fi
	147	.PP
	148	Create a new data string to storing in the handle.
	149	.PP
	150	.nf
dc6d4b5a BC	151	memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
	152
	153	dhcpctl_set_value (lease, ipaddrstring,
	154	"ip-address");
d758ad8c TL	155	.fi
	156	.PP
	157	We're setting the ip-address attribute of the lease handle to the
	158	given address. We've not set any other attributes so when the server
	159	makes the association the ip address will be all it uses to look up
	160	the lease in its tables.
	161	.PP
	162	.nf
dc6d4b5a	163	dhcpctl_open_object (lease, connection, 0);
d758ad8c TL	164	.fi
	165	.PP
	166	Here we prime the connection with the request to look up the lease in
	167	the server and fill up the local handle with the attributes the server
	168	will send over in its answer.
	169	.PP
	170	.nf
dc6d4b5a BC	171	dhcpctl_wait_for_completion (lease,
dc6d4b5a BC	172	&waitstatus);
d758ad8c TL	173	.fi
	174	.PP
	175	This call causes the message to get sent to the server (the message to
	176	look up the lease and send back the attribute values in the
	177	answer). The value in the variable waitstatus when the function
	178	returns will be the result from the server. If the message could
	179	not be processed properly by the server then the error will be
	180	reflected here.
	181	.PP
	182	.nf
dc6d4b5a BC	183	if (waitstatus != ISC_R_SUCCESS) {
	184	/* server not authoritative */
	185	exit (0);
	186	}
	187
	188	dhcpctl_data_string_dereference(&ipaddrstring,
	189	MDL);
d758ad8c TL	190	.fi
	191	.PP
	192	Clean-up memory we no longer need.
	193	.PP
	194	.nf
dc6d4b5a	195	dhcpctl_get_value (&value, lease, "ends");
d758ad8c TL	196	.fi
	197	.PP
	198	Get the attribute named ``ends'' from the lease handle. This is a
	199	4-byte integer of the time (in unix epoch seconds) that the lease
	200	will expire.
	201	.PP
	202	.nf
dc6d4b5a BC	203
	204	memcpy(&thetime, value->value, value->len);
	205	dhcpctl_data_string_dereference(&value, MDL);
	206
	207	fprintf (stdout, "ending time is %s",
	208	ctime(&thetime));
	209	}
	210
d758ad8c TL	211	.fi
	212	.SH AUTHENTICATION
	213	If the server demands authenticated connections then before opening
	214	the connection the user must call dhcpctl_new_authenticator.
	215	.PP
	216	.nf
dc6d4b5a BC	217	dhcpctl_handle authenticator = NULL;
	218	const char *keyname = "a-key-name";
	219	const char *algorithm = "hmac-md5";
	220	const char *secret = "a-shared-secret";
	221
	222	dhcpctl_new_authenticator (&authenticator,
	223	keyname,
	224	algorithm,
	225	secret,
	226	strlen(secret) + 1);
d758ad8c TL	227	.fi
	228	.PP
	229	The keyname, algorithm and secret must all match what is specified in
	230	the server's dhcpd.conf file:
	231	.PP
	232	.nf
dc6d4b5a BC	233	key "a-key-name" {
	234	algorithm hmac-md5;
	235	secret "a-shared-secret";
	236	};
	237
	238	# Set the omapi-key value to use
	239	# authenticated connections
	240	omapi-key "a-key-name";
d758ad8c TL	241	.fi
	242	.PP
	243	The authenticator handle that is created by the call to
	244	dhcpctl_new_authenticator must be given as the last (the 4th) argument
	245	to the call to dhcpctl_connect(). All messages will then be signed
	246	with the given secret string using the specified algorithm.
	247	.SH SEE ALSO
	248	dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
	249	.SH AUTHOR
	250	.B omapi
	251	was created by Ted Lemon of Nominum, Inc. Information about Nominum
	252	and support contracts for DHCP and BIND can be found at
	253	.B http://www.nominum.com. This documentation was written by James
	254	Brister of Nominum, Inc.