1 \input texinfo @c -*-texinfo-*-
5 @setfilename ../../info/emacs-gnutls.info
6 @settitle Emacs GnuTLS Integration @value{VERSION}
10 This file describes the Emacs GnuTLS integration.
12 Copyright @copyright{} 2012--2017 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
19 and with the Back-Cover Texts as in (a) below. A copy of the license
20 is included in the section entitled ``GNU Free Documentation License''.
22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
23 modify this GNU manual.''
27 @dircategory Emacs network features
29 * Emacs GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration.
33 @title Emacs GnuTLS Integration
34 @author by Ted Zlatanov
36 @vskip 0pt plus 1filll
45 This manual describes the Emacs GnuTLS integration.
47 GnuTLS is a library that establishes encrypted @acronym{SSL} or
48 @acronym{TLS} connections. Emacs supports it through the
49 @file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el}
55 * Overview:: Overview of the GnuTLS integration.
57 * Help For Developers::
58 * GNU Free Documentation License:: The license for this documentation.
67 The GnuTLS library is an optional add-on for Emacs. Through it, any
68 Emacs Lisp program can establish encrypted network connections that
69 use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer
70 Security} (@acronym{TLS}) protocols. The process of using
71 @acronym{SSL} and @acronym{TLS} in establishing connections is as
72 automated and transparent as possible.
74 The user has only a few customization options currently: the log
75 level, priority string, trustfile list, and the minimum number of bits
76 to be used in Diffie-Hellman key exchange. Rumors that every Emacs
77 library requires at least 83 customizable variables are thus proven
81 @chapter Help For Users
83 From the user's perspective, there's nothing to the GnuTLS
84 integration. It Just Works for any Emacs Lisp code that uses
85 @code{open-protocol-stream} or @code{open-network-stream}
86 (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
87 Manual}). The two functions are equivalent, the first one being an
90 There's one way to find out if GnuTLS is available, by calling
91 @code{gnutls-available-p}. This is a little bit trickier on the W32
92 (Windows) platform, but if you have the GnuTLS DLLs (available from
93 @url{http://sourceforge.net/projects/ezwinports/files/} thanks to Eli
94 Zaretskii) in the same directory as Emacs, you should be OK.
96 @defun gnutls-available-p
97 This function returns non-@code{nil} if GnuTLS is available in this
98 instance of Emacs, @code{nil} otherwise. If GnuTLS is available, the
99 value is a list of GnuTLS capabilities supported by the installed
100 GnuTLS library, which depends on the library version. The meaning of
101 the capabilities is documented in the doc string of this function.
104 Oh, but sometimes things go wrong. Budgets aren't balanced,
105 television ads lie, and even TLS and SSL connections can fail to work
106 properly. Well, there's something to be done in the last case.
108 @defvar gnutls-log-level
109 The @code{gnutls-log-level} variable sets the log level. 1 is
110 verbose. 2 is very verbose. 5 is crazy. Crazy! Set it to 1 or 2
111 and look in the @file{*Messages*} buffer for the debugging
115 @defvar gnutls-algorithm-priority
116 The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority
117 string. This is global, not per host name (although
118 @code{gnutls-negotiate} supports a priority string per connection so
119 it could be done if needed). The priority string syntax is in the
120 @uref{https://www.gnu.org/software/gnutls/documentation.html, GnuTLS
124 @defvar gnutls-trustfiles
125 The @code{gnutls-trustfiles} variable is a list of trustfiles
126 (certificates for the issuing authorities). This is global, not per
127 host name (although @code{gnutls-negotiate} supports a trustfile per
128 connection so it could be done if needed). The trustfiles can be in
129 PEM or DER format and examples can be found in most Unix
130 distributions. By default the following locations are tried in this
131 order: @file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu,
132 Gentoo and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for
133 Fedora and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse;
134 @file{/usr/ssl/certs/ca-bundle.crt} for Cygwin;
135 @file{/usr/local/share/certs/ca-root-nss.crt} for FreeBSD. You can
136 easily customize @code{gnutls-trustfiles} to be something else, but
137 let us know if you do, so we can make the change to benefit the other
138 users of that platform.
141 @defvar gnutls-verify-error
142 The @code{gnutls-verify-error} variable allows you to verify SSL/TLS
143 server certificates for all connections or by host name. It defaults
144 to @code{nil} for now but will likely be changed to @code{t} later,
145 meaning that all certificates will be verified.
147 There are two checks available currently, that the certificate has
148 been issued by a trusted authority as defined by
149 @code{gnutls-trustfiles}, and that the hostname matches the
150 certificate. @code{t} enables both checks, but you can enable them
151 individually as well with @code{:trustfiles} and @code{:hostname}
154 Because of the low-level interactions with the GnuTLS library, there
155 is no way currently to ask if a certificate can be accepted. You have
156 to look in the @file{*Messages*} buffer.
159 @defvar gnutls-min-prime-bits
160 The @code{gnutls-min-prime-bits} variable is a pretty exotic
161 customization for cases where you want to refuse handshakes with keys
162 under a specific size. If you don't know for sure that you need it,
163 you don't. Leave it @code{nil}.
166 @node Help For Developers
167 @chapter Help For Developers
169 The GnuTLS library is detected automatically at compile time. You
170 should see that it's enabled in the @code{configure} output. If not,
171 follow the standard procedure for finding out why a system library is
172 not picked up by the Emacs compilation. On the W32 (Windows)
173 platform, installing the DLLs with a recent build should be enough.
175 Just use @code{open-protocol-stream} or @code{open-network-stream}
176 (the two are equivalent, the first one being an alias to the second).
177 You should not have to use the @file{gnutls.el} functions directly.
178 But you can test them with @code{open-gnutls-stream}.
180 @defun open-gnutls-stream name buffer host service &optional nowait
181 This function creates a buffer connected to a specific @var{host} and
182 @var{service} (port number or service name). The parameters and their
183 syntax are the same as those given to @code{open-network-stream}
184 (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
185 Manual}). The connection process is called @var{name} (made unique if
186 necessary). This function returns the connection process.
188 The @var{nowait} parameter means that the socket should be
189 asynchronous, and the connection process will be returned to the
190 caller before TLS negotiation has happened.
193 ;; open a HTTPS connection
194 (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")
196 ;; open a IMAPS connection
197 (open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
202 @findex gnutls-asynchronous-parameters
203 If called with @var{nowait}, the process is returned immediately
204 (before connecting to the server). In that case, the process object
205 is told what parameters to use when negotiating the connection
206 by using the @code{gnutls-asynchronous-parameters} function.
208 The function @code{gnutls-negotiate} is not generally useful and it
209 may change as needed, so please see @file{gnutls.el} for the details.
211 @defun gnutls-negotiate spec
212 Please see @file{gnutls.el} for the @var{spec} details and for usage,
213 but do not rely on this function's interface if possible.
216 @node GNU Free Documentation License
217 @appendix GNU Free Documentation License
218 @include doclicense.texi
221 @unnumbered Function Index
225 @unnumbered Variable Index