High-Level API¶

The high-level API contains three main classes for interacting with GSSAPI, representing the primary abstractions that GSSAPI provides: Name, Credentials, and SecurityContext.

Note

Classes in the high-level API inherit from the corresponding classes in the low-level API, and thus may be passed in to low-level API functions.

Warning

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

Main Classes¶

Names¶

class Name(base=None, name_type=None, token=None, composite=False)[source]¶

A GSSAPI Name

This class represents a GSSAPI name which may be used with used with and/or returned by other GSSAPI methods.

It inherits from the low-level GSSAPI Name class, and thus may used with both low-level and high-level API methods.

This class may be pickled and unpickled, as well as copied.

The str() and bytes() methods may be used to retrieve the text of the name.

Note

Name strings will be automatically converted to and from unicode strings as appropriate. If a method is listed as returning a str object, it will return a unicode string.

The encoding used will be python-gssapi’s current encoding, which defaults to UTF-8.

The constructor can be used to “import” a name from a human readable representation, or from a token, and can also be used to convert a low-level gssapi.raw.names.Name object into a high-level object.

If a Name object from the low-level API is passed as the base argument, it will be converted into a high-level object.

If the token argument is used, the name will be imported using the token. If the token was exported as a composite token, pass composite=True.

Otherwise, a new name will be created, using the base argument as the human-readable string and the name_type argument to denote the name type.

Raises:	`BadNameTypeError` `BadNameError` `BadMechanismError`

display_as(name_type)[source]¶

Display this name as the given name type.

This method attempts to display the current Name using the syntax of the given NameType, if possible.

Warning

In MIT krb5 versions below 1.13.3, this method can segfault if the name was not originally created with a name_type that was not None (even in cases when a name_type is later “added”, such as via canonicalize()). Do not use this method unless you are sure the above conditions can never happen in your code.

Warning

In addition to the above warning, current versions of MIT krb5 do not actually fully implement this method, and it may return incorrect results in the case of canonicalized names.

requires the RFC 6680 extension

Parameters:	name_type (OID) – the `NameType` to use to display the given name
Returns:	the displayed name
Return type:	str
Raises:	`OperationUnavailableError`

name_type¶: The NameType of this name

export(composite=False)[source]¶

Export this name as a token.

This method exports the name into a byte string which can then be imported by using the token argument of the constructor.

Parameters:	composite (bool) – whether or not use to a composite token – requires the RFC 6680 extension
Returns:	the exported name in token form
Return type:	bytes
Raises:	`MechanismNameRequiredError` `BadNameTypeError` `BadNameError`

canonicalize(mech)[source]¶

Canonicalize a name with respect to a mechanism.

This method returns a new Name that is canonicalized according to the given mechanism.

Parameters:	mech (OID) – the `MechType` to use
Returns:	the canonicalized name
Return type:	Name
Raises:	`BadMechanismError` `BadNameTypeError` `BadNameError`

is_mech_name¶: Whether or not this name is a mechanism name (requires the RFC 6680 extension)

mech¶: The mechanism associated with this name (requires the RFC 6680 extension)

attributes¶

The attributes of this name (requires the RFC 6680 extension)

The attributes are presenting in the form of a MutableMapping (a dict-like object).

Retrieved values will always be in the form of frozensets.

When assigning values, if iterables are used, they be considered to be the set of values for the given attribute. If a non-iterable is used, it will be considered a single value, and automatically wrapped in an iterable.

Note

String types (includes bytes) are not considered to be iterables in this case.

Credentials¶

class Credentials[source]¶

GSSAPI Credentials

This class represents a set of GSSAPI credentials which may be used with and/or returned by other GSSAPI methods.

It inherits from the low-level GSSAPI Creds class, and thus may used with both low-level and high-level API methods.

If your implementation of GSSAPI supports the credentials import-export extension, you may pickle and unpickle this object.

The constructor either acquires or imports a set of GSSAPI credentials.

If the base argument is used, an existing Cred object from the low-level API is converted into a high-level object.

If the token argument is used, the credentials are imported using the token, if the credentials import-export extension is supported (requires the Credentials Import/Export Extension).

Otherwise, the credentials are acquired as per the acquire() method.

Raises:	`BadMechanismError` `BadNameTypeError` `BadNameError` `ExpiredCredentialsError` `MissingCredentialsError`

name¶: Get the name associated with these credentials

lifetime¶: Get the remaining lifetime of these credentials

