LIBGNUTLS_EXTRA_VERSION

#define     LIBGNUTLS_EXTRA_VERSION

gnutls_openpgp_recv_key_func ()

int         (*gnutls_openpgp_recv_key_func) (gnutls_session_t session,
                                             unsigned char *keyfpr,
                                             unsigned int keyfpr_length,
                                             gnutls_datum_t *key);

A callback of this type is used to retrieve OpenPGP keys. Only useful on the server, and will only be used if the peer send a key fingerprint instead of a full key. See also gnutls_openpgp_set_recv_key_function().

gnutls_openpgp_set_recv_key_function ()

void        gnutls_openpgp_set_recv_key_function
                                            (gnutls_session_t session,
                                             gnutls_openpgp_recv_key_funcfunc );

This funtion will set a key retrieval function for OpenPGP keys. This callback is only useful in server side, and will be used if the peer sent a key fingerprint instead of a full key.

gnutls_certificate_set_openpgp_key_file ()

int         gnutls_certificate_set_openpgp_key_file
                                            (gnutls_certificate_credentials_tres ,
                                             const char *CERTFILE,
                                             const char *KEYFILE);

This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. It doesn't matter whether the keys are armored or not, but the files should only contain one key which should not be encrypted.

gnutls_certificate_set_openpgp_key_mem ()

int         gnutls_certificate_set_openpgp_key_mem
                                            (gnutls_certificate_credentials_tres ,
                                             const gnutls_datum_t *CERT,
                                             const gnutls_datum_t *KEY);

This funtion is used to load OpenPGP keys into the GnuTLS credential structure. It doesn't matter whether the keys are armored or not, but the files should only contain one key which should not be encrypted.

gnutls_certificate_set_openpgp_keyserver ()

int         gnutls_certificate_set_openpgp_keyserver
                                            (gnutls_certificate_credentials_tres ,
                                             const char *keyserver,
                                             int port);

This funtion will set a key server for use with openpgp keys. This key server will only be used if the peer sends a key fingerprint instead of a key in the handshake. Using a key server may delay the handshake process.

gnutls_certificate_set_openpgp_trustdb ()

int         gnutls_certificate_set_openpgp_trustdb
                                            (gnutls_certificate_credentials_tres ,
                                             const char *trustdb);

This funtion will set a GnuPG trustdb which will be used in key verification functions. Only version 3 trustdb files are supported.

gnutls_certificate_set_openpgp_keyring_mem ()

int         gnutls_certificate_set_openpgp_keyring_mem
                                            (gnutls_certificate_credentials_t c,
                                             unsigned char *data,
                                             size_t dlen);

The function is used to set keyrings that will be used internally by various OpenPGP functions. For example to find a key when it is needed for an operations. The keyring will also be used at the verification functions.

gnutls_certificate_set_openpgp_keyring_file ()

int         gnutls_certificate_set_openpgp_keyring_file
                                            (gnutls_certificate_credentials_t c,
                                             const char *file);

The function is used to set keyrings that will be used internally by various OpenPGP functions. For example to find a key when it is needed for an operations. The keyring will also be used at the verification functions.

enum gnutls_ia_apptype_t

  typedef enum
  {
    GNUTLS_IA_APPLICATION_PAYLOAD = 0,
    GNUTLS_IA_INTERMEDIATE_PHASE_FINISHED = 1,
    GNUTLS_IA_FINAL_PHASE_FINISHED = 2
  } gnutls_ia_apptype_t;

gnutls_ia_avp_func ()

int         (*gnutls_ia_avp_func)           (gnutls_session_t session,
                                             void *ptr,
                                             const char *last,
                                             size_t lastlen,
                                             char **next,
                                             size_t *nextlen);

gnutls_ia_free_client_credentials ()

void        gnutls_ia_free_client_credentials
                                            (gnutls_ia_client_credentials_t sc);

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.

gnutls_ia_allocate_client_credentials ()

int         gnutls_ia_allocate_client_credentials
                                            (gnutls_ia_client_credentials_t *sc);

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it.

Adding this credential to a session will enable TLS/IA, and will require an Application Phase after the TLS handshake (if the server support TLS/IA). Use gnutls_ia_require_inner_phase() to toggle the TLS/IA mode.

gnutls_ia_free_server_credentials ()

void        gnutls_ia_free_server_credentials
                                            (gnutls_ia_server_credentials_t sc);

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.

gnutls_ia_allocate_server_credentials ()

int         gnutls_ia_allocate_server_credentials
                                            (gnutls_ia_server_credentials_t *sc);

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it.

Adding this credential to a session will enable TLS/IA, and will require an Application Phase after the TLS handshake (if the client support TLS/IA). Use gnutls_ia_require_inner_phase() to toggle the TLS/IA mode.

gnutls_ia_set_client_avp_function ()

void        gnutls_ia_set_client_avp_function
                                            (gnutls_ia_client_credentials_t cred,
                                             gnutls_ia_avp_func avp_func);

Set the TLS/IA AVP callback handler used for the session.

The AVP callback is called to process AVPs received from the server, and to get a new AVP to send to the server.

The callback's function form is: int (*avp_func) (gnutls_session_t session, void *ptr, const char *last, size_t lastlen, char **next, size_t *nextlen);

The session parameter is the gnutls_session_t structure corresponding to the current session. The ptr parameter is the application hook pointer, set through gnutls_ia_set_client_avp_ptr(). The AVP received from the server is present in last of lastlen size, which will be NULL on the first invocation. The newly allocated output AVP to send to the server should be placed in *next of *nextlen size.

The callback may invoke gnutls_ia_permute_inner_secret() to mix any generated session keys with the TLS/IA inner secret.

Return 0 (GNUTLS_IA_APPLICATION_PAYLOAD) on success, or a negative error code to abort the TLS/IA handshake.

Note that the callback must use allocate the next parameter using gnutls_malloc(), because it is released via gnutls_free() by the TLS/IA handshake function.

gnutls_ia_set_client_avp_ptr ()

void        gnutls_ia_set_client_avp_ptr    (gnutls_ia_client_credentials_t cred,
                                             void *ptr);

Sets the pointer that will be provided to the TLS/IA callback function as the first argument.

gnutls_ia_get_client_avp_ptr ()

void*       gnutls_ia_get_client_avp_ptr    (gnutls_ia_client_credentials_tcred );

gnutls_ia_set_server_avp_function ()

void        gnutls_ia_set_server_avp_function
                                            (gnutls_ia_server_credentials_t cred,
                                             gnutls_ia_avp_func avp_func);

gnutls_ia_set_server_avp_ptr ()

void        gnutls_ia_set_server_avp_ptr    (gnutls_ia_server_credentials_t cred,
                                             void *ptr);

Sets the pointer that will be provided to the TLS/IA callback function as the first argument.

gnutls_ia_get_server_avp_ptr ()

void*       gnutls_ia_get_server_avp_ptr    (gnutls_ia_server_credentials_tcred );

gnutls_ia_handshake_p ()

int         gnutls_ia_handshake_p           (gnutls_session_t session);

Predicate to be used after gnutls_handshake() to decide whether to invoke gnutls_ia_handshake(). Usable by both clients and servers.

gnutls_ia_handshake ()

int         gnutls_ia_handshake             (gnutls_session_t session);

Perform a TLS/IA handshake. This should be called after gnutls_handshake() iff gnutls_ia_handshake_p().

Return 0 on success, or an error code.

gnutls_ia_permute_inner_secret ()

int         gnutls_ia_permute_inner_secret  (gnutls_session_t session,
                                             size_t session_keys_size,
                                             const char *session_keys);

Permute the inner secret using the generated session keys.

This can be called in the TLS/IA AVP callback to mix any generated session keys with the TLS/IA inner secret.

gnutls_ia_endphase_send ()

int         gnutls_ia_endphase_send         (gnutls_session_t session,
                                             int final_p);

Send a TLS/IA end phase message.

In the client, this should only be used to acknowledge an end phase message sent by the server.

In the server, this can be called instead of gnutls_ia_send() if the server wishes to end an application phase.

gnutls_ia_verify_endphase ()

int         gnutls_ia_verify_endphase       (gnutls_session_t session,
                                             const char *checksum);

