gssapi(3)

🎀 hey bestie, this is gssapi(3) — Heimdal GSS-API library 🎀

okay so like, this is the manual page for the Heimdal GSS-API library, and it's giving main character energy for real. We're gonna go through every function, every parameter, every lil detail, and yes, we're keeping it all. No cap. 💅

---

🌸 NAME 🌸

gssapi — Heimdal GSS-API functions 🫶

---

✨ SYNOPSIS ✨

Functions 💖

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)
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)
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)
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)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_iov_buffer
    (OM_uint32 *minor_status, gss_iov_buffer_desc *iov, int iov_count)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_canonicalize_name
    (OM_uint32 *minor_status, gss_const_name_t input_name, const gss_OID
    mech_type, gss_name_t *output_name)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_display_status
    (OM_uint32 *minor_status, OM_uint32 status_value, int status_type,
    const gss_OID mech_type, OM_uint32 *message_context, gss_buffer_t
    status_string)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_export_name (OM_uint32
    *minor_status, gss_const_name_t input_name, gss_buffer_t
    exported_name)
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)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_init_sec_context
    (OM_uint32 *minor_status, gss_const_cred_id_t initiator_cred_handle,
    gss_ctx_id_t *context_handle, gss_const_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)
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)
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)
GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL gss_oid_equal (gss_const_OID a,
    gss_const_OID b)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_cred
    (OM_uint32 *minor_status, gss_cred_id_t *cred_handle)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_name
    (OM_uint32 *minor_status, gss_name_t *input_name)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap (OM_uint32
    *minor_status, gss_const_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)

Variables 🧚

gss_OID_desc GSSAPI_LIB_FUNCTION __gss_c_attr_stream_sizes_oid_desc

---

💖 Detailed Description 💖

okay so literally, this is the whole Heimdal GSS-API function set, bestie. It's giving "everything you need to build and use security contexts" energy. The actual docs for each function are right below in Function Documentation, and we're keeping every single parameter, return value, and side note. Periodt. 👑

---

📚 Function Documentation 📚

gss_add_oid_set_member 💅

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)

Adds an oid to the oid set. But bestie, listen: this function does not make a copy of the oid, so the pointer to member_oid needs to stay stable for the whole entire time oid_set is used. Like, don't move it, don't free it, don't play games. 🫠

If there's already a duplicate member of the oid, the new member is not added to the set. We love a no-duplicates queen. ✨

Parameters 🌸

• minor_status — minor status code.
• member_oid — member to add to the oid set.
• oid_set — oid set to add the member too.

Returns 🎀

a gss_error code, see gss_display_status() about printing the error code.

---

gss_canonicalize_name 🦋

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_canonicalize_name
    (OM_uint32 *minor_status, gss_const_name_t input_name, const gss_OID
    mech_type, gss_name_t *output_name)

gss_canonicalize_name takes an Internal Name (IN) and converts it into a mechanism-specific Mechanism Name (MN). It's giving glow-up, but for names. 💅

The input name may be multiple names, or generic name types.

If the input_name is of the GSS_C_NT_USER_NAME, and the Kerberos mechanism is specified, the resulting MN type is a GSS_KRB5_NT_PRINCIPAL_NAME.

For more information about Internal names and mechanism names. (iykyk)

Parameters 🌈

• minor_status — minor status code.
• input_name — name to covert, unchanged by gss_canonicalize_name().
• mech_type — the type to convert Name too.
• output_name — the resulting type, release with gss_release_name(), independent of input_name.

Returns ⭐

a gss_error code, see gss_display_status() about printing the error code.

---

gss_display_status 💖

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_display_status
    (OM_uint32 *minor_status, OM_uint32 status_value, int status_type,
    const gss_OID mech_type, OM_uint32 *message_context, gss_buffer_t
    status_string)

Convert a GSS-API status code to text. Finally, words instead of numbers. 😭

Parameters 💜

• minor_status — minor status code
• status_value — status value to convert
• status_type — One of: GSS_C_GSS_CODE - status_value is a GSS status code, GSS_C_MECH_CODE - status_value is a mechanism status code
• mech_type — underlying mechanism. Use GSS_C_NO_OID to obtain the system default.
• message_context — state information to extract further messages from the status_value
• status_string — the allocated text representation. Release with gss_release_buffer()

