Re: Emacs core TLS support

[Chong Yidong <cyd@stupidchicken.com>]

Hi Ted,

Thanks for bringing up the patch again.  I haven't read it closely, but
here are some initial remarks and questions:


Ted Zlatanov <tzz@lifelogs.com> writes:

> +  do {
> +    rtnval = gnutls_read( state, buf, nbyte);
> +    printf("read %d bytes\n", rtnval);
> +  } while( rtnval==GNUTLS_E_INTERRUPTED || rtnval==GNUTLS_E_AGAIN);

You should use the GNU style here.

> +DEFUN ("gnutls-init", Fgnutls_init, Sgnutls_init, 2, 2, 0,
> +       doc: /* Initializes GNU TLS for process PROC for use as CONNECTION-END.

This should be "Initialize" instead of "Initializes".

In general, this docstring is not very informative.  I have not been
following this patch closely; just from reading the docstring, I'm not
sure what gnutls-init is supposed to do.  I assume that it means that,
once it is called, all data sent from Emacs to the process PROC, and
vice versa, will be encrypted using the GnuTLS library.  Is that right?
Does `gnutls-handshake' need to be called before, or after, this?  What
happens if you try to send data to PROC before `gnutls-handshake'?
These issues should be explained in the docstring.

More generally, why do we need to a separate `gnutls-init' call, instead
of making `gnutls-handshake' and other functions automatically enable
GnuTLS functionality for the process?

> +DEFUN ("gnutls-deinit", Fgnutls_deinit, Sgnutls_deinit, 1, 1, 0,

I think this should be called `gnutls-stop' or something like that;
"deinit" is not a proper word.  Maybe rename `gnutls-init' to
`gnutls-start'.

> +DEFUN ("gnutls-global-init", Fgnutls_global_init,
> +       Sgnutls_global_init, 0, 0, 0,
> +       doc: /* Initializes global GNU TLS state to defaults.
> +Call `gnutls-global-deinit' when GNU TLS usage is no longer needed.
> +Returns zero on success. */)

This is again not very informative.  Does it mean that it is equivalent
to calling `gnutls-init' on every process by default?

> +DEFUN ("gnutls-global-deinit", Fgnutls_global_deinit,

Again, "deinit" should not be used.

> +DEFUN ("gnutls-protocol-set-priority", Fgnutls_protocol_set_priority,
> +       Sgnutls_protocol_set_priority, 1, MANY, 0,
> +       doc: /* Sets the priority on the protocol versions supported by GNU TLS for PROCESS.
> +The first parameter must be a process.	Subsequent parameters should
> +be integers.  Priority is higher for protocols specified before

Use the word "argument" instead of "parameter".  Also, there is some
formatting mix-up in this and other docstrings.