Low-Level API

The low-level API contains a variety of Python functions that map directly to the corresponding C functions. Additionally, it contains several basic wrapper classes that wrap underlying C structs and automatically deallocate them when the Python object itself is deallocated.

Warning

All methods in both the high-level and low-level APIs may throw the generic GSSError exception.

Core RFC 2744

Names

Note

Some functions in the following section will refer to “mechanism names”. These are not names of mechanisms. Instead, they are a special form of name specific to a given mechanism.

class Name

A GSSAPI Name

canonicalize_name(name, mech)

Canonicalize an arbitrary GSSAPI Name into a Mechanism Name

This method turns any GSSAPI name into a “mechanism name” – a full form name specific to a mechanism.

Parameters:
  • name (Name) – the name to canonicalize
  • mech (MechType) – the mechanism type to use to canonicalize the name
Returns:

a canonicalized version of the input name
Return type:

Name
Raises:
compare_name(name1, name2)

Check two GSSAPI names to see if they are the same.

This method compares two GSSAPI names, checking to see if they are equivalent.

Parameters:
  • name1 (Name) – the first name to compare
  • name2 (Name) – the second name to compare
Returns:

whether or not the names are equal
Return type:

bool
Raises:
display_name(name, name_type=True)

Convert a GSSAPI name into its components.

This method converts a GSSAPI Name back into its text form. If name_type is True, it also attempts to retrieve the NameType of the name (otherwise the returned name type will be None).

Parameters:
  • name (Name) – the name in question
  • name_type (bool) – whether or not to retrieve the name type
Returns:

the text part of the name and its type
Return type:

DisplayNameResult
Raises:

BadNameError
duplicate_name(name)

Duplicate a GSSAPI name.

Parameters:name (Name) – the name to duplicate
Returns:a duplicate of the input name
Return type:Name
Raises:BadNameError
export_name()

Export a GSSAPI name.

This method “produces a canonical contigous string representation of a mechanism name, suitable for direct comparison for use in authorization functions”.

The input name must be a valid GSSAPI mechanism name, as generated by canonicalize_name() or accept_sec_context().

Parameters:

name (Name) – the name to export
Returns:

the exported name
Return type:

bytes
Raises:
import_name(name, name_type=None)

Convert a string and a name type into a GSSAPI name.

This method takes a string name and a name type and converts them into a GSSAPI Name.

Parameters:
  • name (bytes) – the string version of the name
  • name_type (NameType) – the type of this name
Returns:

the GSSAPI version of the name
Return type:

Name
Raises:
release_name(name)

Release a GSSAPI name.

This method frees a GSSAPI Name. You probably won’t have to do this.

Warning

This method is deprecated. Names are automatically freed by Python.

Parameters:name (Name) – the name in question
Raises:BadNameError

Credentials

class Creds

GSSAPI Credentials

acquire_cred(name=None, lifetime=None, mechs=None, usage=’both’)

Get GSSAPI credentials for the given name and mechanisms.

This method gets GSSAPI credentials corresponding to the given name and mechanims. The desired TTL and usage for the the credential may also be specified.

Parameters:
  • name (Name) – the name for which to acquire the credentials (or None for the “no name” functionality)
  • lifetime (int) – the lifetime for the credentials (or None for indefinite)
  • mechs ([MechType]) – the desired mechanisms for which the credentials should work, or None for the default set
  • usage (str) – the usage type for the credentials: may be ‘initiate’, ‘accept’, or ‘both’
Returns:

the resulting credentials, the actual mechanisms with which they may be used, and their actual lifetime (or None for indefinite or not supported)
Return type:

AcquireCredResult
Raises:
add_cred(input_cred, name, mech, usage=’initiate’, init_lifetime=None, accept_lifetime=None, mutate_input=False)

Add a credential element to a credential.

This method can be used to either compose two credentials (i.e., original and new credential), or to add a new element to an existing credential.

Parameters:
  • input_cred (Cred) – the set of credentials to which to add the new credentials
  • name (Name) – name of principal to acquire a credential for
  • mech (MechType) – the desired security mechanism (required).
  • usage (str) – usage type for credentials. Possible values: ‘initiate’ (default), ‘accept’, ‘both’ (failsafe).
  • init_lifetime (int) – lifetime of credentials for use in initiating security contexts (None for indefinite)
  • accept_lifetime (int) – lifetime of credentials for use in accepting security contexts (None for indefinite)
  • mutate_input (bool) – whether to mutate the input credentials (True) or produce a new set of credentials (False). Defaults to False
Returns:

the actual mechanisms with which the credentials may be used, the actual initiator TTL, and the actual acceptor TTL (None for either indefinite or not supported). Note that the credentials may be set to None if mutate_input is set to True.
Return type:

AddCredResult
Raises:
inquire_cred(creds, name=True, lifetime=True, usage=True, mechs=True)

