code.delx.au - gnu-emacs/blob - 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 @include docstyle.texi
   8
   9 @copying
  10 This file describes the Emacs GnuTLS integration.
  11
  12 Copyright @copyright{} 2012--2016 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 the following locations are tried in this
 127 order: @file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu,
 128 Gentoo and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for
 129 Fedora and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse;
 130 @file{/usr/ssl/certs/ca-bundle.crt} for Cygwin;
 131 @file{/usr/local/share/certs/ca-root-nss.crt} for FreeBSD.  You can
 132 easily customize @code{gnutls-trustfiles} to be something else, but
 133 let us know if you do, so we can make the change to benefit the other
 134 users of that platform.
 135 @end defvar
 136
 137 @defvar gnutls-verify-error
 138 The @code{gnutls-verify-error} variable allows you to verify SSL/TLS
 139 server certificates for all connections or by host name.  It defaults
 140 to @code{nil} for now but will likely be changed to @code{t} later,
 141 meaning that all certificates will be verified.
 142
 143 There are two checks available currently, that the certificate has
 144 been issued by a trusted authority as defined by
 145 @code{gnutls-trustfiles}, and that the hostname matches the
 146 certificate.  @code{t} enables both checks, but you can enable them
 147 individually as well with @code{:trustfiles} and @code{:hostname}
 148 instead.
 149
 150 Because of the low-level interactions with the GnuTLS library, there
 151 is no way currently to ask if a certificate can be accepted.  You have
 152 to look in the @file{*Messages*} buffer.
 153 @end defvar
 154
 155 @defvar gnutls-min-prime-bits
 156 The @code{gnutls-min-prime-bits} variable is a pretty exotic
 157 customization for cases where you want to refuse handshakes with keys
 158 under a specific size.  If you don't know for sure that you need it,
 159 you don't.  Leave it @code{nil}.
 160 @end defvar
 161
 162 @node Help For Developers
 163 @chapter Help For Developers
 164
 165 The GnuTLS library is detected automatically at compile time.  You
 166 should see that it's enabled in the @code{configure} output.  If not,
 167 follow the standard procedure for finding out why a system library is
 168 not picked up by the Emacs compilation.  On the W32 (Windows)
 169 platform, installing the DLLs with a recent build should be enough.
 170
 171 Just use @code{open-protocol-stream} or @code{open-network-stream}
 172 (the two are equivalent, the first one being an alias to the second).
 173 You should not have to use the @file{gnutls.el} functions directly.
 174 But you can test them with @code{open-gnutls-stream}.
 175
 176 @defun open-gnutls-stream name buffer host service &optional nowait
 177 This function creates a buffer connected to a specific @var{host} and
 178 @var{service} (port number or service name).  The parameters and their
 179 syntax are the same as those given to @code{open-network-stream}
 180 (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
 181 Manual}).  The connection process is called @var{name} (made unique if
 182 necessary).  This function returns the connection process.
 183
 184 The @var{nowait} parameter means that the scoket should be
 185 asynchronous, and the connection process will be returned to the
 186 caller before TLS negotiation has happened.
 187
 188 @lisp
 189 ;; open a HTTPS connection
 190 (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")
 191
 192 ;; open a IMAPS connection
 193 (open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
 194 @end lisp
 195
 196 @end defun
 197
 198 @findex gnutls-asynchronous-parameters
 199 If called with @var{nowait}, the process is returned immediately
 200 (before connecting to the server).  In that case, the process object
 201 is told what parameters to use when negotiating the connection
 202 by using the @code{gnutls-asynchronous-parameters} function.
 203
 204 The function @code{gnutls-negotiate} is not generally useful and it
 205 may change as needed, so please see @file{gnutls.el} for the details.
 206
 207 @defun gnutls-negotiate spec
 208 Please see @file{gnutls.el} for the @var{spec} details and for usage,
 209 but do not rely on this function's interface if possible.
 210 @end defun
 211
 212 @node GNU Free Documentation License
 213 @appendix GNU Free Documentation License
 214 @include doclicense.texi
 215
 216 @node Function Index
 217 @unnumbered Function Index
 218 @printindex fn
 219
 220 @node Variable Index
 221 @unnumbered Variable Index
 222 @printindex vr
 223
 224 @bye
 225
 226 @c End: