HsOpenSSL-0.10.1.2: (Incomplete) OpenSSL binding for Haskell

OpenSSL.Session

Contents

Description

Functions for handling SSL connections. These functions use GHC specific calls to cooperative the with the scheduler so that blocking functions only actually block the Haskell thread, not a whole OS thread.

Synopsis

Contexts

data SSLContext Source

An SSL context. Contexts carry configuration such as a server's private key, root CA certiifcates etc. Contexts are stateful IO objects; they start empty and various options are set on them by the functions in this module. Note that an empty context will pretty much cause any operation to fail since it doesn't even have any ciphers enabled.

Contexts are not thread safe so they carry a QSem with them which only lets a single thread work inside them at a time. Thus, one must always use withContext, not withForeignPtr directly.

context :: IO SSLContextSource

Create a new SSL context.

contextSetPrivateKey :: KeyPair k => SSLContext -> k -> IO ()Source

Install a private key into a context.

contextSetCertificate :: SSLContext -> X509 -> IO ()Source

Install a certificate (public key) into a context.

contextSetPrivateKeyFile :: SSLContext -> FilePath -> IO ()Source

Install a private key file in a context. The key is given as a path to the file which contains the key. The file is parsed first as PEM and, if that fails, as ASN1. If both fail, an exception is raised.

contextSetCertificateFile :: SSLContext -> FilePath -> IO ()Source

Install a certificate (public key) file in a context. The key is given as a path to the file which contains the key. The file is parsed first as PEM and, if that fails, as ASN1. If both fail, an exception is raised.

contextSetCiphers :: SSLContext -> String -> IO ()Source

Set the ciphers to be used by the given context. The string argument is a list of ciphers, comma separated, as given at http:www.openssl.orgdocsapps/ciphers.html

Unrecognised ciphers are ignored. If no ciphers from the list are recognised, an exception is raised.

contextCheckPrivateKey :: SSLContext -> IO BoolSource

Return true iff the private key installed in the given context matches the certificate also installed.

data VerificationMode Source

Constructors

VerifyNone 
VerifyPeer 

Fields

vpFailIfNoPeerCert :: Bool

is a certificate required

vpClientOnce :: Bool

only request once per connection

vpCallback :: Maybe (Bool -> X509StoreCtx -> IO Bool)

optional callback

contextSetCAFile :: SSLContext -> FilePath -> IO ()Source

Set the location of a PEM encoded list of CA certificates to be used when verifying a server's certificate

contextSetCADirectory :: SSLContext -> FilePath -> IO ()Source

Set the path to a directory which contains the PEM encoded CA root certificates. This is an alternative to contextSetCAFile. See http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html for details of the file naming scheme

contextGetCAStore :: SSLContext -> IO X509StoreSource

Get a reference to, not a copy of, the X.509 certificate storage in the SSL context.

SSL connections

data SSL Source

This is the type of an SSL connection

SSL objects are not thread safe, so they carry a QSem around with them which only lets a single thread work inside them at a time. Thus, one must always use withSSL, rather than withForeignPtr directly.

IO with SSL objects is non-blocking and many SSL functions return a error code which signifies that it needs to read or write more data. We handle these calls and call threadWaitRead and threadWaitWrite at the correct times. Thus multiple OS threads can be blocked inside IO in the same SSL object at a time, because they aren't really in the SSL object, they are waiting for the RTS to wake the Haskell thread.

data SSLResult a Source

This is the type of an SSL IO operation. Errors are handled by exceptions while everything else is one of these. Note that reading from an SSL socket can result in WantWrite and vice versa.

Constructors

SSLDone a

operation finished successfully

WantRead

needs more data from the network

WantWrite

needs more outgoing buffer space

connection :: SSLContext -> Socket -> IO SSLSource

Wrap a Socket in an SSL connection. Reading and writing to the Socket after this will cause weird errors in the SSL code. The SSL object carries a handle to the Socket so you need not worry about the garbage collector closing the file descriptor out from under you.

fdConnection :: SSLContext -> Fd -> IO SSLSource

Wrap a socket Fd in an SSL connection.

accept :: SSL -> IO ()Source

Perform an SSL server handshake

tryAccept :: SSL -> IO (SSLResult ())Source

Try to perform an SSL server handshake without blocking

connect :: SSL -> IO ()Source

Perform an SSL client handshake

tryConnect :: SSL -> IO (SSLResult ())Source

Try to perform an SSL client handshake without blocking

read :: SSL -> Int -> IO ByteStringSource

Try to read the given number of bytes from an SSL connection. On EOF an empty ByteString is returned. If the connection dies without a graceful SSL shutdown, an exception is raised.

tryRead :: SSL -> Int -> IO (SSLResult ByteString)Source

Try to read the given number of bytes from an SSL connection without blocking.

write :: SSL -> ByteString -> IO ()Source

Write a given ByteString to the SSL connection. Either all the data is written or an exception is raised because of an error.

tryWrite :: SSL -> ByteString -> IO (SSLResult ())Source

Try to write a given ByteString to the SSL connection without blocking.

lazyRead :: SSL -> IO ByteStringSource

Lazily read all data until reaching EOF. If the connection dies without a graceful SSL shutdown, an exception is raised.

lazyWrite :: SSL -> ByteString -> IO ()Source

Write a lazy ByteString to the SSL connection. In contrast to write, there is a chance that the string is written partway and then an exception is raised for an error. The string doesn't necessarily have to be finite.

shutdown :: SSL -> ShutdownType -> IO ()Source

Cleanly shutdown an SSL connection. Note that SSL has a concept of a secure shutdown, which is distinct from just closing the TCP connection. This performs the former and should always be preferred.

This can either just send a shutdown, or can send and wait for the peer's shutdown message.

tryShutdown :: SSL -> ShutdownType -> IO (SSLResult ())Source

Try to cleanly shutdown an SSL connection without blocking.

data ShutdownType Source

Constructors

Bidirectional

wait for the peer to also shutdown

Unidirectional

only send our shutdown

getPeerCertificate :: SSL -> IO (Maybe X509)Source

After a successful connection, get the certificate of the other party. If this is a server connection, you probably won't get a certificate unless you asked for it with contextSetVerificationMode

getVerifyResult :: SSL -> IO BoolSource

Get the result of verifing the peer's certificate. This is mostly for clients to verify the certificate of the server that they have connected it. You must set a list of root CA certificates with contextSetCA... for this to make sense.

Note that this returns True iff the peer's certificate has a valid chain to a root CA. You also need to check that the certificate is correct (i.e. has the correct hostname in it) with getPeerCertificate.

sslSocket :: SSL -> Maybe SocketSource

Get the socket underlying an SSL connection

sslFd :: SSL -> FdSource

Get the underlying socket Fd

SSL Exceptions

data SomeSSLException Source

The root exception type for all SSL exceptions.

data ConnectionAbruptlyTerminated Source

The peer uncleanly terminated the connection without sending the "close notify" alert.

data ProtocolError Source

A failure in the SSL library occurred, usually a protocol error.

Constructors

ProtocolError !String