[gnutls-dev] Updated release notes about API/ABI break
simon at josefsson.org
Thu Nov 29 15:26:43 CET 2007
Updated to align with 2.1.7. Hopefully this will be the final text.
Backwards incompatible API/ABI 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. This means breaking the
API and ABI backwards compatibility. That is something we try to
avoid unless it is necessary. We decided to also remove the already
deprecated stub functions for X.509 to XML conversion and TLS
authorization (see below) when we had the opportunity.
Generally, most applications does not need to be modified. Just
re-compile them against the latest GnuTLS release, and it should work
Applications that use the OpenPGP or SRP features needs to be
modified. Below is a list of the modified APIs and discussion of what
the minimal things you need to modify in your application to make it
work with GnuTLS 2.2.
Note that GnuTLS 2.2 also introduces new APIs -- such as
gnutls_set_priority() that is superior to
gnutls_set_default_priority() -- that you may want to start using.
However, using those new APIs is not required to use GnuTLS 2.2 since
the old functions continue are still supported. This text only
discuss what you minimally have to modify.
XML related changes
The function `gnutls_x509_crt_to_xml' has been removed. It has been
deprecated and only returned an error code since GnuTLS version
1.2.11. Nobody has complained, so users doesn't seem to miss the
functionality. We don't know of any other library 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. If you want
help to find some other library to use here, please explain and
discuss your use case on help-gnutls at gnu.org.
TLS Authorization related changes
Everything related to TLS authorizations have been removed, they were
only stub functions that returned an error code:
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 SRP example code
(doc/examples/ex-client-srp.c and doc/examples/ex-serv-srp.c) 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 is
used. There are #define's to map the old names to the new. You may
run into problems if you have a switch-case with cases for both SRP
alerts, since they are now mapped to the same value. The solution is
to drop the SRP alerts from such switch cases, as they are now
deprecated in favor of GNUTLS_A_UNKNOWN_PSK_IDENTITY.
OpenPGP related changes
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:
The following functions 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 functions are:
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