Commit | Line | Data |
---|---|---|
6b4f4a2d TZ |
1 | \input texinfo @c -*-texinfo-*- |
2 | ||
3 | @setfilename ../../info/emacs-gnutls | |
4 | @settitle Emacs GnuTLS Integration @value{VERSION} | |
5 | ||
6 | @set VERSION 0.3 | |
7 | ||
8 | @copying | |
9 | This file describes the Emacs GnuTLS integration. | |
10 | ||
11 | Copyright @copyright{} 2012 Free Software Foundation, Inc. | |
12 | ||
13 | @quotation | |
14 | Permission is granted to copy, distribute and/or modify this document | |
15 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
16 | any later version published by the Free Software Foundation; with no | |
17 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' | |
18 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
19 | is included in the section entitled ``GNU Free Documentation License'' | |
20 | in the Emacs manual. | |
21 | ||
22 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
23 | modify this GNU manual. Buying copies from the FSF supports it in | |
24 | developing GNU and promoting software freedom.'' | |
25 | ||
26 | This document is part of a collection distributed under the GNU Free | |
27 | Documentation License. If you want to distribute this document | |
28 | separately from the collection, you can do so by adding a copy of the | |
29 | license to the document, as described in section 6 of the license. | |
30 | @end quotation | |
31 | @end copying | |
32 | ||
226b6743 | 33 | @dircategory Emacs network features |
6b4f4a2d | 34 | @direntry |
226b6743 | 35 | * GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration. |
6b4f4a2d TZ |
36 | @end direntry |
37 | ||
38 | @titlepage | |
39 | @title Emacs GnuTLS Integration | |
40 | @author by Ted Zlatanov | |
41 | @page | |
42 | @vskip 0pt plus 1filll | |
43 | @insertcopying | |
44 | @end titlepage | |
45 | ||
46 | @contents | |
47 | ||
48 | @ifnottex | |
49 | @node Top | |
50 | @top Emacs GnuTLS | |
51 | This manual describes the Emacs GnuTLS integration. | |
52 | ||
53 | GnuTLS is a library that establishes encrypted @acronym{SSL} or | |
54 | @acronym{TLS} connections. Emacs supports it through the | |
55 | @file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el} | |
56 | Emacs Lisp library. | |
57 | ||
58 | @insertcopying | |
59 | ||
60 | @menu | |
61 | * Overview:: Overview of the GnuTLS integration. | |
62 | * Help For Users:: | |
63 | * Help For Developers:: | |
64 | * Function Index:: | |
65 | * Variable Index:: | |
66 | @end menu | |
67 | @end ifnottex | |
68 | ||
69 | @node Overview | |
70 | @chapter Overview | |
71 | ||
72 | The GnuTLS library is an optional add-on for Emacs. Through it, any | |
73 | Emacs Lisp program can establish encrypted network connections that | |
74 | use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer | |
75 | Security} (@acronym{TLS}) protocols. The process of using | |
76 | @acronym{SSL} and @acronym{TLS} in establishing connections is as | |
77 | automated and transparent as possible. | |
78 | ||
79 | The user has only a few customization options currently: the log | |
80 | level, priority string, trustfile list, and the minimum number of bits | |
81 | to be used in Diffie-Hellman key exchange. Rumors that every Emacs | |
82 | library requires at least 83 customizable variables are thus proven | |
83 | false. | |
84 | ||
85 | @node Help For Users | |
86 | @chapter Help For Users | |
87 | ||
88 | From the user's perspective, there's nothing to the GnuTLS | |
89 | integration. It Just Works for any Emacs Lisp code that uses | |
90 | @code{open-protocol-stream} or @code{open-network-stream} | |
91 | (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference | |
92 | Manual}). The two functions are equivalent, the first one being an | |
93 | alias of the second. | |
94 | ||
95 | There's one way to find out if GnuTLS is available, by calling | |
96 | @code{gnutls-available-p}. This is a little bit trickier on the W32 | |
97 | (Windows) platform, but if you have the GnuTLS DLLs (available from | |
98 | @url{http://sourceforge.net/projects/ezwinports/files/} thanks to Eli | |
99 | Zaretskii) in the same directory as Emacs, you should be OK. | |
100 | ||
101 | @defun gnutls-available-p | |
102 | This function returns t if GnuTLS is available in this instance of Emacs. | |
103 | @end defun | |
104 | ||
105 | Oh, but sometimes things go wrong. Budgets aren't balanced, | |
106 | television ads lie, and even TLS and SSL connections can fail to work | |
107 | properly. Well, there's something to be done in the last case. | |
108 | ||
109 | @defvar gnutls-log-level | |
110 | The @code{gnutls-log-level} variable sets the log level. 1 is | |
111 | verbose. 2 is very verbose. 5 is crazy. Crazy! Set it to 1 or 2 | |
112 | and look in the @code{*Messages*} buffer for the debugging | |
113 | information. | |
114 | @end defvar | |
115 | ||
116 | @defvar gnutls-algorithm-priority | |
117 | The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority | |
118 | string. This is global, not per host name (although | |
119 | @code{gnutls-negotiate} supports a priority string per connection so | |
120 | it could be done if needed). The priority string syntax is in the | |
121 | @uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS | |
122 | documentation}. | |
123 | @end defvar | |
124 | ||
125 | @defvar gnutls-trustfiles | |
126 | The @code{gnutls-trustfiles} variable is a list of trustfiles | |
127 | (certificates for the issuing authorities). This is global, not per | |
128 | host name (although @code{gnutls-negotiate} supports a trustfile per | |
129 | connection so it could be done if needed). The trustfiles can be in | |
130 | PEM or DER format and examples can be found in most Unix | |
131 | distributions. By default four locations are tried in this order: | |
132 | @file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu, Gentoo | |
133 | and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for Fedora | |
134 | and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse; | |
135 | @file{/usr/ssl/certs/ca-bundle.crt} for Cygwin. You can easily | |
136 | customize @code{gnutls-trustfiles} to be something else, but let us | |
137 | know if you do, so we can make the change to benefit the other users | |
138 | of that platform. | |
139 | @end defvar | |
140 | ||
141 | @defvar gnutls-min-prime-bits | |
142 | The @code{gnutls-min-prime-bits} variable is a pretty exotic | |
143 | customization for cases where you want to refuse handshakes with keys | |
144 | under a specific size. If you don't know for sure that you need it, | |
145 | you don't. Leave it @code{nil}. | |
146 | @end defvar | |
147 | ||
148 | @node Help For Developers | |
149 | @chapter Help For Developers | |
150 | ||
151 | The GnuTLS library is detected automatically at compile time. You | |
152 | should see that it's enabled in the @code{configure} output. If not, | |
153 | follow the standard procedure for finding out why a system library is | |
154 | not picked up by the Emacs compilation. On the W32 (Windows) | |
155 | platform, installing the DLLs with a recent build should be enough. | |
156 | ||
157 | Just use @code{open-protocol-stream} or @code{open-network-stream} | |
158 | (the two are equivalent, the first one being an alias to the second). | |
159 | You should not have to use the @file{gnutls.el} functions directly. | |
160 | But you can test them with @code{open-gnutls-stream}. | |
161 | ||
162 | @defun open-gnutls-stream name buffer host service | |
163 | This function creates a buffer connected to a specific @var{host} and | |
164 | @var{service} (port number or service name). The parameters and their | |
165 | syntax are the same as those given to @code{open-network-stream} | |
166 | (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference | |
167 | Manual}). The connection process is called @var{name} (made unique if | |
168 | necessary). This function returns the connection process. | |
169 | ||
170 | @lisp | |
171 | ;; open a HTTPS connection | |
172 | (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https") | |
173 | ||
174 | ;; open a IMAPS connection | |
175 | (open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps") | |
176 | @end lisp | |
177 | ||
178 | @end defun | |
179 | ||
180 | The function @code{gnutls-negotiate} is not generally useful and it | |
181 | may change as needed, so please see @file{gnutls.el} for the details. | |
182 | ||
183 | @defun gnutls-negotiate spec | |
184 | Please see @file{gnutls.el} for the @var{spec} details and for usage, | |
185 | but do not rely on this function's interface if possible. | |
186 | @end defun | |
187 | ||
188 | @node Function Index | |
189 | @chapter Function Index | |
190 | @printindex fn | |
191 | ||
192 | @node Variable Index | |
193 | @chapter Variable Index | |
194 | @printindex vr | |
195 | ||
196 | @bye | |
197 | ||
198 | @c End: |