Returns 🌟

a gss_error code.

---

gss_export_name 🎀

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_export_name (OM_uint32 *
    minor_status, gss_const_name_t input_name, gss_buffer_t exported_name)

Convert a GGS-API name from internal form to contiguous string. (Yes, the original says GGS-API, and we're keeping it because it's iconic in its own way. 💀)

See also: gss_import_name(), Internal names and mechanism names.

Parameters 🌸

• minor_status — minor status code
• input_name — input name in internal name form
• exported_name — output name in contiguos string form

Returns 🫶

a gss_error code, see gss_display_status() about printing the error code.

---

gss_import_name 🧚

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)

Convert a GGS-API name from contiguous string to internal form. The reverse of export, bestie. 🔁

Type of name and their format:

• GSS_C_NO_OID
• GSS_C_NT_USER_NAME
• GSS_C_NT_HOSTBASED_SERVICE
• GSS_C_NT_EXPORT_NAME
• GSS_C_NT_ANONYMOUS
• GSS_KRB5_NT_PRINCIPAL_NAME

See also: gss_export_name(), Internal names and mechanism names.

Parameters 💅

• minor_status — minor status code
• input_name_buffer — import name buffer
• input_name_type — type of the import name buffer
• output_name — the resulting type, release with gss_release_name(), independent of input_name

Returns ✨

a gss_error code, see gss_display_status() about printing the error code.

---

gss_init_sec_context 🔥

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_init_sec_context
    (OM_uint32 *minor_status, gss_const_cred_id_t initiator_cred_handle,
    gss_ctx_id_t *context_handle, gss_const_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)

As the initiator, build a context with an acceptor. It's giving "let's link up securely." 🤝

Returns in the major:

• GSS_S_COMPLETE - if the context if build
• GSS_S_CONTINUE_NEEDED - if the caller needs to continue another round of gss_init_sec_context
• error code - any other error code

Parameters 💖

• minor_status — minor status code.
• initiator_cred_handle — the credential to use when building the context, if GSS_C_NO_CREDENTIAL is passed, the default credential for the mechanism will be used.
• context_handle — a pointer to a context handle, will be returned as long as there is not an error.
• target_name — the target name of acceptor, created using gss_import_name(). The name is can be of any name types the mechanism supports, check supported name types with gss_inquire_names_for_mech().
• input_mech_type — 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 GSS-API mechanisms section.
• req_flags — flags using when building the context, see Context creation flags
• time_req — time requested this context should be valid in seconds, common used value is GSS_C_INDEFINITE
• input_chan_bindings — Channel bindings used, if not exepected otherwise, used GSS_C_NO_CHANNEL_BINDINGS
• input_token — input token sent from the acceptor, for the initial packet the buffer of { NULL, 0 } should be used.
• actual_mech_type — the actual mech used, MUST NOT be freed since it pointing to static memory.
• output_token — if there is an output token, regardless of complete, continue_needed, or error it should be sent to the acceptor
• ret_flags — 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.
• time_rec — amount of time this context is valid for

Returns 🌟

a gss_error code, see gss_display_status() about printing the error code.

---

gss_inquire_attrs_for_mech 💜

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)

List support attributes for a mech and/or all mechanisms. It's giving "what can this mech do, bestie?" 🔍

Parameters 🎀

• minor_status — minor status code
• mech — given together with mech_attr will return the list of attributes for mechanism, can optionally be GSS_C_NO_OID.
• mech_attr — see mech parameter, can optionally be NULL, release with gss_release_oid_set().
• known_mech_attrs — all attributes for mechanisms supported, release with gss_release_oid_set().

---

gss_inquire_saslname_for_mech 🦋

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)

Returns different protocol names and description of the mechanism. It's giving name tag, but for mechanisms. 🏷️

---

Parameters

• minor_status — minor status code 💅
• desired_mech — mech list query 🔍
• sasl_mech_name — SASL GS2 protocol name 🎀
• mech_name — gssapi protocol name ✨
• mech_description — description of gssapi mech 📝

Returns

