--- /dev/null
+\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:
HCoop / bpt / emacs.git / commitdiff