diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # pipes-network-tls Utilities to deal with TLS-secured network connections using the -**pipes** and **pipes-safe** libraries. +**pipes**, **pipes-safe** and **tls** libraries. Currently, only TCP sockets are supported. diff --git a/examples/tls-echo.hs b/examples/tls-echo.hs --- a/examples/tls-echo.hs +++ b/examples/tls-echo.hs @@ -29,7 +29,7 @@ putStrLn $ show caddr <> " quit." main :: IO () -main = do +main = Z.withSocketsDo $ do args <- getArgs case getOpt RequireOrder options args of (actions, [hostname,port], _) -> do diff --git a/examples/tls-tunnel.hs b/examples/tls-tunnel.hs --- a/examples/tls-tunnel.hs +++ b/examples/tls-tunnel.hs @@ -44,7 +44,7 @@ main :: IO () -main = do +main = Pt.withSocketsDo $ do args <- getArgs case getOpt RequireOrder options args of (actions, [locHost,locPort,remHost,remPort], _) -> do diff --git a/pipes-network-tls.cabal b/pipes-network-tls.cabal --- a/pipes-network-tls.cabal +++ b/pipes-network-tls.cabal @@ -1,5 +1,5 @@ name: pipes-network-tls -version: 0.1.0.0 +version: 0.1.1.0 license: BSD3 license-file: LICENSE copyright: Copyright (c) Renzo Carbonara 2013 @@ -29,6 +29,9 @@ * "Control.Proxy.TCP.TLS.Safe" is similar to "Control.Proxy.TCP.TLS", except the exported 'Control.Proxy.Proxy's themselves can obtain new TLS resources safely by using the facilities providied by the @pipes-safe@ package. + . + See the @NEWS@ file in the source distribution to learn about any + important changes between version. source-repository head type: git @@ -40,10 +43,10 @@ base (==4.*), bytestring (>=0.9.2.1), network, - network-simple-tls (>=0.1 && <0.2), + network-simple-tls (>=0.1.1 && <0.2), pipes (>=3.3 && <3.4), pipes-safe (>=1.2 && <1.3), - pipes-network (>=0.5 && <0.6), + pipes-network (>=0.5.1 && <0.6), tls (>=1.1 && <1.2), transformers (>=0.2 && <0.4) exposed-modules: diff --git a/src/Control/Proxy/TCP/TLS.hs b/src/Control/Proxy/TCP/TLS.hs --- a/src/Control/Proxy/TCP/TLS.hs +++ b/src/Control/Proxy/TCP/TLS.hs @@ -38,6 +38,10 @@ , contextReadTimeoutS , contextWriteTimeoutD + -- * Note to Windows users + -- $windows-users + , S.withSocketsDo + -- * Exports , S.HostPreference(..) , S.Credential(..) @@ -56,17 +60,46 @@ -------------------------------------------------------------------------------- +-- $windows-users +-- +-- If you are running Windows, then you /must/ call 'S.withSocketsDo', just +-- once, right at the beginning of your program. That is, change your program's +-- 'main' function from: +-- +-- @ +-- main = do +-- print \"Hello world\" +-- -- rest of the program... +-- @ +-- +-- To: +-- +-- @ +-- main = 'S.withSocketsDo' $ do +-- print \"Hello world\" +-- -- rest of the program... +-- @ +-- +-- If you don't do this, your networking code won't work and you will get many +-- unexpected errors at runtime. If you use an operating system other than +-- Windows then you don't need to do this, but it is harmless to do it, so it's +-- recommended that you do for portability reasons. + +-------------------------------------------------------------------------------- + -- $client-side -- -- Here's how you could run a simple TLS-secured TCP client: -- --- > import Control.Proxy.TCP.TLS --- > --- > settings <- getDefaultClientSettings --- > connect settings "www.example.org" "443" $ \(tlsCtx, remoteAddr) -> do --- > putStrLn $ "Secure connection established to " ++ show remoteAddr --- > -- now you may use tlsCtx as you please within this scope, possibly with --- > -- the contextReadS or contextWriteD proxies explained below. +-- @ +-- import "Control.Proxy.TCP.TLS" +-- +-- \ settings <- 'S.getDefaultClientSettings' +-- 'S.connect' settings \"www.example.org\" \"443\" $ \(tlsCtx, remoteAddr) -> do +-- putStrLn $ \"Secure connection established to \" ++ show remoteAddr +-- -- now you may use tlsCtx as you please within this scope, possibly with +-- -- the 'contextReadS' or 'contextWriteD' proxies explained below. +-- @ -------------------------------------------------------------------------------- @@ -77,21 +110,23 @@ -- @example.org@. You will need a X509 certificate and a private key appropiate -- to be used at that hostname. -- --- > import Control.Proxy.TCP.TLS --- > import Network.TLS.Extra (fileReadCertificate, fileReadPrivateKey) --- > --- > cert <- fileReadCertificate "~/example.org.crt" --- > pkey <- fileReadPrivateKey "~/example.org.key" --- > let cred = Credential cert pkey [] --- > settings = makeServerSettings cred Nothing --- > --- > serve settings (Host "example.org") "4433" $ \(tlsCtx, remoteAddr) -> do --- > putStrLn $ "Secure connection established from " ++ show remoteAddr --- > -- now you may use tlsCtx as you please within this scope, possibly with --- > -- the contextReadS or contextWriteD proxies explained below. +-- @ +-- import "Control.Proxy.TCP.TLS" +-- import "Network.TLS.Extra" (fileReadCertificate, fileReadPrivateKey) -- +-- \ cert <- 'Network.TLS.Extra.fileReadCertificate' \"~/example.org.crt\" +-- pkey <- 'Network.TLS.Extra.fileReadPrivateKey' \"~/example.org.key\" +-- let cred = 'S.Credential' cert pkey [] +-- settings = 'S.makeServerSettings' cred Nothing +-- +-- \ 'S.serve' settings ('S.Host' \"example.org\") \"4433\" $ \(tlsCtx, remoteAddr) -> do +-- putStrLn $ \"Secure connection established from \" ++ show remoteAddr +-- -- now you may use tlsCtx as you please within this scope, possibly with +-- -- the 'contextReadS' or 'contextWriteD' proxies explained below. +-- @ +-- -- If you need more control on the way your server runs, then you can use more --- advanced functions such as 'listen', 'accept' and 'acceptFork'. +-- advanced functions such as 'S.listen', 'S.accept' and 'S.acceptFork'. -------------------------------------------------------------------------------- diff --git a/src/Control/Proxy/TCP/TLS/Safe.hs b/src/Control/Proxy/TCP/TLS/Safe.hs --- a/src/Control/Proxy/TCP/TLS/Safe.hs +++ b/src/Control/Proxy/TCP/TLS/Safe.hs @@ -46,6 +46,10 @@ , contextReadS , contextWriteD + -- * Note to Windows users + -- $windows-users + , NS.withSocketsDo + -- * Exports , S.HostPreference(..) , S.Credential(..) @@ -69,18 +73,47 @@ -------------------------------------------------------------------------------- +-- $windows-users +-- +-- If you are running Windows, then you /must/ call 'NS.withSocketsDo', just +-- once, right at the beginning of your program. That is, change your program's +-- 'main' function from: +-- +-- @ +-- main = do +-- print \"Hello world\" +-- -- rest of the program... +-- @ +-- +-- To: +-- +-- @ +-- main = 'NS.withSocketsDo' $ do +-- print \"Hello world\" +-- -- rest of the program... +-- @ +-- +-- If you don't do this, your networking code won't work and you will get many +-- unexpected errors at runtime. If you use an operating system other than +-- Windows then you don't need to do this, but it is harmless to do it, so it's +-- recommended that you do for portability reasons. + +-------------------------------------------------------------------------------- + -- $client-side -- -- Here's how you could run a simple TLS-secured TCP client: -- --- > import Control.Proxy.TCP.TLS.Safe --- > --- > settings <- getDefaultClientSettings --- > connect settings "www.example.org" "443" $ \(tlsCtx, remoteAddr) -> do --- > tryIO . putStrLn $ "Secure connection established to " ++ show remoteAddr --- > -- now you may use tlsCtx as you please within this scope, possibly with --- > -- the contextReadS or contextWriteD proxies explained below. +-- @ +-- import "Control.Proxy.TCP.TLS.Safe" -- +-- \ settings <- 'S.getDefaultClientSettings' +-- 'connect' settings \"www.example.org\" \"443\" $ \(tlsCtx, remoteAddr) -> do +-- tryIO . putStrLn $ \"Secure connection established to \" ++ show remoteAddr +-- -- now you may use tlsCtx as you please within this scope, possibly with +-- -- the 'contextReadS' or 'contextWriteD' proxies explained below. +-- @ +-- -- You might prefer to use the simpler but less general solutions offered by -- 'connectReadS' and 'connectWriteD', so check those too. @@ -93,7 +126,7 @@ -- -- The connection is properly closed when done or in case of exceptions. If you -- need to manage the lifetime of the connection resources yourself, then use --- 'connectTls' instead. +-- 'S.connectTls' instead. connect :: (P.Proxy p, Monad m) => (forall x. P.SafeIO x -> m x) -- ^Monad morphism. @@ -134,14 +167,6 @@ -- proxy returns. -- -- The connection is closed when done or in case of exceptions. --- --- Using this proxy you can write code like the following, which prints whatever --- is received through a TLS-secured TCP connection to a given server listening --- at hostname "example.org" on port 4433: --- --- >>> settings <- getDefaultClientSettings --- >>> let src = connectReadS Nothing settings "www.example.org" "4433" --- >>> runSafeIO . runProxy . runEitherK $ src >-> try . printD connectReadS :: P.Proxy p => Maybe Int -- ^Optional timeout in microseconds (1/10^6 seconds). @@ -163,14 +188,6 @@ -- 'P.ExceptionP' proxy transformer. -- -- The connection is properly closed when done or in case of exceptions. --- --- Using this proxy you can write code like the following, which sends data to a --- TLS-secured TCP server listening at hostname "example.org" on port 4433: --- --- >>> :set -XOverloadedStrings --- >>> settings <- getDefaultClientSettings --- >>> let dst = connectWriteS Nothing settings "www.example.org" "4433" --- >>> runSafeIO . runProxy . runEitherK $ fromListS ["He","llo\r\n"] >-> dst connectWriteD :: P.Proxy p => Maybe Int -- ^Optional timeout in microseconds (1/10^6 seconds). @@ -191,19 +208,21 @@ -- @example.org@. You will need a X509 certificate and a private key appropiate -- to be used at that hostname. -- --- > import Control.Proxy.TCP.TLS.Safe --- > import Network.TLS.Extra (fileReadCertificate, fileReadPrivateKey) --- > --- > cert <- fileReadCertificate "~/example.org.crt" --- > pkey <- fileReadPrivateKey "~/example.org.key" --- > let cred = Credential cert pkey [] --- > settings = makeServerSettings cred Nothing --- > --- > serve settings (Host "example.org") "4433" $ \(tlsCtx, remoteAddr) -> do --- > tryIO . putStrLn $ "Secure connection established from " ++ show remoteAddr --- > -- now you may use tlsCtx as you please within this scope, possibly with --- > -- the contextReadS or contextWriteD proxies explained below. +-- @ +-- import "Control.Proxy.TCP.TLS.Safe" +-- import "Network.TLS.Extra" (fileReadCertificate, fileReadPrivateKey) -- +-- \ cert <- 'Network.TLS.Extra.fileReadCertificate' \"~/example.org.crt\" +-- pkey <- 'Network.TLS.Extra.fileReadPrivateKey' \"~/example.org.key\" +-- let cred = 'S.Credential' cert pkey [] +-- settings = 'S.makeServerSettings' cred Nothing +-- +-- \ 'serve' settings ('S.Host' \"example.org\") \"4433\" $ \(tlsCtx, remoteAddr) -> do +-- tryIO . putStrLn $ \"Secure connection established from \" ++ show remoteAddr +-- -- now you may use tlsCtx as you please within this scope, possibly with +-- -- the 'contextReadS' or 'contextWriteD' proxies explained below. +-- @ +-- -- You might prefer to use the simpler but less general solutions offered by -- 'serveReadS' and 'serveWriteD', or if you need to control the way your -- server runs, then you can use more advanced functions such as 'listen', @@ -305,17 +324,6 @@ -- -- Both the listening and connection sockets are closed when done or in case of -- exceptions. --- --- Using this proxy you can write code like the following, which prints data --- received from a TLS-secured TCP connection to the hostname "example.org" at --- port 4433: --- --- >>> import Network.TLS.Extra (fileReadCertificate, fileReadPrivateKey) --- >>> cert <- fileReadCertificate "~/example.org.crt" --- >>> pkey <- fileReadPrivateKey "~/example.org.key" --- >>> let settings = makeServerSettings cert pkey Nothing --- >>> let src = serveReadS Nothing settings (Host "example.org") "4433" --- >>> runSafeIO . runProxy . runEitherK $ src >-> try . printD serveReadS :: P.Proxy p => Maybe Int -- ^Optional timeout in microseconds (1/10^6 seconds). @@ -342,18 +350,6 @@ -- -- Both the listening and connection sockets are closed when done or in case of -- exceptions. --- --- Using this proxy you can write straightforward code like the following, which --- sends data to an incoming TLS-secured TCP connection to the hostname --- "example.org" at port 4433: --- --- >>> :set -XOverloadedStrings --- >>> import Network.TLS.Extra (fileReadCertificate, fileReadPrivateKey) --- >>> cert <- fileReadCertificate "~/example.org.crt" --- >>> pkey <- fileReadPrivateKey "~/example.org.key" --- >>> let settings = makeServerSettings cert pkey Nothing --- >>> let dst = serveWriteD Nothing settings "example.org" "4433" --- >>> runSafeIO . runProxy . runEitherK $ fromListS ["He","llo\r\n"] >-> dst serveWriteD :: P.Proxy p => Maybe Int -- ^Optional timeout in microseconds (1/10^6 seconds).