mechs¶: Get the mechanisms for these credentials

usage¶: Get the usage (initiate, accept, or both) of these credentials

classmethod acquire(name=None, lifetime=None, mechs=None, usage=’both’, store=None)[source]¶

Acquire GSSAPI credentials

This method acquires credentials. If the store argument is used, the credentials will be acquired from the given credential store (if supported). Otherwise, the credentials are acquired from the default store.

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

Using a non-default store requires support for the credentials store extension.

Parameters:	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 `MechType` OIDs to be used with the credentials, or None for the default set usage (str) – the usage for the credentials – either ‘both’, ‘initiate’, or ‘accept’ store (dict) – the credential store information pointing to the credential store from which to acquire the credentials, or None for the default store (requires the Credential Store Extension)
Returns:	the acquired credentials and information about them
Return type:	AcquireCredResult
Raises:	`BadMechanismError` `BadNameTypeError` `BadNameError` `ExpiredCredentialsError` `MissingCredentialsError`

store(store=None, usage=’both’, mech=None, overwrite=False, set_default=False)[source]¶

Store these credentials into the given store

This method stores the current credentials into the specified credentials store. If the default store is used, support for RFC 5588 is required. Otherwise, support for the credentials store extension is required.

requires the RFC 5588 extension or requires the Credential Store Extension

