[gnutls-dev] Work in progress: GnuTLS 2.2 release notes on API changes
simon at josefsson.org
Thu Nov 15 11:03:17 CET 2007
Updated release notes wrt to the API/ABI changes below.
After consideration, I believe we should revert the change to deprecate
gnutls_set_default_priority(). It is a widely used function and
gnutls_set_default_priority2() doesn't offer any significant difference
for most applications. I think people will think that we just change
the API for no reason if we make this change. What do others think?
Nikos is this ok with you?
Further, I believe we could improve the gnutls_set_default_priority2()
API. Right now it is difficult to use from applications. Each
application would need to have a configuration file token (e.g.,
'gnutls-priority: EXPORT') or command line parameter (e.g.,
--gnutls-priority PERFORMANCE) that map to the GnuTLS enum types. A
serious problem is that there would be no consistency between GnuTLS
applications on what the enum names should be and their meaning.
I think it would be better if we had a function like:
int gnutls_set_priority (gnutls_session_t session,
const char *priority);
It would take strings that can be set by users in application
configuration files or command line parameters. GnuTLS could define a
couple of strings:
etc. Eventually we could even support something like OpenSSL's priority
strings, which allow things similar to 'DEFAULT:-AES' to use the
defaults, but remove all AES ciphers.
This interface seems more flexible than the
API changes in GnuTLS 2.2
To adapt to changes in the TLS extension specifications for OpenPGP
and SRP, the GnuTLS API had to be modified. Since we had to modify
the API, we decided to do some long pending API cleanups as well.
Generally, most applications do not need to be modified. Just
re-compile it against the latest GnuTLS release should work. However,
applications that use the OpenPGP or SRP features needs to be
modified. Below is a list of the modified APIs and discussion of what
you need to modify in your application.
The functions `gnutls_set_default_priority',
`gnutls_set_default_export_priority' have been replaced by
`gnutls_set_default_priority2'. There are compatibility mappings from
the old names to the new. (XXX: do we really need to do this? Seems
frivolous to me, at least `gnutls_set_default_priority' is very common,
and could be kept around and supported in the future.)
The function `gnutls_x509_crt_to_xml' was removed, it has not done
anything (except returning an error code) since around GnuTLS 1.2.
Nobody has complained, so users doesn't seem to miss the
functionality. We don't know of any libraries to convert X.509
certificates into XML format, but we decided (long ago) that GnuTLS
isn't the right place for this kind of functionality.
SRP related changes
The callback gnutls_srp_client_credentials_function has a new
prototype, and its semantic has changed. You need to rewrite the
callback, see the updated function documentation and examples for more
The alert codes GNUTLS_A_MISSING_SRP_USERNAME and
GNUTLS_A_UNKNOWN_SRP_USERNAME are no longer used by the SRP
specification, instead the GNUTLS_A_UNKNOWN_PSK_IDENTITY alert should
be used. There are #define's to map the old names to the new.
OpenPGP related changes
The functions `gnutls_certificate_set_openpgp_key_file',
`gnutls_certificate_set_openpgp_keyring_file' has an added parameter
of the (new) type `gnutls_openpgp_crt_fmt_t'. The type specify the
format of the data (binary or base64).
The function `gnutls_certificate_set_openpgp_keyserver' have been
removed. There is no replacement functionality inside GnuTLS. If you
need keyserver functionality, consider using the GnuPG tools.
All functions, types, and error codes related to OpenPGP trustdb
format have been removed. The trustdb format is a non-standard
GnuPG-specific format, and we recommend you to use key rings instead.
The following have been removed:
To improve terminology and align with the X.509 interface, some
functions have been renamed. Compatibility mappings exists. The old
and new names of the affected functions and types are:
Old name New name
More information about the Gnutls-devel