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 July 4, 2008 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 recieved 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 contect. 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 credentions 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.Sh INDEX 177.Bl -tag -width "MMMM" 178.It Xr rpc_gss_seccreate 3 179Create a new security context 180.It Xr rpc_gss_set_defaults 3 181Set service and quality of protection for a context 182.It Xr rpc_gss_max_data_length 3 183Calculate maximum client message sizes. 184.It Xr rpc_gss_get_error 3 185Get details of the last error 186.It Xr rpc_gss_mech_to_oid 3 187Convert a mechanism name to the corresponding GSS-API oid. 188.It Xr rpc_gss_oid_to_mech 3 189Convert a GSS-API oid to a mechanism name 190.It Xr rpc_gss_qop_to_num 3 191Convert a quality of protection name to the corresponding number 192.It Xr rpc_gss_get_mechanisms 3 193Get a list of security mechanisms. 194.It Xr rpc_gss_get_mech_info 3 195Return extra information about a security mechanism 196.It Xr rpc_gss_get_versions 3 197Return the maximum and minimum supported versions of the 198.Nm 199protocol 200.It Xr rpc_gss_is_installed 3 201Query for the presence of a particular security mechanism 202.It Xr rpc_gss_set_svc_name 3 203Set the name of a service principal which matches a given RPC program 204plus version pair 205.It Xr rpc_gss_getcred 3 206Get credential details for the security context of an RPC request 207.It Xr rpc_gss_set_callback 3 208Install a callback routine which is called on the server when new 209security contexts are created 210.It Xr rpc_gss_get_principal_name 3 211Create a client principal name from various strings 212.It Xr rpc_gss_svc_max_data_length 3 213Calculate maximum server message sizes. 214.El 215.Sh SEE ALSO 216.Xr rpc 3 , 217.Xr gssapi 3 , 218.Xr gss_export_name 3 , 219.Xr mech 5 , 220.Xr qop 5 , 221.Xr rpcset_gss 3 222.Sh HISTORY 223The 224.Nm 225manual page example first appeared in 226.Fx 8.0 . 227.Sh AUTHORS 228This 229manual page was written by 230.An Doug Rabson Aq dfr@FreeBSD.org . 231