Parameters:	store (dict) – the store into which to store the credentials, or None for the default store. usage (str) – the usage to store the credentials with – either ‘both’, ‘initiate’, or ‘accept’ mech (OID) – the `MechType` 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` `ExpiredCredentialsError` `MissingCredentialsError` `OperationUnavailableError` `DuplicateCredentialsElementError`

impersonate(name=None, lifetime=None, mechs=None, usage=’initiate’)[source]¶

Impersonate a name using the current credentials

This method acquires credentials by impersonating another name using the current credentials.

requires the Service4User Extension

Parameters:	name (Name) – the name to impersonate lifetime (int) – the desired lifetime of the new credentials, or None for indefinite mechs (list) – the desired `MechType` OIDs for the new credentials usage (str) – the desired usage for the new credentials – either ‘both’, ‘initiate’, or ‘accept’. Note that some mechanisms may only support ‘initiate’.
Returns:	the new credentials impersonating the given name
Return type:	Credentials

inquire(name=True, lifetime=True, usage=True, mechs=True)[source]¶

Inspect these credentials for information

This method inspects these credentials for information about them.

Parameters:	name (bool) – get the name associated with the credentials lifetime (bool) – get the remaining lifetime for the credentials usage (bool) – get the usage for the credentials mechs (bool) – get the mechanisms associated with the credentials
Returns:	the information about the credentials, with None used when the corresponding argument was False
Return type:	InquireCredResult
Raises:	`MissingCredentialsError` `InvalidCredentialsError` `ExpiredCredentialsError`

inquire_by_mech(mech, name=True, init_lifetime=True, accept_lifetime=True, usage=True)[source]¶

Inspect these credentials for per-mechanism information

This method inspects these credentials for per-mechanism information about them.

Parameters:

mech (OID) – the mechanism for which to retrive the information
name (bool) – get the name associated with the credentials
init_lifetime (bool) – get the remaining initiate lifetime for the credentials
accept_lifetime (bool) – get the remaining accept lifetime for the credentials
usage (bool) – get the usage for the credentials

Returns:

the information about the credentials,: with None used when the corresponding argument was False

Return type:

InquireCredByMechResult

add(name, mech, usage=’both’, init_lifetime=None, accept_lifetime=None, impersonator=None, store=None)[source]¶

Acquire more credentials to add to the current set

This method works like acquire(), 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(), you cannot pass None desired name or mechanism.

If the impersonator argument is used, the credentials will impersonate the given name using the impersonator credentials (requires the Service4User Extension).

If the store argument is used, the credentials will be acquired from the given credential store (requires the Credential Store Extension). Otherwise, the credentials are acquired from the default store.

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

Note that the store argument is not compatible with the impersonator argument.

Parameters:	name (Name) – the name associated with the credentials mech (OID) – the desired `MechType` to be used with the credentials usage (str) – the usage for the 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 impersonator (Credentials) – the credentials to use to impersonate the given name, or None to not acquire normally (requires the Service4User Extension) store (dict) – the credential store information pointing to the credential store from which to acquire the credentials, or None for the default store (requires the Credential Store Extension)
Returns:	the credentials set containing the current credentials and the newly acquired ones.
Return type:	Credentials
Raises:	`BadMechanismError` `BadNameTypeError` `BadNameError` `DuplicateCredentialsElementError` `ExpiredCredentialsError` `MissingCredentialsError`

export()[source]¶

Export these credentials into a token

This method exports the current credentials to a token that can then be imported by passing the token argument to the constructor.

This is often used to pass credentials between processes.

requires the Credentials Import/Export Extension

Returns:	the exported credentials in token form
Return type:	bytes

Security Contexts¶

class SecurityContext(base=None, token=None, name=None, creds=None, lifetime=None, flags=None, mech=None, channel_bindings=None, usage=None)[source]¶

A GSSAPI Security Context

This class represents a GSSAPI security context that may be used with and/or returned by other GSSAPI methods.

It inherits from the low-level GSSAPI SecurityContext class, and thus may used with both low-level and high-level API methods.

This class may be pickled and unpickled (the attached delegated credentials object will not be preserved, however).

The constructor creates a new security context, but does not begin the initiate or accept process.

If the base argument is used, an existing SecurityContext object from the low-level API is converted into a high-level object.

If the token argument is passed, the security context is imported using the token.

Otherwise, a new security context is created.

If the usage argument is not passed, the constructor will attempt to detect what the appropriate usage is based on either the existing security context (if base or token are used) or the argument set.

For a security context of the initiate usage, the name argument must be used, and the creds, mech, flags, lifetime, and channel_bindings arguments may be used as well.

For a security context of the accept usage, the creds and channel_bindings arguments may optionally be used.

get_signature(message)[source]¶

Calculate the signature for a message.

This method calculates the signature (called a MIC) for the given message, which may be then used with verify_signature() to confirm the validity of the signature. This is useful if you wish to transmit the message signature and message in your own format.

Parameters:	message (bytes) – the input message
Returns:	the message signature
Return type:	bytes
Raises:	`ExpiredContextError` `MissingContextError` `BadQoPError`

verify_signature(message, mic)[source]¶

Verify the signature for a message.

This method verifies that a signature (generated by get_signature() is valid for the given message.

If the signature is valid, the method will return. Otherwise, it will raise an error.

Parameters:	message (bytes) – the message mic (bytes) – the signature to verify
Raises:	`BadMICError` – the signature was not valid `InvalidTokenError` `DuplicateTokenError` `ExpiredTokenError` `TokenTooLateError` `TokenTooEarlyError` `ExpiredContextError` `MissingContextError`

wrap(message, encrypt)[source]¶

Wrap a message, optionally with encryption

This wraps a message, signing it and optionally encrypting it.

Parameters:	message (bytes) – the message to wrap encrypt (bool) – whether or not to encrypt the message
Returns:	the wrapped message and details about it (e.g. whether encryption was used succesfully)
Return type:	WrapResult
Raises:	`ExpiredContextError` `MissingContextError` `BadQoPError`

unwrap(message)[source]¶

Unwrap a wrapped message.

This method unwraps/unencrypts a wrapped message, verifying the signature along the way.

Parameters:	message (bytes) – the message to unwrap/decrypt
Returns:	the unwrapped message and details about it (e.g. wheter encryption was used)
Return type:	UnwrapResult
Raises:	`InvalidTokenError` `BadMICError` `DuplicateTokenError` `ExpiredTokenError` `TokenTooLateError` `TokenTooEarlyError` `ExpiredContextError` `MissingContextError`

encrypt(message)[source]¶

Encrypt a message.

This method wraps and encrypts a message, similarly to wrap(). The difference is that encryption is always used, and the method will raise an exception if this is not possible. Additionally, this method simply returns the encrypted message directly.

Parameters:	message (bytes) – the message to encrypt
Returns:	the encrypted message
Return type:	bytes
Raises:	`EncryptionNotUsed` – the encryption could not be used `ExpiredContextError` `MissingContextError` `BadQoPError`

decrypt(message)[source]¶

Decrypt a message.

This method decrypts and unwraps a message, verifying the signature along the way, similarly to unwrap(). The difference is that this method will raise an exception if encryption was established by the context and not used, and simply returns the decrypted message directly.

Parameters:	message (bytes) – the encrypted message
Returns:	the decrypted message
Return type:	bytes
Raises:	`EncryptionNotUsed` – encryption was expected, but not used `InvalidTokenError` `BadMICError` `DuplicateTokenError` `ExpiredTokenError` `TokenTooLateError` `TokenTooEarlyError` `ExpiredContextError` `MissingContextError`

get_wrap_size_limit(desired_output_size, encrypted=True)[source]¶

Calculate the maximum message size for a given wrapped message size.

This method calculates the maximum input message size for a given maximum wrapped/encrypted message size.

Parameters:	desired_output_size (int) – the maximum output message size encrypted (bool) – whether or not encryption should be taken into account
Returns:	the maximum input message size
Return type:	int
Raises:	`MissingContextError` `ExpiredContextError` `BadQoPError`

process_token(token)[source]¶

Process an output token asynchronously.

This method processes an output token even when the security context was not expecting it.

Warning

This method is deprecated.

Parameters:	token (bytes) – the token to process
Raises:	`InvalidTokenError` `MissingContextError`

export()[source]¶

Export a security context.

This method exports a security context, allowing it to be passed between processes.

Returns:	the exported security context
Return type:	bytes
Raises:	`ExpiredContextError` `MissingContextError` `OperationUnavailableError`

lifetime¶: The amount of time for which this context remains valid

delegated_creds¶: The credentials delegated from the initiator to the acceptor

Warning

This value will not be preserved across picklings. These should be separately exported and transfered.

initiator_name¶: The Name of the initiator of this context

target_name¶: The Name of the target of this context

mech¶: The mechanism (MechType) in use by this context

actual_flags¶: The flags set on this context

locally_initiated¶: Whether this context was locally intiated

complete¶: Whether negotiation for this context has been completed

step(token=None)[source]¶

Perform a negotation step.

This method performs a negotiation step based on the usage type of this context. If __DEFER_STEP_ERRORS__ is set to True on the class, this method will return a token, even when exceptions would be thrown. The generated exception will be thrown on the next method call or property lookup on the context. This is the default behavior.

This method should be used in a while loop, as such:

input_token = None
try:
    while not ctx.complete:
        output_token = ctx.step(input_token)
        input_token = send_and_receive(output_token)
except GSSError as e:
     handle_the_issue()

Tip

Disabling __DEFER_STEP_ERRORS__ is rarely necessary. When this method is used in a loop (as above), __DEFER_STEP_ERRORS__ will ensure that you always send an error token when it’s available, keeping the other end of the security context updated with the status of the negotiation.

Parameters:	token (bytes) – the input token from the other participant’s step
Returns:	the output token to send to the other participant
Return type:	bytes
Raises:	`InvalidTokenError` `InvalidCredentialsError` `MissingCredentialsError` `ExpiredCredentialsError` `BadChannelBindingsError` `BadMICError` `ExpiredTokenError` – (initiate only) `DuplicateTokenError` `MissingContextError` `BadNameTypeError` – (initiate only) `BadNameError` – (initiate only) `BadMechanismError`

Enums and Helper Classes¶

The following enumerations from the low-level API are also used with the high-level API. For convienience, the are imported in the high-level API gssapi module:

class NameType¶

Bases: object

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 MechType¶

Bases: object

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 RequirementFlag¶

Bases: enum.IntEnum

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.

class AddressType¶

Bases: enum.IntEnum

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.

Similiarly, there are a couple classes from the low-level API that are imported into the high-level API module. These classes are less likely to be used directly by a user, but are returned by several methods:

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

class IntEnumFlagSet¶

Bases: gssapi.raw.types.GenericFlagSet

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.

Exceptions¶

The high-level API can raise all of the exceptions that the low-level API can raise in addition to several other high-level-specific exceptions:

exception GeneralError(minor_message, **kwargs)[source]¶

Bases: Exception

A General High-Level API Error

MAJOR_MESSAGE = ‘General error’¶

FMT_STR = ‘{maj}: {min}.’¶

exception UnknownUsageError(minor_message, **kwargs)[source]¶

Bases: gssapi.exceptions.GeneralError

An Error indicating an unknown usage type

MAJOR_MESSAGE = ‘Unable to determine {obj} usage’¶

exception EncryptionNotUsed(minor_message, unwrapped_message=None, **kwargs)[source]¶

Bases: gssapi.exceptions.GeneralError

An Error indicating that encryption was requested, but not used

MAJOR_MESSAGE = ‘Confidentiality was requested, but not used’¶

exception BadChannelBindingsError¶

High-Level API¶

Main Classes¶

Names¶

Credentials¶

Security Contexts¶

Enums and Helper Classes¶

Exceptions¶

Utilities¶