From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Ted Zlatanov Newsgroups: gmane.emacs.devel Subject: Re: GnuTLS docs Date: Mon, 09 Apr 2012 08:25:55 -0400 Organization: =?utf-8?B?0KLQtdC+0LTQvtGAINCX0LvQsNGC0LDQvdC+0LI=?= @ Cienfuegos Message-ID: <878vi5nlbg.fsf@lifelogs.com> References: <87d37q7ld4.fsf@gnu.org> <871uo6puac.fsf@gnu.org> <87y5qa72vm.fsf_-_@lifelogs.com> <834nsycjs0.fsf@gnu.org> <87y5qa5chf.fsf@lifelogs.com> <83pqblc2ih.fsf@gnu.org> <87pqbl6c9l.fsf@lifelogs.com> <83d37lb3nu.fsf@gnu.org> <87d37hofbs.fsf@lifelogs.com> <83k41p8ibl.fsf@gnu.org> Reply-To: emacs-devel@gnu.org NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: dough.gmane.org 1333974380 12489 80.91.229.3 (9 Apr 2012 12:26:20 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 9 Apr 2012 12:26:20 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 09 14:26:19 2012 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1SHDfn-0007fq-7L for ged-emacs-devel@m.gmane.org; Mon, 09 Apr 2012 14:26:19 +0200 Original-Received: from localhost ([::1]:41841 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SHDfm-0005Kn-KK for ged-emacs-devel@m.gmane.org; Mon, 09 Apr 2012 08:26:18 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:34193) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SHDfi-0005KX-4j for emacs-devel@gnu.org; Mon, 09 Apr 2012 08:26:16 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SHDff-0003pW-7J for emacs-devel@gnu.org; Mon, 09 Apr 2012 08:26:13 -0400 Original-Received: from plane.gmane.org ([80.91.229.3]:39419) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SHDfe-0003pH-PE for emacs-devel@gnu.org; Mon, 09 Apr 2012 08:26:11 -0400 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1SHDfa-0007af-Nq for emacs-devel@gnu.org; Mon, 09 Apr 2012 14:26:06 +0200 Original-Received: from c-76-28-40-19.hsd1.vt.comcast.net ([76.28.40.19]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 09 Apr 2012 14:26:06 +0200 Original-Received: from tzz by c-76-28-40-19.hsd1.vt.comcast.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 09 Apr 2012 14:26:06 +0200 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: emacs-devel@gnu.org Original-Lines: 326 Original-X-Complaints-To: usenet@dough.gmane.org X-Gmane-NNTP-Posting-Host: c-76-28-40-19.hsd1.vt.comcast.net X-Face: bd.DQ~'29fIs`T_%O%C\g%6jW)yi[zuz6; d4V0`@y-~$#3P_Ng{@m+e4o<4P'#(_GJQ%TT= D}[Ep*b!\e,fBZ'j_+#"Ps?s2!4H2-Y"sx" Mail-Copies-To: never User-Agent: Gnus/5.130004 (Ma Gnus v0.4) Emacs/24.0.95 (gnu/linux) Cancel-Lock: sha1:jC11MM5YW4y2L9NIf64vBADPl7Y= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:149497 Archived-At: --=-=-= Content-Type: text/plain On Mon, 09 Apr 2012 10:39:42 +0300 Eli Zaretskii wrote: >> From: Ted Zlatanov >> 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 look. 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 check? Thanks! Ted --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=emacs-gnutls.doc.patch === 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 + + * Makefile.in: Add emacs-gnutls to the INFO_FILES target. + 2012-04-09 Glenn Morris * 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. 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@ === 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 + + * Makefile.in (INFO_TARGETS): Add gnutls.texi to build. + + * gnutls.texi: New file to explain the GnuTLS integration. + + 2012-04-05 Teodor Zlatanov * 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 $(mkinfodir) === 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-*- + +@setfilename ../../info/gnutls +@settitle Emacs GnuTLS Integration @value{VERSION} + +@set VERSION 0.3 + +@copying +This file describes the Emacs GnuTLS integration. + +Copyright @copyright{} 2008-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: --=-=-=--