Inspect credentials for information.

This method inspects a Creds object for information.

Parameters:
  • creds (Creds) – the credentials to inspect
  • name (bool) – get the Name associated with the credentials
  • lifetime (bool) – get the TTL for the credentials
  • usage (bool) – get the usage type of the credentials
  • mechs (bool) – the mechanims used with the credentials
Returns:

the information about the credentials,

with unused fields set to None
Return type:

InquireCredResult
Raises:
inquire_cred_by_mech(creds, mech, name=True, init_lifetime=True, accept_lifetime=True, usage=True)

Inspect credentials for mechanism-specific information.

This method inspects a Creds object for information specific to a particular mechanism. It functions similarly to inquire_cred().

Parameters:
  • creds (Creds) – the credentials to inspect
  • mech (OID) – the desired mechanism
  • name (bool) – get the Name associated with the credentials
  • init_lifetime (bool) – get the initiator TTL for the credentials
  • accept_lifetime (bool) – get the acceptor TTL for the credentials
  • usage (bool) – get the usage type of the credentials
Returns:

the information about the credentials,

with unused fields set to None
Return type:

InquireCredByMechResult
Raises:
release_cred(creds)

Release GSSAPI Credentials.

This method releases GSSAPI credentials.

Warning

This method is deprecated. Credentials are automatically freed by Python.

Parameters:creds (Creds) – the credentials in question
Raises:MissingCredentialsError

Security Contexts

class SecurityContext

A GSSAPI Security Context

accept_sec_context(input_token, acceptor_creds=None, context=None, channel_bindings=None)

Accept a GSSAPI security context.

This method accepts a GSSAPI security context using a token sent by the initiator, using the given credentials. It can either be used to accept a security context and create a new security context object, or to update an existing security context object.

Warning

This changes the input context!

Parameters:
  • input_token (bytes) – the token sent by the context initiator
  • acceptor_creds (Creds) – the credentials to be used to accept the context (or None to use the default credentials)
  • context (SecurityContext) – the security context to update (or None to create a new security context object)
  • channel_bindings (ChannelBindings) – The channel bindings (or None for no channel bindings)
Returns:

the resulting security context, the initiator

name, the mechanism being used, the output token, the flags in use, the lifetime of the context (or None for indefinite or not supported), the delegated credentials (valid only if the delegate_to_peer flag is set), and whether or not further token exchanges are needed to finalize the security context.
Return type:

AcceptSecContextResult
Raises:
context_time(context)

Get the amount of time for which the given context will remain valid.

This method determines the amount of time for which the given security context will remain valid. An expired context will give a result of 0.

Parameters:

context (SecurityContext) – the security context in question
Returns:

the number of seconds for which the context will be valid
Return type:

int
Raises:
delete_sec_context(context, local_only=True)

Delete a GSSAPI security context.

This method deletes a GSSAPI security context, returning an output token to send to the other holder of the security context to notify them of the deletion.

Note

This method generally should not be used. SecurityContext objects will automatically be freed by Python.

Parameters:
  • context (SecurityContext) – the security context in question
  • local_only (bool) – should we request local deletion (True), or also remote deletion (False), in which case a token is also returned
Returns:

the output token (if remote deletion is requested). Generally

this is None, but bytes for compatibility.
Return type:

bytes
Raises:

MissingContextError
export_sec_context(context)

Export a context for use in another process.

This method exports a security context, deactivating in the current process and creating a token which can then be imported into another process with import_sec_context().

Warning: this modifies the input context

Parameters:

context (SecurityContext) – the context to send to another process
Returns:

the output token to be imported
Return type:

bytes
Raises:
import_sec_context(token)

Import a context from another process.

This method imports a security context established in another process by reading the specified token which was output by export_sec_context().

Raises:
init_sec_context(target_name, creds=None, context=None, mech=None, flags=None, lifetime=None, channel_bindings=None, input_token=None)

Initiate a GSSAPI security context.

This method initiates a GSSAPI security context, targeting the given target name. To create a basic context, just provide the target name. Further calls used to update the context should pass in the output context of the last call, as well as the input token received from the acceptor.

Warning

This changes the input context!

Parameters:
  • target_name (Name) – the target for the security context
  • creds (Creds) – the credentials to use to initiate the context, or None to use the default credentials
  • context (SecurityContext) – the security context to update, or None to create a new context
  • mech (MechType) – the mechanism type for this security context, or None for the default mechanism type
  • flags (list) – the flags to request for the security context, or None to use the default set: mutual_authentication and out_of_sequence_detection. This may also be an IntEnumFlagSet
  • lifetime (int) – the request lifetime of the security context (a value of 0 or None means indefinite)
  • channel_bindings (ChannelBindings) – The channel bindings (or None for no channel bindings)
  • input_token (bytes) – the token to use to update the security context, or None if you are creating a new context
Returns:

the output security context, the actual mech type, the actual flags used, the output token to send to the acceptor, the actual lifetime of the context (or None if not supported or indefinite), and whether or not more calls are needed to finish the initiation.
Return type:

InitSecContextResult
Raises:
inquire_context(context, initiator_name=True, target_name=True, lifetime=True, mech=True, flags=True, locally_init=True, complete=True)

Get information about a security context.

This method obtains information about a security context, including the initiator and target names, as well as the TTL, mech, flags, and its current state (open vs closed).

Note

the target name may be None if it would have been GSS_C_NO_NAME

Parameters:context (SecurityContext) – the context in question
Returns:
the initiator name, the target name, the TTL
(can be None for indefinite or not supported), the mech type, the flags, whether or not the context was locally initiated, and whether or not the context is currently fully established
Return type:InquireContextResult
Raises:MissingContextError
process_context_token(context, token)

Process a token asynchronously.

This method provides a way to process a token, even if the given security context is not expecting one. For example, if the initiator has the initSecContext return that the context is complete, but the acceptor is unable to accept the context, and wishes to send a token to the initiator, letting the initiator know of the error.

Warning

This method has been essentially deprecated by RFC 2744.

Parameters:
  • context (SecurityContext) – the security context against which to process the token
  • token (bytes) – the token to process
Raises:
get_mic(context, message, qop=None)

Generate a MIC for a message.

This method generates a Message Integrity Check token for the given message. This can be separately trasmitted to the other entity, unlike wrap, which bundles the MIC and the message together.

Parameters:
  • context (SecurityContext) – the current security context
  • message (bytes) – the message for which to generate the MIC
  • qop (int) – the requested Quality of Protection (or None to use the default)
Returns:

the generated MIC token
Return type:

bytes
Raises:
unwrap(context, message)

Unwrap/Decrypt a message.

This method unwraps or decrypts a message, depending on whether the sender used confidentiality.

Parameters:
  • context (SecurityContext) – the current security context
  • message (bytes) – the message to unwrap/decrypt
Returns:

the unwrapped/decrypted message, whether or on

encryption was used, and the QoP used
Return type:

UnwrapResult
Raises:
verify_mic(context, message, token)

Verify that a MIC matches a message.

This method verifies that the given MIC matches the given message. If the MIC does not match the given message, an exception will be raised.

Parameters:
  • context (SecurityContext) – the current security context
  • message (bytes) – the message in question
  • token (bytes) – the MIC token in question
Returns:

the QoP used.
Return type:

int
Raises:
wrap(context, message, confidential=True, qop=None)

Wrap/Encrypt a message.

This method wraps or encrypts a message (depending on the value of confidential) with the given Quality of Protection.

Parameters:
  • context (SecurityContext) – the current security context
  • message (bytes) – the message to wrap or encrypt
  • confidential (bool) – whether or not to encrypt the message (True), or just wrap it with a MIC (False)
  • qop (int) – the desired Quality of Protection (or None for the default QoP)
Returns:

the wrapped/encrypted message, and whether or not

encryption was actually used
Return type:

WrapResult
Raises:
wrap_size_limit(context, output_size, confidential=True, qop=None)

Calculate the max message size.

This method calculates the unwrapped/unencrypted message size for the given maximum wrapped/encrypted message size.

Parameters:
  • context (SecurityContext) – the current security context
  • output_size (int) – the maximum desired wrapped/encrypted message size
  • confidential (bool) – whether or not confidentiality is being used
  • qop (int) – the QoP that will be when you actually call wrap (or None for the default QoP)
Returns:

the maximum unencrypted/unwrapped message size
Return type:

int
Raises:

Misc

class OID

A GSSAPI OID

A new OID may be created by passing the elements argument to the constructor. The elements argument should be a bytes consisting of the BER-encoded values in the OID.

To retrive the underlying bytes, use the bytes() function in Python 3 or the __bytes__() method directly in Python 2.

This object is hashable, and may be compared using equality operators.

from_int_seq(integer_sequence)

Create a OID from a sequence of integers.

This method creates an OID from a sequence of integers. The sequence can either be in dotted form as a string, or in list form.

This method is not for BER-encoded byte strings, which can be passed directly to the OID constructor.

Parameters:integer_sequence – either a list of integers or a string in dotted form
Returns:the OID represented by the given integer sequence
Return type:OID
Raises:ValueError – the sequence is less than two elements long
exception GSSError

A GSSAPI Error

This Exception represents an error returned from the GSSAPI C bindings. It contains the major and minor status codes returned by the method which caused the error, and can generate human-readable string messages from the error codes

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
MESSAGE = ‘Major ({maj_stat}): {maj_str}, Minor ({min_stat}): {min_str}’
gen_message()

Retrieves all messages for this error’s status codes

This method retrieves all messages for this error’s status codes, and forms them into a string for use as an exception message

