Safe Haskell	Safe-Inferred
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 serverCertVerifier
  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
  where
    -- For now, rustls-ffi does not provide a built-in way to access
    -- the OS certificate store.
    serverCertVerifier =
      Rustls.ServerCertVerifier
        { Rustls.serverCertVerifierCertificates =
            pure $
              Rustls.PemCertificatesFromFile
                "/etc/ssl/certs/ca-certificates.crt"
                Rustls.PEMCertificateParsingStrict,
          Rustls.serverCertVerifierCRLs = []
        }
:}

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 {
- clientConfigServerCertVerifier :: ServerCertVerifier
- clientConfigTLSVersions :: [TLSVersion]
- clientConfigCipherSuites :: [CipherSuite]
- clientConfigALPNProtocols :: [ALPNProtocol]
- clientConfigEnableSNI :: Bool
- clientConfigCertifiedKeys :: [CertifiedKey]
}
defaultClientConfigBuilder :: ServerCertVerifier -> ClientConfigBuilder
data ServerCertVerifier = 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 {
- serverConfigCertifiedKeys :: NonEmpty CertifiedKey
- serverConfigTLSVersions :: [TLSVersion]
- serverConfigCipherSuites :: [CipherSuite]
- serverConfigALPNProtocols :: [ALPNProtocol]
- serverConfigIgnoreClientOrder :: Bool
- serverConfigClientCertVerifier :: Maybe ClientCertVerifier
}
defaultServerConfigBuilder :: NonEmpty CertifiedKey -> 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 :: MonadIO m => Connection side -> Int -> m ByteString
writeBS :: MonadIO m => Connection side -> ByteString -> m ()
handshake :: MonadIO m => Connection side -> HandshakeQuery side a -> m a
data HandshakeQuery (side :: Side) a
getALPNProtocol :: HandshakeQuery side (Maybe ALPNProtocol)
getTLSVersion :: HandshakeQuery side TLSVersion
getCipherSuite :: HandshakeQuery side CipherSuite
getSNIHostname :: HandshakeQuery Server (Maybe Text)
getPeerCertificate :: CSize -> HandshakeQuery side (Maybe DERCertificate)
sendCloseNotify :: MonadIO m => Connection side -> m ()
data LogCallback
newLogCallback :: (LogLevel -> Text -> IO ()) -> Acquire LogCallback
data LogLevel
- = LogLevelError
- | LogLevelWarn
- | LogLevelInfo
- | LogLevelDebug
- | LogLevelTrace
readPtr :: MonadIO m => Connection side -> Ptr Word8 -> CSize -> m CSize
writePtr :: 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
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
defaultTLSVersions :: NonEmpty TLSVersion
allTLSVersions :: NonEmpty TLSVersion
data CipherSuite
cipherSuiteID :: CipherSuite -> Word16
showCipherSuite :: CipherSuite -> Text
defaultCipherSuites :: NonEmpty CipherSuite
allCipherSuites :: NonEmpty CipherSuite
data RustlsException
isCertError :: RustlsException -> Bool
newtype RustlsLogException = RustlsLogException SomeException

Client

Builder

data ClientConfigBuilder Source #

Rustls client config builder.

Constructors

ClientConfigBuilder

Fields

