Permalink
Browse files

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.
  • Loading branch information...
1 parent 0fc749f commit a7b156135f7ebbbf22bf9dcfbfd13e5f9f3e4669 @tzz tzz committed Apr 9, 2012
Showing with 230 additions and 5 deletions.
  1. +6 −0 ChangeLog
  2. +5 −5 Makefile.in
  3. +8 −0 doc/misc/ChangeLog
  4. +12 −0 doc/misc/Makefile.in
  5. +198 −0 doc/misc/emacs-gnutls.texi
  6. +1 −0 info/dir
View
@@ -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.
View
@@ -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@
View
@@ -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.
View
@@ -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)
View
@@ -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:
View
@@ -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

0 comments on commit a7b1561

Please sign in to comment.