[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: GnuTLS docs

From: Ted Zlatanov
Subject: Re: GnuTLS docs
Date: Mon, 09 Apr 2012 08:25:55 -0400
User-agent: Gnus/5.130004 (Ma Gnus v0.4) Emacs/24.0.95 (gnu/linux)

On Mon, 09 Apr 2012 10:39:42 +0300 Eli Zaretskii <address@hidden> wrote: 

>> From: Ted Zlatanov <address@hidden>
>> Date: Sun, 08 Apr 2012 21:37:43 -0400
>> Thanks, Eli.  Could you take a look at the attached first draft?

EZ> Looks good, thanks.  A few comments below.

Thanks for the comments.  I've used all of them and the doc looks
better.  See attached the proposed patch that modifies all the
Makefile.in mentions and names the new file emacs-gnutls.texi.  Take a

I don't know if I've done the info addition correctly.  I think so, but
`make' keeps re-running `makeinfo' in the doc/misc directory.  Could you


=== modified file 'ChangeLog'
--- ChangeLog   2012-04-09 06:40:20 +0000
+++ ChangeLog   2012-04-09 12:21:51 +0000
@@ -1,3 +1,7 @@
+2012-04-09  Teodor Zlatanov  <address@hidden>
+       * Makefile.in: Add emacs-gnutls to the INFO_FILES target.
 2012-04-09  Glenn Morris  <address@hidden>
        * Makefile.in (leim): Check cd return value.  Pass fewer variables.

=== modified file 'Makefile.in'
--- Makefile.in 2012-04-09 06:40:20 +0000
+++ Makefile.in 2012-04-09 12:16:18 +0000
@@ -136,11 +136,11 @@
 # system, it is inappropriate to imply that it is part of Emacs.
 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".

=== modified file 'doc/misc/ChangeLog'
--- doc/misc/ChangeLog  2012-04-06 01:56:38 +0000
+++ doc/misc/ChangeLog  2012-04-09 12:02:11 +0000
@@ -1,3 +1,10 @@
+2012-04-09  Teodor Zlatanov  <address@hidden>
+       * Makefile.in (INFO_TARGETS): Add gnutls.texi to build.
+       * gnutls.texi: New file to explain the GnuTLS integration.
 2012-04-05  Teodor Zlatanov  <address@hidden>
        * auth.texi (Secret Service API): Edit further and give examples.

=== modified file 'doc/misc/Makefile.in'
--- doc/misc/Makefile.in        2012-01-19 07:21:25 +0000
+++ doc/misc/Makefile.in        2012-04-09 12:08:26 +0000
@@ -68,6 +68,7 @@
        $(infodir)/flymake \
        $(infodir)/forms \
        $(infodir)/gnus \
+       $(infodir)/emacs-gnutls \
        $(infodir)/idlwave \
        $(infodir)/info \
        $(infodir)/mairix-el \
@@ -119,6 +120,7 @@
        flymake.dvi \
        forms.dvi \
        gnus.dvi \
+       emacs-gnutls.dvi \
        idlwave.dvi \
        info.dvi \
        mairix-el.dvi \
@@ -170,6 +172,7 @@
        flymake.pdf \
        forms.pdf \
        gnus.pdf \
+       emacs-gnutls.pdf \
        idlwave.pdf \
        info.pdf \
        mairix-el.pdf \
@@ -342,6 +345,15 @@
 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

=== added file 'doc/misc/emacs-gnutls.texi'
--- doc/misc/emacs-gnutls.texi  1970-01-01 00:00:00 +0000
+++ doc/misc/emacs-gnutls.texi  2012-04-09 11:58:41 +0000
@@ -0,0 +1,198 @@
+\input texinfo                  @c -*-texinfo-*-
address@hidden ../../info/gnutls
address@hidden Emacs GnuTLS Integration @value{VERSION}
address@hidden VERSION 0.3
+This file describes the Emacs GnuTLS integration.
+Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.
+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.
address@hidden quotation
address@hidden copying
address@hidden Emacs lisp libraries
+* GnuTLS: (gnutls).          The Emacs GnuTLS Integration.
address@hidden direntry
address@hidden Emacs GnuTLS Integration
address@hidden by Ted Zlatanov
address@hidden 0pt plus 1filll
address@hidden titlepage
address@hidden Top
address@hidden Emacs GnuTLS
+This manual describes the Emacs GnuTLS integration.
+GnuTLS is a library that establishes encrypted @acronym{SSL} or
address@hidden connections.  Emacs supports it through the
address@hidden and @file{gnutls.h} C files and the @file{gnutls.el}
+Emacs Lisp library.
+* Overview::                    Overview of the GnuTLS integration.
+* Help For Users::
+* Help For Developers::
+* Function Index::
+* Variable Index::
address@hidden menu
address@hidden ifnottex
address@hidden Overview
address@hidden 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
address@hidden 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
address@hidden Help For Users
address@hidden 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
address@hidden 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
address@hidden  This is a little bit trickier on the W32
+(Windows) platform, but if you have the GnuTLS DLLs (available from
address@hidden://sourceforge.net/projects/ezwinports/files/} thanks to Eli
+Zaretskii) in the same directory as Emacs, you should be OK.
address@hidden gnutls-available-p
+This function returns t if GnuTLS is available in this instance of Emacs.
address@hidden 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.
address@hidden 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
address@hidden defvar
address@hidden gnutls-algorithm-priority
+The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority
+string.  This is global, not per host name (although
address@hidden supports a priority string per connection so
+it could be done if needed).  The priority string syntax is in the
address@hidden://www.gnu.org/software/gnutls/documentation.html, GnuTLS
address@hidden defvar
address@hidden 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:
address@hidden/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;
address@hidden/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.
address@hidden defvar
address@hidden 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}.
address@hidden defvar
address@hidden Help For Developers
address@hidden 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}.
address@hidden open-gnutls-stream name buffer host service
+This function creates a buffer connected to a specific @var{host} and
address@hidden (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.
+;; 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")
address@hidden lisp
address@hidden 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.
address@hidden 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.
address@hidden defun
address@hidden Function Index
address@hidden Function Index
address@hidden fn
address@hidden Variable Index
address@hidden Variable Index
address@hidden vr
address@hidden End:

reply via email to

[Prev in Thread] Current Thread [Next in Thread]