mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-28 10:56:36 +00:00
894e21df1e
* doc/lispref/processes.texi (Network Processes): Clarify the meaning of :tls-parameters. * lisp/net/gnutls.el (open-gnutls-stream): Clarify :nowait. * lisp/net/gnutls.el (gnutls-boot-parameters): Factor out into own function. (gnutls-negotiate): Use it. (open-gnutls-stream): Ditto. * src/eval.c (vformat_string): Refactor out the printing bits from verror. (verror): Use it. * src/gnutls.c (boot_error): Mark failed processes with the real error message. * src/lisp.h: Declare vformat_string.
227 lines
8.2 KiB
Plaintext
227 lines
8.2 KiB
Plaintext
\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--2016 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{http://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 @code{t} if GnuTLS is available in this instance of Emacs.
|
|
@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). The priority string syntax is in the
|
|
@uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS
|
|
documentation}.
|
|
@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 nowait
|
|
This function creates a buffer connected to a specific @var{host} and
|
|
@var{service} (port number or service name). The parameters 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 @var{nowait} parameter means that the scoket should be
|
|
asynchronous, and the connection process will be returned to the
|
|
caller before TLS negotiation has happened.
|
|
|
|
@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:
|