     [file docstyle.texi not included]

Emacs GnuTLS
************

This manual describes the Emacs GnuTLS integration.

GnuTLS is a library that establishes encrypted SSL or TLS connections.  Emacs supports it through the gnutls.c and gnutls.h C files and the gnutls.el Emacs Lisp library.

This file describes the Emacs GnuTLS integration.

Copyright © 2012--2016 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

Overview
********

The GnuTLS library is an optional add-on for Emacs.  Through it, any Emacs Lisp program can establish encrypted network connections that use Secure Socket Layer (SSL) and Transport Layer Security (TLS) protocols.  The process of using SSL and TLS in establishing connections is as automated and transparent as possible.

The user has only a few customization options currently: the log level, priority string, trustfile list, and the minimum number of bits to be used in Diffie-Hellman key exchange.  Rumors that every Emacs library requires at least 83 customizable variables are thus proven false.

Help For Users
**************

From the user's perspective, there's nothing to the GnuTLS integration.  It Just Works for any Emacs Lisp code that uses open-protocol-stream or open-network-stream (see Network Connections (The Emacs Lisp Reference Manual)).  The two functions are equivalent, the first one being an alias of the second.

There's one way to find out if GnuTLS is available, by calling gnutls-available-p.  This is a little bit trickier on the W32 (Windows) platform, but if you have the GnuTLS DLLs (available from http://sourceforge.net/projects/ezwinports/files/ thanks to Eli Zaretskii) in the same directory as Emacs, you should be OK.

 -- Function: gnutls-available-p
     This function returns t if GnuTLS is available in this instance of Emacs.

Oh, but sometimes things go wrong.  Budgets aren't balanced, television ads lie, and even TLS and SSL connections can fail to work properly.  Well, there's something to be done in the last case.

 -- Variable: gnutls-log-level
     The gnutls-log-level variable sets the log level.  1 is verbose.  2 is very verbose.  5 is crazy.  Crazy!  Set it to 1 or 2 and look in the *Messages* buffer for the debugging information.

 -- Variable: gnutls-algorithm-priority
     The gnutls-algorithm-priority variable sets the GnuTLS priority string.  This is global, not per host name (although gnutls-negotiate supports a priority string per connection so it could be done if needed).  The priority string syntax is in the GnuTLS documentation (http://www.gnu.org/software/gnutls/documentation.html).

 -- Variable: gnutls-trustfiles
     The gnutls-trustfiles variable is a list of trustfiles (certificates for the issuing authorities).  This is global, not per host name (although gnutls-negotiate supports a trustfile per connection so it could be done if needed).  The trustfiles can be in PEM or DER format and examples can be found in most Unix distributions.  By default the following locations are tried in this order: /etc/ssl/certs/ca-certificates.crt for Debian, Ubuntu, Gentoo and Arch Linux; /etc/pki/tls/certs/ca-bundle.crt for Fedora and RHEL; /etc/ssl/ca-bundle.pem for Suse; /usr/ssl/certs/ca-bundle.crt for Cygwin; /usr/local/share/certs/ca-root-nss.crt for FreeBSD.  You can easily customize gnutls-trustfiles to be something else, but let us know if you do, so we can make the change to benefit the other users of that platform.

 -- Variable: gnutls-verify-error
     The gnutls-verify-error variable allows you to verify SSL/TLS server certificates for all connections or by host name.  It defaults to nil for now but will likely be changed to t later, meaning that all certificates will be verified.

     There are two checks available currently, that the certificate has been issued by a trusted authority as defined by gnutls-trustfiles, and that the hostname matches the certificate.  t enables both checks, but you can enable them individually as well with :trustfiles and :hostname instead.

     Because of the low-level interactions with the GnuTLS library, there is no way currently to ask if a certificate can be accepted.  You have to look in the *Messages* buffer.

 -- Variable: gnutls-min-prime-bits
     The gnutls-min-prime-bits variable is a pretty exotic customization for cases where you want to refuse handshakes with keys under a specific size.  If you don't know for sure that you need it, you don't.  Leave it nil.

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
     This function creates a buffer connected to a specific HOST and SERVICE (port number or service name).  The parameters and their syntax are the same as those given to open-network-stream (see Network Connections (The Emacs Lisp Reference Manual)).  The connection process is called NAME (made unique if necessary).  This function returns the connection process.

          ;; 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")

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.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]