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.
- data SSLContext
- context :: IO SSLContext
- contextSetPrivateKey :: KeyPair k => SSLContext -> k -> IO ()
- contextSetCertificate :: SSLContext -> X509 -> IO ()
- contextSetPrivateKeyFile :: SSLContext -> FilePath -> IO ()
- contextSetCertificateFile :: SSLContext -> FilePath -> IO ()
- contextSetCiphers :: SSLContext -> String -> IO ()
- contextSetDefaultCiphers :: SSLContext -> IO ()
- contextCheckPrivateKey :: SSLContext -> IO Bool
- data VerificationMode
- = VerifyNone
- | VerifyPeer { }
- contextSetVerificationMode :: SSLContext -> VerificationMode -> IO ()
- contextSetCAFile :: SSLContext -> FilePath -> IO ()
- contextSetCADirectory :: SSLContext -> FilePath -> IO ()
- contextGetCAStore :: SSLContext -> IO X509Store
- data SSL
- connection :: SSLContext -> Socket -> IO SSL
- accept :: SSL -> IO ()
- connect :: SSL -> IO ()
- read :: SSL -> Int -> IO ByteString
- write :: SSL -> ByteString -> IO ()
- lazyRead :: SSL -> IO ByteString
- lazyWrite :: SSL -> ByteString -> IO ()
- shutdown :: SSL -> ShutdownType -> IO ()
- data ShutdownType
- getPeerCertificate :: SSL -> IO (Maybe X509)
- getVerifyResult :: SSL -> IO Bool
- sslSocket :: SSL -> Socket
- data SomeSSLException
- data ConnectionCleanlyClosed
- data ConnectionAbruptlyTerminated
- data WantConnect
- data WantAccept
- data WantX509Lookup
- data SSLIOError
- data ProtocolError
- data UnknownError = UnknownError !Int
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
VerifyNone | |
VerifyPeer | |
|
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
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.
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.
read :: SSL -> Int -> IO ByteStringSource
Try the 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.
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
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.
data ShutdownType Source
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.
SSL Exceptions
data SomeSSLException Source
The root exception type for all SSL exceptions.
data ConnectionCleanlyClosed Source
The TLS/SSL connection has been closed. If the protocol version
is SSL 3.0 or TLS 1.0, this result code is returned only if a
closure alert has occurred in the protocol, i.e. if the connection
has been closed cleanly. Note that in this case
ConnectionCleanlyClosed
does not necessarily indicate that the
underlying transport has been closed.
data ConnectionAbruptlyTerminated Source
The peer uncleanly terminated the connection without sending the "close notify" alert.
data WantConnect Source
The operation did not complete; the same TLS/SSL I/O function
should be called again later. The underlying socket was not
connected yet to the peer and the call would block in
connect
. The SSL function should be called again when the
connection is established. This message can only appear with
connect
.
data WantAccept Source
The operation did not complete; the same TLS/SSL I/O function
should be called again later. The underlying socket was not
connected yet to the peer and the call would block in accept
. The
SSL function should be called again when the connection is
established. This message can only appear with accept
.
data WantX509Lookup Source
The operation did not complete because an application callback set by SSL_CTX_set_client_cert_cb() has asked to be called again. The TLS/SSL I/O function should be called again later. Details depend on the application.
data SSLIOError Source
Some I/O error occurred. The OpenSSL error queue may contain more information on the error. If the error queue is empty (i.e. ERR_get_error() returns 0), ret can be used to find out more about the error: If ret == 0, an EOF was observed that violates the protocol. If ret == -1, the underlying BIO reported an I/O error (for socket I/O on Unix systems, consult errno for details).
data ProtocolError Source
A failure in the SSL library occurred, usually a protocol error. The OpenSSL error queue contains more information on the error.
data UnknownError Source
SSL_get_error() returned an error code which is unknown to this library.