1RPC_GSS_SECCREATE(3) BSD Library Functions Manual RPC_GSS_SECCREATE(3)
2
4 RPCSEC_GSS — GSS-API based authentication for RPC
5
7 #include <rpc/rpcsec_gss.h>
8
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 To use this system, an application must first use rpc_gss_seccreate() to
20 establish a security context.
21
23 Data structures used by RPCSEC_GSS appear below.
24 rpc_gss_service_t
26 This type defines the types of security service required for
27 rpc_gss_seccreate().
28 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 rpc_gss_options_ret_t
37 This structure contains various optional values which are used
38 while creating a security context.
39 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 rpc_gss_options_ret_t
48 Various details of the created security context are returned using
49 this structure.
50 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 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 typedef struct {
70 int len;
71 char name[1];
72 } *rpc_gss_principal_t;
73 rpc_gss_rawcred_t
75 This structure is used to access the raw credentials associated
76 with a security context.
77 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 rpc_gss_ucred_t
88 Unix credentials which are derived form the raw credentials,
89 accessed via rpc_gss_getcred().
90 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 rpc_gss_lock_t
99 Structure used to enforce a particular QOP and service.
100 typedef struct {
102 bool_t locked;
103 rpc_gss_rawcred_t *raw_cred;
104 } rpc_gss_lock_t;
105 rpc_gss_callback_t
107 Callback structure used by rpc_gss_set_callback().
108 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 rpc_gss_error_t
121 Structure used to return error information by rpc_gss_get_error().
122 typedef struct {
124 int rpc_gss_error;
125 int system_error; /* same as errno */
126 } rpc_gss_error_t;
127 /*
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
135 rpc_gss_seccreate(3)
136 Create a new security context
137 rpc_gss_set_defaults(3)
139 Set service and quality of protection for a context
140 rpc_gss_max_data_length(3)
142 Calculate maximum client message sizes.
143 rpc_gss_get_error(3)
145 Get details of the last error
146 rpc_gss_mech_to_oid(3)
148 Convert a mechanism name to the corresponding GSS-API oid.
149 rpc_gss_oid_to_mech(3)
151 Convert a GSS-API oid to a mechanism name
152 rpc_gss_qop_to_num(3)
154 Convert a quality of protection name to the corresponding number
155 rpc_gss_get_mechanisms(3)
157 Get a list of security mechanisms.
158 rpc_gss_get_mech_info(3)
160 Return extra information about a security mechanism
161 rpc_gss_get_versions(3)
163 Return the maximum and minimum supported versions of the RPCSEC_GSS
164 protocol
165 rpc_gss_is_installed(3)
167 Query for the presence of a particular security mechanism
168 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 rpc_gss_getcred(3)
174 Get credential details for the security context of an RPC request
175 rpc_gss_set_callback(3)
177 Install a callback routine which is called on the server when new
178 security contexts are created
179 rpc_gss_get_principal_name(3)
181 Create a client principal name from various strings
182 rpc_gss_svc_max_data_length(3)
184 Calculate maximum server message sizes.
185
187 These functions are part of libtirpc.
188
190 rpc(3), gssapi(3)
191
193 This manual page was written by Doug Rabson <dfr@FreeBSD.org>.
194BSD January 26, 2010 BSD