xftp: negotiate protocol with ALPN

rfcs/2024-03-28-xftp-version.md

@@ -0,0 +1,120 @@
+# XFTP version agreement
+
+## Problem
+
+XFTP is using HTTP2 protocol for encoding requests and responses.
+Unlike SMP which has a connection handshake initiated by a server and signals available versions XFTP/HTTP2 is almost entirely client-driven.
+So, a client can only try to guess which protocol versions are supported by a server by sending a probe/hello request first.
+Determining the endpoint for such a request is an implicit version agreement by itself.
+Sending such a request to an old server would error out and requiring it from old clients would break them.
+
+## Solution
+
+The TLS layer used by the XFTP server has an optional [ALPN](https://datatracker.ietf.org/doc/html/rfc7301) extension which allows the client and server to negotiate protocols and store the decision in TLS session context.
+Unless a client and a server run ALPN-aware versions, they would default to the old "unversioned" protocol.
+
+TLS extension content is a 65kb chunk, but ALPN standard breaks it into 254b-sized chunks making it unusable for things like key exchange.
+The exchange is still client-driven: the client proposes a list, and then a server callback picks one.
+In effect, this makes it usable only to signal that some application-level handshake is desired and supported.
+
+## Implementation
+
+ALPN can be used to negotiate for any TLS-based protocol, but the description will focus on XFTP.
+
+TransportClientConfig gets a new `alpn :: Maybe [ALPN]` field so a TLS transport can use it during TLS client creation.
+XFTP client sets it to `Just ["xftp/1"]`.
+The exact value is not important as long it is in agreement with the server side, but ALPN RFC insists on it being an IANA-registered identifier.
+
+XFTP server sets `onALPNClientSuggest` TLS hook to pick the protocol when it is provided.
+The `tls` library treats SHOULD from the RFC as MUST and does a client-side check that the server responded with one of the client-proposed protocols.
+
+Upon connection, transport implementation invokes `getNegotiatedProtocol` and stores it in `tlsALPN :: Maybe ALPN` field of transport context.
+HTTP2 transport implementation using `withHTTP2` passes negotiated "protocol" to client and server setup callbacks where they store it in their respective wrappers along with TLS session ID.
+A server request handler then knows by looking at the `sessionALPN` if it should require a "handshake" request first.
+A client code that got HTTP2Client with `sessionALPN` set knows if it has to proceed with handshake request.
+A handshake request still has to be initiated by a client, so it should be kept minimal, just enough data to pass the initiative to a server.
+A reply to that initial request should contain a server version range for the client to pick.
+A client then commits to a version, sending its part of a handshake.
+
+In the future ALPN negotiation can be dropped in favor of mandatory handshakes or used to signal further handshake schemes.
+
+The XFTP handshake data types and validation code are cloned from SMP.
+Currently they carry version information and session authentication parameters.
+Authentication parameters made mandatory as this exchange is guarded by the handshake version.
+
+### Server side
+
+`runHTTP2Server` callback used by `xftpServer` should get access to the session state to track handshakes.
+A local `TMap SessionId Handshake` is enough to switch request handlers.
+The HTTP2 server framework is extended with a way to signal client disconnection to remove sessions from this map.
+
+The `Handshake` type mimics implicit state in stream based handshakes of SMP and NTF.
+
+```haskell
+data Handshake
+  = HandshakeSent C.PrivateKeyX25519 -- server private key that will be merged with client public in `THandleAuth`
+  | HandshakeAccepted THandleAuth VersionXFTP -- session steady state after handshakes
+```
+
+An HTTP2 request without ALPN is treated as legacy and requires no session entry.
+Its `Request`s are marked with `THandleParams {thVersion = VersionXFTP 1, ..}`.
+
+An HTTP2 request with ALPN requires a session lookup.
+- A lack of entry indicates that a client must send an empty request, to which the server replies with its "server handshake" block and stores its private state in `HandshakeSent`.
+- If the session entry contains `HandshakeSent`, then the only valid request content is the "client handshake" block.
+  The server validates client handshake (in the same way as SMP) and stores authentication and version in `HandshakeAccepted`
+- If the session entry contains `HandshakeAccepted`, then the server just passes it to `THandleParams`.
+
+### Client side
+
+`getXFTPClient` tweaks its transport config to include the ALPN marker and then checks if the client got its `sessionALPN` value.
+If there's a value set, it then sends an initial block and checks out the server handshake in response.
+After validation, it sends "client handshake" request to finish version negotiation.
+
+```haskell
+let tcConfig = (transportClientConfig xftpNetworkConfig) {alpn = Just ["xftp/1"]}
+-- ...
+http2Client <- liftEitherError xftpClientError $ getVerifiedHTTP2Client -- ...
+thVersion <- case sessionALPN http2Client of
+  Nothing -> pure $ VersionXFTP 1
+  Just proto -> negotiate http2Client proto
+```
+
+The resulting `XFTPClient` then contains a negotiated version and can be used to send transmissions with a more recent encoding.
+
+## Block encoding
+
+### Client Hello (request)
+
+A request with an empty body and no padding.
+
+### Server handshake (response)
+
+SMP-encoded and padded to `xftpBlockSize` (~16kb).
+
+```haskell
+data XFTPServerHandshake = XFTPServerHandshake
+  { xftpVersionRange :: VersionRangeXFTP,
+    sessionId :: SessionId, -- validated by client against TLS unique
+    authPubKey ::
+      ( X.CertificateChain, -- fingerprint validated by client against pre-shared hash
+        X.SignedExact X.PubKey -- signature validated by client against server key from TLS
+      )
+  }
+```
+
+### Client handshake (request)
+
+SMP-encoded and padded to `xftpBlockSize` (~16kb).
+
+```haskell
+data XFTPClientHandshake = XFTPClientHandshake
+  { xftpVersion :: VersionXFTP,
+    keyHash :: C.KeyHash, -- validated by server against its own cert fingerprint
+    authPubKey :: C.PublicKeyX25519
+  }
+```
+
+### Server confirmation (response)
+
+A response with an empty body and no padding.

src/Simplex/FileTransfer/Client.hs

@@ -4,11 +4,14 @@
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE PatternSynonyms #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TupleSections #-}
 {-# LANGUAGE TypeApplications #-}
 
 module Simplex.FileTransfer.Client where
 
+import Control.Logger.Simple
 import Control.Monad
 import Control.Monad.Except
 import Crypto.Random (ChaChaDRG)
@@ -20,6 +23,8 @@ import Data.Int (Int64)
 import Data.List.NonEmpty (NonEmpty (..))
 import Data.Time (UTCTime)
 import Data.Word (Word32)
+import qualified Data.X509 as X
+import qualified Data.X509.Validation as XV
 import qualified Network.HTTP.Types as N
 import qualified Network.HTTP2.Client as H
 import Simplex.FileTransfer.Description (mb)
@@ -37,6 +42,7 @@ import Simplex.Messaging.Client
 import Simplex.Messaging.Client.Agent ()
 import qualified Simplex.Messaging.Crypto as C
 import qualified Simplex.Messaging.Crypto.Lazy as LC
+import Simplex.Messaging.Encoding (smpDecode, smpEncode)
 import Simplex.Messaging.Encoding.String
 import Simplex.Messaging.Protocol
   ( BasicAuth,
@@ -45,12 +51,13 @@ import Simplex.Messaging.Protocol
     RecipientId,
     SenderId,
   )
-import Simplex.Messaging.Transport (THandleParams (..), supportedParameters)
-import Simplex.Messaging.Transport.Client (TransportClientConfig, TransportHost)
+import Simplex.Messaging.Transport (HandshakeError (VERSION), THandleAuth (..), THandleParams (..), TransportError (..), supportedParameters)
+import Simplex.Messaging.Transport.Client (TransportClientConfig, TransportHost, alpn)
 import Simplex.Messaging.Transport.HTTP2
 import Simplex.Messaging.Transport.HTTP2.Client
 import Simplex.Messaging.Transport.HTTP2.File
-import Simplex.Messaging.Util (bshow, whenM)
+import Simplex.Messaging.Util (bshow, liftEitherWith, liftError', tshow, whenM)
+import Simplex.Messaging.Version (compatibleVersion, pattern Compatible)
 import UnliftIO
 import UnliftIO.Directory
 
@@ -63,7 +70,8 @@ data XFTPClient = XFTPClient
 
 data XFTPClientConfig = XFTPClientConfig
   { xftpNetworkConfig :: NetworkConfig,
-    uploadTimeoutPerMb :: Int64
+    uploadTimeoutPerMb :: Int64,
+    serverVRange :: VersionRangeXFTP
   }
 
 data XFTPChunkBody = XFTPChunkBody
@@ -85,26 +93,64 @@ defaultXFTPClientConfig :: XFTPClientConfig
 defaultXFTPClientConfig =
   XFTPClientConfig
     { xftpNetworkConfig = defaultNetworkConfig,
-      uploadTimeoutPerMb = 10000000 -- 10 seconds
+      uploadTimeoutPerMb = 10000000, -- 10 seconds
+      serverVRange = supportedFileServerVRange
     }
 
-getXFTPClient :: TransportSession FileResponse -> XFTPClientConfig -> (XFTPClient -> IO ()) -> IO (Either XFTPClientError XFTPClient)
-getXFTPClient transportSession@(_, srv, _) config@XFTPClientConfig {xftpNetworkConfig} disconnected = runExceptT $ do
-  let tcConfig = transportClientConfig xftpNetworkConfig
+getXFTPClient :: TVar ChaChaDRG -> TransportSession FileResponse -> XFTPClientConfig -> (XFTPClient -> IO ()) -> IO (Either XFTPClientError XFTPClient)
+getXFTPClient g transportSession@(_, srv, _) config@XFTPClientConfig {xftpNetworkConfig, serverVRange} disconnected = runExceptT $ do
+  let tcConfig = (transportClientConfig xftpNetworkConfig) {alpn = Just ["xftp/1"]}
       http2Config = xftpHTTP2Config tcConfig config
       username = proxyUsername transportSession
       ProtocolServer _ host port keyHash = srv
   useHost <- liftEither $ chooseTransportHost xftpNetworkConfig host
   clientVar <- newTVarIO Nothing
   let usePort = if null port then "443" else port
       clientDisconnected = readTVarIO clientVar >>= mapM_ disconnected
-  http2Client <- withExceptT xftpClientError . ExceptT $ getVerifiedHTTP2Client (Just username) useHost usePort (Just keyHash) Nothing http2Config clientDisconnected
-  let HTTP2Client {sessionId} = http2Client
-      thParams = THandleParams {sessionId, blockSize = xftpBlockSize, thVersion = currentXFTPVersion, thAuth = Nothing, implySessId = False, batch = True}
-      c = XFTPClient {http2Client, thParams, transportSession, config}
+  http2Client <- liftError' xftpClientError $ getVerifiedHTTP2Client (Just username) useHost usePort (Just keyHash) Nothing http2Config clientDisconnected
+  let HTTP2Client {sessionId, sessionALPN} = http2Client
+      thParams0 = THandleParams {sessionId, blockSize = xftpBlockSize, thVersion = VersionXFTP 1, thAuth = Nothing, implySessId = False, batch = True}
+  logDebug $ "Client negotiated handshake protocol: " <> tshow sessionALPN
+  thParams <- case sessionALPN of
+    Just "xftp/1" -> xftpClientHandshakeV1 g serverVRange keyHash http2Client thParams0
+    Nothing -> pure thParams0
+    _ -> throwError $ PCETransportError (TEHandshake VERSION)
+  let c = XFTPClient {http2Client, thParams, transportSession, config}
   atomically $ writeTVar clientVar $ Just c
   pure c
 
+xftpClientHandshakeV1 :: TVar ChaChaDRG -> VersionRangeXFTP -> C.KeyHash -> HTTP2Client -> THandleParamsXFTP -> ExceptT XFTPClientError IO THandleParamsXFTP
+xftpClientHandshakeV1 g serverVRange keyHash@(C.KeyHash kh) c@HTTP2Client {sessionId, serverKey} thParams0 = do
+  shs <- getServerHandshake
+  (v, sk) <- processServerHandshake shs
+  (k, pk) <- atomically $ C.generateKeyPair g
+  sendClientHandshake XFTPClientHandshake {xftpVersion = v, keyHash, authPubKey = k}
+  pure thParams0 {thAuth = Just THandleAuth {peerPubKey = sk, privKey = pk}, thVersion = v}
+  where
+    getServerHandshake = do
+      let helloReq = H.requestNoBody "POST" "/" []
+      HTTP2Response {respBody = HTTP2Body {bodyHead = shsBody}} <-
+        liftError' (const $ PCEResponseError HANDSHAKE) $ sendRequestDirect c helloReq Nothing
+      liftHS . smpDecode =<< liftHS (C.unPad shsBody)
+    processServerHandshake XFTPServerHandshake {xftpVersionRange, sessionId = serverSessId, authPubKey = serverAuth} = do
+      unless (sessionId == serverSessId) $ throwError $ PCEResponseError SESSION
+      case xftpVersionRange `compatibleVersion` serverVRange of
+        Nothing -> throwError $ PCEResponseError HANDSHAKE
+        Just (Compatible v) ->
+          fmap (v,) . liftHS $ do
+            let (X.CertificateChain cert, exact) = serverAuth
+            case cert of
+              [_leaf, ca] | XV.Fingerprint kh == XV.getFingerprint ca X.HashSHA256 -> pure ()
+              _ -> throwError "bad certificate"
+            pubKey <- C.verifyX509 serverKey exact
+            C.x509ToPublic (pubKey, []) >>= C.pubKey
+    sendClientHandshake chs = do
+      chs' <- liftHS $ C.pad (smpEncode chs) xftpBlockSize
+      let chsReq = H.requestBuilder "POST" "/" [] $ byteString chs'
+      HTTP2Response {respBody = HTTP2Body {bodyHead}} <- liftError' (const $ PCEResponseError HANDSHAKE) $ sendRequestDirect c chsReq Nothing
+      unless (B.null bodyHead) $ throwError $ PCEResponseError HANDSHAKE
+    liftHS = liftEitherWith (const $ PCEResponseError HANDSHAKE)
+
 closeXFTPClient :: XFTPClient -> IO ()
 closeXFTPClient XFTPClient {http2Client} = closeHTTP2Client http2Client
 
@@ -198,8 +244,8 @@ downloadXFTPChunk g c@XFTPClient {config} rpKey fId chunkSpec@XFTPRcvChunkSpec {
         let t = chunkTimeout config chunkSize
         ExceptT (sequence <$> (t `timeout` download cbState)) >>= maybe (throwError PCEResponseTimeout) pure
         where
-          download cbState = runExceptT $
-            withExceptT PCEResponseError $
+          download cbState =
+            runExceptT . withExceptT PCEResponseError $
               receiveEncFile chunkPart cbState chunkSpec `catchError` \e ->
                 whenM (doesFileExist filePath) (removeFile filePath) >> throwError e
       _ -> throwError $ PCEResponseError NO_FILE

src/Simplex/FileTransfer/Client/Agent.hs

@@ -11,6 +11,7 @@ import Control.Logger.Simple (logInfo)
 import Control.Monad
 import Control.Monad.Except
 import Control.Monad.Trans (lift)
+import Crypto.Random (ChaChaDRG)
 import Data.Bifunctor (first)
 import qualified Data.ByteString.Char8 as B
 import Data.Text (Text)
@@ -60,15 +61,15 @@ newXFTPAgent config = do
 
 type ME a = ExceptT XFTPClientAgentError IO a
 
-getXFTPServerClient :: XFTPClientAgent -> XFTPServer -> ME XFTPClient
-getXFTPServerClient XFTPClientAgent {xftpClients, config} srv = do
+getXFTPServerClient :: TVar ChaChaDRG -> XFTPClientAgent -> XFTPServer -> ME XFTPClient
+getXFTPServerClient g XFTPClientAgent {xftpClients, config} srv = do
   atomically getClientVar >>= either newXFTPClient waitForXFTPClient
   where
     connectClient :: ME XFTPClient
     connectClient =
       ExceptT $
         first (XFTPClientAgentError srv)
-          <$> getXFTPClient (1, srv, Nothing) (xftpConfig config) clientDisconnected
+          <$> getXFTPClient g (1, srv, Nothing) (xftpConfig config) clientDisconnected
 
     clientDisconnected :: XFTPClient -> IO ()
     clientDisconnected _ = do