xref: /freebsd/lib/librpcsec_gss/rpcsec_gss.3 (revision 38a52bd3) 
1.\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/
2.\" Authors: Doug Rabson <dfr@rabson.org>
3.\" Developed with Red Inc: Alfred Perlstein <alfred@FreeBSD.org>
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
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.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.Dd January 26, 2010
28.Dt RPC_GSS_SECCREATE 3
29.Os
30.Sh NAME
31.Nm RPCSEC_GSS
32.Nd "GSS-API based authentication for RPC"
33.Sh LIBRARY
34.Lb librpcsec_gss
35.Sh SYNOPSIS
36.In rpc/rpcsec_gss.h
37.Sh DESCRIPTION
38.Nm
39is a security mechanism for the RPC protocol.
40It uses the Generic Security Service API (GSS-API) to establish a
41security context between a client and a server and to ensure that all
42subsequent communication between client and server are properly
43authenticated.
44Optionally, extra protection can be applied to the connection.
45The integrity service uses checksums to ensure that all data sent by
46a peer is received without modification.
47The privacy service uses encryption to ensure that no third party can
48access the data for a connection.
49.Pp
50To use this system, an application must first use
51.Fn rpc_gss_seccreate
52to establish a security context.
53.Sh DATA STRUCTURES
54Data structures used by
55.Nm
56appear below.
57.Bl -tag -width "MMMM"
58.It Vt rpc_gss_service_t
59This type defines the types of security service required for
60.Fn rpc_gss_seccreate .
61.Bd -literal
62typedef enum {
63	rpc_gss_svc_default	= 0,
64	rpc_gss_svc_none	= 1,
65	rpc_gss_svc_integrity	= 2,
66	rpc_gss_svc_privacy	= 3
67} rpc_gss_service_t;
68.Ed
69.It Vt rpc_gss_options_ret_t
70This structure contains various optional values which are used while
71creating a security context.
72.Bd -literal
73typedef struct {
74	int		req_flags;	/* GSS request bits */
75	int		time_req;	/* requested lifetime */
76	gss_cred_id_t	my_cred;	/* GSS credential */
77	gss_channel_bindings_t input_channel_bindings;
78} rpc_gss_options_req_t;
79.Ed
80.It Vt rpc_gss_options_ret_t
81Various details of the created security context are returned using
82this structure.
83.Bd -literal
84typedef struct {
85	int		major_status;
86	int		minor_status;
87	u_int		rpcsec_version;
88	int		ret_flags;
89	int		time_req;
90	gss_ctx_id_t	gss_context;
91	char		actual_mechanism[MAX_GSS_MECH];
92} rpc_gss_options_ret_t;
93.Ed
94.It Vt rpc_gss_principal_t
95This type is used to refer to an client principal which is represented
96in GSS-API exported name form
97(see
98.Xr gss_export_name 3
99for more details).
100Names in this format may be stored in access control lists or compared
101with other names in exported name form.
102This structure is returned by
103.Fn rpc_gss_get_principal_name
104and is also referenced by the
105.Vt rpc_gss_rawcred_t
106structure.
107.Bd -literal
108typedef struct {
109	int		len;
110	char		name[1];
111} *rpc_gss_principal_t;
112.Ed
113.It Vt rpc_gss_rawcred_t
114This structure is used to access the raw credentials associated with a
115security context.
116.Bd -literal
117typedef struct {
118	u_int		version;	/* RPC version number */
119	const char	*mechanism;	/* security mechanism */
120	const char	*qop;		/* quality of protection */
121	rpc_gss_principal_t client_principal; /* client name */
122	const char	*svc_principal;	/* server name */
123	rpc_gss_service_t service;	/* service type */
124} rpc_gss_rawcred_t;
125.Ed
126.It Vt rpc_gss_ucred_t
127Unix credentials which are derived form the raw credentials,
128accessed via
129.Fn rpc_gss_getcred .
130.Bd -literal
131typedef struct {
132	uid_t		uid;		/* user ID */
133	gid_t		gid;		/* group ID */
134	short		gidlen;
135	gid_t		*gidlist;	/* list of groups */
136} rpc_gss_ucred_t;
137.Ed
138.It Vt rpc_gss_lock_t
139Structure used to enforce a particular QOP and service.
140.Bd -literal
141typedef struct {
142	bool_t		locked;
143	rpc_gss_rawcred_t *raw_cred;
144} rpc_gss_lock_t;
145.Ed
146.It Vt rpc_gss_callback_t
147Callback structure used by
148.Fn rpc_gss_set_callback .
149.Bd -literal
150typedef struct {
151	u_int		program;	/* RPC program number */
152	u_int		version;	/* RPC version number */
153					/* user defined callback */
154	bool_t		(*callback)(struct svc_req *req,
155				    gss_cred_id_t deleg,
156				    gss_ctx_id_t gss_context,
157				    rpc_gss_lock_t *lock,
158				    void **cookie);
159} rpc_gss_callback_t;
160.Ed
161.It Vt rpc_gss_error_t
162Structure used to return error information by
163.Fn rpc_gss_get_error .
164.Bd -literal
165typedef struct {
166	int		rpc_gss_error;
167	int		system_error;	/* same as errno */
168} rpc_gss_error_t;
169
170/*
171 * Values for rpc_gss_error
172 */
173#define RPC_GSS_ER_SUCCESS	0	/* no error */
174#define RPC_GSS_ER_SYSTEMERROR	1	/* system error */
175.Ed
176.El
177.Sh INDEX
178.Bl -tag -width "MMMM"
179.It Xr rpc_gss_seccreate 3
180Create a new security context
181.It Xr rpc_gss_set_defaults 3
182Set service and quality of protection for a context
183.It Xr rpc_gss_max_data_length 3
184Calculate maximum client message sizes.
185.It Xr rpc_gss_get_error 3
186Get details of the last error
187.It Xr rpc_gss_mech_to_oid 3
188Convert a mechanism name to the corresponding GSS-API oid.
189.It Xr rpc_gss_oid_to_mech 3
190Convert a GSS-API oid to a mechanism name
191.It Xr rpc_gss_qop_to_num 3
192Convert a quality of protection name to the corresponding number
193.It Xr rpc_gss_get_mechanisms 3
194Get a list of security mechanisms.
195.It Xr rpc_gss_get_mech_info 3
196Return extra information about a security mechanism
197.It Xr rpc_gss_get_versions 3
198Return the maximum and minimum supported versions of the
199.Nm
200protocol
201.It Xr rpc_gss_is_installed 3
202Query for the presence of a particular security mechanism
203.It Xr rpc_gss_set_svc_name 3
204Set the name of a service principal which matches a given RPC program
205plus version pair
206.It Xr rpc_gss_getcred 3
207Get credential details for the security context of an RPC request
208.It Xr rpc_gss_set_callback 3
209Install a callback routine which is called on the server when new
210security contexts are created
211.It Xr rpc_gss_get_principal_name 3
212Create a client principal name from various strings
213.It Xr rpc_gss_svc_max_data_length 3
214Calculate maximum server message sizes.
215.El
216.Sh SEE ALSO
217.Xr gss_export_name 3 ,
218.Xr gssapi 3 ,
219.Xr rpc 3 ,
220.Xr mech 5 ,
221.Xr qop 5
222.Sh HISTORY
223The
224.Nm
225library first appeared in
226.Fx 8.0 .
227.Sh AUTHORS
228This
229manual page was written by
230.An Doug Rabson Aq Mt dfr@FreeBSD.org .
231