tls-1.6.0: TLS/SSL protocol native implementation (Server and Client)

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | experimental
Portability | unknown
Safe Haskell | Safe-Inferred
Language | Haskell2010

Network.TLS.QUIC

Contents

- Handshakers
- Callback
- Secrets
- Negotiated parameters
- Extensions
- Errors
- Hash
- Constants
- Supported

Description

Experimental API to run the TLS handshake establishing a QUIC connection.

On the northbound API:

- QUIC starts a TLS client or server thread with `tlsQUICClient` or `tlsQUICServer`.

TLS invokes QUIC callbacks to use the QUIC transport

- TLS uses `quicSend` and `quicRecv` to send and receive handshake message fragments.
- TLS calls `quicInstallKeys` to provide to QUIC the traffic secrets it should use for encryption/decryption.
- TLS calls `quicNotifyExtensions` to notify to QUIC the transport parameters exchanged through the handshake protocol.
- TLS calls `quicDone` when the handshake is done.

Synopsis

- tlsQUICClient :: ClientParams -> QUICCallbacks -> IO ()
- tlsQUICServer :: ServerParams -> QUICCallbacks -> IO ()
- data QUICCallbacks = QUICCallbacks {
  - quicSend :: [(CryptLevel, ByteString)] -> IO ()
  - quicRecv :: CryptLevel -> IO (Either TLSError ByteString)
  - quicInstallKeys :: Context -> KeyScheduleEvent -> IO ()
  - quicNotifyExtensions :: Context -> [ExtensionRaw] -> IO ()
  - quicDone :: Context -> IO ()
  }
- data CryptLevel
  - = CryptInitial
  - | CryptMasterSecret
  - | CryptEarlySecret
  - | CryptHandshakeSecret
  - | CryptApplicationSecret
- data KeyScheduleEvent
  - = InstallEarlyKeys (Maybe EarlySecretInfo)
  - | InstallHandshakeKeys HandshakeSecretInfo
  - | InstallApplicationKeys ApplicationSecretInfo
- data EarlySecretInfo = EarlySecretInfo Cipher (ClientTrafficSecret EarlySecret)
- data HandshakeSecretInfo = HandshakeSecretInfo Cipher (TrafficSecrets HandshakeSecret)
- newtype ApplicationSecretInfo = ApplicationSecretInfo (TrafficSecrets ApplicationSecret)
- data EarlySecret
- data HandshakeSecret
- data ApplicationSecret
- type TrafficSecrets a = (ClientTrafficSecret a, ServerTrafficSecret a)
- newtype ServerTrafficSecret a = ServerTrafficSecret ByteString
- newtype ClientTrafficSecret a = ClientTrafficSecret ByteString
- type NegotiatedProtocol = ByteString
- data HandshakeMode13
  - = FullHandshake
  - | HelloRetryRequest
  - | PreSharedKey
  - | RTT0
- data ExtensionRaw = ExtensionRaw ExtensionID ByteString
- type ExtensionID = Word16
- extensionID_QuicTransportParameters :: ExtensionID
- errorTLS :: String -> IO a
- errorToAlertDescription :: TLSError -> AlertDescription
- errorToAlertMessage :: TLSError -> String
- fromAlertDescription :: AlertDescription -> Word8
- toAlertDescription :: Word8 -> Maybe AlertDescription
- hkdfExpandLabel :: Hash -> ByteString -> ByteString -> ByteString -> Int -> ByteString
- hkdfExtract :: Hash -> ByteString -> ByteString -> ByteString
- hashDigestSize :: Hash -> Int
- quicMaxEarlyDataSize :: Int
- defaultSupported :: Supported

# Handshakers

tlsQUICClient :: ClientParams -> QUICCallbacks -> IO () Source #

Start a TLS handshake thread for a QUIC client. The client will use the specified TLS parameters and call the provided callback functions to send and receive handshake data.

tlsQUICServer :: ServerParams -> QUICCallbacks -> IO () Source #

Start a TLS handshake thread for a QUIC server. The server will use the specified TLS parameters and call the provided callback functions to send and receive handshake data.

# Callback

data QUICCallbacks Source #

Callbacks implemented by QUIC and to be called by TLS at specific points during the handshake. TLS may invoke them from external threads but calls are not concurrent. Only a single callback function is called at a given point in time.

Constructors

QUICCallbacks |

Fields

