In general, all the useful functions, classes and constants from the modules within gssapi such as InitContext, Name, etc, are available as members of the gssapi package, so you can do:
>>> from gssapi import Credential, Name, AcceptContext
The flags here have two uses: they can be passed in a list as the req_flags parameter to InitContext to request that the corresponding feature is enabled, and they are set as the flags attribute of an established security context to indicate that the corresponding feature has been negotiated and enabled.
Flag indicating that credential delegation from the initiator to the acceptor should be used, or has been used if this flag is set on an established context.
Flag indicating that mutual authentication of the acceptor to the initiator (as well as vice versa) should be requested when initiating a connection, or has been used if this flag is set on an established context.
Flag indicating that message replay detection should be requested when initiating a connection, or has been used if this flag is set on an established context.
Flag indicating that out-of-sequence message detection should be requested when initiating a connection, or has been used if this flag is set on an established context.
Flag indicating that message confidentiality services (encryption) should be requested when initiating a connection, or has been used if this flag is set on an established context.
Flag indicating that message integrity services (signing) should be requested when initiating a connection, or has been used if this flag is set on an established context.
Flag requesting that the initiator’s identity should be concealed from the acceptor, or indicating that the initiator’s identity was not revealed to the acceptor on an established context.
Flag indicating that message confidentiality or integrity services are available on a context, which may be set even before the context is fully established, if the services can be used at that point.
Flag indicating that a context is exportable and importable between different processes.
Flag used to request that credential delegation be used, but only to acceptors that are permitted to be delegated to by some mechanism-specific policy (e.g. the OK-AS-DELEGATE ticket flag in Kerberos, which can be set on services to indicate they are trusted for delegation). This flag is only used to request this behaviour from InitContext.
If C_DELEG_FLAG is set, it overrides this flag and causes delegation to always be used, regardless of policy.
This flag is not available in versions of MIT Kerberos 5 before Release 1.7, so if this Python package is installed using an older version, this constant will not be defined as a member of the gssapi module.
Constant which can be passed as the usage parameter to Credential to acquire a credential suitable for both initiating and accepting security contexts.
Constant which can be passed as the usage parameter to Credential to acquire a credential suitable for initiating security contexts only.
Constant which can be passed as the usage parameter to Credential to acquire a credential suitable for accepting security contexts only.
Represents an indefinite lifetime for a security context or credential; can be passed as the lifetime parameter to Credential to request a credential with the maximum possible lifetime.
Represents a local username. The value should be a simple username string like “dave”.
On UNIX-like systems, represents a numeric UID. The value should be an int.
As above, but the value should be a decimal string representation of the numeric UID like “501”.
Represents a service on a certain host. The value should be a string of the form “service” (normally indicating the service is on this host) or “service@hostname”. This is normally used to create the peer_name parameter when initiating a security context, and is the most common method of targeting services.
Represents an anonymous name. The value is ignored.
These constants represent different address families that can be used as the initiator_addrtype or acceptor_addrtype parameters to ChannelBindings, to denote the type of the initiator and acceptor addresses in the channel bindings. These will generally not be useful except in some rare circumstances, as most of these address families are no longer widely used, and using IP addresses in GSSAPI channel bindings is deprecated and does not work across NAT. They are only included for completeness’ sake.
Unspecified address type.
Host-local address type.
Internet address type (IPv4).
ARPAnet IMP address type.
pup protocols (eg BSP) address type.
MIT CHAOS protocol address type.
XEROX NS address type.
nbs address type.
ECMA address type.
datakit protocols address type.
CCITT protocols.
IBM SNA address type.
DECnet address type.
Direct data link interface address type.
LAT address type.
NSC Hyperchannel address type.
AppleTalk address type.
BISYNC 2780/3780 address type.
Distributed system services address type.
OSI TP4 address type.
X.25.
IPv6 address type. May not be defined in some implementations, e.g. MIT Kerberos.
No address specified.
These status codes may be returned as the maj_status attribute of a GSSCException raised by various GSSAPI operations. For a full reference to the meaning of the various status codes, check RFC 2744 Section 3.9.1 - the constants here are equivalent to the status codes listed in the RFC without the GSS_ prefix.
This status code does not represent an error and shouldn’t be used as the maj_status attribute of a GSSCException, as it represents successful completion.
Bases: object
Acquire a reference to a credential. Use this to select a credential with a specific name to use in an AcceptContext, to select a specific identity from the user’s credential set to use as an initiator credential, or to obtain a credential using a password.
Note that obtaining a credential using a password is a nonstandard extension to the GSSAPI and may not be supported by the underlying implementation (see Compatibility); in that case NotImplementedError will be raised if a password parameter is passed to the Credential constructor. Also, if the password parameter is passed, normally the desired_name parameter must also be provided.
Parameters: |
|
---|---|
Returns: | a Credential object referring to the requested credential. |
Raises: | GSSException if there is an error acquiring a reference to the credential. NotImplementedError if a password is provided but the underlying GSSAPI implementation does not support acquiring credentials with a password. |
Serializes this credential into a byte string, which can be passed to imprt() in another process in order to deserialize the byte string back into a credential. Exporting a credential does not destroy it.
Returns: | The serialized token representation of this credential. |
---|---|
Return type: | bytes |
Raises: | GSSException if there is a problem with exporting the credential. NotImplementedError if the underlying GSSAPI implementation does not support the gss_export_cred C function. |
Deserializes a byte string token into a Credential object. The token must have previously been exported by the same GSSAPI implementation as is being used to import it.
Parameters: | token (bytes) – A token previously obtained from the export() of another Credential object. |
---|---|
Returns: | A Credential object constructed from the token. |
Raises: | GSSException if there is a problem with importing the credential. NotImplementedError if the underlying GSSAPI implementation does not support the gss_import_cred C function. |
The lifetime in seconds for which this credential is valid.
The usage of the credential, either gssapi.C_INITIATE, gssapi.C_ACCEPT or gssapi.C_BOTH.
Bases: object
Represents channel bindings that identify the initiator and acceptor of a security context. This class is a generic one that can be subclassed to provide channel bindings for specific address types.
Parameters: |
|
---|
The parameters initiator_addrtype, application_data, etc, can also be set as attributes on instances of this class.
Bases: gssapi.chanbind.ChannelBindings
Represents channel bindings using IPv4 initiator and/or acceptor addresses. Note that using IP addresses in GSSAPI channel bindings is deprecated and does not work across NAT. However this class may be useful if implementing an application protocol that requires IP channel bindings, like FTP with GSSAPI authentication.
Parameters: |
---|
Bases: gssapi.chanbind.ChannelBindings
Represents channel bindings using IPv6 initiator and/or acceptor addresses. Note that using IP addresses in GSSAPI channel bindings is deprecated and does not work across NAT. However this class may be useful if implementing an application protocol that requires IP channel bindings, like FTP with GSSAPI authentication. This class will only be available if the underlying implementation defines the address type GSS_C_AF_INET6.
Parameters: |
---|
Bases: gssapi.ctx.Context
This class is used to accept a connection from an initiator and establish and manage a security context on the acceptor side. The initiator is normally authenticated as part of the context establishment process, though some mechanisms support anonymous peers.
Parameters: |
|
---|
If the initiator delegated a credential to this acceptor, this will be Credential object containing the delegated credential. Otherwise it will be set to None.
If this context has authenticated an initiator, this will be a MechName object representing the initiator. Otherwise it will be set to None.
Performs a step to establish the context as an acceptor.
This method should be called in a loop and fed input tokens from the initiator, and its output tokens should be sent to the initiator, until this context’s established attribute is True.
Parameters: | input_token (bytes) – The input token from the initiator (required). |
---|---|
Returns: | either a byte string with the next token to send to the initiator, or None if there is no further token to send to the initiator. |
Raises: | GSSException if there is an error establishing the context. |
Bases: object
Represents a GSSAPI security context. This class manages establishing the context with a peer, and optionally can provide integrity (signing) and confidentiality (encryption) protection for messages exchanged with the peer.
This class is not particularly useful in itself, but holds common functionality for all types of context. To use a context as the initiator or acceptor, create an InitContext or AcceptContext, respectively.
If this context has been established (via the exchange of tokens with a peer), this will be True. Otherwise it will be False.
If this context has been established, this will be a OID identifying the mechanism used to establish the security context. Otherwise it will be None.
This is an integer which is the bitwise-OR of all the flags representing features that have been negotiated on an established connection. It is recommended to check the properties integrity_negotiated, confidentiality_negotiated, etc, instead of doing bitwise comparisons on this attribute.
After step() has been called, this property will be set to True if confidentiality (encryption) has been negotiated in this context, False otherwise. If this property is True, you can use wrap() with the conf_req param set to True to encrypt messages sent to the peer application.
Delete a security context. This method will delete the local data structures associated with the specified security context, and may return an output token, which when passed to process_context_token() on the peer may instruct it to also delete its context.
RFC 2744 recommends that GSSAPI mechanisms do not emit any output token when they’re deleted, so this behaviour could be considered deprecated.
After this method is called, this security context will become invalid and should not be used in any way.
Returns: | An output token if one was emitted by the GSSAPI mechanism, otherwise an empty bytestring. |
---|---|
Return type: | bytes |
This method deactivates the security context for the calling process and returns an interprocess token which, when passed to imprt() in another process, will re-activate the context in the second process. Only a single instantiation of a given context may be active at any one time; attempting to access this security context after calling export() will fail. This method can only be used on a valid context where is_transferable is True.
Returns: | a token which represents this security context |
---|---|
Return type: | bytes |
Calculates a cryptographic message integrity code (MIC) over an application message, and returns that MIC in a token. This is in contrast to wrap() which calculates a MIC over a message, optionally encrypts it and returns the original message and the MIC packed into a single token. The peer application can then verify the MIC to ensure the associated message has not been changed in transit.
Parameters: |
|
---|---|
Returns: | A MIC for the message calculated using this security context’s cryptographic keys |
Return type: | bytes |
Calculates the maximum size of message that can be fed to wrap() so that the size of the resulting wrapped token (message plus wrapping overhead) is no more than a given maximum output size.
Parameters: | |
---|---|
Returns: | The maximum input size (in bytes) of message that can be passed to wrap() |
Return type: | int |
This is the corresponding method to export(), used to import a saved context token from another process into this one and construct a Context object from it.
Parameters: | import_token (bytes) – a token obtained from the export() of another context |
---|---|
Returns: | a Context object created from the imported token |
Return type: | Context |
After step() has been called, this property will be set to True if the initiator did not reveal its name to the acceptor, False if the initiator’s name is revealed and authenticated to the acceptor. If True, the peer_name property of the AcceptContext will be an anonymous internal name.
After step() has been called, this property will be set to True if integrity protection (signing) has been negotiated in this context, False otherwise. If this property is True, you can use get_mic() to sign messages with a message integrity code (MIC), which the peer application can verify.
True if the context can be transferred between processes using export() and imprt(), False otherwise.
The lifetime of the context in seconds (only valid after step() has been called). If the context does not have a time limit on its validity, this will be gssapi.C_INDEFINITE
After step() has been called, this property will be set to True if mutual authentication was negotiated, False otherwise.
Provides a way to pass an asynchronous token to the security context, outside of the normal context-establishment token passing flow. This method is not normally used, but some example uses are:
Parameters: | context_token (bytes) – The context token to pass to the security context |
---|---|
Raises: | DefectiveToken if consistency checks on the token failed. NoContext if this context is invalid. GSSException for any other GSSAPI errors. |
After step() has been called, this property will be set to True if the security context can use replay detection for messages protected by get_mic() and wrap(). False if replay detection cannot be used.
After step() has been called, this property will be set to True if the security context can use out-of-sequence message detection for messages protected by get_mic() and wrap(). False if OOS detection cannot be used.
Takes a token that has been generated by the peer application with wrap(), verifies and optionally decrypts it, using this security context’s cryptographic keys.
If the supplementary parameter is False (default), returns the unwrapped message only. If supplementary is True, returns a tuple (unwrapped_message, supplementary_info) where supplementary_info is a tuple containing zero or more of the constants S_DUPLICATE_TOKEN, S_OLD_TOKEN, S_UNSEQ_TOKEN and S_GAP_TOKEN. The supplementary info tells the caller whether a replayed or out-of-sequence message was detected.
Parameters: |
|
---|---|
Returns: | the verified and decrypted message if supplementary is False, or a tuple (unwrapped_message, supplementary_info) if supplementary is True. |
Raises: | GSSException if integrity_negotiated is false, or if the verification or decryption fails, if the message was modified, or if confidentiality was required (conf_req was True) but the message did not have confidentiality protection applied (was not encrypted), or if the qop_req parameter was set and it did not match the QOP applied to the message. |
Takes a message integrity code (MIC) that has been generated by the peer application for a given message, and verifies it against a message, using this security context’s cryptographic keys.
If the supplementary parameter is False (default), returns the quality of protection only (the qop_state value). If supplementary is True, returns a tuple (qop_state, supplementary_info) where supplementary_info is a tuple containing zero or more of the constants S_DUPLICATE_TOKEN, S_OLD_TOKEN, S_UNSEQ_TOKEN and S_GAP_TOKEN. The supplementary info tells the caller whether a replayed or out-of-sequence message was detected.
Parameters: |
|
---|---|
Returns: | qop_state if supplementary is False, or (qop_state, supplementary_info) if supplementary is True. |
Raises: | GSSException if integrity_negotiated is false, or GSSCException if the verification fails indicating the message was modified. |
Wraps a message with a message integrity code, and if conf_req is True, encrypts the message. The message can be decrypted and the MIC verified by the peer by passing the token returned from this method to unwrap() on the peer’s side.
Parameters: |
|
---|---|
Returns: | the wrapped message in a token suitable for passing to unwrap() |
Return type: | bytes |
Raises: | GSSException if integrity protection is not available (integrity_negotiated is False), or if the conf_req parameter is True and confidentiality protection is not available (confidentiality_negotiated is False) |
Bases: gssapi.ctx.Context
An instance of this class can be used to initiate a secure context between two applications. The application using InitContext must specify the Name of the acceptor it wants to connect to, and send the first token it obtains from step() to the acceptor. The acceptor should then respond and proceed with the establishment of the security context.
Parameters: |
|
---|
Performs a step to establish the context as an initiator.
This method should be called in a loop and fed input tokens from the acceptor, and its output tokens should be sent to the acceptor, until this context’s established attribute is True.
Parameters: | input_token (bytes) – The input token from the acceptor (omit this param or pass None on the first call). |
---|---|
Returns: | either a byte string with the next token to send to the acceptor, or None if there is no further token to send to the acceptor. |
Raises: | GSSException if there is an error establishing the context. |
All GSSAPI-related exceptions raised by this library are subclasses of GSSException. Errors reported by the C API are represented by subclasses of GSSCException, and errors which are reported by the C API and are specific to a given mechanism are represented by subclasses of GSSMechException. There are then specific exception classes for each of the error statuses defined in RFC 2744 Section 3.9.1, for example BadStructure or CredentialsExpired.
Note that exceptions raised by the library may inherit from more than one exception class, for example an exception raised by verify_mic() may be an instance of both BadSignature and also GSSMechException.
Bases: gssapi.error.GSSRoutineError
Incorrect channel bindings were supplied. Corresponds to a status of S_BAD_BINDINGS.
Bases: gssapi.error.GSSRoutineError
An unsupported mechanism was requested. Corresponds to a status of S_BAD_MECH.
Bases: gssapi.error.GSSRoutineError
An invalid name was supplied. Corresponds to a status of S_BAD_NAME.
Bases: gssapi.error.GSSRoutineError
A supplied name was of an unsupported type. Corresponds to a status of S_BAD_NAMETYPE.
Bases: gssapi.error.GSSRoutineError
The quality-of-protection requested could not be provided. Corresponds to a status of S_BAD_QOP.
Bases: gssapi.error.GSSRoutineError
A token had an invalid MIC. Corresponds to a status of S_BAD_SIG.
Bases: gssapi.error.GSSRoutineError
An invalid status code was supplied. Corresponds to a status of S_BAD_STATUS.
Bases: gssapi.error.GSSCallingError
A parameter was malformed. Corresponds to a status of S_CALL_BAD_STRUCTURE.
Bases: gssapi.error.GSSRoutineError
The context has expired. Corresponds to a status of S_CONTEXT_EXPIRED.
Bases: gssapi.error.GSSRoutineError
The referenced credentials have expired. Corresponds to a status of S_CREDENTIALS_EXPIRED.
Bases: gssapi.error.GSSRoutineError
A credential was invalid. Corresponds to a status of S_DEFECTIVE_CREDENTIAL.
Bases: gssapi.error.GSSRoutineError
A token was invalid. Corresponds to a status of S_DEFECTIVE_TOKEN.
Bases: gssapi.error.GSSRoutineError
The requested credential element already exists. Corresponds to a status of S_DUPLICATE_ELEMENT.
Bases: gssapi.error.GSSRoutineError
Miscellaneous failure. Corresponds to a status of S_FAILURE.
Bases: gssapi.error.GSSException
Represents a GSSAPI error reported by the C GSSAPI.
The major status code reported by the C GSSAPI which caused this exception.
The minor status code (normally mechanism-specific) reported by the C GSSAPI which caused this exception.
A string describing the error created by the C GSSAPI.
Bases: gssapi.error.GSSCException
Parent class for errors that are specific to the C language bindings.
Bases: exceptions.Exception
Represents a GSSAPI Exception.
If the exception was raised as a result of a failure to establish a security context, this attribute may be set to a bytestring which should be sent to the peer of the security context, to notify the peer that context establishment failed and that they should delete their associated security context. If not applicable, the attribute will be set to None.
Bases: gssapi.error.GSSCException
Represents a GSSAPI mechanism-specific error reported by the C GSSAPI.
The major status code reported by the C GSSAPI which caused this exception.
The minor status code (normally mechanism-specific) reported by the C GSSAPI which caused this exception.
A string describing the error created by the C GSSAPI.
Bases: gssapi.error.GSSCException
Parent class for errors that are defined in the GSS-API specification.
Bases: gssapi.error.GSSCallingError
A required input parameter could not be read. Corresponds to a status of S_CALL_INACCESSIBLE_READ.
Bases: gssapi.error.GSSCallingError
A required output parameter could not be written. Corresponds to a status of S_CALL_INACCESSIBLE_WRITE.
Bases: gssapi.error.GSSRoutineError
The provided name was not a mechanism name. Corresponds to a status of S_NAME_NOT_MN.
Bases: gssapi.error.GSSRoutineError
No context has been established. Corresponds to a status of S_NO_CONTEXT.
Bases: gssapi.error.GSSRoutineError
No credentials were supplied, or the credentials were unavailable or inaccessible. Corresponds to a status of S_NO_CRED.
Bases: gssapi.error.GSSRoutineError
The operation is forbidden by local security policy. Corresponds to a status of S_UNAUTHORIZED.
Bases: gssapi.error.GSSRoutineError
The operation or option is unavailable. Corresponds to a status of S_UNAVAILABLE.
Creates a “friendly” error message from a GSS status code. This is used to create the GSSCException.message of a GSSCException.
Parameters: |
|
---|---|
Returns: | a list of strings describing the error. |
Return type: | list of strings |
Bases: gssapi.names.Name
Represents a GSSAPI Mechanism Name (MN) as obtained by canonicalize() or as the peer_name property of an AcceptContext.
Don’t construct instances of this class directly; use canonicalize() on a Name to create a MechName.
Returns a representation of the Mechanism Name which is suitable for direct string comparison against other exported Mechanism Names. Its form is defined in the GSSAPI specification (RFC 2743). It can also be re-imported by constructing a Name with the name_type param set to gssapi.C_NT_EXPORT_NAME.
Returns: | an exported bytestring representation of this mechanism name |
---|---|
Return type: | bytes |
Bases: object
Used to construct GSSAPI internal-form names from a string representation (or numeric UID on POSIX platforms).
Parameters: |
|
---|
Create a canonical mechanism name (MechName) from an arbitrary internal name. The canonical MechName would be set as the peer_name property on an acceptor’s AcceptContext if an initiator performed a successful authentication to the acceptor using the given mechanism, using a Credential obtained using this Name.
Parameters: | mech (OID) – The mechanism to canonicalize this name for |
---|---|
Returns: | a canonical mechanism name based on this internal name. |
Return type: | MechName |
Bases: gssapi.oids.OIDSet
Represents a set of OIDs returned by the GSSAPI. This object supports array access to the OIDs contained within, and can also be modified by add() to incrementally construct a set from a number of OIDs.
Factory function to create a new MutableOIDSet with a single member.
Parameters: | single_oid (OID) – the OID to use as a member of the new set |
---|---|
Returns: | a mutable OID set with the OID passed in as the only member |
Return type: | MutableOIDSet |
Bases: object
Represents an Object Identifier. These are used by GSSAPI to identify mechanism types, and name types, amongst other things.
Normally there is no reason to construct instances of this class directly; objects of this class are returned from get_all_mechs() or mech_from_string() to identify mechanisms, as the mech_type attribute of Context objects, and as the type attribute of Name objects.
Takes a string form of a mechanism OID, in dot-separated: “1.2.840.113554.1.2.2” or numeric ASN.1: “{1 2 840 113554 1 2 2}” notation, and returns an OID object representing the mechanism, which can be passed to other GSSAPI methods.
Parameters: | input_string – a string representing the desired mechanism OID. |
---|---|
Returns: | the mechanism OID. |
Return type: | OID |
Raises: | ValueError if the the input string is ill-formatted. |
Raises: | KeyError if the mechanism identified by the string is not supported by the underlying GSSAPI implementation. |
Bases: object
Represents a set of OIDs returned by the GSSAPI. This object supports array access to the OIDs contained within. This set is immutable; if you need to incrementally create an OIDSet by adding OID objects to it, use MutableOIDSet.