From 6b4f4a2d6badbe414c8b662feeac3db8edcbda89 Mon Sep 17 00:00:00 2001 From: Ted Zlatanov Date: Mon, 9 Apr 2012 09:10:22 -0400 Subject: [PATCH] Add documentation for the Emacs GnuTLS integration. * 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. --- ChangeLog | 6 ++ Makefile.in | 10 +- doc/misc/ChangeLog | 8 ++ doc/misc/Makefile.in | 12 +++ doc/misc/emacs-gnutls.texi | 198 +++++++++++++++++++++++++++++++++++++ info/dir | 1 + 6 files changed, 230 insertions(+), 5 deletions(-) create mode 100644 doc/misc/emacs-gnutls.texi diff --git a/ChangeLog b/ChangeLog index 2fe50a6d83..a1b9a9ca7d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2012-04-09 Teodor Zlatanov + + * info/dir (File): + * Makefile.in: Add emacs-gnutls to the info directory and the + INFO_FILES target. + 2012-04-09 Glenn Morris * Makefile.in (leim): Check cd return value. Pass fewer variables. diff --git a/Makefile.in b/Makefile.in index 3ee5e8ae8e..8851384162 100644 --- a/Makefile.in +++ b/Makefile.in @@ -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@ diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index e2f2c94967..ee6b7606c5 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,11 @@ +2012-04-09 Teodor Zlatanov + + * 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 * auth.texi (Secret Service API): Edit further and give examples. diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 6fd0b983b8..429b84abf8 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 \ @@ -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) diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi new file mode 100644 index 0000000000..d429f21fbf --- /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/info/dir b/info/dir index 06ee2ab824..d18a38cefa 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.20.1