- quicSend :: [(CryptLevel, ByteString)] -> IO ()

  Called by TLS so that QUIC sends one or more handshake fragments. The content transiting on this API is the plaintext of the fragments and QUIC responsability is to encrypt this payload with the key material given for the specified level and an appropriate encryption scheme.

  The size of the fragments may exceed QUIC datagram limits so QUIC may break them into smaller fragments.

  The handshake protocol sometimes combines content at two levels in a single flight. The TLS library does its best to provide this in the same `quicSend` call and with a multi-valued argument. QUIC can then decide how to transmit this optimally.

- quicRecv :: CryptLevel -> IO (Either TLSError ByteString)

  Called by TLS to receive from QUIC the next plaintext handshake fragment. The argument specifies with which encryption level the fragment should be decrypted.

  QUIC may return partial fragments to TLS. TLS will then call `quicRecv` again as long as necessary. Note however that fragments must be returned in the correct sequence, i.e. the order the TLS peer emitted them.

  The function may return an error to TLS if end of stream is reached or if a protocol error has been received, believing the handshake cannot proceed any longer. If the TLS handshake protocol cannot recover from this error, the failure condition will be reported back to QUIC through the control interface.

- quicInstallKeys :: Context -> KeyScheduleEvent -> IO ()

  Called by TLS when new encryption material is ready to be used in the handshake. The next `quicSend` or `quicRecv` may now use the associated encryption level (although the previous level is also possible: directions Send/Recv do not change at the same time).

- quicNotifyExtensions :: Context -> [ExtensionRaw] -> IO ()

  Called by TLS when QUIC-specific extensions have been received from the peer.

- quicDone :: Context -> IO ()

  Called when `handshake` is done. `tlsQUICServer` is finished after calling this hook. `tlsQUICClient` calls `recvData` after calling this hook to wait for new session tickets.

data CryptLevel Source #

TLS encryption level.

Constructors

CryptInitial | Unprotected traffic
CryptMasterSecret | Protected with master secret (TLS < 1.3)
CryptEarlySecret | Protected with early traffic secret (TLS 1.3)
CryptHandshakeSecret | Protected with handshake traffic secret (TLS 1.3)
CryptApplicationSecret | Protected with application traffic secret (TLS 1.3)

#### Instances

Instances details

Show CryptLevel Source # |
Instance details Defined in Network.TLS.Record.State Methods showsPrec :: Int -> CryptLevel -> ShowS Source # show :: CryptLevel -> String Source # showList :: [CryptLevel] -> ShowS Source #
Eq CryptLevel Source # |
Instance details Defined in Network.TLS.Record.State Methods (==) :: CryptLevel -> CryptLevel -> Bool Source # (/=) :: CryptLevel -> CryptLevel -> Bool Source #

data KeyScheduleEvent Source #

Argument given to `quicInstallKeys` when encryption material is available.

Constructors

InstallEarlyKeys (Maybe EarlySecretInfo) | Key material and parameters for traffic at 0-RTT level
InstallHandshakeKeys HandshakeSecretInfo | Key material and parameters for traffic at handshake level
InstallApplicationKeys ApplicationSecretInfo | Key material and parameters for traffic at application level

# Secrets

data EarlySecretInfo Source #

Handshake information generated for traffic at 0-RTT level.

Constructors

EarlySecretInfo Cipher (ClientTrafficSecret EarlySecret) |

#### Instances

Instances details

Show EarlySecretInfo Source # |
Instance details Defined in Network.TLS.Handshake.Control Methods showsPrec :: Int -> EarlySecretInfo -> ShowS Source # show :: EarlySecretInfo -> String Source # showList :: [EarlySecretInfo] -> ShowS Source #

data HandshakeSecretInfo Source #

Handshake information generated for traffic at handshake level.

Constructors

HandshakeSecretInfo Cipher (TrafficSecrets HandshakeSecret) |

#### Instances

Instances details

Show HandshakeSecretInfo Source # |
Instance details Defined in Network.TLS.Handshake.Control Methods showsPrec :: Int -> HandshakeSecretInfo -> ShowS Source # show :: HandshakeSecretInfo -> String Source # showList :: [HandshakeSecretInfo] -> ShowS Source #

newtype ApplicationSecretInfo Source #

Handshake information generated for traffic at application level.

Constructors

ApplicationSecretInfo (TrafficSecrets ApplicationSecret) |

#### Instances

Instances details

Show ApplicationSecretInfo Source # |
Instance details Defined in Network.TLS.Handshake.Control Methods showsPrec :: Int -> ApplicationSecretInfo -> ShowS Source # show :: ApplicationSecretInfo -> String Source # showList :: [ApplicationSecretInfo] -> ShowS Source #

