Network.Protocol.SASL.GNU

gsasl-0.3.6: Bindings for GNU libgsasl

Safe Haskell | None
Language | Haskell98

Network.Protocol.SASL.GNU

Contents

- Library Information
- SASL Contexts
- Mechanisms
- SASL Sessions
  - Session Properties
  - Session IO
  - Error handling
- Bundled codecs

Synopsis

- headerVersion :: (Integer, Integer, Integer)
- libraryVersion :: IO (Integer, Integer, Integer)
- checkVersion :: IO Bool
- data SASL a
- runSASL :: SASL a -> IO a
- setCallback :: (Property -> Session Progress) -> SASL ()
- runCallback :: Property -> Session Progress
- newtype Mechanism = Mechanism ByteString
- clientMechanisms :: SASL [Mechanism]
- clientSupports :: Mechanism -> SASL Bool
- clientSuggestMechanism :: [Mechanism] -> SASL (Maybe Mechanism)
- serverMechanisms :: SASL [Mechanism]
- serverSupports :: Mechanism -> SASL Bool
- data Session a
- runClient :: Mechanism -> Session a -> SASL (Either Error a)
- runServer :: Mechanism -> Session a -> SASL (Either Error a)
- mechanismName :: Session Mechanism
- data Property
  - = PropertyAuthID
  - | PropertyAuthzID
  - | PropertyPassword
  - | PropertyAnonymousToken
  - | PropertyService
  - | PropertyHostname
  - | PropertyGSSAPIDisplayName
  - | PropertyPasscode
  - | PropertySuggestedPIN
  - | PropertyPIN
  - | PropertyRealm
  - | PropertyDigestMD5HashedPassword
  - | PropertyQOPS
  - | PropertyQOP
  - | PropertyScramIter
  - | PropertyScramSalt
  - | PropertyScramSaltedPassword
  - | ValidateSimple
  - | ValidateExternal
  - | ValidateAnonymous
  - | ValidateGSSAPI
  - | ValidateSecurID
- setProperty :: Property -> ByteString -> Session ()
- getProperty :: Property -> Session (Maybe ByteString)
- getPropertyFast :: Property -> Session (Maybe ByteString)
- data Progress
  - = Complete
  - | NeedsMore
- step :: ByteString -> Session (ByteString, Progress)
- step64 :: ByteString -> Session (ByteString, Progress)
- encode :: ByteString -> Session ByteString
- decode :: ByteString -> Session ByteString
- data Error
  - = UnknownMechanism
  - | MechanismCalledTooManyTimes
  - | MallocError
  - | Base64Error
  - | CryptoError
  - | SASLPrepError
  - | MechanismParseError
  - | AuthenticationError
  - | IntegrityError
  - | NoClientCode
  - | NoServerCode
  - | NoCallback
  - | NoAnonymousToken
  - | NoAuthID
  - | NoAuthzID
  - | NoPassword
  - | NoPasscode
  - | NoPIN
  - | NoService
  - | NoHostname
  - | GSSAPI_ReleaseBufferError
  - | GSSAPI_ImportNameError
  - | GSSAPI_InitSecContextError
  - | GSSAPI_AcceptSecContextError
  - | GSSAPI_UnwrapError
  - | GSSAPI_WrapError
  - | GSSAPI_AquireCredError
  - | GSSAPI_DisplayNameError
  - | GSSAPI_UnsupportedProtectionError
  - | GSSAPI_EncapsulateTokenError
  - | GSSAPI_DecapsulateTokenError
  - | GSSAPI_InquireMechForSASLNameError
  - | GSSAPI_TestOIDSetMemberError
  - | GSSAPI_ReleaseOIDSetError
  - | KerberosV5_InitError
  - | KerberosV5_InternalError
  - | SecurID_ServerNeedAdditionalPasscode
  - | SecurID_ServerNeedNewPIN
- catch :: Session a -> (Error -> Session a) -> Session a
- handle :: (Error -> Session a) -> Session a -> Session a
- try :: Session a -> Session (Either Error a)
- throw :: Error -> Session a
- toBase64 :: ByteString -> ByteString
- fromBase64 :: ByteString -> ByteString
- md5 :: ByteString -> ByteString
- sha1 :: ByteString -> ByteString
- hmacMD5 :: ByteString -> ByteString -> ByteString
- hmacSHA1 :: ByteString -> ByteString -> ByteString
- nonce :: Integer -> IO ByteString
- random :: Integer -> IO ByteString

# Library Information

headerVersion :: (Integer, Integer, Integer)

Which version of `gsasl.h` this module was compiled against

libraryVersion :: IO (Integer, Integer, Integer)

Which version of `libgsasl.so` is loaded

checkVersion :: IO Bool

Whether the header and library versions are compatible

# SASL Contexts

data SASL a

Instances

Monad SASL |
Functor SASL |
Applicative SASL |
MonadIO SASL |

runSASL :: SASL a -> IO a

setCallback :: (Property -> Session Progress) -> SASL ()

Set the current SASL callback. The callback will be used by mechanisms to discover various parameters, such as usernames and passwords.

runCallback :: Property -> Session Progress

