emacs-gnutls: Help For Users
2 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 ‘open-protocol-stream’
or ‘open-network-stream’ (
Network Connections (elisp)Network.).
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
‘gnutls-available-p’. This is a little bit trickier on the W32
(Windows) platform, but if you have the GnuTLS DLLs (available from
<http://sourceforge.net/projects/ezwinports/files/> thanks to Eli
Zaretskii) in the same directory as Emacs, you should be OK.
-- Function: gnutls-available-p
This function returns ‘t’ if GnuTLS is available in this instance
of Emacs.
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.
-- Variable: gnutls-log-level
The ‘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 ‘*Messages*’ buffer for the debugging information.
-- Variable: gnutls-algorithm-priority
The ‘gnutls-algorithm-priority’ variable sets the GnuTLS priority
string. This is global, not per host name (although
‘gnutls-negotiate’ supports a priority string per connection so it
could be done if needed). The priority string syntax is in the
GnuTLS documentation
(http://www.gnu.org/software/gnutls/documentation.html).
-- Variable: gnutls-trustfiles
The ‘gnutls-trustfiles’ variable is a list of trustfiles
(certificates for the issuing authorities). This is global, not
per host name (although ‘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 the following locations are tried in
this order: ‘/etc/ssl/certs/ca-certificates.crt’ for Debian,
Ubuntu, Gentoo and Arch Linux; ‘/etc/pki/tls/certs/ca-bundle.crt’
for Fedora and RHEL; ‘/etc/ssl/ca-bundle.pem’ for Suse;
‘/usr/ssl/certs/ca-bundle.crt’ for Cygwin;
‘/usr/local/share/certs/ca-root-nss.crt’ for FreeBSD. You can
easily customize ‘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.
-- Variable: gnutls-verify-error
The ‘gnutls-verify-error’ variable allows you to verify SSL/TLS
server certificates for all connections or by host name. It
defaults to ‘nil’ for now but will likely be changed to ‘t’ later,
meaning that all certificates will be verified.
There are two checks available currently, that the certificate has
been issued by a trusted authority as defined by
‘gnutls-trustfiles’, and that the hostname matches the certificate.
‘t’ enables both checks, but you can enable them individually as
well with ‘:trustfiles’ and ‘:hostname’ instead.
Because of the low-level interactions with the GnuTLS library,
there is no way currently to ask if a certificate can be accepted.
You have to look in the ‘*Messages*’ buffer.
-- Variable: gnutls-min-prime-bits
The ‘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 ‘nil’.
Info Catalog
emacs-gnutls: Overview
emacs-gnutls: Top
emacs-gnutls: Help For Developers