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