3.4 Input and Output

The underlying transport of a TLS session can be any Scheme input/output port (see Ports and File Descriptors in The GNU Guile Reference Manual). This has to be specified using set-session-transport-port!.

However, for better performance, a raw file descriptor can be specified, using set-session-transport-fd!. For instance, if the transport layer is a socket port over an OS-provided socket, you can use the port->fdes or fileno procedure to obtain the underlying file descriptor and pass it to set-session-transport-fd! (see port->fdes and fileno in The GNU Guile Reference Manual). This would work as follows:

(let ((socket (socket PF_INET SOCK_STREAM 0))
      (session (make-session connection-end/client)))

  ;;
  ;; Establish a TCP connection...
  ;;

  ;; Use the file descriptor that underlies SOCKET.
  (set-session-transport-fd! session (fileno socket)))

Once a TLS session is established, data can be communicated through it (i.e., via the TLS record layer) using the port returned by session-record-port:

(let ((session (make-session connection-end/client)))

  ;;
  ;; Initialize the various parameters of SESSION, set up
  ;; a network connection, etc.
  ;;

  (let ((i/o (session-record-port session)))
    (display "Hello peer!" i/o)
    (let ((greetings (read i/o)))

      ;; …

      (bye session close-request/rdwr))))

Note that each write to the session record port leads to the transmission of an encrypted TLS “Application Data” packet. In the above example, we create an Application Data packet for the 11 bytes for the string that we write. This is not efficient both in terms of CPU usage and bandwidth (each packet adds at least 5 bytes of overhead and can lead to one write system call), so we recommend that applications do their own buffering.

A lower-level I/O API is provided by record-send and record-receive! which take a bytevector (or a SRFI-4 vector) to represent the data sent or received. While it might improve performance, it is much less convenient than the session record port and should rarely be needed.