\input texinfo @c -*-texinfo-*- @set VERSION 0.3 @setfilename ../../info/emacs-gnutls.info @settitle Emacs GnuTLS Integration @value{VERSION} @include docstyle.texi @copying This file describes the Emacs GnuTLS integration. Copyright @copyright{} 2012--2021 Free Software Foundation, Inc. @quotation 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.'' @end quotation @end copying @dircategory Emacs network features @direntry * Emacs GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration. @end direntry @titlepage @title Emacs GnuTLS Integration @author by Ted Zlatanov @page @vskip 0pt plus 1filll @insertcopying @end titlepage @contents @ifnottex @node Top @top Emacs GnuTLS This manual describes the Emacs GnuTLS integration. GnuTLS is a library that establishes encrypted @acronym{SSL} or @acronym{TLS} connections. Emacs supports it through the @file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el} Emacs Lisp library. @insertcopying @menu * Overview:: Overview of the GnuTLS integration. * Help For Users:: * Help For Developers:: * GNU Free Documentation License:: The license for this documentation. * Function Index:: * Variable Index:: @end menu @end ifnottex @node Overview @chapter Overview The GnuTLS library is an optional add-on for Emacs. Through it, any Emacs Lisp program can establish encrypted network connections that use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer Security} (@acronym{TLS}) protocols. The process of using @acronym{SSL} and @acronym{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. @node Help For Users @chapter 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 @code{open-protocol-stream} or @code{open-network-stream} (@pxref{Network,, Network Connections, elisp, 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 @code{gnutls-available-p}. This is a little bit trickier on the W32 (Windows) platform, but if you have the GnuTLS DLLs (available from @url{https://sourceforge.net/projects/ezwinports/files/} thanks to Eli Zaretskii) in the same directory as Emacs, you should be OK. @defun gnutls-available-p This function returns non-@code{nil} if GnuTLS is available in this instance of Emacs, @code{nil} otherwise. If GnuTLS is available, the value is a list of GnuTLS capabilities supported by the installed GnuTLS library, which depends on the library version. The meaning of the capabilities is documented in the doc string of this function. @end defun 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. @defvar gnutls-log-level The @code{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 @file{*Messages*} buffer for the debugging information. @end defvar @defvar gnutls-algorithm-priority The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority string. This is global, not per host name (although @code{gnutls-negotiate} supports a priority string per connection so it could be done if needed). For details see the @uref{https://www.gnu.org/software/gnutls/documentation.html, GnuTLS documentation} and the @uref{https://gnutls.org/manual/html_node/Priority-Strings.html, GnuTLS priority string syntax and description}. @end defvar @defvar gnutls-trustfiles The @code{gnutls-trustfiles} variable is a list of trustfiles (certificates for the issuing authorities). This is global, not per host name (although @code{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: @file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu, Gentoo and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for Fedora and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse; @file{/usr/ssl/certs/ca-bundle.crt} for Cygwin; @file{/usr/local/share/certs/ca-root-nss.crt} for FreeBSD@. You can easily customize @code{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. @end defvar @defvar gnutls-verify-error The @code{gnutls-verify-error} variable allows you to verify SSL/TLS server certificates for all connections or by host name. It defaults to @code{nil} for now but will likely be changed to @code{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 @code{gnutls-trustfiles}, and that the hostname matches the certificate. @code{t} enables both checks, but you can enable them individually as well with @code{:trustfiles} and @code{: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 @file{*Messages*} buffer. @end defvar @defvar gnutls-min-prime-bits The @code{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 @code{nil}. @end defvar @node Help For Developers @chapter Help For Developers The GnuTLS library is detected automatically at compile time. You should see that it's enabled in the @code{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 @code{open-protocol-stream} or @code{open-network-stream} (the two are equivalent, the first one being an alias to the second). You should not have to use the @file{gnutls.el} functions directly. But you can test them with @code{open-gnutls-stream}. @defun open-gnutls-stream name buffer host service &optional parameters This function creates a buffer connected to a specific @var{host} and @var{service} (port number or service name). The mandatory arguments and their syntax are the same as those given to @code{open-network-stream} (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference Manual}). The connection process is called @var{name} (made unique if necessary). This function returns the connection process. The optional @var{parameters} argument is a list of keywords and values. The only keywords which currently have any effect are @code{:client-certificate}, @code{:nowait}, and @code{:coding}. Passing @w{@code{:client certificate t}} triggers looking up of client certificates matching @var{host} and @var{service} using the @file{auth-source} library. Any resulting client certificates are passed down to the lower TLS layers. The format used by @file{.authinfo} to specify the per-server keys is described in @ref{Help for users,,auth-source, auth, Emacs auth-source Library}. Passing @w{@code{: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 @var{parameters} can also be a symbol, which is interpreted the same as passing a list containing @code{:nowait} and the value of that symbol. Example calls: @lisp ;; 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") @end lisp @end defun @findex gnutls-asynchronous-parameters If called with @var{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 @code{gnutls-asynchronous-parameters} function. The function @code{gnutls-negotiate} is not generally useful and it may change as needed, so please see @file{gnutls.el} for the details. @defun gnutls-negotiate spec Please see @file{gnutls.el} for the @var{spec} details and for usage, but do not rely on this function's interface if possible. @end defun @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi @node Function Index @unnumbered Function Index @printindex fn @node Variable Index @unnumbered Variable Index @printindex vr @bye @c End: