crypto/heimdal/doc/doxyout/gssapi/man/man3/gssapi.3

   1 .TH "Heimdal GSS-API functions" 3 "11 Jan 2012" "Version 1.5.2" "HeimdalGSS-APIlibrary" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Heimdal GSS-API functions \-
   6 .SS "Functions"
   7
   8 .in +1c
   9 .ti -1c
  10 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_add_oid_set_member\fP (OM_uint32 *minor_status, const gss_OID member_oid, gss_OID_set *oid_set)"
  11 .br
  12 .ti -1c
  13 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_wrap_iov\fP (OM_uint32 *minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int *conf_state, gss_iov_buffer_desc *iov, int iov_count)"
  14 .br
  15 .ti -1c
  16 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_unwrap_iov\fP (OM_uint32 *minor_status, gss_ctx_id_t context_handle, int *conf_state, gss_qop_t *qop_state, gss_iov_buffer_desc *iov, int iov_count)"
  17 .br
  18 .ti -1c
  19 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_wrap_iov_length\fP (OM_uint32 *minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int *conf_state, gss_iov_buffer_desc *iov, int iov_count)"
  20 .br
  21 .ti -1c
  22 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_release_iov_buffer\fP (OM_uint32 *minor_status, gss_iov_buffer_desc *iov, int iov_count)"
  23 .br
  24 .ti -1c
  25 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_canonicalize_name\fP (OM_uint32 *minor_status, const gss_name_t input_name, const gss_OID mech_type, gss_name_t *output_name)"
  26 .br
  27 .ti -1c
  28 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_import_name\fP (OM_uint32 *minor_status, const gss_buffer_t input_name_buffer, const gss_OID input_name_type, gss_name_t *output_name)"
  29 .br
  30 .ti -1c
  31 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_init_sec_context\fP (OM_uint32 *minor_status, const gss_cred_id_t initiator_cred_handle, gss_ctx_id_t *context_handle, const gss_name_t target_name, const gss_OID input_mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID *actual_mech_type, gss_buffer_t output_token, OM_uint32 *ret_flags, OM_uint32 *time_rec)"
  32 .br
  33 .ti -1c
  34 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_inquire_saslname_for_mech\fP (OM_uint32 *minor_status, const gss_OID desired_mech, gss_buffer_t sasl_mech_name, gss_buffer_t mech_name, gss_buffer_t mech_description)"
  35 .br
  36 .ti -1c
  37 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_inquire_attrs_for_mech\fP (OM_uint32 *minor_status, gss_const_OID mech, gss_OID_set *mech_attr, gss_OID_set *known_mech_attrs)"
  38 .br
  39 .ti -1c
  40 .RI "GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL \fBgss_oid_equal\fP (gss_const_OID a, gss_const_OID b)"
  41 .br
  42 .ti -1c
  43 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_release_cred\fP (OM_uint32 *minor_status, gss_cred_id_t *cred_handle)"
  44 .br
  45 .ti -1c
  46 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_release_name\fP (OM_uint32 *minor_status, gss_name_t *input_name)"
  47 .br
  48 .ti -1c
  49 .RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_wrap\fP (OM_uint32 *minor_status, const gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, const gss_buffer_t input_message_buffer, int *conf_state, gss_buffer_t output_message_buffer)"
  50 .br
  51 .in -1c
  52 .SS "Variables"
  53
  54 .in +1c
  55 .ti -1c
  56 .RI "gss_OID_desc GSSAPI_LIB_FUNCTION \fB__gss_c_attr_stream_sizes_oid_desc\fP"
  57 .br
  58 .in -1c
  59 .SH "Detailed Description"
  60 .PP
  61
  62 .SH "Function Documentation"
  63 .PP
  64 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_add_oid_set_member (OM_uint32 * minor_status, const gss_OID member_oid, gss_OID_set * oid_set)"
  65 .PP
  66 Add a oid to the oid set, function does not make a copy of the oid, so the pointer to member_oid needs to be stable for the whole time oid_set is used.
  67 .PP
  68 If there is a duplicate member of the oid, the new member is not added to to the set.
  69 .PP
  70 \fBParameters:\fP
  71 .RS 4
  72 \fIminor_status\fP minor status code.
  73 .br
  74 \fImember_oid\fP member to add to the oid set
  75 .br
  76 \fIoid_set\fP oid set to add the member too
  77 .RE
  78 .PP
  79 \fBReturns:\fP
  80 .RS 4
  81 a gss_error code, see gss_display_status() about printing the error code.
  82 .RE
  83 .PP
  84
  85 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_canonicalize_name (OM_uint32 * minor_status, const gss_name_t input_name, const gss_OID mech_type, gss_name_t * output_name)"
  86 .PP
  87 gss_canonicalize_name takes a Internal Name (IN) and converts in into a mechanism specific Mechanism Name (MN).
  88 .PP
  89 The input name may multiple name, or generic name types.
  90 .PP
  91 If the input_name if of the GSS_C_NT_USER_NAME, and the Kerberos mechanism is specified, the resulting MN type is a GSS_KRB5_NT_PRINCIPAL_NAME.
  92 .PP
  93 For more information about \fBinternalVSmechname\fP.
  94 .PP
  95 \fBParameters:\fP
  96 .RS 4
  97 \fIminor_status\fP minor status code.
  98 .br
  99 \fIinput_name\fP name to covert, unchanged by \fBgss_canonicalize_name()\fP.
 100 .br
 101 \fImech_type\fP the type to convert Name too.
 102 .br
 103 \fIoutput_name\fP the resulting type, release with \fBgss_release_name()\fP, independent of input_name.
 104 .RE
 105 .PP
 106 \fBReturns:\fP
 107 .RS 4
 108 a gss_error code, see gss_display_status() about printing the error code.
 109 .RE
 110 .PP
 111
 112 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_import_name (OM_uint32 * minor_status, const gss_buffer_t input_name_buffer, const gss_OID input_name_type, gss_name_t * output_name)"
 113 .PP
 114 Import a name internal or mechanism name
 115 .PP
 116 Type of name and their format:
 117 .IP "\(bu" 2
 118 GSS_C_NO_OID
 119 .IP "\(bu" 2
 120 GSS_C_NT_USER_NAME
 121 .IP "\(bu" 2
 122 GSS_C_NT_HOSTBASED_SERVICE
 123 .IP "\(bu" 2
 124 GSS_C_NT_EXPORT_NAME
 125 .IP "\(bu" 2
 126 GSS_C_NT_ANONYMOUS
 127 .IP "\(bu" 2
 128 GSS_KRB5_NT_PRINCIPAL_NAME
 129 .PP
 130 .PP
 131 For more information about \fBinternalVSmechname\fP.
 132 .PP
 133 \fBParameters:\fP
 134 .RS 4
 135 \fIminor_status\fP minor status code
 136 .br
 137 \fIinput_name_buffer\fP import name buffer
 138 .br
 139 \fIinput_name_type\fP type of the import name buffer
 140 .br
 141 \fIoutput_name\fP the resulting type, release with \fBgss_release_name()\fP, independent of input_name
 142 .RE
 143 .PP
 144 \fBReturns:\fP
 145 .RS 4
 146 a gss_error code, see gss_display_status() about printing the error code.
 147 .RE
 148 .PP
 149
 150 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_init_sec_context (OM_uint32 * minor_status, const gss_cred_id_t initiator_cred_handle, gss_ctx_id_t * context_handle, const gss_name_t target_name, const gss_OID input_mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID * actual_mech_type, gss_buffer_t output_token, OM_uint32 * ret_flags, OM_uint32 * time_rec)"
 151 .PP
 152 As the initiator build a context with an acceptor.
 153 .PP
 154 Returns in the major
 155 .IP "\(bu" 2
 156 GSS_S_COMPLETE - if the context if build
 157 .IP "\(bu" 2
 158 GSS_S_CONTINUE_NEEDED - if the caller needs to continue another round of gss_i nit_sec_context
 159 .IP "\(bu" 2
 160 error code - any other error code
 161 .PP
 162 .PP
 163 \fBParameters:\fP
 164 .RS 4
 165 \fIminor_status\fP minor status code.
 166 .br
 167 \fIinitiator_cred_handle\fP the credential to use when building the context, if GSS_C_NO_CREDENTIAL is passed, the default credential for the mechanism will be used.
 168 .br
 169 \fIcontext_handle\fP a pointer to a context handle, will be returned as long as there is not an error.
 170 .br
 171 \fItarget_name\fP the target name of acceptor, created using \fBgss_import_name()\fP. The name is can be of any name types the mechanism supports, check supported name types with gss_inquire_names_for_mech().
 172 .br
 173 \fIinput_mech_type\fP mechanism type to use, if GSS_C_NO_OID is used, Kerberos (GSS_KRB5_MECHANISM) will be tried. Other available mechanism are listed in the \fBGSS-API mechanisms\fP section.
 174 .br
 175 \fIreq_flags\fP flags using when building the context, see \fBContext creation flags\fP
 176 .br
 177 \fItime_req\fP time requested this context should be valid in seconds, common used value is GSS_C_INDEFINITE
 178 .br
 179 \fIinput_chan_bindings\fP Channel bindings used, if not exepected otherwise, used GSS_C_NO_CHANNEL_BINDINGS
 180 .br
 181 \fIinput_token\fP input token sent from the acceptor, for the initial packet the buffer of { NULL, 0 } should be used.
 182 .br
 183 \fIactual_mech_type\fP the actual mech used, MUST NOT be freed since it pointing to static memory.
 184 .br
 185 \fIoutput_token\fP if there is an output token, regardless of complete, continue_needed, or error it should be sent to the acceptor
 186 .br
 187 \fIret_flags\fP return what flags was negotitated, caller should check if they are accetable. For example, if GSS_C_MUTUAL_FLAG was negotiated with the acceptor or not.
 188 .br
 189 \fItime_rec\fP amount of time this context is valid for
 190 .RE
 191 .PP
 192 \fBReturns:\fP
 193 .RS 4
 194 a gss_error code, see gss_display_status() about printing the error code.
 195 .RE
 196 .PP
 197
 198 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_inquire_attrs_for_mech (OM_uint32 * minor_status, gss_const_OID mech, gss_OID_set * mech_attr, gss_OID_set * known_mech_attrs)"
 199 .PP
 200 List support attributes for a mech and/or all mechanisms.
 201 .PP
 202 \fBParameters:\fP
 203 .RS 4
 204 \fIminor_status\fP minor status code
 205 .br
 206 \fImech\fP given together with mech_attr will return the list of attributes for mechanism, can optionally be GSS_C_NO_OID.
 207 .br
 208 \fImech_attr\fP see mech parameter, can optionally be NULL, release with gss_release_oid_set().
 209 .br
 210 \fIknown_mech_attrs\fP all attributes for mechanisms supported, release with gss_release_oid_set().
 211 .RE
 212 .PP
 213
 214 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_inquire_saslname_for_mech (OM_uint32 * minor_status, const gss_OID desired_mech, gss_buffer_t sasl_mech_name, gss_buffer_t mech_name, gss_buffer_t mech_description)"
 215 .PP
 216 Returns different protocol names and description of the mechanism.
 217 .PP
 218 \fBParameters:\fP
 219 .RS 4
 220 \fIminor_status\fP minor status code
 221 .br
 222 \fIdesired_mech\fP mech list query
 223 .br
 224 \fIsasl_mech_name\fP SASL GS2 protocol name
 225 .br
 226 \fImech_name\fP gssapi protocol name
 227 .br
 228 \fImech_description\fP description of gssapi mech
 229 .RE
 230 .PP
 231 \fBReturns:\fP
 232 .RS 4
 233 returns GSS_S_COMPLETE or a error code.
 234 .RE
 235 .PP
 236
 237 .SS "GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL gss_oid_equal (gss_const_OID a, gss_const_OID b)"
 238 .PP
 239 Compare two GSS-API OIDs with each other.
 240 .PP
 241 GSS_C_NO_OID matches nothing, not even it-self.
 242 .PP
 243 \fBParameters:\fP
 244 .RS 4
 245 \fIa\fP first oid to compare
 246 .br
 247 \fIb\fP second oid to compare
 248 .RE
 249 .PP
 250 \fBReturns:\fP
 251 .RS 4
 252 non-zero when both oid are the same OID, zero when they are not the same.
 253 .RE
 254 .PP
 255
 256 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_cred (OM_uint32 * minor_status, gss_cred_id_t * cred_handle)"
 257 .PP
 258 Release a credentials
 259 .PP
 260 Its ok to release the GSS_C_NO_CREDENTIAL/NULL credential, it will return a GSS_S_COMPLETE error code. On return cred_handle is set ot GSS_C_NO_CREDENTIAL.
 261 .PP
 262 Example:
 263 .PP
 264 .PP
 265 .nf
 266  gss_cred_id_t cred = GSS_C_NO_CREDENTIAL;
 267  major = gss_release_cred(&minor, &cred);
 268 .fi
 269 .PP
 270 .PP
 271 \fBParameters:\fP
 272 .RS 4
 273 \fIminor_status\fP minor status return code, mech specific
 274 .br
 275 \fIcred_handle\fP a pointer to the credential too release
 276 .RE
 277 .PP
 278 \fBReturns:\fP
 279 .RS 4
 280 an gssapi error code
 281 .RE
 282 .PP
 283
 284 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_iov_buffer (OM_uint32 * minor_status, gss_iov_buffer_desc * iov, int iov_count)"
 285 .PP
 286 Free all buffer allocated by \fBgss_wrap_iov()\fP or \fBgss_unwrap_iov()\fP by looking at the GSS_IOV_BUFFER_FLAG_ALLOCATED flag.
 287 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_name (OM_uint32 * minor_status, gss_name_t * input_name)"
 288 .PP
 289 Free a name
 290 .PP
 291 import_name can point to NULL or be NULL, or a pointer to a gss_name_t structure. If it was a pointer to gss_name_t, the pointer will be set to NULL on success and failure.
 292 .PP
 293 \fBParameters:\fP
 294 .RS 4
 295 \fIminor_status\fP minor status code
 296 .br
 297 \fIinput_name\fP name to free
 298 .RE
 299 .PP
 300 \fBReturns:\fP
 301 .RS 4
 302 a gss_error code, see gss_display_status() about printing the error code.
 303 .RE
 304 .PP
 305
 306 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_unwrap_iov (OM_uint32 * minor_status, gss_ctx_id_t context_handle, int * conf_state, gss_qop_t * qop_state, gss_iov_buffer_desc * iov, int iov_count)"
 307 .PP
 308 Decrypt or verifies the signature on the data.
 309 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap (OM_uint32 * minor_status, const gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, const gss_buffer_t input_message_buffer, int * conf_state, gss_buffer_t output_message_buffer)"
 310 .PP
 311 Wrap a message using either confidentiality (encryption + signature) or sealing (signature).
 312 .PP
 313 \fBParameters:\fP
 314 .RS 4
 315 \fIminor_status\fP minor status code.
 316 .br
 317 \fIcontext_handle\fP context handle.
 318 .br
 319 \fIconf_req_flag\fP if non zero, confidentiality is requestd.
 320 .br
 321 \fIqop_req\fP type of protection needed, in most cases it GSS_C_QOP_DEFAULT should be passed in.
 322 .br
 323 \fIinput_message_buffer\fP messages to wrap
 324 .br
 325 \fIconf_state\fP returns non zero if confidentiality was honoured.
 326 .br
 327 \fIoutput_message_buffer\fP the resulting buffer, release with gss_release_buffer().
 328 .RE
 329 .PP
 330
 331 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap_iov (OM_uint32 * minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int * conf_state, gss_iov_buffer_desc * iov, int iov_count)"
 332 .PP
 333 Encrypts or sign the data.
 334 .PP
 335 This is a more complicated version of \fBgss_wrap()\fP, it allows the caller to use AEAD data (signed header/trailer) and allow greater controll over where the encrypted data is placed.
 336 .PP
 337 The maximum packet size is gss_context_stream_sizes.max_msg_size.
 338 .PP
 339 The caller needs provide the folloing buffers when using in conf_req_flag=1 mode:
 340 .PP
 341 .IP "\(bu" 2
 342 HEADER (of size gss_context_stream_sizes.header) { DATA or SIGN_ONLY } (optional, zero or more) PADDING (of size gss_context_stream_sizes.blocksize, if zero padding is zero, can be omitted) TRAILER (of size gss_context_stream_sizes.trailer)
 343 .PP
 344 .PP
 345 .IP "\(bu" 2
 346 on DCE-RPC mode, the caller can skip PADDING and TRAILER if the DATA elements is padded to a block bountry and header is of at least size gss_context_stream_sizes.header + gss_context_stream_sizes.trailer.
 347 .PP
 348 .PP
 349 HEADER, PADDING, TRAILER will be shrunken to the size required to transmit any of them too large.
 350 .PP
 351 To generate \fBgss_wrap()\fP compatible packets, use: HEADER | DATA | PADDING | TRAILER
 352 .PP
 353 When used in conf_req_flag=0,
 354 .PP
 355 .IP "\(bu" 2
 356 HEADER (of size gss_context_stream_sizes.header) { DATA or SIGN_ONLY } (optional, zero or more) PADDING (of size gss_context_stream_sizes.blocksize, if zero padding is zero, can be omitted) TRAILER (of size gss_context_stream_sizes.trailer)
 357 .PP
 358 .PP
 359 The input sizes of HEADER, PADDING and TRAILER can be fetched using \fBgss_wrap_iov_length()\fP or gss_context_query_attributes().
 360 .SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap_iov_length (OM_uint32 * minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int * conf_state, gss_iov_buffer_desc * iov, int iov_count)"
 361 .PP
 362 Update the length fields in iov buffer for the types:
 363 .IP "\(bu" 2
 364 GSS_IOV_BUFFER_TYPE_HEADER
 365 .IP "\(bu" 2
 366 GSS_IOV_BUFFER_TYPE_PADDING
 367 .IP "\(bu" 2
 368 GSS_IOV_BUFFER_TYPE_TRAILER
 369 .PP
 370 .PP
 371 Consider using gss_context_query_attributes() to fetch the data instead.
 372 .SH "Variable Documentation"
 373 .PP
 374 .SS "gss_OID_desc GSSAPI_LIB_FUNCTION \fB__gss_c_attr_stream_sizes_oid_desc\fP"
 375 .PP
 376 \fBInitial value:\fP
 377 .PP
 378 .nf
 379
 380     {10, rk_UNCONST('\x2a\x86\x48\x86\xf7\x12\x01\x02\x01\x03')}
 381 .fi
 382 Query the context for parameters.
 383 .PP
 384 SSPI equivalent if this function is QueryContextAttributes.
 385 .PP
 386 .IP "\(bu" 2
 387 GSS_C_ATTR_STREAM_SIZES data is a gss_context_stream_sizes.
 388 .PP
 389