1RPC_GSS_SECCREATE(3)     BSD Library Functions Manual     RPC_GSS_SECCREATE(3)
2

NAME

4     RPCSEC_GSS — GSS-API based authentication for RPC
5

SYNOPSIS

7     #include <rpc/rpcsec_gss.h>
8

DESCRIPTION

10     RPCSEC_GSS is a security mechanism for the RPC protocol.  It uses the
11     Generic Security Service API (GSS-API) to establish a security context
12     between a client and a server and to ensure that all subsequent communi‐
13     cation between client and server are properly authenticated.  Optionally,
14     extra protection can be applied to the connection.  The integrity service
15     uses checksums to ensure that all data sent by a peer is received without
16     modification.  The privacy service uses encryption to ensure that no
17     third party can access the data for a connection.
18
19     To use this system, an application must first use rpc_gss_seccreate() to
20     establish a security context.
21

DATA STRUCTURES

23     Data structures used by RPCSEC_GSS appear below.
24
25     rpc_gss_service_t
26           This type defines the types of security service required for
27           rpc_gss_seccreate().
28
29           typedef enum {
30                   rpc_gss_svc_default     = 0,
31                   rpc_gss_svc_none        = 1,
32                   rpc_gss_svc_integrity   = 2,
33                   rpc_gss_svc_privacy     = 3
34           } rpc_gss_service_t;
35
36     rpc_gss_options_ret_t
37           This structure contains various optional values which are used
38           while creating a security context.
39
40           typedef struct {
41                   int             req_flags;      /* GSS request bits */
42                   int             time_req;       /* requested lifetime */
43                   gss_cred_id_t   my_cred;        /* GSS credential */
44                   gss_channel_bindings_t input_channel_bindings;
45           } rpc_gss_options_req_t;
46
47     rpc_gss_options_ret_t
48           Various details of the created security context are returned using
49           this structure.
50
51           typedef struct {
52                   int             major_status;
53                   int             minor_status;
54                   u_int           rpcsec_version;
55                   int             ret_flags;
56                   int             time_req;
57                   gss_ctx_id_t    gss_context;
58                   char            actual_mechanism[MAX_GSS_MECH];
59           } rpc_gss_options_ret_t;
60
61     rpc_gss_principal_t
62           This type is used to refer to an client principal which is repre‐
63           sented in GSS-API exported name form (see gss_export_name(3) for
64           more details).  Names in this format may be stored in access con‐
65           trol lists or compared with other names in exported name form.
66           This structure is returned by rpc_gss_get_principal_name() and is
67           also referenced by the rpc_gss_rawcred_t structure.
68
69           typedef struct {
70                   int             len;
71                   char            name[1];
72           } *rpc_gss_principal_t;
73
74     rpc_gss_rawcred_t
75           This structure is used to access the raw credentials associated
76           with a security context.
77
78           typedef struct {
79                   u_int           version;        /* RPC version number */
80                   const char      *mechanism;     /* security mechanism */
81                   const char      *qop;           /* quality of protection */
82                   rpc_gss_principal_t client_principal; /* client name */
83                   const char      *svc_principal; /* server name */
84                   rpc_gss_service_t service;      /* service type */
85           } rpc_gss_rawcred_t;
86
87     rpc_gss_ucred_t
88           Unix credentials which are derived form the raw credentials,
89           accessed via rpc_gss_getcred().
90
91           typedef struct {
92                   uid_t           uid;            /* user ID */
93                   gid_t           gid;            /* group ID */
94                   short           gidlen;
95                   gid_t           *gidlist;       /* list of groups */
96           } rpc_gss_ucred_t;
97
98     rpc_gss_lock_t
99           Structure used to enforce a particular QOP and service.
100
101           typedef struct {
102                   bool_t          locked;
103                   rpc_gss_rawcred_t *raw_cred;
104           } rpc_gss_lock_t;
105
106     rpc_gss_callback_t
107           Callback structure used by rpc_gss_set_callback().
108
109           typedef struct {
110                   u_int           program;        /* RPC program number */
111                   u_int           version;        /* RPC version number */
112                                                   /* user defined callback */
113                   bool_t          (*callback)(struct svc_req *req,
114                                               gss_cred_id_t deleg,
115                                               gss_ctx_id_t gss_context,
116                                               rpc_gss_lock_t *lock,
117                                               void **cookie);
118           } rpc_gss_callback_t;
119
120     rpc_gss_error_t
121           Structure used to return error information by rpc_gss_get_error().
122
123           typedef struct {
124                   int             rpc_gss_error;
125                   int             system_error;   /* same as errno */
126           } rpc_gss_error_t;
127
128           /*
129            * Values for rpc_gss_error
130            */
131           #define RPC_GSS_ER_SUCCESS      0       /* no error */
132           #define RPC_GSS_ER_SYSTEMERROR  1       /* system error */
133

INDEX

135     rpc_gss_seccreate(3)
136           Create a new security context
137
138     rpc_gss_set_defaults(3)
139           Set service and quality of protection for a context
140
141     rpc_gss_max_data_length(3)
142           Calculate maximum client message sizes.
143
144     rpc_gss_get_error(3)
145           Get details of the last error
146
147     rpc_gss_mech_to_oid(3)
148           Convert a mechanism name to the corresponding GSS-API oid.
149
150     rpc_gss_oid_to_mech(3)
151           Convert a GSS-API oid to a mechanism name
152
153     rpc_gss_qop_to_num(3)
154           Convert a quality of protection name to the corresponding number
155
156     rpc_gss_get_mechanisms(3)
157           Get a list of security mechanisms.
158
159     rpc_gss_get_mech_info(3)
160           Return extra information about a security mechanism
161
162     rpc_gss_get_versions(3)
163           Return the maximum and minimum supported versions of the RPCSEC_GSS
164           protocol
165
166     rpc_gss_is_installed(3)
167           Query for the presence of a particular security mechanism
168
169     rpc_gss_set_svc_name(3)
170           Set the name of a service principal which matches a given RPC pro‐
171           gram plus version pair
172
173     rpc_gss_getcred(3)
174           Get credential details for the security context of an RPC request
175
176     rpc_gss_set_callback(3)
177           Install a callback routine which is called on the server when new
178           security contexts are created
179
180     rpc_gss_get_principal_name(3)
181           Create a client principal name from various strings
182
183     rpc_gss_svc_max_data_length(3)
184           Calculate maximum server message sizes.
185

AVAILABILITY

187     These functions are part of libtirpc.
188

SEE ALSO

190     rpc(3), gssapi(3)
191

AUTHORS

193     This manual page was written by Doug Rabson <dfr@FreeBSD.org>.
194
195BSD                            January 26, 2010                            BSD
Impressum