Returns:a string for use as this error’s message
Return type:bytes
get_all_statuses()

Retrieve all messages for a status code.

This method retrieves all human-readable messages available for the given status code.

Parameters:
  • code (int) – the status code in question
  • is_maj (bool) – whether this is a major status code (True) or minor status code (False)
Returns:

A list of string messages associated with the

given code
Return type:

[bytes]
class GSSErrorRegistry
indicate_mechs()

Get the currently supported mechanisms.

This method retrieves the currently supported GSSAPI mechanisms. Note that if unknown mechanims are found, those will be skipped.

inquire_mechs_for_name(name)

List the mechanisms which can process a name.

This method lists the mechanisms which may be able to process the given name.

Parameters:name (Name) – the name in question
Returns:the mechanism OIDs able to process the given name
Return type:list
Raises:GSSError
inquire_names_for_mech(mech)

Get the name types supported by a mechanism.

This method retrives the different name types supported by the given mechanism.

Parameters:mech (OID) – the mechanism in question
Returns:the name type OIDs supported by the given mechanism
Return type:list
Raises:GSSError
class AddressType

GSSAPI Channel Bindings Address Types

This IntEnum represents the various address types used with the ChannelBindings structure.

The numbers behind the values correspond directly to their C counterparts. There is no value for GSS_C_AF_UNSPEC, since this is represented by None.

appletalk = 16
arpanet = 3
bisync = 17
ccitt = 10
chaos = 5
datakit = 9
decnet = 12
dli = 13
dss = 18
ecma = 8
hyperchannel = 15
ibm_sna = 11
ip = 2
lat = 14
local = 1
nbs = 7
null = 255
osi_tp4 = 19
pup = 4
x25 = 21
xerox_ns = 6
class GenericFlagSet

A set backed by a 32-bit integer

This is a set backed by a 32 bit integer. the members are integers where only one bit is set.

The class supports normal set operations, as well as traditional “flag set” operations, such as bitwise AND, OR, and XOR.

MAX_VAL = 2147483648
add()
discard()
class IntEnumFlagSet

A set backed by a 32-bit integer with enum members

This class is a GenericFlagSet where the returned members are values in an IntEnum.

It functions exactly like a GenericFlagSet, except that it also supports bitwise operations with the enum values.

class MechType

GSSAPI Mechanism Types

This enum-like object contains any mechanism OID values registered by imported mechanisms.

kerberos = <OID 1.2.840.113554.1.2.2>
class NameType

GSSAPI Name Types

This enum-like object represents GSSAPI name types (to be used with import_name(), etc)

anonymous = <OID 1.3.6.1.5.6.3>
composite_export = <OID 1.3.6.1.5.6.6>
export = <OID 1.3.6.1.5.6.4>
hostbased_service = <OID 1.2.840.113554.1.2.1.4>
kerberos_principal = <OID 1.2.840.113554.1.2.2.1>
machine_uid = <OID 1.2.840.113554.1.2.1.2>
string_uid = <OID 1.2.840.113554.1.2.1.3>
user = <OID 1.2.840.113554.1.2.1.1>
class RequirementFlag

GSSAPI Requirement Flags

This IntEnum represents flags used with the SecurityContext-related methods (e.g. init_sec_context())

The numbers behind the values correspond directly to their C counterparts.

anonymity = 64
confidentiality = 16
dce_style = 4096
delegate_to_peer = 1
extended_error = 16384
identify = 8192
integrity = 32
mutual_authentication = 2
out_of_sequence_detection = 8
protection_ready = 128
replay_detection = 4
transferable = 256
class ChannelBindings

GSSAPI Channel Bindings

This class represents a set of GSSAPI channel bindings.

Parameters:
  • initiator_address_type (AddressType) – the initiator address type
  • initiator_address (bytes) – the initiator address
  • acceptor_address_type (AddressType) – the acceptor address type
  • acceptor_address (bytes) – the acceptor address
  • application_data (bytes) – additional application-specific data
acceptor_address
acceptor_address_type
application_data
initiator_address
initiator_address_type

Additional RFCs and Extensions

The following is a list of GSSAPI extensions supported by the low-level API.

Note

While all of these extensions have bindings, they may not be supported by your particularly GSSAPI implementation. In this case, they will not be compiled, and will simply not be available in the gssapi.raw namespace.

RFC 5588 (GSS-API Extension for Storing Delegated Credentials)

store_cred(creds, usage=’both’, mech=None, overwrite=False, set_default=False)

Store credentials into the default store.

This method stores the given credentials into the default store. They may then be retrieved later using acquire_cred().

Parameters:
  • creds (Creds) – the credentials to store
  • usage (str) – the usage to store the credentials with – either ‘both’, ‘initiate’, or ‘accept’
  • mech (OID) – the mechansim to associate with the stored credentials
  • overwrite (bool) – whether or not to overwrite existing credentials stored with the same name, etc
  • set_default (bool) – whether or not to set these credentials as the default credentials for the given store.
Returns:

the results of the credential storing operation
Return type:

StoreCredResult
Raises:

Credential Store Extensions

Credential Store Extension

acquire_cred_from(store=None, name=None, lifetime=None, mechs=None, usage=’both’)

Acquire credentials from the given store.

This method acquires credentials from the store specified by the given credential store information.

The credential store information is a dictionary containing mechanisms-specific keys and values pointing to a credential store or stores.

Parameters:
  • store (dict) – the credential store information pointing to the credential store from which to acquire the credentials
  • name (Name) – the name associated with the credentials, or None for the default name
  • lifetime (int) – the desired lifetime of the credentials, or None for indefinite
  • mechs (list) – the desired mechanisms to be used with these credentials, or None for the default set
  • usage (str) – the usage for these credentials – either ‘both’, ‘initiate’, or ‘accept’
Returns:

the acquired credentials and information about

them
Return type:

AcquireCredResult
Raises:

GSSError
add_cred_from(store, input_creds, name, mech, usage=’both’, init_lifetime=None, accept_lifetime=None)

Acquire credentials to add to the current set from the given store.

This method works like acquire_cred_from(), except that it adds the acquired credentials for a single mechanism to a copy of the current set, instead of creating a new set for multiple mechanisms. Unlike acquire_cred(), you cannot pass None for the desired name or mechanism.

The credential store information is a dictionary containing mechanisms-specific keys and values pointing to a credential store or stores.

Parameters:
  • store (dict) – the store into which to store the credentials, or None for the default store.
  • name (Name) – the name associated with the credentials
  • mech (OID) – the desired mechanism to be used with these credentials
  • usage (str) – the usage for these credentials – either ‘both’, ‘initiate’, or ‘accept’
  • init_lifetime (int) – the desired initiate lifetime of the credentials, or None for indefinite
  • accept_lifetime (int) – the desired accept lifetime of the credentials, or None for indefinite
Returns:

the new credentials set and information about

it
Return type:

AcquireCredResult
Raises:

GSSError
store_cred_into(store, creds, usage=’both’, mech=None, overwrite=False, set_default=False)

Store credentials into the given store.

This method stores the given credentials into the store specified by the given store information. They may then be retrieved later using acquire_cred_from() or add_cred_from().

The credential store information is a dictionary containing mechanisms-specific keys and values pointing to a credential store or stores.

Parameters:
  • store (dict) – the store into which to store the credentials, or None for the default store.
  • creds (Creds) – the credentials to store
  • usage (str) – the usage to store the credentials with – either ‘both’, ‘initiate’, or ‘accept’
  • mech (OID) – the mechansim to associate with the stored credentials
  • overwrite (bool) – whether or not to overwrite existing credentials stored with the same name, etc
  • set_default (bool) – whether or not to set these credentials as the default credentials for the given store.
Returns:

the results of the credential storing operation
Return type:

StoreCredResult
Raises:

GSSError

RFC 6680 (GSS-API Naming Extensions)

delete_name_attribute(name, attr)

Remove an attribute from a name.

This method removes an attribute from a Name. This method may be used before set_name_attribute() clear the values of an attribute before setting a new value (making the latter method work like a ‘set’ operation instead of an ‘add’ operation).

Note that the removal of certain attributes may not be allowed.

Parameters:
  • name (Name) – the name to remove the attribute from
  • attr (bytes) – the name of the attribute
Raises:
display_name_ext(name, name_type)

Display the given Name using the given name type.

This method attempts to display the given Name using the syntax of the given name type. If this is not possible, an appropriate error will be raised.

Parameters:
  • name (Name) – the name to display
  • name_type (OID) – the name type (see NameType) to use to display the given name
Returns:

the displayed name
Return type:

bytes
Raises:

OperationUnavailableError – the given name could not be displayed using the given name type
export_name_composite(name)

Export a name, preserving attribute information.

This method functions similarly to export_name(), except that it preserves attribute information. The resulting bytes may be imported using import_name() with the NameType.composite_export name type.

Note

Some versions of MIT Kerberos require you to either canonicalize a name once it has been imported with composite-export name type, or to import using the normal export name type.

Parameters:name (Name) – the name to export
Returns:the exported composite name
Return type:bytes
Raises:GSSError
get_name_attribute(name, attr, more=None)

Get the value(s) of a name attribute.

This method retrieves the value(s) of the given attribute for the given Name.

Note that this functionality matches pseudo-API presented in RFC 6680, not the C API (which uses a state variable and multiple calls to retrieve multiple values).

Parameters:
  • name (Name) – the Name from which to get the attribute
  • attr (bytes) – the name of the attribute
Returns:

the raw version of the value(s),

the human-readable version of the value(s), whether or not the attribute was authenticated, and whether or not the attribute’s value set was marked as complete
Return type:

GetNameAttributeResult
Raises:

OperationUnavailableError – the given attribute is unknown or unset
inquire_name(name, mech_name=True, attrs=True)

Get information about a Name.

This method retrives information about the given name, including the set of attribute names for the given name, as well as whether or not the name is a mechanism name. Additionally, if the given name is a mechanism name, the associated mechansim is returned as well.

Parameters:
  • name (Name) – the name about which to inquire
  • mech_name (bool) – whether or not to retrieve if this name is a mech_name (and the associate mechanism)
  • attrs (bool) – whether or not to retrieve the attribute name list
Returns:

the set of attribute names for the given name,

whether or not the name is a Mechanism Name, and potentially the associated mechanism if it is a Mechanism Name
Return type:

InquireNameResult
Raises:

GSSError
set_name_attribute(name, attr, value, complete=False)

Set the value(s) of a name attribute.

This method sets the value(s) of the given attribute on the given name.

Note that this functionality more closely matches the pseudo-API presented in RFC 6680, not the C API (which uses multiple calls to add multiple values). However, multiple calls to this method will continue adding values, so delete_name_attribute() must be used in between calls to “clear” the values.

Parameters:
  • name (Name) – the Name on which to set the attribute
  • attr (bytes) – the name of the attribute
  • value (list) – a list of bytes objects to use as the value(s)
  • complete (bool) – whether or not to mark this attribute’s value set as being “complete”
Raises:

OperationUnavailableError – the given attribute name is unknown or could not be set

Credentials Import-Export Extensions

Credentials Import/Export Extension

export_cred(creds)

Export GSSAPI credentials.

This method exports GSSSAPI credentials into a token which may be transmitted between different processes.

Parameters:creds (Creds) – the credentials object to be exported
Returns:the exported token representing the given credentials object
Return type:bytes
Raises:GSSError
import_cred(token)

Import GSSAPI credentials from a token.

This method imports a credentials object from a token previously exported by export_cred().

Parameters:token (bytes) – the token to import
Returns:the imported credentials object
Return type:Creds
Raises:GSSError

DCE (IOV/AEAD) Extensions

class IOV

A GSSAPI IOV

AUTO_ALLOC_BUFFERS = {<IOVBufferType.padding: 9>, <IOVBufferType.header: 2>, <IOVBufferType.mic_token: 12>, <IOVBufferType.trailer: 7>}
count()
index()
class IOVBufferType

IOV Buffer Types

This IntEnum represent GSSAPI IOV buffer types to be used with the IOV methods.

The numbers behind the values correspond directly to their C counterparts.

data = 1
empty = 0
header = 2
mech_params = 3
mic_token = 12
padding = 9
sign_only = 11
stream = 10
trailer = 7
unwrap_aead(context, message, associated=None)

Unwrap/Decrypt an AEAD message.

This method takes an encrpyted/wrapped AEAD message and some associated data, and returns an unwrapped/decrypted message.

Parameters:
  • context (SecurityContext) – the current security context
  • message (bytes) – the AEAD message to unwrap or decrypt
  • associated (bytes) – associated data that goes with the message
Returns:

the unwrapped/decrypted message, whether or on

encryption was used, and the QoP used
Return type:

UnwrapResult
Raises:

GSSError
unwrap_iov(context, message)

Unwrap/Decrypt an IOV message.

This method uwraps or decrypts an IOV message. The allocate parameter of the IOVBuffer objects in the IOV indicates whether or not that particular buffer should be automatically allocated (for use with padding, header, and trailer buffers).

As a special case, you may pass an entire IOV message as a single ‘stream’. In this case, pass a buffer type of IOVBufferType.stream followed by a buffer type of IOVBufferType.data. The former should contain the entire IOV message, while the latter should be empty.

Warning

This modifies the input IOV.

Parameters:
  • context (SecurityContext) – the current security context
  • message (IOV) – an IOV containing the message
Returns:

whether or not confidentiality was used,

and the QoP used.
Return type:

IOVUnwrapResult
Raises:

GSSError
wrap_aead(context, message, associated=None, confidential=True, qop=None)

Wrap/Encrypt an AEAD message.

This method takes an input message and associated data, and outputs and AEAD message.

Parameters:
  • context (SecurityContext) – the current security context
  • message (bytes) – the message to wrap or encrypt
  • associated (bytes) – associated data to go with the message
  • confidential (bool) – whether or not to encrypt the message (True), or just wrap it with a MIC (False)
  • qop (int) – the desired Quality of Protection (or None for the default QoP)
Returns:

the wrapped/encrypted total message, and whether or not

encryption was actually used
Return type:

WrapResult
Raises:

GSSError
wrap_iov(context, message, confidential=True, qop=None)

Wrap/Encrypt an IOV message.

This method wraps or encrypts an IOV message. The allocate parameter of the IOVBuffer objects in the IOV indicates whether or not that particular buffer should be automatically allocated (for use with padding, header, and trailer buffers).

Warning

This modifies the input IOV.

Parameters:
  • context (SecurityContext) – the current security context
  • message (IOV) – an IOV containing the message
  • confidential (bool) – whether or not to encrypt the message (True), or just wrap it with a MIC (False)
  • qop (int) – the desired Quality of Protection (or None for the default QoP)
Returns:

whether or not confidentiality was actually used
Return type:

bool
Raises:

GSSError
wrap_iov_length(context, message, confidential=True, qop=None)

Appropriately size padding, trailer, and header IOV buffers.

This method sets the length values on the IOV buffers. You should already have data provided for the data (and sign-only) buffer(s) so that padding lengths can be appropriately computed.

In Python terms, this will result in an appropriately sized bytes object consisting of all zeros.

Warning

This modifies the input IOV.

Parameters:
  • context (SecurityContext) – the current security context
  • message (IOV) – an IOV containing the message
Returns:

a list of :class:IOVBuffer` objects, and whether or not

encryption was actually used
Return type:

WrapResult
Raises:

GSSError

IOV MIC Extensions

get_mic_iov(context, message, qop=None)

Generate MIC tokens for the given IOV message.

This method generates a MIC token for the given IOV message, and places it in the IOVBufferType.mic_token buffer in the IOV. This method operates entirely in-place, and returns nothing.

Warning

This modifies the input IOV.

Parameters:
  • context (SecurityContext) – the current security context
  • message (IOV) – the IOV containing the message
  • qop (int) – the desired Quality of Protection (or None for the default QoP)
Raises:

GSSError
get_mic_iov_length(context, message, qop=None)

Allocate space for the MIC buffer in the given IOV message.

This method allocates space for the MIC token buffer (IOVBufferType.mic_token) in the given IOV message.

Warning

This modifies the input IOV.

Parameters:
  • context (SecurityContext) – the current security context
  • message (IOV) – the IOV containing the message
  • qop (int) – the desired Quality of Protection (or None for the default QoP)
Raises:

GSSError
verify_mic_iov(context, message, qop=None)

Verify that the MIC matches the data in the given IOV message.

This method verifies that the MIC token in the MIC buffer (IOVBufferType.mic_token) match the data buffer(s) in the given IOV method.

Parameters:
  • context (SecurityContext) – the current security context
  • message (IOV) – the IOV containing the message
Returns:

the QoP used to generate the MIC token
Return type:

int
Raises:

GSSError

Services4User Extensions

Service4User Extension

acquire_cred_impersonate_name(impersonator_cred, name, lifetime=None, mechs=None, usage=’initiate’)

Acquire credentials by impersonating another name.

This method is one of the ways to use S4U2Self. It acquires credentials by impersonating another name using a set of proxy credentials. The impersonator credentials must have a usage of ‘both’ or ‘initiate’.

Parameters:
  • impersonator_cred (Cred) – the credentials with permissions to impersonate the target name
  • name (Name) – the name to impersonate
  • lifetime (int) – the lifetime for the credentials (or None for indefinite)
  • mechs ([MechType]) – the desired mechanisms for which the credentials should work (or None for the default set)
  • usage (str) – the usage type for the credentials: may be ‘initiate’, ‘accept’, or ‘both’
Returns:

the resulting credentials, the actual mechanisms with which they may be used, and their actual lifetime (or None for indefinite or not support)
Return type:

AcquireCredResult
Raises:

GSSError
add_cred_impersonate_name(input_cred, impersonator_cred, name, mech, usage=’initiate’, init_lifetime=None, accept_lifetime=None)

Add a credentials element to a credential by impersonating another name.

This method is one of the ways to use S4U2Self. It adds credentials to the input credentials by impersonating another name using a set of proxy credentials. The impersonator credentials must have a usage of ‘both’ or ‘initiate’.

Parameters:
  • input_cred (Cred) – the set of credentials to which to add the new credentials
  • impersonator_cred (Cred) – the credentials with permissions to impersonate the target name
  • name (Name) – the name to impersonate
  • mech (MechType) – the desired mechanism. Note that this is both singular and required, unlike acquireCredImpersonateName
  • usage (str) – the usage type for the credentials: may be ‘initiate’, ‘accept’, or ‘both’
  • init_lifetime (int) – the lifetime for the credentials to remain valid when using them to initiate security contexts (or None for indefinite)
  • accept_lifetime (int) – the lifetime for the credentials to remain valid when using them to accept security contexts (or None for indefinite)
Returns:

the actual mechanisms with which the credentials may be used, the actual initiator TTL, and the actual acceptor TTL (the TTLs may be None for indefinite or not supported)
Return type:

AddCredResult
Raises:

GSSError

Acquiring Credentials With a Password Extensions

acquire_cred_with_password(name, password, lifetime=None, mechs=None, usage=”initiate”)

Acquire credentials through provided password.

This function is originally from Solaris and is not documented by either MIT or Heimdal.

In general, it functions similarly to acquire_cred().

Parameters:
  • name (Name) – the name to acquire credentials for
  • password (bytes) – the password used to acquire credentialss with
  • lifetime (int) – the lifetime for the credentials (or None for indefinite)
  • mechs ([MechType]) – the desired mechanisms for which the credentials should work (or None for the default set)
  • usage (str) – usage type for credentials. Possible values: ‘initiate’ (default), ‘accept’, ‘both’ (failsafe).
Returns:

the resulting credentials, the actual mechanisms with which they may be used, and their actual lifetime (or None for indefinite or not supported)
Return type:

AcquireCredResult
Raises:

GSSError
add_cred_with_password(input_cred, name, mech, password, usage=’initiate’, init_lifetime=None, accept_lifetime=None)

Add a credential-element to a credential using provided password.

This function is originally from Solaris and is not documented by either MIT or Heimdal.

In general, it functions similarly to add_cred().

Parameters:
  • input_cred (Creds) – the credentials to add to
  • name (Name) – the name to acquire credentials for
  • mech (MechType) – the desired mechanism. Note that this is both singular and required
  • password (bytes) – the password used to acquire credentialss with
  • usage (str) – the usage type for the credentials: may be ‘initiate’, ‘accept’, or ‘both’
  • init_lifetime (int) – the lifetime for the credentials to remain valid when using them to initiate security contexts (or None for indefinite)
  • accept_lifetime (int) – the lifetime for the credentials to remain valid when using them to accept security contexts (or None for indefinite)
Returns:

the actual mechanisms with which the credentials may be used, the actual initiator TTL, and the actual acceptor TTL (the TTLs may be None for indefinite or not supported)
Return type:

AddCredResult
Raises:

GSSError

Exceptions

exception BadChannelBindingsError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 262144
exception BadMICError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 393216
exception BadMechanismError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 65536
exception BadNameError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 131072
exception BadNameTypeError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 196608
exception BadQoPError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 917504
exception BadStatusError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 327680
exception ContextReadError

Bases: gssapi.raw.exceptions.ParameterReadError, gssapi.raw.exceptions.MissingContextError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception ContextWriteError

Bases: gssapi.raw.exceptions.ParameterWriteError, gssapi.raw.exceptions.MissingContextError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception CredentialsReadError

Bases: gssapi.raw.exceptions.ParameterReadError, gssapi.raw.exceptions.MissingCredentialsError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception CredentialsWriteError

Bases: gssapi.raw.exceptions.ParameterWriteError, gssapi.raw.exceptions.MissingCredentialsError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception DuplicateCredentialsElementError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 1114112
exception DuplicateTokenError

Bases: gssapi.raw.exceptions.SupplementaryError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
SUPPLEMENTARY_CODE = 2
exception ExpiredContextError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 786432
exception ExpiredCredentialsError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 720896
exception ExpiredTokenError

Bases: gssapi.raw.exceptions.SupplementaryError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
SUPPLEMENTARY_CODE = 4
exception InvalidCredentialsError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 655360
exception InvalidTokenError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 589824
exception MalformedParameterError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
CALLING_CODE = 50331648
exception MechanismNameRequiredError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 1179648
exception MissingContextError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 524288
exception MissingCredentialsError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 458752
exception NameReadError

Bases: gssapi.raw.exceptions.ParameterReadError, gssapi.raw.exceptions.BadNameError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception NameTypeReadError

Bases: gssapi.raw.exceptions.ParameterReadError, gssapi.raw.exceptions.BadNameTypeError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception OperationUnavailableError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 1048576
exception ParameterReadError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
CALLING_CODE = 16777216
exception ParameterWriteError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
CALLING_CODE = 33554432
exception SupplementaryError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception TokenOutOfSequenceError

Bases: gssapi.raw.exceptions.SupplementaryError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception TokenReadError

Bases: gssapi.raw.exceptions.ParameterReadError, gssapi.raw.exceptions.InvalidTokenError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
exception TokenTooEarlyError

Bases: gssapi.raw.exceptions.TokenOutOfSequenceError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
SUPPLEMENTARY_CODE = 16
exception TokenTooLateError

Bases: gssapi.raw.exceptions.TokenOutOfSequenceError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
SUPPLEMENTARY_CODE = 8
exception UnauthorizedError

Bases: gssapi.raw.misc.GSSError

Create a new GSSError.

This method creates a new GSSError, retrieves the releated human-readable string messages, and uses the results to construct an exception message

Parameters:
  • maj_code (int) – the major code associated with this error
  • min_code (int) – the minor code associated with this error
  • token (bytes) – an error token associated with the error
ROUTINE_CODE = 983040