Safe Haskell	None
Language	GHC2021

Rustls

Contents

Client
Server
Connection
Misc

Description

TLS bindings for Rustls via rustls-ffi.

See the README on GitHub for setup instructions.

Currently, most of the functionality exposed by rustls-ffi is available, while rustls-ffi is still missing some more niche Rustls features.

Also see http-client-rustls for making HTTPS requests using http-client and Rustls.

Client example

Suppose you have already opened a Socket to example.org, port 443 (see e.g. the examples at Network.Socket). This small example showcases how to perform a simple HTTP GET request:

>>> :set -XOverloadedStrings
>>> import qualified Rustls
>>> import Network.Socket (Socket)
>>> import Data.Acquire (withAcquire)
>>> :{
example :: Socket -> IO ()
example socket = do
  -- It is encouraged to share a single `clientConfig` when creating multiple
  -- TLS connections.
  clientConfig <-
    Rustls.buildClientConfig =<< Rustls.defaultClientConfigBuilder
  let backend = Rustls.mkSocketBackend socket
      newConnection =
        Rustls.newClientConnection backend clientConfig "example.org"
  withAcquire newConnection $ \conn -> do
    Rustls.writeBS conn "GET /"
    recv <- Rustls.readBS conn 1000 -- max number of bytes to read
    print recv
:}

Using `Acquire`

Some API functions (like newClientConnection and newServerConnection) return an Acquire from resourcet, as it is a convenient abstraction for exposing a value that should be consumed in a "bracketed" manner.

Usually, it can be used via with or withAcquire, or via allocateAcquire when a MonadResource constraint is available. If you really need the extra flexibility, you can also access separate open… and close… functions by reaching for Data.Acquire.Internal.

Synopsis

data ClientConfigBuilder = ClientConfigBuilder {
- clientConfigCryptoProvider :: CryptoProvider
- clientConfigServerCertVerifier :: ServerCertVerifier
- clientConfigALPNProtocols :: [ALPNProtocol]
- clientConfigEnableSNI :: Bool
- clientConfigCertifiedKeys :: [CertifiedKey]
}
defaultClientConfigBuilder :: MonadIO m => m ClientConfigBuilder
data ServerCertVerifier
- = PlatformServerCertVerifier
- | ServerCertVerifier {
  - serverCertVerifierCertificates :: NonEmpty PEMCertificates
  - serverCertVerifierCRLs :: [CertificateRevocationList]
  }
data ClientConfig
clientConfigLogCallback :: ClientConfig -> Maybe LogCallback
buildClientConfig :: MonadIO m => ClientConfigBuilder -> m ClientConfig
newClientConnection :: Backend -> ClientConfig -> Text -> Acquire (Connection 'Client)
data ServerConfigBuilder = ServerConfigBuilder {
- serverConfigCryptoProvider :: CryptoProvider
- serverConfigCertifiedKeys :: NonEmpty CertifiedKey
- serverConfigALPNProtocols :: [ALPNProtocol]
- serverConfigIgnoreClientOrder :: Bool
- serverConfigClientCertVerifier :: Maybe ClientCertVerifier
}
defaultServerConfigBuilder :: MonadIO m => NonEmpty CertifiedKey -> m ServerConfigBuilder
data ClientCertVerifier = ClientCertVerifier {
- clientCertVerifierPolicy :: ClientCertVerifierPolicy
- clientCertVerifierCertificates :: NonEmpty PEMCertificates
- clientCertVerifierCRLs :: [CertificateRevocationList]
}
data ClientCertVerifierPolicy
- = AllowAnyAuthenticatedClient
- | AllowAnyAnonymousOrAuthenticatedClient
data ServerConfig
serverConfigLogCallback :: ServerConfig -> Maybe LogCallback
buildServerConfig :: MonadIO m => ServerConfigBuilder -> m ServerConfig
newServerConnection :: Backend -> ServerConfig -> Acquire (Connection 'Server)
data Connection (side :: Side)
data Side
- = Client
- | Server
readBS :: forall m (side :: Side). MonadIO m => Connection side -> Int -> m ByteString
writeBS :: forall m (side :: Side). MonadIO m => Connection side -> ByteString -> m ()
handshake :: forall m (side :: Side) a. MonadIO m => Connection side -> HandshakeQuery side a -> m a
data HandshakeQuery (side :: Side) a
getALPNProtocol :: forall (side :: Side). HandshakeQuery side (Maybe ALPNProtocol)
getTLSVersion :: forall (side :: Side). HandshakeQuery side TLSVersion
getNegotiatedCipherSuite :: forall (side :: Side). HandshakeQuery side NegotiatedCipherSuite
getSNIHostname :: HandshakeQuery 'Server (Maybe Text)
getPeerCertificate :: forall (side :: Side). CSize -> HandshakeQuery side (Maybe DERCertificate)
sendCloseNotify :: forall m (side :: Side). MonadIO m => Connection side -> m ()
data LogCallback
newLogCallback :: (LogLevel -> Text -> IO ()) -> Acquire LogCallback
data LogLevel
- = LogLevelError
- | LogLevelWarn
- | LogLevelInfo
- | LogLevelDebug
- | LogLevelTrace
readPtr :: forall m (side :: Side). MonadIO m => Connection side -> Ptr Word8 -> CSize -> m CSize
writePtr :: forall m (side :: Side). MonadIO m => Connection side -> Ptr Word8 -> CSize -> m CSize
version :: Text
data Backend = Backend {
- backendRead :: Ptr Word8 -> CSize -> IO CSize
- backendWrite :: Ptr Word8 -> CSize -> IO CSize
}
mkSocketBackend :: Socket -> Backend
mkByteStringBackend :: (Int -> IO ByteString) -> (ByteString -> IO ()) -> Backend
data CryptoProvider
getDefaultCryptoProvider :: MonadIO m => m CryptoProvider
setCryptoProviderCipherSuites :: MonadError RustlsException m => [CipherSuite] -> CryptoProvider -> m CryptoProvider
cryptoProviderCipherSuites :: CryptoProvider -> [CipherSuite]
cryptoProviderTLSVersions :: CryptoProvider -> [TLSVersion]
newtype ALPNProtocol = ALPNProtocol {
- unALPNProtocol :: ByteString
}
data PEMCertificates
- = PEMCertificatesInMemory ByteString PEMCertificateParsing
- | PemCertificatesFromFile FilePath PEMCertificateParsing
data PEMCertificateParsing
- = PEMCertificateParsingStrict
- | PEMCertificateParsingLax
data CertifiedKey = CertifiedKey {
- certificateChain :: ByteString
- privateKey :: ByteString
}
newtype DERCertificate = DERCertificate {
- unDERCertificate :: ByteString
}
newtype CertificateRevocationList = CertificateRevocationList {
- unCertificateRevocationList :: ByteString
}
data TLSVersion where
- pattern TLS12 :: TLSVersion
- pattern TLS13 :: TLSVersion
data CipherSuite = CipherSuite {
- cipherSuiteID :: Word16
- cipherSuiteName :: Text
- cipherSuiteTLSVersion :: TLSVersion
}
data NegotiatedCipherSuite = NegotiatedCipherSuite {
- negotiatedCipherSuiteID :: Word16
- negotiatedCipherSuiteName :: Text
}
data RustlsException
isCertError :: RustlsException -> Bool
newtype RustlsLogException = RustlsLogException SomeException

Client

Builder

data ClientConfigBuilder Source #

Rustls client config builder.

Constructors

ClientConfigBuilder

Fields

clientConfigCryptoProvider :: CryptoProvider
The cryptography provider.
clientConfigServerCertVerifier :: ServerCertVerifier
The server certificate verifier.
clientConfigALPNProtocols :: [ALPNProtocol]
ALPN protocols.
clientConfigEnableSNI :: Bool
Whether to enable Server Name Indication. Defaults to True.
clientConfigCertifiedKeys :: [CertifiedKey]
List of CertifiedKeys for client authentication.
Clients that want to support both ECDSA and RSA certificates will want the ECDSA to go first in the list.

Instances

Instances details

Generic ClientConfigBuilder Source #

Instance details

PlatformServerCertVerifier	Verify the validity of TLS certificates based on the operating system's certificate facilities, using rustls-platform-verifier.
ServerCertVerifier
Fields serverCertVerifierCertificates :: NonEmpty PEMCertificates Certificates used to verify TLS server certificates. serverCertVerifierCRLs :: [CertificateRevocationList] List of certificate revocation lists used to verify TLS server certificates.

:: Backend
-> ClientConfig
-> Text	Hostname.
-> Acquire (Connection 'Client)

ClientCertVerifier
Fields clientCertVerifierPolicy :: ClientCertVerifierPolicy Which client connections are allowed. clientCertVerifierCertificates :: NonEmpty PEMCertificates Certificates used to verify TLS client certificates. clientCertVerifierCRLs :: [CertificateRevocationList] List of certificate revocation lists used to verify TLS client certificates.

AllowAnyAuthenticatedClient	Allow any authenticated client (i.e. offering a trusted certificate), and reject clients offering none.
AllowAnyAnonymousOrAuthenticatedClient	Allow any authenticated client (i.e. offering a trusted certificate), but also allow clients offering none.

:: forall m (side :: Side). MonadIO m
=> Connection side
-> Int	Maximum result length. Note that a buffer of this size will be allocated.
-> m ByteString

Applicative (HandshakeQuery side) Source #
Instance details Defined in Rustls.Internal Methods pure :: a -> HandshakeQuery side a # (<>) :: HandshakeQuery side (a -> b) -> HandshakeQuery side a -> HandshakeQuery side b # liftA2 :: (a -> b -> c) -> HandshakeQuery side a -> HandshakeQuery side b -> HandshakeQuery side c # (>) :: HandshakeQuery side a -> HandshakeQuery side b -> HandshakeQuery side b # (<*) :: HandshakeQuery side a -> HandshakeQuery side b -> HandshakeQuery side a #
Functor (HandshakeQuery side) Source #
Instance details Defined in Rustls.Internal Methods fmap :: (a -> b) -> HandshakeQuery side a -> HandshakeQuery side b # (<$) :: a -> HandshakeQuery side b -> HandshakeQuery side a #
Monad (HandshakeQuery side) Source #
Instance details Defined in Rustls.Internal Methods (>>=) :: HandshakeQuery side a -> (a -> HandshakeQuery side b) -> HandshakeQuery side b # (>>) :: HandshakeQuery side a -> HandshakeQuery side b -> HandshakeQuery side b # return :: a -> HandshakeQuery side a #

LogLevelError
LogLevelWarn
LogLevelInfo
LogLevelDebug
LogLevelTrace

Backend
Fields backendRead :: Ptr Word8 -> CSize -> IO CSize Read data from the backend into the given buffer. backendWrite :: Ptr Word8 -> CSize -> IO CSize Write data from the given buffer to the backend.

Show CryptoProvider Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> CryptoProvider -> ShowS # show :: CryptoProvider -> String # showList :: [CryptoProvider] -> ShowS #

:: MonadError RustlsException m
=> [CipherSuite]	Must be a subset of `cryptoProviderCipherSuites`. Only the `cipherSuiteID` is used.
-> CryptoProvider
-> m CryptoProvider

PEMCertificatesInMemory ByteString PEMCertificateParsing	In-memory PEM-encoded certificates.
PemCertificatesFromFile FilePath PEMCertificateParsing	Fetch PEM-encoded root certificates from a file.

CertifiedKey
Fields certificateChain :: ByteString PEM-encoded certificate chain. privateKey :: ByteString PEM-encoded private key.

CertificateRevocationList
Fields unCertificateRevocationList :: ByteString

Storable TLSVersion Source #
Instance details Defined in Rustls.Internal.FFI Methods sizeOf :: TLSVersion -> Int # alignment :: TLSVersion -> Int # peekElemOff :: Ptr TLSVersion -> Int -> IO TLSVersion # pokeElemOff :: Ptr TLSVersion -> Int -> TLSVersion -> IO () # peekByteOff :: Ptr b -> Int -> IO TLSVersion # pokeByteOff :: Ptr b -> Int -> TLSVersion -> IO () # peek :: Ptr TLSVersion -> IO TLSVersion # poke :: Ptr TLSVersion -> TLSVersion -> IO () #
Show TLSVersion Source #
Instance details Defined in Rustls.Internal.FFI Methods showsPrec :: Int -> TLSVersion -> ShowS # show :: TLSVersion -> String # showList :: [TLSVersion] -> ShowS #
Eq TLSVersion Source #
Instance details Defined in Rustls.Internal.FFI Methods (==) :: TLSVersion -> TLSVersion -> Bool # (/=) :: TLSVersion -> TLSVersion -> Bool #
Ord TLSVersion Source #
Instance details Defined in Rustls.Internal.FFI Methods compare :: TLSVersion -> TLSVersion -> Ordering # (<) :: TLSVersion -> TLSVersion -> Bool # (<=) :: TLSVersion -> TLSVersion -> Bool # (>) :: TLSVersion -> TLSVersion -> Bool # (>=) :: TLSVersion -> TLSVersion -> Bool # max :: TLSVersion -> TLSVersion -> TLSVersion # min :: TLSVersion -> TLSVersion -> TLSVersion #

CipherSuite
Fields cipherSuiteID :: Word16 The IANA value of the cipher suite. The bytes are interpreted in network order. See https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 for a list. cipherSuiteName :: Text The text representation of the cipher suite. cipherSuiteTLSVersion :: TLSVersion The TLS version of the cipher suite.

NegotiatedCipherSuite
Fields negotiatedCipherSuiteID :: Word16 The IANA value of the cipher suite. The bytes are interpreted in network order. See https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 for a list. negotiatedCipherSuiteName :: Text The text representation of the cipher suite.

Exception RustlsException Source #
Instance details Defined in Rustls.Internal Methods toException :: RustlsException -> SomeException # fromException :: SomeException -> Maybe RustlsException # displayException :: RustlsException -> String # backtraceDesired :: RustlsException -> Bool #
Show RustlsException Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> RustlsException -> ShowS # show :: RustlsException -> String # showList :: [RustlsException] -> ShowS #

Exception RustlsLogException Source #
Instance details Defined in Rustls.Internal Methods toException :: RustlsLogException -> SomeException # fromException :: SomeException -> Maybe RustlsLogException # displayException :: RustlsLogException -> String # backtraceDesired :: RustlsLogException -> Bool #
Show RustlsLogException Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> RustlsLogException -> ShowS # show :: RustlsLogException -> String # showList :: [RustlsLogException] -> ShowS #

Client example

Using Acquire

Client

Builder

Instances

Instances

Config

Open a connection

Server

Builder

Instances

Instances

Instances

Config

Open a connection

Connection

Read and write

Handshaking

Instances

Closing

Logging

Instances

Raw Ptr-based API

Misc

Backend

Crypto provider

Instances

Types

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Exceptions

Instances

Instances

Using `Acquire`

Raw `Ptr`-based API