returns GSS_S_COMPLETE or a error code. 😭

---

gss_oid_equal

GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL gss_oid_equal (gss_const_OID a,
    gss_const_OID b)

Compare two GSS-API OIDs with each other. 💖

Bestie warning: GSS_C_NO_OID matches nothing, not even it-self. 💀

Parameters

• a — first oid to compare
• b — second oid to compare

Returns

non-zero when both oid are the same OID, zero when they are not the same. ✨

---

gss_release_cred

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_cred (OM_uint32 *
    minor_status, gss_cred_id_t * cred_handle)

Release a credentials 🫶

It's 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 to GSS_C_NO_CREDENTIAL. 😌

Example:

gss_cred_id_t cred = GSS_C_NO_CREDENTIAL;
major = gss_release_cred(&minor, &cred);

Parameters

• minor_status — minor status return code, mech specific
• cred_handle — a pointer to the credential to release

Returns

an gssapi error code

---

gss_release_iov_buffer

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_iov_buffer
    (OM_uint32 * minor_status, gss_iov_buffer_desc * iov, int iov_count)

Free all buffer allocated by gss_wrap_iov() or gss_unwrap_iov() by looking at the GSS_IOV_BUFFER_FLAG_ALLOCATED flag. 🧹

---

gss_release_name

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_name (OM_uint32 *
    minor_status, gss_name_t * input_name)

Free a name 🕊️

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. 💯

Parameters

• minor_status — minor status code
• input_name — name to free

Returns

a gss_error code, see gss_display_status() about printing the error code. 📖

---

gss_unwrap_iov

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)

Decrypt or verifies the signature on the data. 🔓

---

gss_wrap

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap (OM_uint32 *
    minor_status, gss_const_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)

Wrap a message using either confidentiality (encryption + signature) or sealing (signature). 🎁

Parameters

• minor_status — minor status code.
• context_handle — context handle.
• conf_req_flag — if non zero, confidentiality is requested.
• qop_req — type of protection needed, in most cases it GSS_C_QOP_DEFAULT should be passed in.
• input_message_buffer — messages to wrap
• conf_state — returns non zero if confidentiality was honoured.
• output_message_buffer — the resulting buffer, release with gss_release_buffer().

---

gss_wrap_iov

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)

Encrypts or sign the data. ✍️

This is a more complicated version of gss_wrap(), it allows the caller to use AEAD data (signed header/trailer) and allow greater control over where the encrypted data is placed. 🎛️

The maximum packet size is gss_context_stream_sizes.max_msg_size.

The caller needs provide the following buffers when using in conf_req_flag=1 mode:

• 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)
• on DCE-RPC mode, the caller can skip PADDING and TRAILER if the DATA elements is padded to a block boundary and header is of at least size gss_context_stream_sizes.header + gss_context_stream_sizes.trailer.

HEADER, PADDING, TRAILER will be shrunken to the size required to transmit if any of them are too large. 📏

To generate gss_wrap() compatible packets, use: HEADER | DATA | PADDING | TRAILER

When used in conf_req_flag=0,

• 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)

The input sizes of HEADER, PADDING and TRAILER can be fetched using gss_wrap_iov_length() or gss_context_query_attributes().

---

gss_wrap_iov_length

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)

Update the length fields in iov buffer for the types:

• GSS_IOV_BUFFER_TYPE_HEADER
• GSS_IOV_BUFFER_TYPE_PADDING
• GSS_IOV_BUFFER_TYPE_TRAILER

Consider using gss_context_query_attributes() to fetch the data instead. 💡

---

Variable Documentation

gss_OID_desc GSSAPI_LIB_FUNCTION __gss_c_attr_stream_sizes_oid_desc

Initial value:

=
    {10, rk_UNCONST("a686)}

Query the context for parameters.

SSPI equivalent if this function is QueryContextAttributes.

• GSS_C_ATTR_STREAM_SIZES data is a gss_context_stream_sizes.

---

Author

Generated automatically by Doxygen for Heimdal GSS-API library from the source code. 🤖

---

Version 7.8.0 — Tue Nov 15 2022 — gssapi(3) 💖✨ Stay slaying, bestie! 👑