3 Help For Developers

The GnuTLS library is detected automatically at compile time. You should see that it’s enabled in the configure output. If not, follow the standard procedure for finding out why a system library is not picked up by the Emacs compilation. On the W32 (Windows) platform, installing the DLLs with a recent build should be enough.

Just use open-protocol-stream or open-network-stream (the two are equivalent, the first one being an alias to the second). You should not have to use the gnutls.el functions directly. But you can test them with open-gnutls-stream.

Function: open-gnutls-stream name buffer host service &optional parameters

This function creates a buffer connected to a specific host and service (port number or service name). The mandatory arguments and their syntax are the same as those given to open-network-stream (see Network Connections in The Emacs Lisp Reference Manual). The connection process is called name (made unique if necessary). This function returns the connection process.

The optional parameters argument is a list of keywords and values. The only keywords which currently have any effect are :client-certificate, :nowait, and :coding.

Passing :client certificate t triggers looking up of client certificates matching host and service using the auth-source library. Any resulting client certificates are passed down to the lower TLS layers. The format used by .authinfo to specify the per-server keys is described in auth-source in Emacs auth-source Library.

Passing :nowait t means that the socket should be asynchronous, and the connection process will be returned to the caller before TLS negotiation has happened.

For historical reasons parameters can also be a symbol, which is interpreted the same as passing a list containing :nowait and the value of that symbol.

Example calls:

;; open a HTTPS connection
(open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")

;; open a IMAPS connection
(open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")

If called with nowait, the process is returned immediately (before connecting to the server). In that case, the process object is told what parameters to use when negotiating the connection by using the gnutls-asynchronous-parameters function.

The function gnutls-negotiate is not generally useful and it may change as needed, so please see gnutls.el for the details.

Function: gnutls-negotiate spec

Please see gnutls.el for the spec details and for usage, but do not rely on this function’s interface if possible.