Verify TLS/IA end phase checksum data. If verification fails, the GNUTLS_A_INNER_APPLICATION_VERIFICATION alert is sent to the other sie.

This function is called when gnutls_ia_recv() return GNUTLS_E_WARNING_IA_IPHF_RECEIVED or GNUTLS_E_WARNING_IA_FPHF_RECEIVED.

gnutls_ia_send ()

ssize_t     gnutls_ia_send                  (gnutls_session_t session,
                                             const char *data,
                                             size_t sizeofdata);

Send TLS/IA application payload data. This function has the similar semantics with send(). The only difference is that is accepts a GNUTLS session, and uses different error codes.

The TLS/IA protocol is synchronous, so you cannot send more than one packet at a time. The client always send the first packet.

To finish an application phase in the server, use gnutls_ia_endphase_send(). The client cannot end an application phase unilaterally; rather, a client is required to respond with an endphase of its own if gnutls_ia_recv indicates that the server has sent one.

If the EINTR is returned by the internal push function (the default is send()} then GNUTLS_E_INTERRUPTED will be returned. If GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call this function again, with the same parameters; alternatively you could provide a NULL pointer for data, and 0 for size.

gnutls_ia_recv ()

ssize_t     gnutls_ia_recv                  (gnutls_session_t session,
                                             char *data,
                                             size_t sizeofdata);

Receive TLS/IA data. This function has the similar semantics with recv(). The only difference is that is accepts a GNUTLS session, and uses different error codes.

If the server attempt to finish an application phase, this function will return GNUTLS_E_WARNING_IA_IPHF_RECEIVED or GNUTLS_E_WARNING_IA_FPHF_RECEIVED. The caller should then invoke gnutls_ia_verify_endphase(), and if it runs the client side, also send an endphase message of its own using gnutls_ia_endphase_send.

If EINTR is returned by the internal push function (the default is code{recv()}) then GNUTLS_E_INTERRUPTED will be returned. If GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call this function again, with the same parameters; alternatively you could provide a NULL pointer for data, and 0 for size.

gnutls_ia_generate_challenge ()

int         gnutls_ia_generate_challenge    (gnutls_session_t session,
                                             size_t buffer_size,
                                             char *buffer);

Generate an application challenge that the client cannot control or predict, based on the TLS/IA inner secret.

gnutls_ia_extract_inner_secret ()

void        gnutls_ia_extract_inner_secret  (gnutls_session_t session,
                                             char *buffer);

Copy the 48 bytes large inner secret into the specified buffer

This function is typically used after the TLS/IA handshake has concluded. The TLS/IA inner secret can be used as input to a PRF to derive session keys. Do not use the inner secret directly as a session key, because for a resumed session that does not include an application phase, the inner secret will be identical to the inner secret in the original session. It is important to include, for example, the client and server randomness when deriving a sesssion key from the inner secret.

gnutls_ia_enable ()

void        gnutls_ia_enable                (gnutls_session_t session,
                                             int allow_skip_on_resume);

Specify whether we must advertise support for the TLS/IA extension during the handshake.

At the client side, we always advertise TLS/IA if gnutls_ia_enable was called before the handshake; at the server side, we also require that the client has advertised that it wants to run TLS/IA before including the advertisement, as required by the protocol.

Similarly, at the client side we always advertise that we allow TLS/IA to be skipped for resumed sessions if allow_skip_on_resume is non-zero; at the server side, we also require that the session is indeed resumable and that the client has also advertised that it allows TLS/IA to be skipped for resumed sessions.

After the TLS handshake, call gnutls_ia_handshake_p() to find out whether both parties agreed to do a TLS/IA handshake, before calling gnutls_ia_handshake() or one of the lower level gnutls_ia_* functions.

gnutls_global_init_extra ()

int         gnutls_global_init_extra        (void);

This function initializes the global state of gnutls-extra library to defaults. Returns zero on success.

Note that gnutls_global_init() has to be called before this function. If this function is not called then the gnutls-extra library will not be usable.

gnutls_extra_check_version ()

const char* gnutls_extra_check_version      (const char *req_version);

Check that the version of the gnutls-extra library is at minimum the requested one and return the version string; return NULL if the condition is not satisfied. If a NULL is passed to this function, no check is done, but the version string is simply returned.