doc/misc/emacs-gnutls.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @set VERSION 0.3
   4
   5 @setfilename ../../info/emacs-gnutls.info
   6 @settitle Emacs GnuTLS Integration @value{VERSION}
   7 @documentencoding UTF-8
   8
   9 @copying
  10 This file describes the Emacs GnuTLS integration.
  11
  12 Copyright @copyright{} 2012--2014 Free Software Foundation, Inc.
  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
  20 is included in the section entitled ``GNU Free Documentation License''.
  21
  22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  23 modify this GNU manual.''
  24 @end quotation
  25 @end copying
  26
  27 @dircategory Emacs network features
  28 @direntry
  29 * Emacs GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration.
  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::
  58 * GNU Free Documentation License::  The license for this documentation.
  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 @code{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 @file{*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
 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 @file{*Messages*} buffer.
 152 @end defvar
 153
 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
 201 @node GNU Free Documentation License
 202 @appendix GNU Free Documentation License
 203 @include doclicense.texi
 204
 205 @node Function Index
 206 @unnumbered Function Index
 207 @printindex fn
 208
 209 @node Variable Index
 210 @unnumbered Variable Index
 211 @printindex vr
 212
 213 @bye
 214
 215 @c End: