bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in

bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in

[Tara Sawyer]

---
 doc/misc/emacs-gnutls.texi | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi
index add79d12e4..e79174d784 100644
--- a/doc/misc/emacs-gnutls.texi
+++ b/doc/misc/emacs-gnutls.texi
@@ -93,6 +93,24 @@ There's one way to find out if GnuTLS is available, by calling
 @url{http://sourceforge.net/projects/ezwinports/files/} thanks to Eli
 Zaretskii) in the same directory as Emacs, you should be OK.
 
+To debug GnuTLS problems, first check the messages buffer, and then
+check the function below @code{gnutls-log-level}
+
+If GnuTLS is not available as a built-in (@code{gnutls-available-p}
+returns an empty list (), emacs will call out to the @code{gnutls-cli}
+program to perform TLS connections.  If you need to modify
+the command it calls you can do this with the variable
+@code{tls-program}.
+For example, if you want to pin a certificate and use Trust On First
+Use(TOFU), then something like this:
+ @code{(add-to-list 'tls-program "gnutls-cli --tofu --x509cafile %t -p
+ %p %h ")}
+ will probably serve you well.
+
+
+
+@section Functions and Variables
+
 @defun gnutls-available-p
 This function returns non-@code{nil} if GnuTLS is available in this
 instance of Emacs, @code{nil} otherwise.  If GnuTLS is available, the
-- 
2.21.0

bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in

[Noam Postavsky]

Tara Sawyer <tara@anne.cat> writes:
  
> +To debug GnuTLS problems, first check the messages buffer, and then
> +check the function below @code{gnutls-log-level}
> +
> +If GnuTLS is not available as a built-in (@code{gnutls-available-p}
> +returns an empty list (), emacs will call out to the @code{gnutls-cli}
> +program to perform TLS connections.  If you need to modify
> +the command it calls you can do this with the variable
> +@code{tls-program}.
> +For example, if you want to pin a certificate and use Trust On First
> +Use(TOFU), then something like this:
> + @code{(add-to-list 'tls-program "gnutls-cli --tofu --x509cafile %t -p
> + %p %h ")}
> + will probably serve you well.

tls.el is getting obsoleted in Emacs 27 (see Bug#31457), so I don't
think we want to add documentation about it.  Basically, you should only
be using it if you really know what you're doing already.

bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in

[Noam Postavsky]

[-- Attachment #1: Type: text/plain, Size: 82 bytes --]

[forwarding to list, please use "Reply All" to keep 34937@debbugs.gnu.org on Cc]


[-- Attachment #2: Type: message/rfc822, Size: 645 bytes --]

From: Tara Anne <tara@anne.cat>
To: Noam Postavsky <npostavs@gmail.com>
Subject: Re: bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in
Date: Tue, 16 Apr 2019 19:06:25 -0700
Message-ID: <6B139D81-701E-40BF-A05B-FCD6C13CC09A@anne.cat>

Well I have no idea what I’m doing, and was forced to learn it.
But if it’s getting obsoleted, then I agree with you.

Thanks for responding!

bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in

[Noam Postavsky]

> From: Tara Anne <tara@anne.cat>
> Well I have no idea what I’m doing, and was forced to learn it.

Do you mean the builtin gnutls-based functions aren't working for you?

bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in

[Tara Anne]

They were not compiled in to my binary release of emacs. No idea why.
Rather than re-compile I opted to just call out,
Hence this patch.


On Apr 17, 2019, at 4:47 AM, Noam Postavsky <npostavs@gmail.com> wrote:

>> From: Tara Anne <tara@anne.cat>
>> Well I have no idea what I’m doing, and was forced to learn it.
> 
> Do you mean the builtin gnutls-based functions aren't working for you?
> 

bug#34937: [PATCH] update user docs for emacs-gnutls; tofu and program vs built-in

[Noam Postavsky]

tags 34937 wontfix
close 34937
quit

Tara Anne <tara@anne.cat> writes:

> They were not compiled in to my binary release of emacs. No idea why.
> Rather than re-compile I opted to just call out,

Ah, well, you might want to look into getting gnutls working,
considering using the external binary can hit bugs like #15905
"url-copy-file sometimes silently downloads garbage or incomplete file"

Anyway, I'm closing this bug report as wontfix, for reasons mentioned
upthread.