[gnutls-dev] Work in progress: GnuTLS 2.2 release notes on API changes
simon at josefsson.org
Wed Nov 14 17:13:21 CET 2007
I'll roll a gnutls 2.2 release candidate within a few days, and I'm
starting to prepare the release notes for the final release. Since we
are breaking the API/ABI version, we need careful documentation.
Here is a starting point, based on a 'diff -ru' of includes/ between
latest 2.0 and 2.1. What have I missed? Other thoughts? Please let me
know what you think. Language fixes are very appreciated, English isn't
my strong subject... Thoughts on the gnutls_set_default_priority change
are also appreciated.
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
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 information.
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 related to OpenPGP trustdb format have been removed, since
the trustdb was a non-standard GnuPG-specific format. Use key rings
instead. The removed functions and types are:
To align terminology, some functions or types have been renamed.
Compatibility mappings exists. The old and new names of the affected
Old name New name
More information about the Gnutls-devel