doc/misc/emacs-gnutls.texi

   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
  33 @dircategory Emacs network features
  34 @direntry
  35 * GnuTLS: (emacs-gnutls).       The Emacs GnuTLS integration.
  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: