[gnutls-devel] higher level session API?

Nikos Mavrogiannopoulos nmav at gnutls.org
Mon Jan 28 02:24:40 CET 2013

Ok it seems I'm closer to a simpler API. A draft version is in:

Currently the code to set credentials is the most complex, but overall
it looks quite an improvement in terms of size of code. An example of a
client and a server is at:



On 01/25/2013 05:24 PM, Tim Rühsen wrote:

> Am Mittwoch, 23. Januar 2013 schrieb Nikos Mavrogiannopoulos:
>> On Mon, Jan 21, 2013 at 10:41 AM, Tim Ruehsen <tim.ruehsen at gmx.de> wrote:
>>>> However I'm wondering whether a full higher level API over
>>>> gnutls_session_t is needed, that for example does not require to handle
>>>> non-fatal errors (e.g. GNUTLS_E_AGAIN, or
>>>> GNUTLS_E_WARNING_ALERT_RECEIVED). That would be the equivalent of FILE*
>>>> for a TLS session. Any thoughts?
>>> For an application developer, a high level API that can be used 'quick and
>>> dirty', would reduce the amounts of code and time ot use gnutls.
>>> e.g. like this pseudo code
>>> gnutls_session_t sess = gnutls_open(
>>>         hostname, port,
>>>         // here come *optional* key, value pairs, some examples
>>>         // GNUTLS_READ_TIMEOUT, 5000, // in milliseconds
>>>         // GNUTLS_PRIORITY, "NORMAL:-VERS-SSL3.0",
>>>         // GNUTLS_CHECK_CERTIFICATE, 0, // switch certificate checking on 
> and off
>>>         / ...
>>>         NULL); // gcc >= 4 is able to check this with attribute 'sentinel'
>> That's pretty high level. I think the networking part (i.e. connection
>> to host and resolving) will have to be kept out. Networking
>> applications already have this code and in these cases it may be
>> harder to use that API. I'm thinking of a simpler API that includes
>> the
>> priority string, the check certificate flag, and a credentials structure if 
> any.
> You are right. Maybe the socket descriptor should go to gnutls_open().
> And isn't the hostname needed for host validation while handshaking ? I think 
> about gnutls_x509_crt_check_hostname().
>>> ssize_t nbytes = gnutls_write(sess, buf, buflen);
>>> ssize_t nbytes = gnutls_printf(sess, "%d - %s\n", ival, str);
>>> ssize_t nbytes = gnutls_read(sess, buf, bufsize);
>>> ssize_t nbytes = gnutls_getline(sess, &buf, &bufsize);
>> I like those. I'll try to add them (I think the getline is missing
>> from the current code).
> If it helps, look at my getline() implementation for file descriptors.
> The internal variables are saved at the end of buf, but you won't need this 
> ugly trick since you have a session variable.
> https://github.com/rockdaboot/mget/blob/master/libmget/io.c
>>> The 'open' function should have reasonable default values to work 'right 
> out
>>> of the box'. It should also do gnutls_global_init() implicitely, if it 
> hasn't
>>> be done yet.
>> That one is tricky because it would mean having explicit thread locks
>> (global_init isn't thread safe). I think global_init should be called
>> independently.
> Yes, to avoid thread locks, global_init needs to be called explicitely.
>>> And back to your idea with queue/flush:
>>> - inspired from TCP_CORK, my idea would be something like
>>>         gnutls_cork()
>>>         do some writes
>>>         gnutls_uncork (or calling it gnutls_flush, if you like)
>>> - or/and implementing something like the Nagle algorithm, kind of 
> automatic
>>> cork/uncork
>> Is that for the gnutls_session_t API?
> It was just an idea without thinking about that ;-)
>> It's an interesting idea and may
>> even remove the need of a higher-level API. I'll think about it.
> A higher level API is always good for application programmers to have a fast 
> success (and a short learning time). Later. if things become more wicked, they 
> will investigate into the mid- and/or low-level API.
> Regards, Tim

More information about the Gnutls-devel mailing list