data EarlySecret Source #

Phantom type indicating early traffic secret.

data HandshakeSecret Source #

Phantom type indicating handshake traffic secrets.

data ApplicationSecret Source #

Phantom type indicating application traffic secrets.

type TrafficSecrets a = (ClientTrafficSecret a, ServerTrafficSecret a) Source #

Hold both client and server traffic secrets at the same step.

newtype ServerTrafficSecret a Source #

A server traffic secret, typed with a parameter indicating a step in the TLS key schedule.

Constructors

ServerTrafficSecret ByteString |

#### Instances

Instances details

Show (ServerTrafficSecret a) Source # |
Instance details Defined in Network.TLS.Types Methods showsPrec :: Int -> ServerTrafficSecret a -> ShowS Source # show :: ServerTrafficSecret a -> String Source # showList :: [ServerTrafficSecret a] -> ShowS Source #

newtype ClientTrafficSecret a Source #

A client traffic secret, typed with a parameter indicating a step in the TLS key schedule.

Constructors

ClientTrafficSecret ByteString |

#### Instances

Instances details

Show (ClientTrafficSecret a) Source # |
Instance details Defined in Network.TLS.Types Methods showsPrec :: Int -> ClientTrafficSecret a -> ShowS Source # show :: ClientTrafficSecret a -> String Source # showList :: [ClientTrafficSecret a] -> ShowS Source #

# Negotiated parameters

type NegotiatedProtocol = ByteString Source #

ID of the application-level protocol negotiated between client and server. See values listed in the IANA registry.

data HandshakeMode13 Source #

Type to show which handshake mode is used in TLS 1.3.

Constructors

FullHandshake | Full handshake is used.
HelloRetryRequest | Full handshake is used with hello retry request.
PreSharedKey | Server authentication is skipped.
RTT0 | Server authentication is skipped and early data is sent.

#### Instances

Instances details

Show HandshakeMode13 Source # |
Instance details Defined in Network.TLS.Handshake.State Methods showsPrec :: Int -> HandshakeMode13 -> ShowS Source # show :: HandshakeMode13 -> String Source # showList :: [HandshakeMode13] -> ShowS Source #
Eq HandshakeMode13 Source # |
Instance details Defined in Network.TLS.Handshake.State Methods (==) :: HandshakeMode13 -> HandshakeMode13 -> Bool Source # (/=) :: HandshakeMode13 -> HandshakeMode13 -> Bool Source #

# Extensions

data ExtensionRaw Source #

The raw content of a TLS extension.

Constructors

ExtensionRaw ExtensionID ByteString |

#### Instances

Instances details

Show ExtensionRaw Source # |
Instance details Defined in Network.TLS.Struct Methods showsPrec :: Int -> ExtensionRaw -> ShowS Source # show :: ExtensionRaw -> String Source # showList :: [ExtensionRaw] -> ShowS Source #
Eq ExtensionRaw Source # |
Instance details Defined in Network.TLS.Struct Methods (==) :: ExtensionRaw -> ExtensionRaw -> Bool Source # (/=) :: ExtensionRaw -> ExtensionRaw -> Bool Source #

type ExtensionID = Word16 Source #

Identifier of a TLS extension.

extensionID_QuicTransportParameters :: ExtensionID Source #

# Errors

errorTLS :: String -> IO a Source #

Can be used by callbacks to signal an unexpected condition. This will then generate an "internal_error" alert in the TLS stack.

errorToAlertDescription :: TLSError -> AlertDescription Source #

Return the alert that a TLS endpoint would send to the peer for the specified library error.

errorToAlertMessage :: TLSError -> String Source #

Return the message that a TLS endpoint can add to its local log for the specified library error.

fromAlertDescription :: AlertDescription -> Word8 Source #

Encode an alert to the assigned value.

toAlertDescription :: Word8 -> Maybe AlertDescription Source #

Decode an alert from the assigned value.

# Hash

hkdfExpandLabel :: Hash -> ByteString -> ByteString -> ByteString -> Int -> ByteString Source #

`HKDF-Expand-Label` function. Returns output keying material of the specified length from the PRK, customized for a TLS label and context.

hkdfExtract :: Hash -> ByteString -> ByteString -> ByteString Source #

`HKDF-Extract` function. Returns the pseudorandom key (PRK) from salt and input keying material (IKM).

hashDigestSize :: Hash -> Int Source #

Digest size in bytes.

# Constants

quicMaxEarlyDataSize :: Int Source #

Max early data size for QUIC.

# Supported

defaultSupported :: Supported Source #