clientConfigServerCertVerifier :: ServerCertVerifier
The server certificate verifier.
clientConfigTLSVersions :: [TLSVersion]
Supported TLSVersions. When empty, good defaults are used.
clientConfigCipherSuites :: [CipherSuite]
Supported CipherSuites in order of preference. When empty, good defaults are used.
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 Defined in Rustls.Internal Associated Types type Rep ClientConfigBuilder :: Type -> Type # Methods from :: ClientConfigBuilder -> Rep ClientConfigBuilder x # to :: Rep ClientConfigBuilder x -> ClientConfigBuilder #
Show ClientConfigBuilder Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> ClientConfigBuilder -> ShowS # show :: ClientConfigBuilder -> String # showList :: [ClientConfigBuilder] -> ShowS #
type Rep ClientConfigBuilder Source #
Instance details Defined in Rustls.Internal type Rep ClientConfigBuilder = D1 ('MetaData "ClientConfigBuilder" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "ClientConfigBuilder" 'PrefixI 'True) ((S1 ('MetaSel ('Just "clientConfigServerCertVerifier") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 ServerCertVerifier) :: (S1 ('MetaSel ('Just "clientConfigTLSVersions") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [TLSVersion]) :: S1 ('MetaSel ('Just "clientConfigCipherSuites") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [CipherSuite]))) :: (S1 ('MetaSel ('Just "clientConfigALPNProtocols") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [ALPNProtocol]) :: (S1 ('MetaSel ('Just "clientConfigEnableSNI") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Bool) :*: S1 ('MetaSel ('Just "clientConfigCertifiedKeys") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [CertifiedKey])))))

defaultClientConfigBuilder :: ServerCertVerifier -> ClientConfigBuilder Source #

A ClientConfigBuilder with good defaults.

data ServerCertVerifier Source #

How to verify TLS server certificates.

Constructors

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.

Instances

Instances details

Generic ServerCertVerifier Source #
Instance details Defined in Rustls.Internal Associated Types type Rep ServerCertVerifier :: Type -> Type # Methods from :: ServerCertVerifier -> Rep ServerCertVerifier x # to :: Rep ServerCertVerifier x -> ServerCertVerifier #
Show ServerCertVerifier Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> ServerCertVerifier -> ShowS # show :: ServerCertVerifier -> String # showList :: [ServerCertVerifier] -> ShowS #
type Rep ServerCertVerifier Source #
Instance details Defined in Rustls.Internal type Rep ServerCertVerifier = D1 ('MetaData "ServerCertVerifier" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "ServerCertVerifier" 'PrefixI 'True) (S1 ('MetaSel ('Just "serverCertVerifierCertificates") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (NonEmpty PEMCertificates)) :*: S1 ('MetaSel ('Just "serverCertVerifierCRLs") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [CertificateRevocationList])))

Config

data ClientConfig Source #

Assembled configuration for a Rustls client connection.

clientConfigLogCallback :: ClientConfig -> Maybe LogCallback Source #

A logging callback.

Note that this is a record selector, so you can use it as a setter:

>>> :{
setLogCallback :: LogCallback -> ClientConfig -> ClientConfig
setLogCallback logCallback clientConfig =
  clientConfig { clientConfigLogCallback = Just logCallback }
:}

buildClientConfig :: MonadIO m => ClientConfigBuilder -> m ClientConfig Source #

Build a ClientConfigBuilder into a ClientConfig.

This is a relatively expensive operation, so it is a good idea to share one ClientConfig when creating multiple Connections.

Open a connection

newClientConnection Source #

Arguments

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

Initialize a TLS connection as a client.

Server

Builder

data ServerConfigBuilder Source #

Rustls client config builder.

Constructors

ServerConfigBuilder

Fields

serverConfigCertifiedKeys :: NonEmpty CertifiedKey
List of CertifiedKeys.
serverConfigTLSVersions :: [TLSVersion]
Supported TLSVersions. When empty, good defaults are used.
serverConfigCipherSuites :: [CipherSuite]
Supported CipherSuites in order of preference. When empty, good defaults are used.
serverConfigALPNProtocols :: [ALPNProtocol]
ALPN protocols.
serverConfigIgnoreClientOrder :: Bool
Ignore the client's ciphersuite order. Defaults to False.
serverConfigClientCertVerifier :: Maybe ClientCertVerifier
Optionally, a client cert verifier.

Instances

Instances details

Generic ServerConfigBuilder Source #
Instance details Defined in Rustls.Internal Associated Types type Rep ServerConfigBuilder :: Type -> Type # Methods from :: ServerConfigBuilder -> Rep ServerConfigBuilder x # to :: Rep ServerConfigBuilder x -> ServerConfigBuilder #
Show ServerConfigBuilder Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> ServerConfigBuilder -> ShowS # show :: ServerConfigBuilder -> String # showList :: [ServerConfigBuilder] -> ShowS #
type Rep ServerConfigBuilder Source #
Instance details Defined in Rustls.Internal type Rep ServerConfigBuilder = D1 ('MetaData "ServerConfigBuilder" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "ServerConfigBuilder" 'PrefixI 'True) ((S1 ('MetaSel ('Just "serverConfigCertifiedKeys") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (NonEmpty CertifiedKey)) :: (S1 ('MetaSel ('Just "serverConfigTLSVersions") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [TLSVersion]) :: S1 ('MetaSel ('Just "serverConfigCipherSuites") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [CipherSuite]))) :: (S1 ('MetaSel ('Just "serverConfigALPNProtocols") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [ALPNProtocol]) :: (S1 ('MetaSel ('Just "serverConfigIgnoreClientOrder") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Bool) :*: S1 ('MetaSel ('Just "serverConfigClientCertVerifier") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe ClientCertVerifier))))))

defaultServerConfigBuilder :: NonEmpty CertifiedKey -> ServerConfigBuilder Source #

A ServerConfigBuilder with good defaults.

data ClientCertVerifier Source #

How to verify TLS client certificates.

Constructors

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.

Instances

Instances details

Generic ClientCertVerifier Source #
Instance details Defined in Rustls.Internal Associated Types type Rep ClientCertVerifier :: Type -> Type # Methods from :: ClientCertVerifier -> Rep ClientCertVerifier x # to :: Rep ClientCertVerifier x -> ClientCertVerifier #
Show ClientCertVerifier Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> ClientCertVerifier -> ShowS # show :: ClientCertVerifier -> String # showList :: [ClientCertVerifier] -> ShowS #
type Rep ClientCertVerifier Source #
Instance details Defined in Rustls.Internal type Rep ClientCertVerifier = D1 ('MetaData "ClientCertVerifier" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "ClientCertVerifier" 'PrefixI 'True) (S1 ('MetaSel ('Just "clientCertVerifierPolicy") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 ClientCertVerifierPolicy) :: (S1 ('MetaSel ('Just "clientCertVerifierCertificates") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (NonEmpty PEMCertificates)) :: S1 ('MetaSel ('Just "clientCertVerifierCRLs") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [CertificateRevocationList]))))

data ClientCertVerifierPolicy Source #

Which client connections are allowed by a ClientCertVerifier.

Constructors

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.

Instances

Instances details

Bounded ClientCertVerifierPolicy Source #
Instance details Defined in Rustls.Internal Methods minBound :: ClientCertVerifierPolicy # maxBound :: ClientCertVerifierPolicy #
Enum ClientCertVerifierPolicy Source #
Instance details Defined in Rustls.Internal Methods succ :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy # pred :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy # toEnum :: Int -> ClientCertVerifierPolicy # fromEnum :: ClientCertVerifierPolicy -> Int # enumFrom :: ClientCertVerifierPolicy -> [ClientCertVerifierPolicy] # enumFromThen :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> [ClientCertVerifierPolicy] # enumFromTo :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> [ClientCertVerifierPolicy] # enumFromThenTo :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> [ClientCertVerifierPolicy] #
Generic ClientCertVerifierPolicy Source #
Instance details Defined in Rustls.Internal Associated Types type Rep ClientCertVerifierPolicy :: Type -> Type # Methods from :: ClientCertVerifierPolicy -> Rep ClientCertVerifierPolicy x # to :: Rep ClientCertVerifierPolicy x -> ClientCertVerifierPolicy #
Show ClientCertVerifierPolicy Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> ClientCertVerifierPolicy -> ShowS # show :: ClientCertVerifierPolicy -> String # showList :: [ClientCertVerifierPolicy] -> ShowS #
Eq ClientCertVerifierPolicy Source #
Instance details Defined in Rustls.Internal Methods (==) :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> Bool # (/=) :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> Bool #
Ord ClientCertVerifierPolicy Source #
Instance details Defined in Rustls.Internal Methods compare :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> Ordering # (<) :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> Bool # (<=) :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> Bool # (>) :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> Bool # (>=) :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> Bool # max :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> ClientCertVerifierPolicy # min :: ClientCertVerifierPolicy -> ClientCertVerifierPolicy -> ClientCertVerifierPolicy #
type Rep ClientCertVerifierPolicy Source #
Instance details Defined in Rustls.Internal type Rep ClientCertVerifierPolicy = D1 ('MetaData "ClientCertVerifierPolicy" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "AllowAnyAuthenticatedClient" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "AllowAnyAnonymousOrAuthenticatedClient" 'PrefixI 'False) (U1 :: Type -> Type))

Config

data ServerConfig Source #

Assembled configuration for a Rustls server connection.

serverConfigLogCallback :: ServerConfig -> Maybe LogCallback Source #

A logging callback.

Note that this is a record selector, so you can use it as a setter:

>>> :{
setLogCallback :: LogCallback -> ServerConfig -> ServerConfig
setLogCallback logCallback serverConfig =
  serverConfig { serverConfigLogCallback = Just logCallback }
:}

buildServerConfig :: MonadIO m => ServerConfigBuilder -> m ServerConfig Source #

Build a ServerConfigBuilder into a ServerConfig.

This is a relatively expensive operation, so it is a good idea to share one ServerConfig when creating multiple Connections.

Open a connection

newServerConnection :: Backend -> ServerConfig -> Acquire (Connection Server) Source #

Initialize a TLS connection as a server.

Connection

data Connection (side :: Side) Source #

A Rustls connection.

data Side Source #

Type-level indicator whether a Connection is client- or server-side.

Constructors

Client
Server

Read and write

readBS Source #

Arguments

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

Read data from the Rustls Connection into a ByteString. The result will not be longer than the given length.

writeBS :: MonadIO m => Connection side -> ByteString -> m () Source #

Write a ByteString to the Rustls Connection.

Handshaking

handshake :: MonadIO m => Connection side -> HandshakeQuery side a -> m a Source #

Ensure that the connection is handshaked. It is only necessary to call this if you want to obtain connection information. You can do so by providing a HandshakeQuery.

>>> :{
getALPNAndTLSVersion ::
  MonadIO m =>
  Connection side ->
  m (Maybe ALPNProtocol, TLSVersion)
getALPNAndTLSVersion conn =
  handshake conn $ (,) <$> getALPNProtocol <*> getTLSVersion
:}

data HandshakeQuery (side :: Side) a Source #

A Monad to get TLS connection information via handshake.

Instances

Instances details

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 #

getALPNProtocol :: HandshakeQuery side (Maybe ALPNProtocol) Source #

Get the negotiated ALPN protocol, if any.

getTLSVersion :: HandshakeQuery side TLSVersion Source #

Get the negotiated TLS protocol version.

getCipherSuite :: HandshakeQuery side CipherSuite Source #

Get the negotiated cipher suite.

getSNIHostname :: HandshakeQuery Server (Maybe Text) Source #

Get the SNI hostname set by the client, if any.

getPeerCertificate :: CSize -> HandshakeQuery side (Maybe DERCertificate) Source #

Get the i-th certificate provided by the peer.

Index 0 is the end entity certificate. Higher indices are certificates in the chain. Requesting an index higher than what is available returns Nothing.

Closing

sendCloseNotify :: MonadIO m => Connection side -> m () Source #

Send a close_notify warning alert. This informs the peer that the connection is being closed.

Logging

data LogCallback Source #

A Rustls connection logging callback.

newLogCallback :: (LogLevel -> Text -> IO ()) -> Acquire LogCallback Source #

Allocate a new logging callback, taking a LogLevel and a message.

If it throws an exception, it will be wrapped in a RustlsLogException and passed to reportError.

🚫 Make sure that its lifetime encloses those of the Connections which you configured to use it.

data LogLevel Source #

Rustls log level.

Constructors

LogLevelError
LogLevelWarn
LogLevelInfo
LogLevelDebug
LogLevelTrace

Instances

Instances details

Bounded LogLevel Source #
Instance details Defined in Rustls.Internal Methods minBound :: LogLevel # maxBound :: LogLevel #
Enum LogLevel Source #
Instance details Defined in Rustls.Internal Methods succ :: LogLevel -> LogLevel # pred :: LogLevel -> LogLevel # toEnum :: Int -> LogLevel # fromEnum :: LogLevel -> Int # enumFrom :: LogLevel -> [LogLevel] # enumFromThen :: LogLevel -> LogLevel -> [LogLevel] # enumFromTo :: LogLevel -> LogLevel -> [LogLevel] # enumFromThenTo :: LogLevel -> LogLevel -> LogLevel -> [LogLevel] #
Generic LogLevel Source #
Instance details Defined in Rustls.Internal Associated Types type Rep LogLevel :: Type -> Type # Methods from :: LogLevel -> Rep LogLevel x # to :: Rep LogLevel x -> LogLevel #
Show LogLevel Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> LogLevel -> ShowS # show :: LogLevel -> String # showList :: [LogLevel] -> ShowS #
Eq LogLevel Source #
Instance details Defined in Rustls.Internal Methods (==) :: LogLevel -> LogLevel -> Bool # (/=) :: LogLevel -> LogLevel -> Bool #
Ord LogLevel Source #
Instance details Defined in Rustls.Internal Methods compare :: LogLevel -> LogLevel -> Ordering # (<) :: LogLevel -> LogLevel -> Bool # (<=) :: LogLevel -> LogLevel -> Bool # (>) :: LogLevel -> LogLevel -> Bool # (>=) :: LogLevel -> LogLevel -> Bool # max :: LogLevel -> LogLevel -> LogLevel # min :: LogLevel -> LogLevel -> LogLevel #
type Rep LogLevel Source #
Instance details Defined in Rustls.Internal type Rep LogLevel = D1 ('MetaData "LogLevel" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) ((C1 ('MetaCons "LogLevelError" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "LogLevelWarn" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "LogLevelInfo" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "LogLevelDebug" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "LogLevelTrace" 'PrefixI 'False) (U1 :: Type -> Type))))

Raw `Ptr`-based API

readPtr :: MonadIO m => Connection side -> Ptr Word8 -> CSize -> m CSize Source #

Read data from the Rustls Connection into the given buffer.

writePtr :: MonadIO m => Connection side -> Ptr Word8 -> CSize -> m CSize Source #

Write data to the Rustls Connection from the given buffer.

Misc

version :: Text Source #

Combined version string of Rustls and rustls-ffi.

>>> version
"rustls-ffi/0.13.0/rustls/0.23.4"

Backend

data Backend Source #

Underlying data source for Rustls.

Constructors

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.

mkSocketBackend :: Socket -> Backend Source #

mkByteStringBackend Source #

Arguments

:: (Int -> IO ByteString)

Read a ByteString with the given max length.

This will silently truncate ByteStrings which are too long.

-> (ByteString -> IO ())

Write a ByteString.

-> Backend

An in-memory Backend.

Types

newtype ALPNProtocol Source #

An ALPN protocol ID. See https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids for a list of registered IDs.

Constructors

ALPNProtocol
Fields unALPNProtocol :: ByteString

Instances

Instances details

Generic ALPNProtocol Source #
Instance details Defined in Rustls.Internal Associated Types type Rep ALPNProtocol :: Type -> Type # Methods from :: ALPNProtocol -> Rep ALPNProtocol x # to :: Rep ALPNProtocol x -> ALPNProtocol #
Show ALPNProtocol Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> ALPNProtocol -> ShowS # show :: ALPNProtocol -> String # showList :: [ALPNProtocol] -> ShowS #
Eq ALPNProtocol Source #
Instance details Defined in Rustls.Internal Methods (==) :: ALPNProtocol -> ALPNProtocol -> Bool # (/=) :: ALPNProtocol -> ALPNProtocol -> Bool #
Ord ALPNProtocol Source #
Instance details Defined in Rustls.Internal Methods compare :: ALPNProtocol -> ALPNProtocol -> Ordering # (<) :: ALPNProtocol -> ALPNProtocol -> Bool # (<=) :: ALPNProtocol -> ALPNProtocol -> Bool # (>) :: ALPNProtocol -> ALPNProtocol -> Bool # (>=) :: ALPNProtocol -> ALPNProtocol -> Bool # max :: ALPNProtocol -> ALPNProtocol -> ALPNProtocol # min :: ALPNProtocol -> ALPNProtocol -> ALPNProtocol #
type Rep ALPNProtocol Source #
Instance details Defined in Rustls.Internal type Rep ALPNProtocol = D1 ('MetaData "ALPNProtocol" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'True) (C1 ('MetaCons "ALPNProtocol" 'PrefixI 'True) (S1 ('MetaSel ('Just "unALPNProtocol") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

data PEMCertificates Source #

A source of PEM-encoded certificates.

Constructors

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

Instances

Instances details

Generic PEMCertificates Source #
Instance details Defined in Rustls.Internal Associated Types type Rep PEMCertificates :: Type -> Type # Methods from :: PEMCertificates -> Rep PEMCertificates x # to :: Rep PEMCertificates x -> PEMCertificates #
Show PEMCertificates Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> PEMCertificates -> ShowS # show :: PEMCertificates -> String # showList :: [PEMCertificates] -> ShowS #
type Rep PEMCertificates Source #
Instance details Defined in Rustls.Internal type Rep PEMCertificates = D1 ('MetaData "PEMCertificates" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "PEMCertificatesInMemory" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 ByteString) :: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 PEMCertificateParsing)) :+: C1 ('MetaCons "PemCertificatesFromFile" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 FilePath) :: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 PEMCertificateParsing)))

data PEMCertificateParsing Source #

Parsing mode for PEM-encoded certificates.

Constructors

PEMCertificateParsingStrict

Fail if syntactically invalid.

PEMCertificateParsingLax

Ignore if syntactically invalid.

This may be useful on systems that have syntactically invalid root certificates.

Instances

Instances details

Bounded PEMCertificateParsing Source #
Instance details Defined in Rustls.Internal Methods minBound :: PEMCertificateParsing # maxBound :: PEMCertificateParsing #
Enum PEMCertificateParsing Source #
Instance details Defined in Rustls.Internal Methods succ :: PEMCertificateParsing -> PEMCertificateParsing # pred :: PEMCertificateParsing -> PEMCertificateParsing # toEnum :: Int -> PEMCertificateParsing # fromEnum :: PEMCertificateParsing -> Int # enumFrom :: PEMCertificateParsing -> [PEMCertificateParsing] # enumFromThen :: PEMCertificateParsing -> PEMCertificateParsing -> [PEMCertificateParsing] # enumFromTo :: PEMCertificateParsing -> PEMCertificateParsing -> [PEMCertificateParsing] # enumFromThenTo :: PEMCertificateParsing -> PEMCertificateParsing -> PEMCertificateParsing -> [PEMCertificateParsing] #
Generic PEMCertificateParsing Source #
Instance details Defined in Rustls.Internal Associated Types type Rep PEMCertificateParsing :: Type -> Type # Methods from :: PEMCertificateParsing -> Rep PEMCertificateParsing x # to :: Rep PEMCertificateParsing x -> PEMCertificateParsing #
Show PEMCertificateParsing Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> PEMCertificateParsing -> ShowS # show :: PEMCertificateParsing -> String # showList :: [PEMCertificateParsing] -> ShowS #
Eq PEMCertificateParsing Source #
Instance details Defined in Rustls.Internal Methods (==) :: PEMCertificateParsing -> PEMCertificateParsing -> Bool # (/=) :: PEMCertificateParsing -> PEMCertificateParsing -> Bool #
Ord PEMCertificateParsing Source #
Instance details Defined in Rustls.Internal Methods compare :: PEMCertificateParsing -> PEMCertificateParsing -> Ordering # (<) :: PEMCertificateParsing -> PEMCertificateParsing -> Bool # (<=) :: PEMCertificateParsing -> PEMCertificateParsing -> Bool # (>) :: PEMCertificateParsing -> PEMCertificateParsing -> Bool # (>=) :: PEMCertificateParsing -> PEMCertificateParsing -> Bool # max :: PEMCertificateParsing -> PEMCertificateParsing -> PEMCertificateParsing # min :: PEMCertificateParsing -> PEMCertificateParsing -> PEMCertificateParsing #
type Rep PEMCertificateParsing Source #
Instance details Defined in Rustls.Internal type Rep PEMCertificateParsing = D1 ('MetaData "PEMCertificateParsing" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "PEMCertificateParsingStrict" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "PEMCertificateParsingLax" 'PrefixI 'False) (U1 :: Type -> Type))

data CertifiedKey Source #

A complete chain of certificates plus a private key for the leaf certificate.

Constructors

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

Instances

Instances details

Generic CertifiedKey Source #
Instance details Defined in Rustls.Internal Associated Types type Rep CertifiedKey :: Type -> Type # Methods from :: CertifiedKey -> Rep CertifiedKey x # to :: Rep CertifiedKey x -> CertifiedKey #
Show CertifiedKey Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> CertifiedKey -> ShowS # show :: CertifiedKey -> String # showList :: [CertifiedKey] -> ShowS #
type Rep CertifiedKey Source #
Instance details Defined in Rustls.Internal type Rep CertifiedKey = D1 ('MetaData "CertifiedKey" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'False) (C1 ('MetaCons "CertifiedKey" 'PrefixI 'True) (S1 ('MetaSel ('Just "certificateChain") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 ByteString) :*: S1 ('MetaSel ('Just "privateKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 ByteString)))

newtype DERCertificate Source #

A DER-encoded certificate.

Constructors

DERCertificate
Fields unDERCertificate :: ByteString

Instances

Instances details

Generic DERCertificate Source #
Instance details Defined in Rustls Associated Types type Rep DERCertificate :: Type -> Type # Methods from :: DERCertificate -> Rep DERCertificate x # to :: Rep DERCertificate x -> DERCertificate #
Show DERCertificate Source #
Instance details Defined in Rustls Methods showsPrec :: Int -> DERCertificate -> ShowS # show :: DERCertificate -> String # showList :: [DERCertificate] -> ShowS #
Eq DERCertificate Source #
Instance details Defined in Rustls Methods (==) :: DERCertificate -> DERCertificate -> Bool # (/=) :: DERCertificate -> DERCertificate -> Bool #
Ord DERCertificate Source #
Instance details Defined in Rustls Methods compare :: DERCertificate -> DERCertificate -> Ordering # (<) :: DERCertificate -> DERCertificate -> Bool # (<=) :: DERCertificate -> DERCertificate -> Bool # (>) :: DERCertificate -> DERCertificate -> Bool # (>=) :: DERCertificate -> DERCertificate -> Bool # max :: DERCertificate -> DERCertificate -> DERCertificate # min :: DERCertificate -> DERCertificate -> DERCertificate #
type Rep DERCertificate Source #
Instance details Defined in Rustls type Rep DERCertificate = D1 ('MetaData "DERCertificate" "Rustls" "rustls-0.1.0.0-inplace" 'True) (C1 ('MetaCons "DERCertificate" 'PrefixI 'True) (S1 ('MetaSel ('Just "unDERCertificate") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

newtype CertificateRevocationList Source #

One or more PEM-encoded certificate revocation lists (CRL).

Constructors

CertificateRevocationList
Fields unCertificateRevocationList :: ByteString

Instances

Instances details

Generic CertificateRevocationList Source #
Instance details Defined in Rustls.Internal Associated Types type Rep CertificateRevocationList :: Type -> Type # Methods from :: CertificateRevocationList -> Rep CertificateRevocationList x # to :: Rep CertificateRevocationList x -> CertificateRevocationList #
Show CertificateRevocationList Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> CertificateRevocationList -> ShowS # show :: CertificateRevocationList -> String # showList :: [CertificateRevocationList] -> ShowS #
type Rep CertificateRevocationList Source #
Instance details Defined in Rustls.Internal type Rep CertificateRevocationList = D1 ('MetaData "CertificateRevocationList" "Rustls.Internal" "rustls-0.1.0.0-inplace" 'True) (C1 ('MetaCons "CertificateRevocationList" 'PrefixI 'True) (S1 ('MetaSel ('Just "unCertificateRevocationList") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

data TLSVersion where Source #

A TLS protocol version supported by Rustls.

Bundled Patterns

pattern TLS12 :: TLSVersion
pattern TLS13 :: TLSVersion

Instances

Instances details

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 #

defaultTLSVersions :: NonEmpty TLSVersion Source #

The default TLSVersions used by Rustls. A subset of allTLSVersions.

allTLSVersions :: NonEmpty TLSVersion Source #

All TLSVersions supported by Rustls.

data CipherSuite Source #

A TLS cipher suite supported by Rustls.

Instances

Instances details

Show CipherSuite Source #
Instance details Defined in Rustls.Internal Methods showsPrec :: Int -> CipherSuite -> ShowS # show :: CipherSuite -> String # showList :: [CipherSuite] -> ShowS #
Eq CipherSuite Source #
Instance details Defined in Rustls.Internal Methods (==) :: CipherSuite -> CipherSuite -> Bool # (/=) :: CipherSuite -> CipherSuite -> Bool #
Ord CipherSuite Source #
Instance details Defined in Rustls.Internal Methods compare :: CipherSuite -> CipherSuite -> Ordering # (<) :: CipherSuite -> CipherSuite -> Bool # (<=) :: CipherSuite -> CipherSuite -> Bool # (>) :: CipherSuite -> CipherSuite -> Bool # (>=) :: CipherSuite -> CipherSuite -> Bool # max :: CipherSuite -> CipherSuite -> CipherSuite # min :: CipherSuite -> CipherSuite -> CipherSuite #

cipherSuiteID :: CipherSuite -> Word16 Source #

Get the IANA value from a 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.

showCipherSuite :: CipherSuite -> Text Source #

Get the text representation of a cipher suite.

defaultCipherSuites :: NonEmpty CipherSuite Source #

The default CipherSuites used by Rustls. A subset of allCipherSuites.

allCipherSuites :: NonEmpty CipherSuite Source #

All CipherSuites supported by Rustls.

Exceptions

data RustlsException Source #

TLS exception thrown by Rustls.

Use displayException for a human-friendly representation.

Instances

Instances details

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

isCertError :: RustlsException -> Bool Source #

Checks if the given RustlsException represents a certificate error.

newtype RustlsLogException Source #

Wrapper for exceptions thrown in a LogCallback.

Constructors

RustlsLogException SomeException

Instances

Instances details

Exception RustlsLogException Source #
Instance details Defined in Rustls.Internal Methods toException :: RustlsLogException -> SomeException # fromException :: SomeException -> Maybe RustlsLogException # displayException :: RustlsLogException -> String #
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

Types

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Exceptions

Instances

Instances

Using `Acquire`

Raw `Ptr`-based API