OpenSSL.Session

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.

Contexts

data SSLContext

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.

Instances

Typeable * SSLContext

context :: IO SSLContext

Create a new SSL context.

contextAddOption :: SSLContext -> SSLOption -> IO ()

Add a protocol option to the context.

contextRemoveOption :: SSLContext -> SSLOption -> IO ()

Remove a protocol option from the context.

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

Install a private key into a context.

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

Install a certificate (public key) into a context.

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

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 ()

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.

contextSetCertificateChainFile :: SSLContext -> FilePath -> IO ()

Install a certificate chain in a context. The certificates must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA.

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

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.orgdocsappsciphers.html

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

contextSetDefaultCiphers :: SSLContext -> IO ()

contextCheckPrivateKey :: SSLContext -> IO Bool

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

data VerificationMode

See http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html

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

Instances

Typeable * VerificationMode

contextSetVerificationMode :: SSLContext -> VerificationMode -> IO ()

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

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

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

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 X509Store

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

SSL connections

data SSL

This is the type of an SSL connection

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.

Instances

Typeable * SSL

data SSLResult a

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

Instances

Functor SSLResult

Foldable SSLResult

Traversable SSLResult

Eq a => Eq (SSLResult a)

Show a => Show (SSLResult a)

Typeable (* -> *) SSLResult

connection :: SSLContext -> Socket -> IO SSL

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 SSL

Wrap a socket Fd in an SSL connection.

addOption :: SSL -> SSLOption -> IO ()

Add a protocol option to the SSL connection.

removeOption :: SSL -> SSLOption -> IO ()

Remove a protocol option from the SSL connection.

accept :: SSL -> IO ()

Perform an SSL server handshake

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

Try to perform an SSL server handshake without blocking

connect :: SSL -> IO ()

Perform an SSL client handshake

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

Try to perform an SSL client handshake without blocking

read :: SSL -> Int -> IO ByteString

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)

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

readPtr :: SSL -> Ptr a -> Int -> IO Int

Read some data into a raw pointer buffer. Retrns the number of bytes read.

tryReadPtr :: SSL -> Ptr a -> Int -> IO (SSLResult Int)

Try to read some data into a raw pointer buffer, without blocking.

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

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 ())

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

writePtr :: SSL -> Ptr a -> Int -> IO ()

Send some data from a raw pointer buffer.

tryWritePtr :: SSL -> Ptr a -> Int -> IO (SSLResult ())

Send some data from a raw pointer buffer, without blocking.

lazyRead :: SSL -> IO ByteString

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

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

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 ()

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 ())

Try to cleanly shutdown an SSL connection without blocking.

data ShutdownType

Constructors

Bidirectional

wait for the peer to also shutdown

Unidirectional

only send our shutdown

Instances

Eq ShutdownType

Show ShutdownType

Typeable * ShutdownType

getPeerCertificate :: SSL -> IO (Maybe X509)

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 Bool

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 Socket

Get the socket underlying an SSL connection

sslFd :: SSL -> Fd

Get the underlying socket Fd

Protocol Options

data SSLOption

The behaviour of the SSL library can be changed by setting several options. During a handshake, the option settings of the SSL object are used. When a new SSL object is created from a SSLContext, the current option setting is copied. Changes to SSLContext do not affect already created SSL objects.

Constructors

SSL_OP_MICROSOFT_SESS_ID_BUG

As of OpenSSL 1.0.0 this option has no effect.

SSL_OP_NETSCAPE_CHALLENGE_BUG

As of OpenSSL 1.0.0 this option has no effect.

SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG

As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect.

SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG

SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER

SSL_OP_SAFARI_ECDHE_ECDSA_BUG

Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.

SSL_OP_SSLEAY_080_CLIENT_DH_BUG

SSL_OP_TLS_D5_BUG

SSL_OP_TLS_BLOCK_PADDING_BUG

SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS

Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers, which cannot be handled by some broken SSL implementations. This option has no effect for connections using other ciphers.

SSL_OP_ALL

All of the above bug workarounds.

SSL_OP_TLS_ROLLBACK_BUG

Disable version rollback attack detection.

During the client key exchange, the client must send the same information about acceptable SSL/TLS protocol levels as during the first hello. Some clients violate this rule by adapting to the server's answer. (Example: the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server only understands up to SSLv3. In this case the client must still use the same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect to the server's answer and violate the version rollback protection.)

SSL_OP_SINGLE_DH_USE

Always create a new key when using temporary/ephemeral DH parameters. This option must be used to prevent small subgroup attacks, when the DH parameters were not generated using "strong" primes (e.g. when using DSA-parameters). If "strong" primes were used, it is not strictly necessary to generate a new DH key during each handshake but it is also recommended. SSL_OP_SINGLE_DH_USE should therefore be enabled whenever temporary/ephemeral DH parameters are used.

SSL_OP_EPHEMERAL_RSA

Always use ephemeral (temporary) RSA key when doing RSA operations. According to the specifications this is only done, when a RSA key can only be used for signature operations (namely under export ciphers with restricted RSA keylength). By setting this option, ephemeral RSA keys are always used. This option breaks compatibility with the SSL/TLS specifications and may lead to interoperability problems with clients and should therefore never be used. Ciphers with DHE (ephemeral Diffie-Hellman) key exchange should be used instead.

SSL_OP_CIPHER_SERVER_PREFERENCE

When choosing a cipher, use the server's preferences instead of the client preferences. When not set, the SSL server will always follow the clients preferences. When set, the SSLv3/TLSv1 server will choose following its own preferences. Because of the different protocol, for SSLv2 the server will send its list of preferences to the client and the client chooses.

SSL_OP_PKCS1_CHECK_1

SSL_OP_PKCS1_CHECK_2

SSL_OP_NETSCAPE_CA_DN_BUG

If we accept a netscape connection, demand a client cert, have a non-self-signed CA which does not have its CA in netscape, and the browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta

SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG

SSL_OP_NO_SSLv2

Do not use the SSLv2 protocol.

SSL_OP_NO_SSLv3

Do not use the SSLv3 protocol.

SSL_OP_NO_TLSv1

Do not use the TLSv1 protocol.

SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION

When performing renegotiation as a server, always start a new session (i.e., session resumption requests are only accepted in the initial handshake). This option is not needed for clients.

SSL_OP_NO_TICKET

Normally clients and servers will, where possible, transparently make use of RFC 4507 tickets for stateless session resumption.

If this option is set this functionality is disabled and tickets will not be used by clients or servers.

SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION

Allow legacy insecure renegotiation between OpenSSL and unpatched clients or servers. See SECURE RENEGOTIATION for more details.

SSL_OP_LEGACY_SERVER_CONNECT

Allow legacy insecure renegotiation between OpenSSL and unpatched servers _only_. See SECURE RENEGOTIATION for more details.

Instances

Eq SSLOption

Ord SSLOption

Show SSLOption

Typeable * SSLOption

SSL Exceptions

data SomeSSLException

The root exception type for all SSL exceptions.

Instances

Show SomeSSLException

Exception SomeSSLException

Typeable * SomeSSLException

data ConnectionAbruptlyTerminated

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

Instances

Eq ConnectionAbruptlyTerminated

Show ConnectionAbruptlyTerminated

Exception ConnectionAbruptlyTerminated

Typeable * ConnectionAbruptlyTerminated

data ProtocolError

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

Constructors

ProtocolError !String

Instances

Eq ProtocolError

Show ProtocolError

Exception ProtocolError

Typeable * ProtocolError