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.
A GSSAPI Name
This class represents a GSSAPI name which may be 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.
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
The NameType
of this name
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.
Canonicalize a name with respect to a mechanism.
This method returns a new Name
that is canonicalized according to the given mechanism.
the canonicalized name
Whether or not this name is a mechanism name (requires the RFC 6680 extension)
The mechanism associated with this name (requires the RFC 6680 extension)
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 frozenset
.
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.
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 Creds
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 cred_imp_exp extension).
Otherwise, the credentials are acquired as per the acquire()
method.
Get the name associated with these credentials
Get the remaining lifetime of these credentials, in seconds
Get the mechanisms for these credentials
Get the usage (initiate, accept, or both) of these credentials
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.
name (Name) – the name associated with the credentials, or None for the default name
lifetime (int) – the desired lifetime of the credentials in seconds, 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 cred_store extension)
the acquired credentials and information about them
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 cred_store extension
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.
the results of the credential storing operation
Impersonate a name using the current credentials
This method acquires credentials by impersonating another name using the current credentials.
requires the s4u extension
name (Name) – the name to impersonate
lifetime (int) – the desired lifetime of the new credentials in seconds, 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’.
the new credentials impersonating the given name
Inspect these credentials for information
This method inspects these credentials for information about them.
the information about the credentials, with None used when the corresponding argument was False
Inspect these credentials for per-mechanism information
This method inspects these credentials for per-mechanism information about them.
mech (OID) – the mechanism for which to retrieve the information
name (bool) – get the name associated with the credentials
init_lifetime (bool) – get the remaining initiate lifetime for the credentials in seconds
accept_lifetime (bool) – get the remaining accept lifetime for the credentials in seconds
usage (bool) – get the usage for the credentials
the information about the credentials, with None used when the corresponding argument was False
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 s4u extension).
If the store argument is used, the credentials will be acquired from the given credential store (requires the cred_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.
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 in seconds, or None for indefinite
accept_lifetime (int) – the desired accept lifetime of the credentials in seconds, or None for indefinite
impersonator (Credentials) – the credentials to use to impersonate the given name, or None to not acquire normally (requires the s4u 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 cred_store extension)
the credentials set containing the current credentials and the newly acquired ones.
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 cred_imp_exp extension
the exported credentials in token form
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.
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.
message (bytes) – the input message
the message signature
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.
the QoP used.
BadMICError – the signature was not valid
Wrap a message, optionally with encryption
This wraps a message, signing it and optionally encrypting it.
the wrapped message and details about it (e.g. whether encryption was used succesfully)
Unwrap a wrapped message.
This method unwraps/unencrypts a wrapped message, verifying the signature along the way.
message (bytes) – the message to unwrap/decrypt
the unwrapped message and details about it (e.g. wheter encryption was used)
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.
message (bytes) – the message to encrypt
the encrypted message
EncryptionNotUsed – the encryption could not be used
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.
message (bytes) – the encrypted message
the decrypted message
EncryptionNotUsed – encryption was expected, but not used
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.
the maximum input message size
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.
token (bytes) – the token to process
Export a security context.
This method exports a security context, allowing it to be passed between processes.
the exported security context
The amount of time for which this context remains valid
The credentials delegated from the initiator to the acceptor
Warning
This value will not be preserved across picklings. These should be separately exported and transferred.
The Name
of the initiator of this context
The Name
of the target of this context
The mechanism (MechType
) in use by this context
The flags set on this context
Whether this context was locally intiated
Whether negotiation for this context has been completed
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) if not output_token: break 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.
token (bytes) – the input token from the other participant’s step
the output token to send to the other participant
ExpiredTokenError – (initiate only)
BadNameTypeError – (initiate only)
BadNameError – (initiate only)
The following enumerations from the low-level API are also used with the high-level API. For convenience, they are imported in the high-level API gssapi
module:
Bases: object
Bases: object
Bases: IntEnum
The ok_as_delegate
flag corresponds to the C level flag GSS_C_DELEG_POLICY_FLAG
. This flag is similar to delegate_to_peer
except it only delegates if the KDC delegation policies for the service principal allow it to use delegation. This is typically used on Microsoft domain environments to control whether constrained or unconstrained delegation is allowed for a service principal. By setting this flag, the delegation process follows the same behaviour as delegation on SSPI/Windows.
Here are the four cases when either of these flags are set or not.
No delegation occurs.
Always try to delegate regardless of the KDC delegation policies. delegate_to_peer
is set in the return flags if successful.
Try to delegate but only if the KDC trusts the service principal for delegation. delegate_to_peer
and ok_as_delegate
are set in the return flags if successful.
Acts like delegate_to_peer
being set but will also set ok_as_delegate
in the return flags if the service principal was trusted for delegation by the KDC.
Bases: IntEnum
Similarly, 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:
Bases: GenericFlagSet
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:
Bases: Exception
Bases: Exception
A General High-Level API Error
Bases: GeneralError
An Error indicating an unknown usage type
Bases: GeneralError
An Error indicating that encryption was requested, but not used
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: SupplementaryError
Bases: GSSError
Bases: GSSError
Bases: SupplementaryError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: ParameterReadError
, BadNameError
Bases: ParameterReadError
, BadNameTypeError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: GSSError
Bases: SupplementaryError
Bases: ParameterReadError
, InvalidTokenError
Bases: TokenOutOfSequenceError
Bases: TokenOutOfSequenceError
Bases: GSSError
Sets the current encoding used for strings
This value is used to encode and decode string values like names.
enc – the encoding to use
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4