path: root/doc/misc/emacs-gnutls.texi

\input texinfo                  @c -*-texinfo-*-

@set VERSION 0.3

@setfilename ../../info/emacs-gnutls.info
@settitle Emacs GnuTLS Integration @value{VERSION}
@include docstyle.texi

@copying
This file describes the Emacs GnuTLS integration.

Copyright @copyright{} 2012--2020 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs network features
@direntry
* Emacs GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration.
@end direntry

@titlepage
@title Emacs GnuTLS Integration
@author by Ted Zlatanov
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Emacs GnuTLS
This manual describes the Emacs GnuTLS integration.

GnuTLS is a library that establishes encrypted @acronym{SSL} or
@acronym{TLS} connections.  Emacs supports it through the
@file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el}
Emacs Lisp library.

@insertcopying

@menu
* Overview::                    Overview of the GnuTLS integration.
* Help For Users::
* Help For Developers::
* GNU Free Documentation License::  The license for this documentation.
* Function Index::
* Variable Index::
@end menu
@end ifnottex

@node Overview
@chapter Overview

The GnuTLS library is an optional add-on for Emacs.  Through it, any
Emacs Lisp program can establish encrypted network connections that
use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer
Security} (@acronym{TLS}) protocols.  The process of using
@acronym{SSL} and @acronym{TLS} in establishing connections is as
automated and transparent as possible.

The user has only a few customization options currently: the log
level, priority string, trustfile list, and the minimum number of bits
to be used in Diffie-Hellman key exchange.  Rumors that every Emacs
library requires at least 83 customizable variables are thus proven
false.

@node Help For Users
@chapter Help For Users

From the user's perspective, there's nothing to the GnuTLS
integration.  It Just Works for any Emacs Lisp code that uses
@code{open-protocol-stream} or @code{open-network-stream}
(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
Manual}).  The two functions are equivalent, the first one being an
alias of the second.

