lib/librpcsec_gss/rpcsec_gss.3

   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
  39 is a security mechanism for the RPC protocol.
  40 It uses the Generic Security Service API (GSS-API) to establish a
  41 security context between a client and a server and to ensure that all
  42 subsequent communication between client and server are properly
  43 authenticated.
  44 Optionally, extra protection can be applied to the connection.
  45 The integrity service uses checksums to ensure that all data sent by
  46 a peer is recieved without modification.
  47 The privacy service uses encryption to ensure that no third party can
  48 access the data for a connection.
  49 .Pp
  50 To use this system, an application must first use
  51 .Fn rpc_gss_seccreate
  52 to establish a security context.
  53 .Sh DATA STRUCTURES
  54 Data structures used by
  55 .Nm
  56 appear below.
  57 .Bl -tag -width "MMMM"
  58 .It Vt rpc_gss_service_t
  59 This type defines the types of security service required for
  60 .Fn rpc_gss_seccreate .
  61 .Bd -literal
  62 typedef 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
  70 This structure contains various optional values which are used while
  71 creating a security contect.
  72 .Bd -literal
  73 typedef 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
  81 Various details of the created security context are returned using
  82 this structure.
  83 .Bd -literal
  84 typedef 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
  95 This type is used to refer to an client principal which is represented
  96 in GSS-API exported name form
  97 (see
  98 .Xr gss_export_name 3
  99 for more details).
 100 Names in this format may be stored in access control lists or compared
 101 with other names in exported name form.
 102 This structure is returned by
 103 .Fn rpc_gss_get_principal_name
 104 and is also referenced by the
 105 .Vt rpc_gss_rawcred_t
 106 structure.
 107 .Bd -literal
 108 typedef struct {
 109         int             len;
 110         char            name[1];
 111 } *rpc_gss_principal_t;
 112 .Ed
 113 .It Vt rpc_gss_rawcred_t
 114 This structure is used to access the raw credentions associated with a
 115 security context.
 116 .Bd -literal
 117 typedef 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
 127 Unix credentials which are derived form the raw credentials,
 128 accessed via
 129 .Fn rpc_gss_getcred .
 130 .Bd -literal
 131 typedef 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
 139 Structure used to enforce a particular QOP and service.
 140 .Bd -literal
 141 typedef 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
 147 Callback structure used by
 148 .Fn rpc_gss_set_callback .
 149 .Bd -literal
 150 typedef 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
 162 Structure used to return error information by
 163 .Fn rpc_gss_get_error .
 164 .Bd -literal
 165 typedef 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
 179 Create a new security context
 180 .It Xr rpc_gss_set_defaults 3
 181 Set service and quality of protection for a context
 182 .It Xr rpc_gss_max_data_length 3
 183 Calculate maximum client message sizes.
 184 .It Xr rpc_gss_get_error 3
 185 Get details of the last error
 186 .It Xr rpc_gss_mech_to_oid 3
 187 Convert a mechanism name to the corresponding GSS-API oid.
 188 .It Xr rpc_gss_oid_to_mech 3
 189 Convert a GSS-API oid to a mechanism name
 190 .It Xr rpc_gss_qop_to_num 3
 191 Convert a quality of protection name to the corresponding number
 192 .It Xr rpc_gss_get_mechanisms 3
 193 Get a list of security mechanisms.
 194 .It Xr rpc_gss_get_mech_info 3
 195 Return extra information about a security mechanism
 196 .It Xr rpc_gss_get_versions 3
 197 Return the maximum and minimum supported versions of the
 198 .Nm
 199 protocol
 200 .It Xr rpc_gss_is_installed 3
 201 Query for the presence of a particular security mechanism
 202 .It Xr rpc_gss_set_svc_name 3
 203 Set the name of a service principal which matches a given RPC program
 204 plus version pair
 205 .It Xr rpc_gss_getcred 3
 206 Get credential details for the security context of an RPC request
 207 .It Xr rpc_gss_set_callback 3
 208 Install a callback routine which is called on the server when new
 209 security contexts are created
 210 .It Xr rpc_gss_get_principal_name 3
 211 Create a client principal name from various strings
 212 .It Xr rpc_gss_svc_max_data_length 3
 213 Calculate 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
 223 The
 224 .Nm
 225 library first appeared in
 226 .Fx 8.0 .
 227 .Sh AUTHORS
 228 This
 229 manual page was written by
 230 .An Doug Rabson Aq dfr@FreeBSD.org .