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

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