code.delx.au - gnu-emacs/blob - 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--2013 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 * 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-min-prime-bits
 136 The @code{gnutls-min-prime-bits} variable is a pretty exotic
 137 customization for cases where you want to refuse handshakes with keys
 138 under a specific size.  If you don't know for sure that you need it,
 139 you don't.  Leave it @code{nil}.
 140 @end defvar
 141
 142 @node Help For Developers
 143 @chapter Help For Developers
 144
 145 The GnuTLS library is detected automatically at compile time.  You
 146 should see that it's enabled in the @code{configure} output.  If not,
 147 follow the standard procedure for finding out why a system library is
 148 not picked up by the Emacs compilation.  On the W32 (Windows)
 149 platform, installing the DLLs with a recent build should be enough.
 150
 151 Just use @code{open-protocol-stream} or @code{open-network-stream}
 152 (the two are equivalent, the first one being an alias to the second).
 153 You should not have to use the @file{gnutls.el} functions directly.
 154 But you can test them with @code{open-gnutls-stream}.
 155
 156 @defun open-gnutls-stream name buffer host service
 157 This function creates a buffer connected to a specific @var{host} and
 158 @var{service} (port number or service name).  The parameters and their
 159 syntax are the same as those given to @code{open-network-stream}
 160 (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
 161 Manual}).  The connection process is called @var{name} (made unique if
 162 necessary).  This function returns the connection process.
 163
 164 @lisp
 165 ;; open a HTTPS connection
 166 (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")
 167
 168 ;; open a IMAPS connection
 169 (open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
 170 @end lisp
 171
 172 @end defun
 173
 174 The function @code{gnutls-negotiate} is not generally useful and it
 175 may change as needed, so please see @file{gnutls.el} for the details.
 176
 177 @defun gnutls-negotiate spec
 178 Please see @file{gnutls.el} for the @var{spec} details and for usage,
 179 but do not rely on this function's interface if possible.
 180 @end defun
 181
 182 @node GNU Free Documentation License
 183 @appendix GNU Free Documentation License
 184 @include doclicense.texi
 185
 186 @node Function Index
 187 @unnumbered Function Index
 188 @printindex fn
 189
 190 @node Variable Index
 191 @unnumbered Variable Index
 192 @printindex vr
 193
 194 @bye
 195
 196 @c End: