[gnutls-devel] gnutls_record_cork and maximum record size

[Jaak Ristioja]

On 19.12.2014 08:55, Nikos Mavrogiannopoulos wrote:
> On Wed, 2014-12-17 at 16:04 +0200, Jaak Ristioja wrote:
>> Hello!
>>
>> The documentation for gnutls_record_cork() states:
>>
>>   If called gnutls_record_send() will no longer send partial records.
>> All queued records will be sent when gnutls_uncork() is called, or when
>> the maximum record size is reached.
>>
>> As I understand the documentation, it implies that if the session is
>> corked by gnutls_record_cork() and the size of the data queued by
>> successive calls to gnutls_record_send() reaches the maximum record
>> size, then gnutls_record_get_max_size() bytes of data are passed to the
>> underlying transport. However, the source code for gnutls_record_send()
>> implies that if the session is corked then data is queued until
>> gnutls_record_uncork() is called (or GNUTLS_E_MEMORY_ERROR is returned).
>> Do I misunderstand the documentation or is there a discrepancy between
>> the source code and the documentation?
> 
> No you don't misunderstand the documentation, it is wrong. I'll update
> it to match the current behavior of the code.

Why not instead update the code to match the documentation? :D There
might also be other projects who rely on the previously released
documentation to be correct and might hit similar issues with a lot of
queued records.

+ * If called, gnutls_record_send() will no longer send partial records.
+ * All queued records will be sent when gnutls_uncork() is called.

This is still somewhat confusing as the first sentence might imply that
complete records will still be sent. Why not write something like this:

  If called, gnutls_record_send() will no longer send any records until
  gnutls_record_uncork() is called. Instead, gnutls_record_send() will
  try to buffer all data passed to it. The data buffered by
  gnutls_record_send() will be sent when gnutls_record_uncork() is
  called.

Because essentially, a gnutls_record_cork() call, followed by a number
of gnutls_record_send() calls, followed by a gnutls_record_uncork() call
is just a way of concatenating the data before it is finally passed to
the underlying TLS implementation as a single chunk of memory.


Best regards,
Jaak Ristioja
Cybernetica AS


PS: Please note that the documentation uses gnutls_cork() and
gnutls_uncork() instead of gnutls_record_cork() and gnutls_record_uncork().