From 5f9a4e98c0b364521a25e9d5cb62ba21544bf309 Mon Sep 17 00:00:00 2001 From: Teodor Zlatanov Date: Thu, 12 Apr 2012 19:59:47 -0400 Subject: [PATCH] Backport addition of emacs-gnutls manual from trunk --- ChangeLog | 4 + doc/misc/ChangeLog | 10 ++ doc/misc/Makefile.in | 12 +++ doc/misc/emacs-gnutls.texi | 198 +++++++++++++++++++++++++++++++++++++ doc/misc/makefile.w32-in | 11 ++- info/dir | 1 + 6 files changed, 233 insertions(+), 3 deletions(-) create mode 100644 doc/misc/emacs-gnutls.texi diff --git a/ChangeLog b/ChangeLog index 8aee7b2ce40..b4f37a8f3e8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2012-04-12 Teodor Zlatanov + + * info/dir, Makefile.in (INFO_FILES): Add emacs-gnutls. + 2012-03-04 Paul Eggert configure: fix ncurses 'configure' issue on Solaris 10 (Bug#10677) diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index f1eff10c7cd..55a745d14c6 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,13 @@ +2012-04-12 Eli Zaretskii + + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add emacs-gnutls. + ($(infodir)/emacs-gnutls, emacs-gnutls.dvi): New targets. + +2012-04-12 Teodor Zlatanov + + * emacs-gnutls.texi: Add documentation for the GnuTLS integration. + * Makefile.in: Add emacs-gnutls.texi to build. + 2012-04-11 Alan Mackenzie * cc-mode.texi (c-offsets-alist): Correct a typo. diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 647f00723b1..60c11d78261 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -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 \ @@ -344,6 +347,15 @@ eieio.dvi: ${srcdir}/eieio.texi eieio.pdf: ${srcdir}/eieio.texi $(ENVADD) $(TEXI2PDF) ${srcdir}/eieio.texi +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) diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi new file mode 100644 index 00000000000..d429f21fbf6 --- /dev/null +++ b/doc/misc/emacs-gnutls.texi @@ -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: diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in index 6e4a65c292c..0f81786cdb5 100644 --- a/doc/misc/makefile.w32-in +++ b/doc/misc/makefile.w32-in @@ -51,7 +51,7 @@ INFO_TARGETS = $(infodir)/ccmode \ $(infodir)/remember $(infodir)/nxml-mode \ $(infodir)/epa $(infodir)/mairix-el $(infodir)/sasl \ $(infodir)/auth $(infodir)/eieio $(infodir)/ede \ - $(infodir)/semantic $(infodir)/edt + $(infodir)/semantic $(infodir)/edt $(infodir)/emacs-gnutls DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \ ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ sieve.dvi pgg.dvi mh-e.dvi \ @@ -62,7 +62,7 @@ DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \ newsticker.dvi rcirc.dvi erc.dvi ert.dvi \ remember.dvi nxml-mode.dvi \ epa.dvi mairix-el.dvi sasl.dvi auth.dvi eieio.dvi ede.dvi \ - semantic.dvi edt.dvi + semantic.dvi edt.dvi emacs-gnutls.dvi INFOSOURCES = info.texi # The following rule does not work with all versions of `make'. @@ -350,6 +350,11 @@ $(infodir)/edt: edt.texi doclicense.texi edt.dvi: edt.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/edt.texi +$(infodir)/emacs-gnutls: emacs-gnutls.texi doclicense.texi + $(MAKEINFO) $(MAKEINFO_OPTS) emacs-gnutls.texi +emacs-gnutls.dvi: emacs-gnutls.texi doclicense.texi + $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-gnutls.texi + mostlyclean: - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* @@ -377,7 +382,7 @@ clean: mostlyclean $(infodir)/epa* $(infodir)/sasl* \ $(infodir)/mairix-el* $(infodir)/auth* \ $(infodir)/eieio* $(infodir)/ede* \ - $(infodir)/semantic* $(infodir)edt* + $(infodir)/semantic* $(infodir)edt* $(infodir)/emacs-gnutls* distclean: clean - $(DEL) makefile diff --git a/info/dir b/info/dir index 06ee2ab8240..d18a38cefa6 100644 --- a/info/dir +++ b/info/dir @@ -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 -- 2.39.2