pipes-network-tls 0.1.0.0 → 0.1.1.0

raw patch · 6 files changed

+119/−85 lines, 6 filesdep ~network-simple-tlsdep ~pipes-networkPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: network-simple-tls, pipes-network

API changes (from Hackage documentation)

Files

• README.md +1/−1
• examples/tls-echo.hs +1/−1
• examples/tls-tunnel.hs +1/−1
• pipes-network-tls.cabal +6/−3
• src/Control/Proxy/TCP/TLS.hs +55/−20
• src/Control/Proxy/TCP/TLS/Safe.hs +55/−59

@@ -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. 

@@ -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

@@ -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

@@ -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:

@@ -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'.  -------------------------------------------------------------------------------- 

@@ -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).