diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/functions/gnutls_prf | 45 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf.short | 1 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_early | 44 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_early.short | 1 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_hash_get | 17 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_hash_get.short | 1 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_raw | 43 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_raw.short | 1 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_rfc5705 | 46 | ||||
| -rw-r--r-- | doc/functions/gnutls_prf_rfc5705.short | 1 |
10 files changed, 200 insertions, 0 deletions
diff --git a/doc/functions/gnutls_prf b/doc/functions/gnutls_prf new file mode 100644 index 0000000..c6e29f2 --- /dev/null +++ b/doc/functions/gnutls_prf @@ -0,0 +1,45 @@ + + + + +@deftypefun {int} {gnutls_prf} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, int @var{server_random_first}, size_t @var{extra_size}, const char * @var{extra}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{server_random_first}: non-zero if server random field should be first in seed + +@var{extra_size}: length of the @code{extra} variable. + +@var{extra}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +Applies the TLS Pseudo-Random-Function (PRF) on the master secret +and the provided data, seeded with the client and server random fields. +For the key expansion specified in RFC5705 see @code{gnutls_prf_rfc5705()} . + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. The @code{server_random_first} indicates whether +the client random field or the server random field should be first +in the seed. Non-zero indicates that the server random field is first, +0 that the client random field is first. + +The @code{extra} variable can be used to add more data to the seed, after +the random variables. It can be used to 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 @code{out} , which must be pre-allocated. + +@strong{Note:} This function produces identical output with @code{gnutls_prf_rfc5705()} +when @code{server_random_first} is set to 0 and @code{extra} is @code{NULL} . Under TLS1.3 +this function will only operate when these conditions are true, or otherwise +return @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun diff --git a/doc/functions/gnutls_prf.short b/doc/functions/gnutls_prf.short new file mode 100644 index 0000000..58a0bfe --- /dev/null +++ b/doc/functions/gnutls_prf.short @@ -0,0 +1 @@ +@item @var{int} @ref{gnutls_prf} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, int @var{server_random_first}, size_t @var{extra_size}, const char * @var{extra}, size_t @var{outsize}, char * @var{out}) diff --git a/doc/functions/gnutls_prf_early b/doc/functions/gnutls_prf_early new file mode 100644 index 0000000..c387362 --- /dev/null +++ b/doc/functions/gnutls_prf_early @@ -0,0 +1,44 @@ + + + + +@deftypefun {int} {gnutls_prf_early} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{context_size}: length of the @code{extra} variable. + +@var{context}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +This function is similar to @code{gnutls_prf_rfc5705()} , but only works in +TLS 1.3 or later to export early keying material. + +Note that the keying material is only available after the +ClientHello message is processed and before the application traffic +keys are established. Therefore this function shall be called in a +handshake hook function for @code{GNUTLS_HANDSHAKE_CLIENT_HELLO} . + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. + +The @code{context} variable can be used to add more data to the seed, after +the random variables. It can be used to 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 @code{out} , which must be pre-allocated. + +Note that, to provide the RFC5705 context, the @code{context} variable +must be non-null. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +@strong{Since:} 3.6.8 +@end deftypefun diff --git a/doc/functions/gnutls_prf_early.short b/doc/functions/gnutls_prf_early.short new file mode 100644 index 0000000..6442803 --- /dev/null +++ b/doc/functions/gnutls_prf_early.short @@ -0,0 +1 @@ +@item @var{int} @ref{gnutls_prf_early} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) diff --git a/doc/functions/gnutls_prf_hash_get b/doc/functions/gnutls_prf_hash_get new file mode 100644 index 0000000..8ada18f --- /dev/null +++ b/doc/functions/gnutls_prf_hash_get @@ -0,0 +1,17 @@ + + + + +@deftypefun {gnutls_digest_algorithm_t} {gnutls_prf_hash_get} (const gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the currently used hash algorithm. In TLS 1.3, the hash +algorithm is used for both the key derivation function and +handshake message authentication code. In TLS 1.2, it matches the +hash algorithm used for PRF. + +@strong{Returns:} the currently used hash algorithm, a +@code{gnutls_digest_algorithm_t} value. + +@strong{Since:} 3.6.13 +@end deftypefun diff --git a/doc/functions/gnutls_prf_hash_get.short b/doc/functions/gnutls_prf_hash_get.short new file mode 100644 index 0000000..01a848c --- /dev/null +++ b/doc/functions/gnutls_prf_hash_get.short @@ -0,0 +1 @@ +@item @var{gnutls_digest_algorithm_t} @ref{gnutls_prf_hash_get} (const gnutls_session_t @var{session}) diff --git a/doc/functions/gnutls_prf_raw b/doc/functions/gnutls_prf_raw new file mode 100644 index 0000000..0058c85 --- /dev/null +++ b/doc/functions/gnutls_prf_raw @@ -0,0 +1,43 @@ + + + + +@deftypefun {int} {gnutls_prf_raw} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{seed_size}, const char * @var{seed}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{seed_size}: length of the @code{seed} variable. + +@var{seed}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +Apply the TLS Pseudo-Random-Function (PRF) on the master secret +and the provided data. + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. The @code{seed} usually contains 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 @code{seed} includes 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 @code{gnutls_prf()} function seeds 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. + +@strong{Note:} This function will only operate under TLS versions prior to 1.3. +In TLS1.3 the use of PRF is replaced with HKDF and the generic +exporters like @code{gnutls_prf_rfc5705()} should be used instead. Under +TLS1.3 this function returns @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun diff --git a/doc/functions/gnutls_prf_raw.short b/doc/functions/gnutls_prf_raw.short new file mode 100644 index 0000000..0c84e86 --- /dev/null +++ b/doc/functions/gnutls_prf_raw.short @@ -0,0 +1 @@ +@item @var{int} @ref{gnutls_prf_raw} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{seed_size}, const char * @var{seed}, size_t @var{outsize}, char * @var{out}) diff --git a/doc/functions/gnutls_prf_rfc5705 b/doc/functions/gnutls_prf_rfc5705 new file mode 100644 index 0000000..f559b75 --- /dev/null +++ b/doc/functions/gnutls_prf_rfc5705 @@ -0,0 +1,46 @@ + + + + +@deftypefun {int} {gnutls_prf_rfc5705} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{context_size}: length of the @code{extra} variable. + +@var{context}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +Exports keying material from TLS/DTLS session to an application, as +specified in RFC5705. + +In the TLS versions prior to 1.3, it applies the TLS +Pseudo-Random-Function (PRF) on the master secret and the provided +data, seeded with the client and server random fields. + +In TLS 1.3, it applies HKDF on the exporter master secret derived +from the master secret. + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. + +The @code{context} variable can be used to add more data to the seed, after +the random variables. It can be used to 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 @code{out} , which must be pre-allocated. + +Note that, to provide the RFC5705 context, the @code{context} variable +must be non-null. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +@strong{Since:} 3.4.4 +@end deftypefun diff --git a/doc/functions/gnutls_prf_rfc5705.short b/doc/functions/gnutls_prf_rfc5705.short new file mode 100644 index 0000000..cf3d183 --- /dev/null +++ b/doc/functions/gnutls_prf_rfc5705.short @@ -0,0 +1 @@ +@item @var{int} @ref{gnutls_prf_rfc5705} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) |