doc/misc/emacs-gnutls.texi

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