There's one way to find out if GnuTLS is available, by calling
@code{gnutls-available-p}.  This is a little bit trickier on the W32
(Windows) platform, but if you have the GnuTLS DLLs (available from
@url{https://sourceforge.net/projects/ezwinports/files/} thanks to Eli
Zaretskii) in the same directory as Emacs, you should be OK.

@defun gnutls-available-p
This function returns non-@code{nil} if GnuTLS is available in this
instance of Emacs, @code{nil} otherwise.  If GnuTLS is available, the
value is a list of GnuTLS capabilities supported by the installed
GnuTLS library, which depends on the library version.  The meaning of
the capabilities is documented in the doc string of this function.
@end defun

Oh, but sometimes things go wrong.  Budgets aren't balanced,
television ads lie, and even TLS and SSL connections can fail to work
properly.  Well, there's something to be done in the last case.

@defvar gnutls-log-level
The @code{gnutls-log-level} variable sets the log level.  1 is
verbose.  2 is very verbose.  5 is crazy.  Crazy!  Set it to 1 or 2
and look in the @file{*Messages*} buffer for the debugging
information.
@end defvar

@defvar gnutls-algorithm-priority
The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority
string.  This is global, not per host name (although
@code{gnutls-negotiate} supports a priority string per connection so
it could be done if needed).  For details see the
@uref{https://www.gnu.org/software/gnutls/documentation.html, GnuTLS
documentation} and the
@uref{https://gnutls.org/manual/html_node/Priority-Strings.html,
GnuTLS priority string syntax and description}.
@end defvar

@defvar gnutls-trustfiles
The @code{gnutls-trustfiles} variable is a list of trustfiles
(certificates for the issuing authorities).  This is global, not per
host name (although @code{gnutls-negotiate} supports a trustfile per
connection so it could be done if needed).  The trustfiles can be in
PEM or DER format and examples can be found in most Unix
distributions.  By default the following locations are tried in this
order: @file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu,
Gentoo and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for
Fedora and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse;
@file{/usr/ssl/certs/ca-bundle.crt} for Cygwin;
@file{/usr/local/share/certs/ca-root-nss.crt} for FreeBSD@.  You can
easily customize @code{gnutls-trustfiles} to be something else, but
let us know if you do, so we can make the change to benefit the other
users of that platform.
@end defvar

@defvar gnutls-verify-error
The @code{gnutls-verify-error} variable allows you to verify SSL/TLS
server certificates for all connections or by host name.  It defaults
to @code{nil} for now but will likely be changed to @code{t} later,
meaning that all certificates will be verified.

There are two checks available currently, that the certificate has
been issued by a trusted authority as defined by
@code{gnutls-trustfiles}, and that the hostname matches the
certificate.  @code{t} enables both checks, but you can enable them
individually as well with @code{:trustfiles} and @code{:hostname}
instead.

Because of the low-level interactions with the GnuTLS library, there
is no way currently to ask if a certificate can be accepted.  You have
to look in the @file{*Messages*} buffer.
@end defvar

@defvar gnutls-min-prime-bits
The @code{gnutls-min-prime-bits} variable is a pretty exotic
customization for cases where you want to refuse handshakes with keys
under a specific size.  If you don't know for sure that you need it,
you don't.  Leave it @code{nil}.
@end defvar

@node Help For Developers
@chapter Help For Developers

The GnuTLS library is detected automatically at compile time.  You
should see that it's enabled in the @code{configure} output.  If not,
follow the standard procedure for finding out why a system library is
not picked up by the Emacs compilation.  On the W32 (Windows)
platform, installing the DLLs with a recent build should be enough.

Just use @code{open-protocol-stream} or @code{open-network-stream}
(the two are equivalent, the first one being an alias to the second).
You should not have to use the @file{gnutls.el} functions directly.
But you can test them with @code{open-gnutls-stream}.

@defun open-gnutls-stream name buffer host service &optional parameters
This function creates a buffer connected to a specific @var{host} and
@var{service} (port number or service name).  The mandatory arguments
and their syntax are the same as those given to
@code{open-network-stream} (@pxref{Network,, Network Connections,
elisp, The Emacs Lisp Reference Manual}).  The connection process is
called @var{name} (made unique if necessary).  This function returns
the connection process.

The optional @var{parameters} argument is a list of keywords and
values.  The only keywords which currently have any effect are
@code{:client-certificate} and @code{:nowait}.

Passing @w{@code{:client certificate t}} triggers looking up of client
certificates matching @var{host} and @var{service} using the
@file{auth-source} library.  Any resulting client certificates are passed
down to the lower TLS layers.  The format used by @file{.authinfo} to
specify the per-server keys is described in @ref{Help for
users,,auth-source, auth, Emacs auth-source Library}.

Passing @w{@code{:nowait t}} means that the socket should be asynchronous,
and the connection process will be returned to the caller before TLS
negotiation has happened.

For historical reasons @var{parameters} can also be a symbol, which is
interpreted the same as passing a list containing @code{:nowait} and
the value of that symbol.

Example calls:

@lisp
;; open a HTTPS connection
(open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")

;; open a IMAPS connection
(open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
@end lisp

@end defun

@findex gnutls-asynchronous-parameters
If called with @var{nowait}, the process is returned immediately
(before connecting to the server).  In that case, the process object
is told what parameters to use when negotiating the connection
by using the @code{gnutls-asynchronous-parameters} function.

The function @code{gnutls-negotiate} is not generally useful and it
may change as needed, so please see @file{gnutls.el} for the details.

@defun gnutls-negotiate spec
Please see @file{gnutls.el} for the @var{spec} details and for usage,
but do not rely on this function's interface if possible.
@end defun

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@node Function Index
@unnumbered Function Index
@printindex fn

@node Variable Index
@unnumbered Variable Index
@printindex vr

@bye

@c End: