usr/src/man/man3nsl/rpcsec_gss.3nsl

   1 '\" te
   2 .\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH RPCSEC_GSS 3NSL "Jun 29, 2001"
   7 .SH NAME
   8 rpcsec_gss \- security flavor incorporating GSS-API protections
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR... ] \fIfile\fR...  -lnsl [ \fIlibrary\fR... ]
  13 #include <rpc/rpcsec_gss.h>
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 \fBRPCSEC_GSS\fR is a security flavor which sits "on top" of the \fBGSS-API\fR
  20 (Generic Security Service API) for network transmissions. Applications using
  21 \fBRPCSEC_GSS\fR can take advantage of \fBGSS-API\fR security features;
  22 moreover, they can use any security mechanism (such as RSA public key or
  23 Kerberos) that works with  the \fBGSS-API.\fR
  24 .sp
  25 .LP
  26 The \fBGSS-API\fR offers two security services beyond the traditional
  27 authentication services \fB(AUTH_DH,\fR \fBAUTH_SYS,\fR and \fBAUTH_KERB):\fR
  28 integrity and privacy.  With integrity, the system uses cryptographic
  29 checksumming to ensure the authenticity of a message (authenticity of
  30 originator, recipient, and data); privacy provides additional security by
  31 encrypting data.  Applications using \fBRPCSEC_GSS\fR specify which service
  32 they wish to use. Type of security service is mechanism-independent.
  33 .sp
  34 .LP
  35 Before exchanging data with a peer, an application must establish a context for
  36 the exchange.   \fBRPCSEC_GSS\fR provides a single function for this purpose,
  37 \fBrpc_gss_seccreate()\fR, which allows the application to specify the security
  38 mechanism, Quality of Protection (QOP), and type of service at context
  39 creation. (The QOP parameter sets the cryptographic algorithms to be used with
  40 integrity or privacy, and is mechanism-dependent.) Once a context is
  41 established, applications can reset the QOP and type of service for each data
  42 unit exchanged, if desired.
  43 .sp
  44 .LP
  45 Valid mechanisms and QOPs may be obtained from configuration files or from the
  46 name service.  Each mechanism has a default QOP.
  47 .sp
  48 .LP
  49 Contexts are destroyed with the usual RPC  \fBauth_destroy()\fR call.
  50 .SS "Data Structures"
  51 .sp
  52 .LP
  53 Some of the data structures used by the \fBRPCSEC_GSS\fR package are shown
  54 below.
  55 .SS "\fBrpc_gss_service_t\fR"
  56 .sp
  57 .LP
  58 This enum defines the types of security services the context may have.
  59 \fBrpc_gss_seccreate()\fR takes this as one argument when setting the service
  60 type for a session.
  61 .sp
  62 .in +2
  63 .nf
  64 typedef enum {
  65    rpc_gss_svc_default = 0,
  66    rpc_gss_svc_none = 1,
  67    rpc_gss_svc_integrity = 2,
  68    rpc_gss_svc_privacy = 3
  69 } rpc_gss_service_t ;
  70 .fi
  71 .in -2
  72
  73 .SS "\fBrpc_gss_options_req_t\fR"
  74 .sp
  75 .LP
  76 Structure containing options passed directly through to the \fBGSS-API.\fR
  77 \fBrpc_gss_seccreate()\fR takes this as an argument when creating a context.
  78 .sp
  79 .in +2
  80 .nf
  81 typedef struct {
  82    int  req_flags;              /*GSS request bits */
  83    int  time_req;           /*requested credential lifetime */
  84    gss_cred_id_t  my_cred;  /*GSS credential struct*/
  85    gss_channel_bindings_t;
  86    input_channel_bindings;
  87 } rpc_gss_options_req_t ;
  88 .fi
  89 .in -2
  90
  91 .SS "\fBrpc_gss_OID\fR"
  92 .sp
  93 .LP
  94 This data type is used by in-kernel RPC routines, and thus is mentioned here
  95 for informational purposes only.
  96 .sp
  97 .in +2
  98 .nf
  99 typedef struct {
 100    u_int        length;
 101    void *elements
 102 } *rpc_gss_OID;
 103 .fi
 104 .in -2
 105
 106 .SS "\fBrpc_gss_options_ret_t\fR"
 107 .sp
 108 .LP
 109 Structure containing  \fBGSS-API\fR options returned to the calling function,
 110 \fBrpc_gss_seccreate()\fR. \fBMAX_GSS_MECH\fR is defined as 128.
 111 .sp
 112 .in +2
 113 .nf
 114 typedef struct {
 115    int           major_status;
 116    int           minor_status;
 117    u_int         rpcsec_version                  /*vers. of RPCSEC_GSS */
 118    int           ret_flags
 119    int           time_req
 120    gss_ctx_id_t  gss_context;
 121    char          actual_mechanism[MAX_GSS_MECH]; /*mechanism used*/
 122 } rpc_gss_options_ret_t;
 123 .fi
 124 .in -2
 125
 126 .SS "\fBrpc_gss_principal_t\fR"
 127 .sp
 128 .LP
 129 The (mechanism-dependent, opaque) client principal type.  Used as an argument
 130 to the \fBrpc_gss_get_principal_name()\fR function, and in the  \fBgsscred\fR
 131 table.  Also referenced by the \fBrpc_gss_rawcred_t\fR structure for raw
 132 credentials (see below).
 133 .sp
 134 .in +2
 135 .nf
 136 typedef struct {
 137    int len;
 138    char name[1];
 139 } *rpc_gss_principal_t;
 140 .fi
 141 .in -2
 142
 143 .SS "\fBrpc_gss_rawcred_t\fR"
 144 .sp
 145 .LP
 146 Structure for raw credentials.  Used by  \fBrpc_gss_getcred()\fR and
 147 \fBrpc_gss_set_callback()\fR.
 148 .sp
 149 .in +2
 150 .nf
 151 typedef struct {
 152    u_int                version;          /*RPC version # */
 153    char                 *mechanism;       /*security mechanism*/
 154    char                 *qop;             /*Quality of Protection*/
 155    rpc_gss_principal_t  client_principal; /*client name*/
 156    char                 *svc_principal;   /*server name*/
 157    rpc_gss_service_t    service;          /*service (integrity, etc.)*/
 158 } rpc_gss_rawcred_t;
 159 .fi
 160 .in -2
 161
 162 .SS "\fBrpc_gss_ucred_t\fR"
 163 .sp
 164 .LP
 165 Structure for UNIX credentials.  Used by  \fBrpc_gss_getcred()\fR as an
 166 alternative to  \fBrpc_gss_rawcred_t\fR.
 167 .sp
 168 .in +2
 169 .nf
 170 typedef struct {
 171    uid_t  uid;      /*user ID*/
 172    gid_t  gid;      /*group ID*/
 173    short  gidlen;
 174    git_t  *gidlist; /*list of groups*/
 175 } rpc_gss_ucred_t;
 176 .fi
 177 .in -2
 178
 179 .SS "\fBrpc_gss_callback_t\fR"
 180 .sp
 181 .LP
 182 Callback structure used by \fBrpc_gss_set_callback()\fR.
 183 .sp
 184 .in +2
 185 .nf
 186 typedef struct {
 187    u_int   program;       /*RPC program #*/
 188    u_int   version;       /*RPC version #*/
 189    bool_t  (*callback)(); /*user-defined callback routine*/
 190 } rpc_gss_callback_t;
 191 .fi
 192 .in -2
 193
 194 .SS "\fBrpc_gss_lock_t\fR"
 195 .sp
 196 .LP
 197 Structure used by a callback routine to enforce a particular QOP and service
 198 for a session.  The \fBlocked\fR field is normally set to \fBFALSE;\fR the
 199 server sets it to \fBTRUE\fR in order to lock the session.  (A locked context
 200 will reject all requests having different QOP and service values than those
 201 found in the \fBraw_cred\fR structure.)  For more information, see the
 202 \fBrpc_gss_set_callback\fR(3NSL) man page.
 203 .sp
 204 .in +2
 205 .nf
 206 typedef struct {
 207    bool_t                 locked;
 208    rpc_gss_rawcred_t      *raw_cred;
 209 } rpc_gss_lock_t;
 210 .fi
 211 .in -2
 212
 213 .SS "\fBrpc_gss_error_t\fR"
 214 .sp
 215 .LP
 216 Structure used by \fBrpc_gss_get_error()\fR to fetch an error code when a
 217 \fBRPCSEC_GSS\fR routine fails.
 218 .sp
 219 .in +2
 220 .nf
 221 typedef struct {
 222    int  rpc_gss_error;
 223    int  system_error;    /*same as errno*/
 224 } rpc_gss_error_t;
 225 .fi
 226 .in -2
 227
 228 .SS "Index to Routines"
 229 .sp
 230 .LP
 231 The following  lists  \fBRPCSEC_GSS\fR routines and the manual reference pages
 232 on which they are described.  An (S) indicates it is a server-side function:
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBRoutine\fR (Manual Page) \fR
 237 .ad
 238 .sp .6
 239 .RS 4n
 240 \fBDescription\fR
 241 .RE
 242
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fBrpc_gss_seccreate\fR(3NSL) \fR
 247 .ad
 248 .sp .6
 249 .RS 4n
 250 Create a secure \fBRPCSEC_GSS\fR context
 251 .RE
 252
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBrpc_gss_set_defaults\fR(3NSL) \fR
 257 .ad
 258 .sp .6
 259 .RS 4n
 260 Switch service, QOP for a session
 261 .RE
 262
 263 .sp
 264 .ne 2
 265 .na
 266 \fB\fBrpc_gss_max_data_length\fR(3NSL) \fR
 267 .ad
 268 .sp .6
 269 .RS 4n
 270 Get maximum data length allowed by transport
 271 .RE
 272
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fBrpc_gss_set_svc_name\fR(3NSL) \fR
 277 .ad
 278 .sp .6
 279 .RS 4n
 280 Set server's principal name (S)
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBrpc_gss_getcred\fR(3NSL) \fR
 287 .ad
 288 .sp .6
 289 .RS 4n
 290 Get credentials of caller (S)
 291 .RE
 292
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fBrpc_gss_set_callback\fR(3NSL) \fR
 297 .ad
 298 .sp .6
 299 .RS 4n
 300 Specify callback to see context use (S)
 301 .RE
 302
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fBrpc_gss_get_principal_name\fR(3NSL) \fR
 307 .ad
 308 .sp .6
 309 .RS 4n
 310 Get client principal name (S)
 311 .RE
 312
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fBrpc_gss_svc_max_data_length\fR(3NSL) \fR
 317 .ad
 318 .sp .6
 319 .RS 4n
 320 Get maximum data length allowed by transport (S)
 321 .RE
 322
 323 .sp
 324 .ne 2
 325 .na
 326 \fB\fBrpc_gss_get_error\fR(3NSL) \fR
 327 .ad
 328 .sp .6
 329 .RS 4n
 330 Get error number
 331 .RE
 332
 333 .sp
 334 .ne 2
 335 .na
 336 \fB\fBrpc_gss_get_mechanisms\fR(3NSL) \fR
 337 .ad
 338 .sp .6
 339 .RS 4n
 340 Get valid mechanism strings
 341 .RE
 342
 343 .sp
 344 .ne 2
 345 .na
 346 \fB\fBrpc_gss_get_mech_info\fR(3NSL) \fR
 347 .ad
 348 .sp .6
 349 .RS 4n
 350 Get valid QOP strings, current service
 351 .RE
 352
 353 .sp
 354 .ne 2
 355 .na
 356 \fB\fBrpc_gss_get_versions\fR(3NSL) \fR
 357 .ad
 358 .sp .6
 359 .RS 4n
 360 Get supported \fBRPCSEC_GSS\fR versions
 361 .RE
 362
 363 .sp
 364 .ne 2
 365 .na
 366 \fB\fBrpc_gss_is_installed\fR(3NSL) \fR
 367 .ad
 368 .sp .6
 369 .RS 4n
 370 Checks if a mechanism is installed
 371 .RE
 372
 373 .sp
 374 .ne 2
 375 .na
 376 \fB\fBrpc_gss_mech_to_oid\fR(3NSL) \fR
 377 .ad
 378 .sp .6
 379 .RS 4n
 380 Maps ASCII mechanism to OID representation
 381 .RE
 382
 383 .sp
 384 .ne 2
 385 .na
 386 \fB\fBrpc_gss_qop_to_num\fR(3NSL) \fR
 387 .ad
 388 .sp .6
 389 .RS 4n
 390 Maps ASCII QOP, mechansim to u_int number
 391 .RE
 392
 393 .SS "Utilities"
 394 .sp
 395 .LP
 396 The \fBgsscred\fR utility manages the \fBgsscred\fR table, which contains
 397 mappings of principal names between network and local credentials.  See
 398 \fBgsscred\fR(1M).
 399 .SH FILES
 400 .sp
 401 .ne 2
 402 .na
 403 \fB\fB/etc/gss/mech\fR \fR
 404 .ad
 405 .RS 18n
 406 List of installed mechanisms
 407 .RE
 408
 409 .sp
 410 .ne 2
 411 .na
 412 \fB\fB/etc/gss/qop\fR \fR
 413 .ad
 414 .RS 18n
 415 List of valid QOPs
 416 .RE
 417
 418 .SH ATTRIBUTES
 419 .sp
 420 .LP
 421 See \fBattributes\fR(5) for descriptions of the following attributes:
 422 .sp
 423
 424 .sp
 425 .TS
 426 box;
 427 c | c
 428 l | l .
 429 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 430 _
 431 MT-Level        MT-Safe
 432 .TE
 433
 434 .SH SEE ALSO
 435 .sp
 436 .LP
 437 \fBgsscred\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), \fBxdr\fR(3NSL), \fBattributes\fR(5), \fBenviron\fR(5)
 438 .sp
 439 .LP
 440 \fIONC+ Developer\&'s Guide\fR
 441 .sp