[gnutls-dev] Re: GnuTLS 1.2.8 with TLS Inner Application (TLS/IA) support

[Simon Josefsson]

I have added the API below which should remove the need for your hack.
Let me know if you have any thoughts on the API, or can think of any
improvements.

This will be part of 1.3.2 which will likely be released later today.

Thanks,
Simon

** New APIs to access the TLS Pseudo-Random-Function (PRF).
The PRF is used by some protocols building on TLS, such as EAP-PEAP
and EAP-TTLS.  One function to access the raw PRF and one to access
the PRF seeded with the client/server random fields are provided.
Suggested by Jouni Malinen <jkmaline at cc.hut.fi>.

** New APIs to acceess the client and server random fields in a session.
These fields can be useful by protocols using TLS.  Note that these
fields are typically used as input to the TLS PRF, and if this is your
intended use, you should use the TLS PRF API that use the
client/server random field directly.  Suggested by Jouni Malinen
<jkmaline at cc.hut.fi>.

New functions to invoke the TLS Pseudo-Random-Function (PRF):
  gnutls_prf
  gnutls_prf_raw

New functions to retrieve the session's client and server random values:
  gnutls_session_get_server_random
  gnutls_session_get_client_random

/**
 * gnutls_prf_raw - access the TLS PRF directly
 * @session: is a #gnutls_session_t structure.
 * @label_size: length of the @label variable.
 * @label: label used in PRF computation, typically a short string.
 * @seed_size: length of the @seed variable.
 * @seed: optional extra data to seed the PRF with.
 * @outsize: size of pre-allocated output buffer to hold the output.
 * @out: pre-allocate buffer to hold the generated data.
 *
 * Apply the TLS Pseudo-Random-Function (PRF) using the master secret
 * on some data.
 *
 * The @label variable usually contain a string denoting the purpose
 * for the generated data.  The @seed usually contain data such as the
 * client and server random, perhaps together with some additional
 * data that is added to guarantee uniqueness of the output for a
 * particular purpose.
 *
 * Because the output is not guaranteed to be unique for a particular
 * session unless @seed include the client random and server random
 * fields (the PRF would output the same data on another connection
 * resumed from the first one), it is not recommended to use this
 * function directly.  The gnutls_prf() function seed the PRF with the
 * client and server random fields directly, and is recommended if you
 * want to generate pseudo random data unique for each session.
 *
 * Return value: Return 0 on success, or an error code.
 **/
int
gnutls_prf_raw (gnutls_session_t session,
		size_t label_size,
		const char *label,
		size_t seed_size,
		const char *seed,
		size_t outsize,
		char *out);

/**
 * gnutls_prf - derive pseudo-random data using the TLS PRF
 * @session: is a #gnutls_session_t structure.
 * @label_size: length of the @label variable.
 * @label: label used in PRF computation, typically a short string.
 * @server_random_first: non-0 if server random field should be first in seed
 * @extra_size: length of the @extra variable.
 * @extra: optional extra data to seed the PRF with.
 * @outsize: size of pre-allocated output buffer to hold the output.
 * @out: pre-allocate buffer to hold the generated data.
 *
 * Apply the TLS Pseudo-Random-Function (PRF) using the master secret
 * on some data, seeded with the client and server random fields.
 *
 * The @label variable usually contain a string denoting the purpose
 * for the generated data.  The @server_random_first indicate whether
 * the client random field or the server random field should be first
 * in the seed.  Non-0 indicate that the server random field is first,
 * 0 that the client random field is first.
 *
 * The @extra variable can be used to add more data to the seed, after
 * the random variables.  It can be used to tie make sure the
 * generated output is strongly connected to some additional data
 * (e.g., a string used in user authentication).
 *
 * The output is placed in *@OUT, which must be pre-allocated.
 *
 * Return value: Return 0 on success, or an error code.
 **/
int
gnutls_prf (gnutls_session_t session,
	    size_t label_size,
	    const char *label,
	    int server_random_first,
	    size_t extra_size,
	    const char *extra,
	    size_t outsize,
	    char *out);

/**
 * gnutls_session_get_client_random - get the session's client random value
 * @session: is a #gnutls_session_t structure.
 *
 * Return a pointer to the 32-byte client random field used in the
 * session.  The pointer must not be modified or deallocated.
 *
 * If a client random value has not yet been established, the output
 * will be garbage, and in particular a %NULL return value should not
 * be expected.
 *
 * Return value: pointer to client random.
 **/
const char *
gnutls_session_get_client_random (gnutls_session_t session);

/**
 * gnutls_session_get_server_random - get the session's server random value
 * @session: is a #gnutls_session_t structure.
 *
 * Return a pointer to the 32-byte server random field used in the
 * session.  The pointer must not be modified or deallocated.
 *
 * If a server random value has not yet been established, the output
 * will be garbage, and in particular a %NULL return value should not
 * be expected.
 *
 * Return value: pointer to server random.
 **/
const char *
gnutls_session_get_server_random (gnutls_session_t session);