Run the current callback; the property indicates what action the callback is expected to perform.

# Mechanisms

newtype Mechanism

Constructors

Mechanism ByteString |

Instances

Eq Mechanism |
Show Mechanism |
IsString Mechanism |

clientMechanisms :: SASL [Mechanism]

A list of `Mechanism`s supported by the `libgsasl` client.

clientSupports :: Mechanism -> SASL Bool

Whether there is client-side support for a specified `Mechanism`.

clientSuggestMechanism :: [Mechanism] -> SASL (Maybe Mechanism)

Given a list of `Mechanism`s, suggest which to use (or `Nothing` if no supported `Mechanism` is found).

serverMechanisms :: SASL [Mechanism]

A list of `Mechanism`s supported by the `libgsasl` server.

serverSupports :: Mechanism -> SASL Bool

Whether there is server-side support for a specified `Mechanism`.

# SASL Sessions

data Session a

Instances

Monad Session |
Functor Session |
Applicative Session |
MonadIO Session |

runClient :: Mechanism -> Session a -> SASL (Either Error a)

Run a session using the `libgsasl` client.

runServer :: Mechanism -> Session a -> SASL (Either Error a)

Run a session using the `libgsasl` server.

mechanismName :: Session Mechanism

The name of the session's SASL mechanism.

## Session Properties

data Property

Constructors

PropertyAuthID |
PropertyAuthzID |
PropertyPassword |
PropertyAnonymousToken |
PropertyService |
PropertyHostname |
PropertyGSSAPIDisplayName |
PropertyPasscode |
PropertySuggestedPIN |
PropertyPIN |
PropertyRealm |
PropertyDigestMD5HashedPassword |
PropertyQOPS |
PropertyQOP |
PropertyScramIter |
PropertyScramSalt |
PropertyScramSaltedPassword |
ValidateSimple |
ValidateExternal |
ValidateAnonymous |
ValidateGSSAPI |
ValidateSecurID |

Instances

Eq Property |
Show Property |

setProperty :: Property -> ByteString -> Session ()

Store some data in the session for the given property. The data must be `NULL`-terminated.

getProperty :: Property -> Session (Maybe ByteString)

Retrieve the data stored in the session for the given property, possibly invoking the current callback to get the value.

getPropertyFast :: Property -> Session (Maybe ByteString)

Retrieve the data stored in the session for the given property, without invoking the current callback.

## Session IO

data Progress

Constructors

Complete |
NeedsMore |

Instances

Eq Progress |
Show Progress |

step :: ByteString -> Session (ByteString, Progress)

Perform one step of SASL authentication. This reads data from the other end, processes it (potentially running the callback), and returns data to be sent back.

Also returns `NeedsMore` if authentication is not yet complete.

step64 :: ByteString -> Session (ByteString, Progress)

A simple wrapper around `step` which uses base64 to decode the input and encode the output.

encode :: ByteString -> Session ByteString

Encode data according to the negotiated SASL mechanism. This might mean the data is integrity or privacy protected.

decode :: ByteString -> Session ByteString

Decode data according to the negotiated SASL mechanism. This might mean the data is integrity or privacy protected.

## Error handling

data Error

Constructors

UnknownMechanism |
MechanismCalledTooManyTimes |
MallocError |
Base64Error |
CryptoError |
SASLPrepError |
MechanismParseError |
AuthenticationError |
IntegrityError |
NoClientCode |
NoServerCode |
NoCallback |
NoAnonymousToken |
NoAuthID |
NoAuthzID |
NoPassword |
NoPasscode |
NoPIN |
NoService |
NoHostname |
GSSAPI_ReleaseBufferError |
GSSAPI_ImportNameError |
GSSAPI_InitSecContextError |
GSSAPI_AcceptSecContextError |
GSSAPI_UnwrapError |
GSSAPI_WrapError |
GSSAPI_AquireCredError |
GSSAPI_DisplayNameError |
GSSAPI_UnsupportedProtectionError |
GSSAPI_EncapsulateTokenError |
GSSAPI_DecapsulateTokenError |
GSSAPI_InquireMechForSASLNameError |
GSSAPI_TestOIDSetMemberError |
GSSAPI_ReleaseOIDSetError |
KerberosV5_InitError |
KerberosV5_InternalError |
SecurID_ServerNeedAdditionalPasscode |
SecurID_ServerNeedNewPIN |

Instances

Show Error |

catch :: Session a -> (Error -> Session a) -> Session a

handle :: (Error -> Session a) -> Session a -> Session a

try :: Session a -> Session (Either Error a)

throw :: Error -> Session a

# Bundled codecs

toBase64 :: ByteString -> ByteString

fromBase64 :: ByteString -> ByteString

md5 :: ByteString -> ByteString

sha1 :: ByteString -> ByteString

hmacMD5

Arguments

:: ByteString | Key
-> ByteString | Input data
-> ByteString |

hmacSHA1

Arguments

:: ByteString | Key
-> ByteString | Input data
-> ByteString |

nonce :: Integer -> IO ByteString

Returns unpredictable data of a given size

random :: Integer -> IO ByteString

Returns cryptographically strong random data of a given size