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
- Returns
a canonicalized version of the input name
- Return type
- 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
- Returns
whether or not the names are equal
- Return type
- 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. Ifname_type
is True, it also attempts to retrieve theNameType
of the name (otherwise the returned name type will beNone
).- Parameters
- Returns
the text part of the name and its type
- Return type
DisplayNameResult
- Raises
- duplicate_name(name)¶
Duplicate a GSSAPI name.
- Parameters
name (Name) – the name to duplicate
- Returns
a duplicate of the input name
- Return type
- Raises
- 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()
oraccept_sec_context()
.- Parameters
name (Name) – the name to export
- Returns
the exported name
- Return type
- 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
- Returns
the GSSAPI version of the name
- Return type
- Raises
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
- 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 toinquire_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
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
- 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
- Raises
- 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
- 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()
.
- 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 beenGSS_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
- 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
- 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
- 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
- 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.
- dotted_form¶
- 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
- Raises
ValueError – the sequence is less than two elements long
- exception GSSError(maj_code, min_code, *args, **kwargs)¶
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
- 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
- get_all_statuses(code, is_maj)¶
Retrieve all messages for a status code.
This method retrieves all human-readable messages available for the given status code.
- class GSSErrorRegistry(name, bases, attributes)¶
- 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.
- 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.
- class AddressType(value)¶
GSSAPI Channel Bindings Address Types
This
IntEnum
represents the various address types used with theChannelBindings
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 byNone
.- local = 1¶
- ip = 2¶
- arpanet = 3¶
- pup = 4¶
- chaos = 5¶
- xerox_ns = 6¶
- nbs = 7¶
- ecma = 8¶
- datakit = 9¶
- ccitt = 10¶
- ibm_sna = 11¶
- decnet = 12¶
- dli = 13¶
- lat = 14¶
- hyperchannel = 15¶
- appletalk = 16¶
- bisync = 17¶
- dss = 18¶
- osi_tp4 = 19¶
- x25 = 21¶
- null = 255¶
- class GenericFlagSet(flags=None)¶
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(flag)¶
Add an element.
- discard(flag)¶
Remove an element. Do not raise an exception if absent.
- class IntEnumFlagSet(enum, flags=None)¶
A set backed by a 32-bit integer with enum members
This class is a
GenericFlagSet
where the returned members are values in anIntEnum
.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(value)¶
GSSAPI Requirement Flags
This
IntEnum
represents flags used with theSecurityContext
-related methods (e.g.init_sec_context()
)The numbers behind the values correspond directly to their C counterparts.
- delegate_to_peer = 1¶
- mutual_authentication = 2¶
- replay_detection = 4¶
- out_of_sequence_detection = 8¶
- confidentiality = 16¶
- integrity = 32¶
- anonymity = 64¶
- protection_ready = 128¶
- transferable = 256¶
- ok_as_delegate = 32768¶
- channel_bound = 2048¶
- dce_style = 4096¶
- identify = 8192¶
- extended_error = 16384¶
- 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. See Common Values for Credentials Store Extensions for valid values
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. Unlikeacquire_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. See Common Values for Credentials Store Extensions for valid values
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()
oradd_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. See Common Values for Credentials Store Extensions for valid values
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
- 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
- Returns
the displayed name
- Return type
- 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 usingimport_name()
with theNameType.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.
- 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
- 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
- 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
- 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.
- import_cred(token)¶
Import GSSAPI credentials from a token.
This method imports a credentials object from a token previously exported by
export_cred()
.
DCE (IOV/AEAD) Extensions¶
- class IOV¶
A GSSAPI IOV
- AUTO_ALLOC_BUFFERS = {<IOVBufferType.header: 2>, <IOVBufferType.trailer: 7>, <IOVBufferType.padding: 9>, <IOVBufferType.mic_token: 12>}¶
- count()¶
- index()¶
- class IOVBufferType(value)¶
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.
- empty = 0¶
- data = 1¶
- header = 2¶
- mech_params = 3¶
- trailer = 7¶
- padding = 9¶
- stream = 10¶
- sign_only = 11¶
- mic_token = 12¶
- 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 theIOV
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 ofIOVBufferType.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
- 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 theIOV
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
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
- 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
- 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
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
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
- Returns
the QoP used to generate the MIC token
- Return type
- 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(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 262144¶
- exception BadMICError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 393216¶
- exception BadMechanismError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 65536¶
- exception BadNameError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 131072¶
- exception BadNameTypeError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 196608¶
- exception BadQoPError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 917504¶
- exception BadStatusError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 327680¶
- exception ContextReadError(maj_code, min_code, *args, **kwargs)¶
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
- exception ContextWriteError(maj_code, min_code, *args, **kwargs)¶
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
- exception CredentialsReadError(maj_code, min_code, *args, **kwargs)¶
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
- exception CredentialsWriteError(maj_code, min_code, *args, **kwargs)¶
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
- exception DuplicateCredentialsElementError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 1114112¶
- exception DuplicateTokenError(maj_code, min_code, *args, **kwargs)¶
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
- SUPPLEMENTARY_CODE = 2¶
- exception ExpiredContextError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 786432¶
- exception ExpiredCredentialsError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 720896¶
- exception ExpiredTokenError(maj_code, min_code, *args, **kwargs)¶
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
- SUPPLEMENTARY_CODE = 4¶
- exception InvalidCredentialsError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 655360¶
- exception InvalidTokenError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 589824¶
- exception MalformedParameterError(maj_code, min_code, *args, **kwargs)¶
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
- CALLING_CODE = 50331648¶
- exception MechanismNameRequiredError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 1179648¶
- exception MissingContextError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 524288¶
- exception MissingCredentialsError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 458752¶
- exception NameReadError(maj_code, min_code, *args, **kwargs)¶
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
- exception NameTypeReadError(maj_code, min_code, *args, **kwargs)¶
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
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
- exception ParameterReadError(maj_code, min_code, *args, **kwargs)¶
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
- CALLING_CODE = 16777216¶
- exception ParameterWriteError(maj_code, min_code, *args, **kwargs)¶
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
- CALLING_CODE = 33554432¶
- exception SupplementaryError(maj_code, min_code, *args, **kwargs)¶
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
- exception TokenOutOfSequenceError(maj_code, min_code, *args, **kwargs)¶
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
- exception TokenReadError(maj_code, min_code, *args, **kwargs)¶
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
- exception TokenTooEarlyError(maj_code, min_code, *args, **kwargs)¶
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
- SUPPLEMENTARY_CODE = 16¶
- exception TokenTooLateError(maj_code, min_code, *args, **kwargs)¶
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
- SUPPLEMENTARY_CODE = 8¶
- exception UnauthorizedError(maj_code, min_code, *args, **kwargs)¶
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
- ROUTINE_CODE = 983040¶