info bigloo

6.7.5.1 SSL Sockets

Bigloo defines SSL sockets, on systems that support them, as first class objects. SSL Sockets permits processes to communicate even if they are on different machines securely via encrypted connections. SSL Sockets are useful for creating secure client-server applications.

SSL library procedure: make-ssl-client-socket hostname port-number #!key (buffer #t) (timeout 0) (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f)

make-ssl-client-socket returns a new client socket object. This object satisfies the socket? predicate (see Socket support) can be used in any context where a socket created by make-client-socket can be used.

A SSL client socket establishes a link between the running application (client) and a remote application (server) listening on port port-number of hostname. If optional argument bufsiz is lesser or equal to 1 then the input port associated with the socket is unbuffered. This is useful for socket clients connected to servers that do not emit #\Newline character after emissions. The optional argument buffer can either be:

A positive fixnum, this gives the size of the buffer.
The boolean #t, a buffer is allocated.
The boolean #f, the socket is unbufferized.
A string, it is used as buffer.

If the optional argument timeout is 0, the execution blocks until the connection is established. If the timeout is provided, the execution unblocks after timeout microseconds unless the connection is established. If the protocol option argument is given, it specifies the encryption protocol. Accepted values are 'sslv2, 'sslv3, 'sslv23 (alias 'ssl), 'tls (alias 'tlsv1) or 'dtls (alias 'dtlsv1). The default value is 'sslv23.

The CAs optional argument specifies the list of certificates to trust as CA (Certificate Authority) for the connection. It must be a list of values of type certificate. If the list is empty, the default list of trusted CA is used (set by the system). Note that giving a list of trusted certificates turns on the peer (server) certificate validation: an &io-error will be raised if the peer (server) certificate is not signed directly or indirectly by one of the certificates in CAs.

The accepted-certs optional argument gives a list of certificate objects (of type certificate) which are accepted as peer (server) certificate. If accepted-certs is #f then every peer (server) certificate is accepted (aside from eventual certificate validation). If accepted-certs is a list, the peer (server) certificate must match one of the given certificates. Otherwise, an &io-error will be raised.

If the connection cannot be established, an &io-error is raised (see Errors, Assertions, and Traces).

When a socket is used in unbufferized mode the characters available on the input port must be read exclusively with read-char or read-line. It is forbidden to use read or any regular grammar. This limitation is imposed by Rgc (see Regular parsing) that intrinsicly associates buffers with regular grammars. If the current Rgc implementation is improved on the coming version this restriction will be eliminated.

The function make-ssl-client-socket is defined in the SSL library. A module that needs this facility must then use a library clause (see Modules). The SSL library can also be loaded from the interpreter using the library-load function (see Bigloo Libraries).

(module imap
   (library ssl)
   (main main))

(let* ((s (make-ssl-client-socket "localhost" 993))
       (p (socket-output s)))
   (display "string" p)
   (newline p)
   (display "abc" p)
   (flush-output-port p)
   (let loop ()
      (loop)))

SSL library procedure: client-socket-use-ssl! socket #!key (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f): Returns an SSL socket built from a socket obtained by make-client-socket (see Socket support). Depending on the implementation and back-end the returned socket may or may not be eq? to socket.

SSL library procedure: make-ssl-server-socket #!key (port 0) (name #f) (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f)

make-ssl-server-socket returns a new server socket object which satisfies the socket? predicate and which can be used in any context where a socket created by make-server-socket can be used (see Socket support).

A SSL server socket opens the port port on the current host name (the server), and allows remote applications (clients) to connect to it. listening on port port-number of hostname. If the optional argument port is not given or is 0, the server socket will use the first availailable port number. If the optional argument name is given, the server socket will be bound to the network interface representing the given host name. If it is #f (the default) the socket will be bound on every local network interface. If the protocol option argument is given, it specifies the encryption protocol. Accepted values are 'sslv2, 'sslv3, 'sslv23 (alias 'ssl), 'tls (alias 'tlsv1) or 'dtls (alias 'dtlsv1). The default value is 'sslv23.

The SSL socket will sign the connection using the optional arguments cert (for the certificate) and pkey (for the private key). The certificate cert must be of type certificate, and the private key pkey must be of type private-key. If any of those two arguments is given, they must both be given. If those optional arguments are missing the connection will be encrypted but not signed from the server side, which means the peer (client) will have to provide a certificate/private key pair to encrypt the connection, and that seldom happens. Typical SSL servers provide their certificate and private key.

Note that since the peer (client) certificate is only known when we are accepting a client socket (with socket-accept) the CAs and accepted-certs optional arguments are only checked during the accept operation of a server socket.

The CAs optional argument specifies the list of certificates to trust as CA (Certificate Authority) for the connection. It must be a list of values of type certificate. If the list is empty, the default list of trusted CA is used (set by the system). Note that giving a list of trusted certificates turns on the peer (client) certificate validation: an &io-error will be raised if the peer (client) certificate is not signed directly or indirectly by one of the certificates in CAs when accepting the client socket.

The accepted-certs optional argument gives a list of certificate objects (of type certificate) which are accepted as peer (client) certificate. If accepted-certs is #f then every peer (client) certificate is accepted (aside from eventual certificate validation). If accepted-certs is a list, the peer (client) certificate must match one of the given certificates. Otherwise, an &io-error will be raised when accepting the client socket.

If the connection cannot be established, an &io-error is raised (see Errors, Assertions, and Traces).

The function make-ssl-server-socket is defined in the SSL library. A module that needs this facility must then use a library clause (see Modules). The SSL library can also be loaded from the interpreter using the library-load function (see Bigloo Libraries).

(module secure-echo
   (library ssl))

(let* ((cert (read-certificate "/etc/ssl/my_cert.crt"))
       (pkey (read-private-key "/etc/ssl/my_key.pkey"))
       (cas (read-pem-file "/etc/ssl/ca.cert"))
       (s (make-ssl-server-socket 1055 :CAs cas :cert cert :pkey pkey))
       (cs (socket-accept s))
       (ip (socket-input cs))
       (op (socket-output cs)))
   (let loop ((e (read ip)))
      (when (not (eof-object? e))
         (write e op)
         (loop (read ip))))
   (socket-close s))

This document was generated on March 31, 2014 using texi2html 5.0.