procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add documentation for the Emacs GnuTLS integration.

Browse source 
* info/dir (File):
* Makefile.in: Add emacs-gnutls to the info directory and the
INFO_FILES target.

* doc/misc/emacs-gnutls.texi: Add documentation for the GnuTLS integration.

* doc/misc/gnutls.texi: New file to explain the GnuTLS integration.

* doc/misc/Makefile.in: Add gnutls.texi to build.
This commit is contained in:
Ted Zlatanov 2012-04-09 09:10:22 -04:00
parent fb7ada5f94
commit 6b4f4a2d6b
6 changed files with 230 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
2012-04-09 Teodor Zlatanov <tzz@lifelogs.com>
* info/dir (File):
* Makefile.in: Add emacs-gnutls to the info directory and the
INFO_FILES target.
2012-04-09 Glenn Morris <rgm@gnu.org>
* Makefile.in (leim): Check cd return value. Pass fewer variables.

10
Makefile.in
View file

@ -136,11 +136,11 @@ MAN_PAGES=ctags.1 ebrowse.1 emacs.1 emacsclient.1 etags.1 \
# system, it is inappropriate to imply that it is part of Emacs.
infodir=@infodir@
INFO_FILES=ada-mode auth autotype calc ccmode cl dbus dired-x ebrowse \
ede ediff edt eieio efaq eintr elisp emacs emacs-mime epa erc \
ert eshell eudc flymake forms gnus idlwave info mairix-el \
message mh-e newsticker nxml-mode org pcl-cvs pgg rcirc \
reftex remember sasl sc semantic ses sieve smtpmail speedbar \
tramp url vip viper widget woman
ede ediff edt eieio efaq eintr elisp emacs emacs-gnutls \
emacs-mime epa erc ert eshell eudc flymake forms gnus \
idlwave info mairix-el message mh-e newsticker nxml-mode \
org pcl-cvs pgg rcirc reftex remember sasl sc semantic ses \
sieve smtpmail speedbar tramp url vip viper widget woman
# If no makeinfo was found and configured --without-makeinfo, "no"; else "yes".
HAVE_MAKEINFO=@HAVE_MAKEINFO@

8
doc/misc/ChangeLog
View file

@ -1,3 +1,11 @@
2012-04-09 Teodor Zlatanov <tzz@lifelogs.com>
* Makefile.in: Add gnutls.texi to build.
* gnutls.texi: New file to explain the GnuTLS integration.
* emacs-gnutls.texi: Add documentation for the GnuTLS integration.
2012-04-05 Teodor Zlatanov <tzz@lifelogs.com>
* auth.texi (Secret Service API): Edit further and give examples.

12
doc/misc/Makefile.in
View file

@ -68,6 +68,7 @@ INFO_TARGETS = \
$(infodir)/flymake \
$(infodir)/forms \
$(infodir)/gnus \
$(infodir)/emacs-gnutls \
$(infodir)/idlwave \
$(infodir)/info \
$(infodir)/mairix-el \
@ -119,6 +120,7 @@ DVI_TARGETS = \
flymake.dvi \
forms.dvi \
gnus.dvi \
emacs-gnutls.dvi \
idlwave.dvi \
info.dvi \
mairix-el.dvi \
@ -170,6 +172,7 @@ PDF_TARGETS = \
flymake.pdf \
forms.pdf \
gnus.pdf \
emacs-gnutls.pdf \
idlwave.pdf \
info.pdf \
mairix-el.pdf \
@ -342,6 +345,15 @@ eieio.dvi: ${srcdir}/eieio.texi
eieio.pdf: ${srcdir}/eieio.texi
$(ENVADD) $(TEXI2PDF) $<
emacs-gnutls : $(infodir)/emacs-gnutls
$(infodir)/emacs-gnutls: emacs-gnutls.texi
$(mkinfodir)
cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $<
emacs-gnutls.dvi: ${srcdir}/emacs-gnutls.texi
$(ENVADD) $(TEXI2DVI) $<
emacs-gnutls.pdf: ${srcdir}/emacs-gnutls.texi
$(ENVADD) $(TEXI2PDF) $<
emacs-mime : $(infodir)/emacs-mime
$(infodir)/emacs-mime: emacs-mime.texi
$(mkinfodir)

198
doc/misc/emacs-gnutls.texi Normal file
View file

@ -0,0 +1,198 @@
\input texinfo @c -*-texinfo-*-
@setfilename ../../info/emacs-gnutls
@settitle Emacs GnuTLS Integration @value{VERSION}
@set VERSION 0.3
@copying
This file describes the Emacs GnuTLS integration.
Copyright @copyright{} 2012 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''
in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs lisp libraries
@direntry
* GnuTLS: (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::
* 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 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 @code{*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 four 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. 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-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
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.
@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
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 Function Index
@chapter Function Index
@printindex fn
@node Variable Index
@chapter Variable Index
@printindex vr
@bye
@c End:

1
info/dir
View file

@ -40,6 +40,7 @@ Emacs editing modes
Emacs network features
* EUDC: (eudc). Emacs client for directory servers (LDAP, PH).
* Gnus: (gnus). The newsreader Gnus.
* GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration.
* Mairix: (mairix-el). Emacs interface to the Mairix mail indexer.
* MH-E: (mh-e). Emacs interface to the MH mail system.
* Message: (message). Mail and news composition mode that