|
|
|
|
|
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
|
|
|
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.
|
|
|
|
Create a new SSL context.
|
|
|
Install a private key into a context.
|
|
|
Install a certificate (public key) into a context.
|
|
|
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.
|
|
|
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.
|
|
|
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.
|
|
|
|
|
Return true iff the private key installed in the given context matches the
certificate also installed.
|
|
|
|
|
|
|
|
Set the location of a PEM encoded list of CA certificates to be used when
verifying a server's certificate
|
|
|
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
|
|
|
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.
|
|
|
|
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.
|
|
|
Perform an SSL server handshake
|
|
|
Perform an SSL client handshake
|
|
|
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 a given ByteString to the SSL connection. Either all the data is
written or an exception is raised because of an error
|
|
|
Lazily read all data until reaching EOF. If the connection dies
without a graceful SSL shutdown, an exception is raised.
|
|
|
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.
|
|
|
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.
|
|
|
Constructors | Bidirectional | wait for the peer to also shutdown
| Unidirectional | only send our shutdown
|
|
|
|
|
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
|
|
|
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.
|
|
|
Get the socket underlying an SSL connection
|
|
Produced by Haddock version 2.4.2 |