Linux Certif

Toute la documentation sur la certification Linux LPI

gnutls_authz_enable

NAME

gnutls_authz_enable - API function

SYNOPSIS

#include <gnutls/gnutls.h>

void gnutls_authz_enable(gnutls_session_t session, const int * client_formats, const int * server_formats, gnutls_authz_recv_callback_func recv_callback, gnutls_authz_send_callback_func send_callback);

ARGUMENTS

gnutls_session_t session

is a gnutls_session_t structure.

const int * client_formats

zero-terminated list of gnutls_authz_data_format_type_t elements with authorization data formats.

const int * server_formats

zero-terminated list of gnutls_authz_data_format_type_t elements with authorization data formats.

gnutls_authz_recv_callback_func recv_callback

your callback function which will receive authz information when it is received.

gnutls_authz_send_callback_func send_callback

your callback function which is responsible for generating authorization data to send.

DESCRIPTION

Indicate willingness to send and receive authorization data, and which formats.

For clients, client_formats indicate which formats the client is willing to send, and server_formats indicate which formats the client can receive.

For servers, client_formats indicate which formats the server is willing to accept from the client, and server_formats indicate which formats the server is willing to send. Before the list is sent to the client, the formats which the client do not support are removed. If no supported formats remains, either or both of the extensions will not be sent.

The send_callback is invoked during the handshake if negotiation of the authorization extension was successful. The function prototype is:

int (*gnutls_authz_send_callback_func) (gnutls_session_t session, const int *client_formats, const int *server_formats);

The client_format contains a list of successfully negotiated formats which the client may send data for to the server. The server_formats contains a list of successfully neogitated formats which the server may send data for to the client. The callback is supposed to invoke gnutls_authz_send_x509_attr_cert(), gnutls_authz_send_saml_assertion(), gnutls_authz_send_x509_attr_cert_url(), or gnutls_authz_send_saml_assertion_url() for the data it wishes to send, passing along the session parameter, and the data. The client_format function should return 0 on success, or an error code, which may be used to abort the handshake on failures.

The recv_callback is invoked during the handshake when authorization data is received. The prototype of the callback should be:

int (*gnutls_authz_recv_callback_func) (gnutls_session_t session, const char *authz_formats, gnutls_datum_t *datums);

The authz_formats contains a list of formats for which data where received. The data for each format is stored in the datums array, where the data associated with the authz_formats[0] format is stored in datums[0]. The function should return 0 on success, but may return an error, which may cause the handshake to abort.

Note that there is no guarantee that send_callback or recv_callback is invoked just because gnutls_authz_enable was invoked. Whether the callbacks are invoked depend on whether negotiation of the extension succeeds. Therefor, if verification of authorization data is done by the recv_callback, care should be made that if the callback is never invoked, it is not interpretetd as successful authorization verification. It is suggested to add some logic check whether authorization data was successfully verified after the call to gnutls_handshake(). That logic could shut down the connection if the authorization data is insufficient.

This function have no effect if it is called during a handshake.

REPORTING BUGS

Report bugs to <bug-gnutls@gnu.org>.

COPYRIGHT

Copyright © 2006, 2007 Free Software Foundation.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

SEE ALSO

The full documentation for gnutls is maintained as a Texinfo manual. If the info and gnutls programs are properly installed at your site, the command

info gnutls

should give you access to the complete manual.