Commit | Line | Data |
---|---|---|
6b4f4a2d TZ |
1 | \input texinfo @c -*-texinfo-*- |
2 | ||
db671917 AS |
3 | @set VERSION 0.3 |
4 | ||
6b4f4a2d TZ |
5 | @setfilename ../../info/emacs-gnutls |
6 | @settitle Emacs GnuTLS Integration @value{VERSION} | |
c6ab4664 | 7 | @documentencoding UTF-8 |
6b4f4a2d | 8 | |
6b4f4a2d TZ |
9 | @copying |
10 | This file describes the Emacs GnuTLS integration. | |
11 | ||
6bc383b1 | 12 | Copyright @copyright{} 2012--2014 Free Software Foundation, Inc. |
6b4f4a2d TZ |
13 | |
14 | @quotation | |
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 | |
0b1af106 | 20 | is included in the section entitled ``GNU Free Documentation License''. |
6b4f4a2d TZ |
21 | |
22 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
6bf430d1 | 23 | modify this GNU manual.'' |
6b4f4a2d TZ |
24 | @end quotation |
25 | @end copying | |
26 | ||
226b6743 | 27 | @dircategory Emacs network features |
6b4f4a2d | 28 | @direntry |
7dc61a66 | 29 | * Emacs GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration. |
6b4f4a2d TZ |
30 | @end direntry |
31 | ||
32 | @titlepage | |
33 | @title Emacs GnuTLS Integration | |
34 | @author by Ted Zlatanov | |
35 | @page | |
36 | @vskip 0pt plus 1filll | |
37 | @insertcopying | |
38 | @end titlepage | |
39 | ||
40 | @contents | |
41 | ||
42 | @ifnottex | |
43 | @node Top | |
44 | @top Emacs GnuTLS | |
45 | This manual describes the Emacs GnuTLS integration. | |
46 | ||
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} | |
50 | Emacs Lisp library. | |
51 | ||
52 | @insertcopying | |
53 | ||
54 | @menu | |
55 | * Overview:: Overview of the GnuTLS integration. | |
56 | * Help For Users:: | |
57 | * Help For Developers:: | |
0b1af106 | 58 | * GNU Free Documentation License:: The license for this documentation. |
6b4f4a2d TZ |
59 | * Function Index:: |
60 | * Variable Index:: | |
61 | @end menu | |
62 | @end ifnottex | |
63 | ||
64 | @node Overview | |
65 | @chapter Overview | |
66 | ||
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. | |
73 | ||
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 | |
78 | false. | |
79 | ||
80 | @node Help For Users | |
81 | @chapter Help For Users | |
82 | ||
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 | |
88 | alias of the second. | |
89 | ||
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. | |
95 | ||
96 | @defun gnutls-available-p | |
97 | This function returns t if GnuTLS is available in this instance of Emacs. | |
98 | @end defun | |
99 | ||
100 | Oh, but sometimes things go wrong. Budgets aren't balanced, | |
101 | television ads lie, and even TLS and SSL connections can fail to work | |
102 | properly. Well, there's something to be done in the last case. | |
103 | ||
104 | @defvar gnutls-log-level | |
105 | The @code{gnutls-log-level} variable sets the log level. 1 is | |
106 | verbose. 2 is very verbose. 5 is crazy. Crazy! Set it to 1 or 2 | |
107 | and look in the @code{*Messages*} buffer for the debugging | |
108 | information. | |
109 | @end defvar | |
110 | ||
111 | @defvar gnutls-algorithm-priority | |
112 | The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority | |
113 | string. This is global, not per host name (although | |
114 | @code{gnutls-negotiate} supports a priority string per connection so | |
115 | it could be done if needed). The priority string syntax is in the | |
116 | @uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS | |
117 | documentation}. | |
118 | @end defvar | |
119 | ||
120 | @defvar gnutls-trustfiles | |
121 | The @code{gnutls-trustfiles} variable is a list of trustfiles | |
122 | (certificates for the issuing authorities). This is global, not per | |
123 | host name (although @code{gnutls-negotiate} supports a trustfile per | |
124 | connection so it could be done if needed). The trustfiles can be in | |
125 | PEM or DER format and examples can be found in most Unix | |
126 | distributions. By default four locations are tried in this order: | |
127 | @file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu, Gentoo | |
128 | and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for Fedora | |
129 | and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse; | |
130 | @file{/usr/ssl/certs/ca-bundle.crt} for Cygwin. You can easily | |
131 | customize @code{gnutls-trustfiles} to be something else, but let us | |
132 | know if you do, so we can make the change to benefit the other users | |
133 | of that platform. | |
134 | @end defvar | |
135 | ||
a0f20f21 TZ |
136 | @defvar gnutls-verify-error |
137 | The @code{gnutls-verify-error} variable allows you to verify SSL/TLS | |
138 | server certificates for all connections or by host name. It defaults | |
139 | to @code{nil} for now but will likely be changed to @code{t} later, | |
140 | meaning that all certificates will be verified. | |
141 | ||
142 | There are two checks available currently, that the certificate has | |
143 | been issued by a trusted authority as defined by | |
144 | @code{gnutls-trustfiles}, and that the hostname matches the | |
145 | certificate. @code{t} enables both checks, but you can enable them | |
146 | individually as well with @code{:trustfiles} and @code{:hostname} | |
147 | instead. | |
148 | ||
149 | Because of the low-level interactions with the GnuTLS library, there | |
150 | is no way currently to ask if a certificate can be accepted. You have | |
151 | to look in the @code{*Messages*} buffer. | |
152 | @end defvar | |
153 | ||
6b4f4a2d TZ |
154 | @defvar gnutls-min-prime-bits |
155 | The @code{gnutls-min-prime-bits} variable is a pretty exotic | |
156 | customization for cases where you want to refuse handshakes with keys | |
157 | under a specific size. If you don't know for sure that you need it, | |
158 | you don't. Leave it @code{nil}. | |
159 | @end defvar | |
160 | ||
161 | @node Help For Developers | |
162 | @chapter Help For Developers | |
163 | ||
164 | The GnuTLS library is detected automatically at compile time. You | |
165 | should see that it's enabled in the @code{configure} output. If not, | |
166 | follow the standard procedure for finding out why a system library is | |
167 | not picked up by the Emacs compilation. On the W32 (Windows) | |
168 | platform, installing the DLLs with a recent build should be enough. | |
169 | ||
170 | Just use @code{open-protocol-stream} or @code{open-network-stream} | |
171 | (the two are equivalent, the first one being an alias to the second). | |
172 | You should not have to use the @file{gnutls.el} functions directly. | |
173 | But you can test them with @code{open-gnutls-stream}. | |
174 | ||
175 | @defun open-gnutls-stream name buffer host service | |
176 | This function creates a buffer connected to a specific @var{host} and | |
177 | @var{service} (port number or service name). The parameters and their | |
178 | syntax are the same as those given to @code{open-network-stream} | |
179 | (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference | |
180 | Manual}). The connection process is called @var{name} (made unique if | |
181 | necessary). This function returns the connection process. | |
182 | ||
183 | @lisp | |
184 | ;; open a HTTPS connection | |
185 | (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https") | |
186 | ||
187 | ;; open a IMAPS connection | |
188 | (open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps") | |
189 | @end lisp | |
190 | ||
191 | @end defun | |
192 | ||
193 | The function @code{gnutls-negotiate} is not generally useful and it | |
194 | may change as needed, so please see @file{gnutls.el} for the details. | |
195 | ||
196 | @defun gnutls-negotiate spec | |
197 | Please see @file{gnutls.el} for the @var{spec} details and for usage, | |
198 | but do not rely on this function's interface if possible. | |
199 | @end defun | |
200 | ||
0b1af106 GM |
201 | @node GNU Free Documentation License |
202 | @appendix GNU Free Documentation License | |
203 | @include doclicense.texi | |
204 | ||
6b4f4a2d | 205 | @node Function Index |
0b1af106 | 206 | @unnumbered Function Index |
6b4f4a2d TZ |
207 | @printindex fn |
208 | ||
209 | @node Variable Index | |
0b1af106 | 210 | @unnumbered Variable Index |
6b4f4a2d TZ |
211 | @printindex vr |
212 | ||
213 | @bye | |
214 | ||
215 | @c End: |