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