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--2017 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 non-@code{nil} if GnuTLS is available in this
  98 instance of Emacs, @code{nil} otherwise.  If GnuTLS is available, the
  99 value is a list of GnuTLS capabilities supported by the installed
 100 GnuTLS library, which depends on the library version.  The meaning of
 101 the capabilities is documented in the doc string of this function.
 102 @end defun
 103
 104 Oh, but sometimes things go wrong.  Budgets aren't balanced,
 105 television ads lie, and even TLS and SSL connections can fail to work
 106 properly.  Well, there's something to be done in the last case.
 107
 108 @defvar gnutls-log-level
 109 The @code{gnutls-log-level} variable sets the log level.  1 is
 110 verbose.  2 is very verbose.  5 is crazy.  Crazy!  Set it to 1 or 2
 111 and look in the @file{*Messages*} buffer for the debugging
 112 information.
 113 @end defvar
 114
 115 @defvar gnutls-algorithm-priority
 116 The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority
 117 string.  This is global, not per host name (although
 118 @code{gnutls-negotiate} supports a priority string per connection so
 119 it could be done if needed).  The priority string syntax is in the
 120 @uref{https://www.gnu.org/software/gnutls/documentation.html, GnuTLS
 121 documentation}.
 122 @end defvar
 123
 124 @defvar gnutls-trustfiles
 125 The @code{gnutls-trustfiles} variable is a list of trustfiles
 126 (certificates for the issuing authorities).  This is global, not per
 127 host name (although @code{gnutls-negotiate} supports a trustfile per
 128 connection so it could be done if needed).  The trustfiles can be in
 129 PEM or DER format and examples can be found in most Unix
 130 distributions.  By default the following locations are tried in this
 131 order: @file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu,
 132 Gentoo and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for
 133 Fedora and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse;
 134 @file{/usr/ssl/certs/ca-bundle.crt} for Cygwin;
 135 @file{/usr/local/share/certs/ca-root-nss.crt} for FreeBSD.  You can
 136 easily customize @code{gnutls-trustfiles} to be something else, but
 137 let us know if you do, so we can make the change to benefit the other
 138 users of that platform.
 139 @end defvar
 140
 141 @defvar gnutls-verify-error
 142 The @code{gnutls-verify-error} variable allows you to verify SSL/TLS
 143 server certificates for all connections or by host name.  It defaults
 144 to @code{nil} for now but will likely be changed to @code{t} later,
 145 meaning that all certificates will be verified.
 146
 147 There are two checks available currently, that the certificate has
 148 been issued by a trusted authority as defined by
 149 @code{gnutls-trustfiles}, and that the hostname matches the
 150 certificate.  @code{t} enables both checks, but you can enable them
 151 individually as well with @code{:trustfiles} and @code{:hostname}
 152 instead.
 153
 154 Because of the low-level interactions with the GnuTLS library, there
 155 is no way currently to ask if a certificate can be accepted.  You have
 156 to look in the @file{*Messages*} buffer.
 157 @end defvar
 158
 159 @defvar gnutls-min-prime-bits
 160 The @code{gnutls-min-prime-bits} variable is a pretty exotic
 161 customization for cases where you want to refuse handshakes with keys
 162 under a specific size.  If you don't know for sure that you need it,
 163 you don't.  Leave it @code{nil}.
 164 @end defvar
 165
 166 @node Help For Developers
 167 @chapter Help For Developers
 168
 169 The GnuTLS library is detected automatically at compile time.  You
 170 should see that it's enabled in the @code{configure} output.  If not,
 171 follow the standard procedure for finding out why a system library is
 172 not picked up by the Emacs compilation.  On the W32 (Windows)
 173 platform, installing the DLLs with a recent build should be enough.
 174
 175 Just use @code{open-protocol-stream} or @code{open-network-stream}
 176 (the two are equivalent, the first one being an alias to the second).
 177 You should not have to use the @file{gnutls.el} functions directly.
 178 But you can test them with @code{open-gnutls-stream}.
 179
 180 @defun open-gnutls-stream name buffer host service &optional nowait
 181 This function creates a buffer connected to a specific @var{host} and
 182 @var{service} (port number or service name).  The parameters and their
 183 syntax are the same as those given to @code{open-network-stream}
 184 (@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
 185 Manual}).  The connection process is called @var{name} (made unique if
 186 necessary).  This function returns the connection process.
 187
 188 The @var{nowait} parameter means that the socket should be
 189 asynchronous, and the connection process will be returned to the
 190 caller before TLS negotiation has happened.
 191
 192 @lisp
 193 ;; open a HTTPS connection
 194 (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")
 195
 196 ;; open a IMAPS connection
 197 (open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
 198 @end lisp
 199
 200 @end defun
 201
 202 @findex gnutls-asynchronous-parameters
 203 If called with @var{nowait}, the process is returned immediately
 204 (before connecting to the server).  In that case, the process object
 205 is told what parameters to use when negotiating the connection
 206 by using the @code{gnutls-asynchronous-parameters} function.
 207
 208 The function @code{gnutls-negotiate} is not generally useful and it
 209 may change as needed, so please see @file{gnutls.el} for the details.
 210
 211 @defun gnutls-negotiate spec
 212 Please see @file{gnutls.el} for the @var{spec} details and for usage,
 213 but do not rely on this function's interface if possible.
 214 @end defun
 215
 216 @node GNU Free Documentation License
 217 @appendix GNU Free Documentation License
 218 @include doclicense.texi
 219
 220 @node Function Index
 221 @unnumbered Function Index
 222 @printindex fn
 223
 224 @node Variable Index
 225 @unnumbered Variable Index
 226 @printindex vr
 227
 228 @bye
 229
 230 @c End: