pysasl.mechanism Package

pysasl.mechanism Module

pysasl.mechanism.Mechanism

A type alias for either server or client mechanisms.

alias of Union[ServerMechanism, ClientMechanism]

exception pysasl.mechanism.ServerChallenge(data)[source]

Raised by server_attempt() to provide server challenges.

Parameters:

data (bytes) – The challenge string that should be sent to the client.

Return type:

None

property data: bytes

The server challenge that should be sent to the client.

class pysasl.mechanism.ChallengeResponse(challenge, response)[source]

A challenge-response exchange between server and client.

Parameters:

  • challenge (bytes) – The server challenge string.

  • response (bytes) – The client response string.

property challenge: bytes

The server challenge string.

property response: bytes

The client response string.

class pysasl.mechanism.ServerMechanism(name)[source]

Base class for implementing SASL mechanisms that support server-side credential verification.

Parameters:

name (str | bytes) –

abstract server_attempt(responses)[source]

For SASL server-side credential verification, receives responses from the client and issues challenges until it has everything needed to verify the credentials.

If a challenge is necessary, a ServerChallenge exception will be raised. The response to this challenge must then be added to responses in the next call to server_attempt().

Parameters:

responses (Sequence[ChallengeResponse]) – The challenge-response exchanges thus far.

Returns:

A tuple of the authentication credentials received from the client once no more challenges are necessary, and an optional final response string from the server used by some mechanisms.

Raises:
Return type:

Tuple[ServerCredentials, bytes | None]

class pysasl.mechanism.ClientMechanism(name)[source]

Base class for implementing SASL mechanisms that support client-side credential verification.

Parameters:

name (str | bytes) –

abstract client_attempt(creds, challenges)[source]

For SASL client-side credential verification, produce responses to send to the server and react to its challenges until the server returns a final success or failure.

Parameters:
Returns:

The response to the most recent server challenge.

Raises:

UnexpectedChallenge – The server has issued a challenge the client mechanism does not recognize.

Return type:

ChallengeResponse

pysasl.mechanism.plain Module

class pysasl.mechanism.plain.PlainMechanism(name=b'PLAIN')[source]

Implements the PLAIN authentication mechanism.

Parameters:

name (str | bytes) –

server_attempt(responses)[source]

For SASL server-side credential verification, receives responses from the client and issues challenges until it has everything needed to verify the credentials.

If a challenge is necessary, a ServerChallenge exception will be raised. The response to this challenge must then be added to responses in the next call to server_attempt().

Parameters:

responses (Sequence[ChallengeResponse]) – The challenge-response exchanges thus far.

Returns:

A tuple of the authentication credentials received from the client once no more challenges are necessary, and an optional final response string from the server used by some mechanisms.

Raises:
Return type:

Tuple[PlainCredentials, None]

client_attempt(creds, challenges)[source]

For SASL client-side credential verification, produce responses to send to the server and react to its challenges until the server returns a final success or failure.

Parameters:
Returns:

The response to the most recent server challenge.

Raises:

UnexpectedChallenge – The server has issued a challenge the client mechanism does not recognize.

Return type:

ChallengeResponse

pysasl.mechanism.login Module

class pysasl.mechanism.login.LoginMechanism(name=b'LOGIN')[source]

Implements the LOGIN authentication mechanism.

Parameters:

name (str | bytes) –

server_attempt(responses)[source]

For SASL server-side credential verification, receives responses from the client and issues challenges until it has everything needed to verify the credentials.

If a challenge is necessary, a ServerChallenge exception will be raised. The response to this challenge must then be added to responses in the next call to server_attempt().

Parameters:

responses (Sequence[ChallengeResponse]) – The challenge-response exchanges thus far.

Returns:

A tuple of the authentication credentials received from the client once no more challenges are necessary, and an optional final response string from the server used by some mechanisms.

Raises:
Return type:

Tuple[PlainCredentials, None]

client_attempt(creds, challenges)[source]

For SASL client-side credential verification, produce responses to send to the server and react to its challenges until the server returns a final success or failure.

Parameters:
Returns:

The response to the most recent server challenge.

Raises:

UnexpectedChallenge – The server has issued a challenge the client mechanism does not recognize.

Return type:

ChallengeResponse

pysasl.mechanism.crammd5 Module

class pysasl.mechanism.crammd5.CramMD5Result(username, challenge, digest)[source]

Because this mechanism uses hash algorithms to compare secrets, the server_attempt() method returns this sub-class which overrides the verify() method.

Parameters:
property authcid: str

The authentication identity, e.g. a login username.

property authzid: str

The authorization identity. The authcid identity must have sufficient privileges to assume this identity for the authentication attempt to succeed.

verify(identity)[source]

Authenticates the credentials against the given identity.

Parameters:

identity (Identity | None) – The identity being authenticated.

Raises:

MechanismUnusable – The mechanism is not capable of verifying identity.

Return type:

bool

class pysasl.mechanism.crammd5.CramMD5Mechanism(name=b'CRAM-MD5')[source]

Implements the CRAM-MD5 authentication mechanism.

Warning

Although secure during transport, offering this mechanism can be dangerous, as it can have implications about how the credentials are stored server-side.

Parameters:

name (str | bytes) –

server_attempt(responses)[source]

For SASL server-side credential verification, receives responses from the client and issues challenges until it has everything needed to verify the credentials.

If a challenge is necessary, a ServerChallenge exception will be raised. The response to this challenge must then be added to responses in the next call to server_attempt().

Parameters:

responses (Sequence[ChallengeResponse]) – The challenge-response exchanges thus far.

Returns:

A tuple of the authentication credentials received from the client once no more challenges are necessary, and an optional final response string from the server used by some mechanisms.

Raises:
Return type:

Tuple[CramMD5Result, None]

client_attempt(creds, challenges)[source]

For SASL client-side credential verification, produce responses to send to the server and react to its challenges until the server returns a final success or failure.

Parameters:
Returns:

The response to the most recent server challenge.

Raises:

UnexpectedChallenge – The server has issued a challenge the client mechanism does not recognize.

Return type:

ChallengeResponse

pysasl.mechanism.oauth Module

class pysasl.mechanism.oauth.OAuth2Mechanism(name=b'XOAUTH2')[source]

Implements the XOAUTH2 authentication mechanism, used by OAuth 2.0 systems to authenticate using access tokens.

Parameters:

name (str | bytes) –

server_attempt(responses)[source]

For SASL server-side credential verification, receives responses from the client and issues challenges until it has everything needed to verify the credentials.

If a challenge is necessary, a ServerChallenge exception will be raised. The response to this challenge must then be added to responses in the next call to server_attempt().

Parameters:

responses (Sequence[ChallengeResponse]) – The challenge-response exchanges thus far.

Returns:

A tuple of the authentication credentials received from the client once no more challenges are necessary, and an optional final response string from the server used by some mechanisms.

Raises:
Return type:

Tuple[ExternalCredentials, None]

client_attempt(creds, challenges)[source]

For SASL client-side credential verification, produce responses to send to the server and react to its challenges until the server returns a final success or failure.

Parameters:
Returns:

The response to the most recent server challenge.

Raises:

UnexpectedChallenge – The server has issued a challenge the client mechanism does not recognize.

Return type:

ChallengeResponse

pysasl.mechanism.external Module

class pysasl.mechanism.external.ExternalMechanism(name=b'EXTERNAL')[source]

Implements the EXTERNAL authentication mechanism.

See also

RFC 4422 Appendix A

Parameters:

name (str | bytes) –

server_attempt(responses)[source]

For SASL server-side credential verification, receives responses from the client and issues challenges until it has everything needed to verify the credentials.

If a challenge is necessary, a ServerChallenge exception will be raised. The response to this challenge must then be added to responses in the next call to server_attempt().

Parameters:

responses (Sequence[ChallengeResponse]) – The challenge-response exchanges thus far.

Returns:

A tuple of the authentication credentials received from the client once no more challenges are necessary, and an optional final response string from the server used by some mechanisms.

Raises:
Return type:

Tuple[ExternalCredentials, None]

client_attempt(creds, challenges)[source]

For SASL client-side credential verification, produce responses to send to the server and react to its challenges until the server returns a final success or failure.

Parameters:
Returns:

The response to the most recent server challenge.

Raises:

UnexpectedChallenge – The server has issued a challenge the client mechanism does not recognize.

Return type:

ChallengeResponse