Safe Haskell | Safe-Inferred |
---|---|
Language | GHC2021 |
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 {}
- defaultClientConfigBuilder :: ServerCertVerifier -> ClientConfigBuilder
- data ServerCertVerifier = ServerCertVerifier {}
- data ClientConfig
- clientConfigLogCallback :: ClientConfig -> Maybe LogCallback
- buildClientConfig :: MonadIO m => ClientConfigBuilder -> m ClientConfig
- newClientConnection :: Backend -> ClientConfig -> Text -> Acquire (Connection Client)
- data ServerConfigBuilder = ServerConfigBuilder {}
- defaultServerConfigBuilder :: NonEmpty CertifiedKey -> ServerConfigBuilder
- data ClientCertVerifier = ClientCertVerifier {}
- data ClientCertVerifierPolicy
- data ServerConfig
- serverConfigLogCallback :: ServerConfig -> Maybe LogCallback
- buildServerConfig :: MonadIO m => ServerConfigBuilder -> m ServerConfig
- newServerConnection :: Backend -> ServerConfig -> Acquire (Connection Server)
- data Connection (side :: Side)
- data Side
- 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
- 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 {}
- mkSocketBackend :: Socket -> Backend
- mkByteStringBackend :: (Int -> IO ByteString) -> (ByteString -> IO ()) -> Backend
- newtype ALPNProtocol = ALPNProtocol {}
- data PEMCertificates
- data PEMCertificateParsing
- data CertifiedKey = CertifiedKey {}
- newtype DERCertificate = DERCertificate {}
- newtype CertificateRevocationList = CertificateRevocationList {}
- 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.
ClientConfigBuilder | |
|
Instances
defaultClientConfigBuilder :: ServerCertVerifier -> ClientConfigBuilder Source #
A ClientConfigBuilder
with good defaults.
data ServerCertVerifier Source #
How to verify TLS server certificates.
ServerCertVerifier | |
|
Instances
Generic ServerCertVerifier Source # | |
Defined in Rustls.Internal type Rep ServerCertVerifier :: Type -> Type # from :: ServerCertVerifier -> Rep ServerCertVerifier x # to :: Rep ServerCertVerifier x -> ServerCertVerifier # | |
Show ServerCertVerifier Source # | |
Defined in Rustls.Internal showsPrec :: Int -> ServerCertVerifier -> ShowS # show :: ServerCertVerifier -> String # showList :: [ServerCertVerifier] -> ShowS # | |
type Rep ServerCertVerifier Source # | |
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 Connection
s.
Open a connection
:: Backend | |
-> ClientConfig | |
-> Text | Hostname. |
-> Acquire (Connection Client) |
Initialize a TLS connection as a client.
Server
Builder
data ServerConfigBuilder Source #
Rustls client config builder.
ServerConfigBuilder | |
|
Instances
defaultServerConfigBuilder :: NonEmpty CertifiedKey -> ServerConfigBuilder Source #
A ServerConfigBuilder
with good defaults.
data ClientCertVerifier Source #
How to verify TLS client certificates.
ClientCertVerifier | |
|
Instances
data ClientCertVerifierPolicy Source #
Which client connections are allowed by a ClientCertVerifier
.
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
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 Connection
s.
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.
Read and write
:: 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 #
Instances
Applicative (HandshakeQuery side) Source # | |
Defined in Rustls.Internal 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 # | |
Defined in Rustls.Internal fmap :: (a -> b) -> HandshakeQuery side a -> HandshakeQuery side b # (<$) :: a -> HandshakeQuery side b -> HandshakeQuery side a # | |
Monad (HandshakeQuery side) Source # | |
Defined in Rustls.Internal (>>=) :: 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 Connection
s which you
configured to use it.
Rustls log level.
Instances
Bounded LogLevel Source # | |
Enum LogLevel Source # | |
Generic LogLevel Source # | |
Show LogLevel Source # | |
Eq LogLevel Source # | |
Ord LogLevel Source # | |
Defined in Rustls.Internal | |
type Rep LogLevel Source # | |
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
Combined version string of Rustls and rustls-ffi.
>>>
version
"rustls-ffi/0.13.0/rustls/0.23.4"
Backend
Underlying data source for Rustls.
mkSocketBackend :: Socket -> Backend Source #
:: (Int -> IO ByteString) | Read a This will silently truncate |
-> (ByteString -> IO ()) | Write a |
-> 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.
Instances
data PEMCertificates Source #
A source of PEM-encoded certificates.
PEMCertificatesInMemory ByteString PEMCertificateParsing | In-memory PEM-encoded certificates. |
PemCertificatesFromFile FilePath PEMCertificateParsing | Fetch PEM-encoded root certificates from a file. |
Instances
data PEMCertificateParsing Source #
Parsing mode for PEM-encoded certificates.
PEMCertificateParsingStrict | Fail if syntactically invalid. |
PEMCertificateParsingLax | Ignore if syntactically invalid. This may be useful on systems that have syntactically invalid root certificates. |
Instances
data CertifiedKey Source #
A complete chain of certificates plus a private key for the leaf certificate.
CertifiedKey | |
|
Instances
Generic CertifiedKey Source # | |
Defined in Rustls.Internal type Rep CertifiedKey :: Type -> Type # from :: CertifiedKey -> Rep CertifiedKey x # to :: Rep CertifiedKey x -> CertifiedKey # | |
Show CertifiedKey Source # | |
Defined in Rustls.Internal showsPrec :: Int -> CertifiedKey -> ShowS # show :: CertifiedKey -> String # showList :: [CertifiedKey] -> ShowS # | |
type Rep CertifiedKey Source # | |
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.
Instances
newtype CertificateRevocationList Source #
One or more PEM-encoded certificate revocation lists (CRL).
Instances
Generic CertificateRevocationList Source # | |
Defined in Rustls.Internal type Rep CertificateRevocationList :: Type -> Type # | |
Show CertificateRevocationList Source # | |
Defined in Rustls.Internal showsPrec :: Int -> CertificateRevocationList -> ShowS # show :: CertificateRevocationList -> String # showList :: [CertificateRevocationList] -> ShowS # | |
type Rep CertificateRevocationList Source # | |
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.
pattern TLS12 :: TLSVersion | |
pattern TLS13 :: TLSVersion |
Instances
defaultTLSVersions :: NonEmpty TLSVersion Source #
The default TLSVersion
s used by Rustls. A subset of allTLSVersions
.
allTLSVersions :: NonEmpty TLSVersion Source #
All TLSVersion
s supported by Rustls.
data CipherSuite Source #
A TLS cipher suite supported by Rustls.
Instances
Show CipherSuite Source # | |
Defined in Rustls.Internal showsPrec :: Int -> CipherSuite -> ShowS # show :: CipherSuite -> String # showList :: [CipherSuite] -> ShowS # | |
Eq CipherSuite Source # | |
Defined in Rustls.Internal (==) :: CipherSuite -> CipherSuite -> Bool # (/=) :: CipherSuite -> CipherSuite -> Bool # | |
Ord CipherSuite Source # | |
Defined in Rustls.Internal 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 CipherSuite
s used by Rustls. A subset of allCipherSuites
.
allCipherSuites :: NonEmpty CipherSuite Source #
All CipherSuite
s supported by Rustls.
Exceptions
data RustlsException Source #
TLS exception thrown by Rustls.
Use displayException
for a human-friendly representation.
Instances
Exception RustlsException Source # | |
Defined in Rustls.Internal | |
Show RustlsException Source # | |
Defined in Rustls.Internal 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
.
Instances
Exception RustlsLogException Source # | |
Defined in Rustls.Internal | |
Show RustlsLogException Source # | |
Defined in Rustls.Internal showsPrec :: Int -> RustlsLogException -> ShowS # show :: RustlsLogException -> String # showList :: [RustlsLogException] -> ShowS # |