[gnutls-dev] Work in progress: GnuTLS 2.2 release notes on API changes

[Simon Josefsson]

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.

/Simon

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.

General changes
---------------

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_key_mem',
`gnutls_certificate_set_openpgp_keyring_mem', and
`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:

 gnutls_certificate_set_openpgp_trustdb
 gnutls_openpgp_trustdb_init
 gnutls_openpgp_trustdb_deinit
 gnutls_openpgp_trustdb_import
 gnutls_openpgp_key_verify_trustdb
 gnutls_openpgp_trustdb_t
 GNUTLS_E_OPENPGP_TRUSTDB_VERSION_UNSUPPORTED

To align terminology, some functions or types have been renamed.
Compatibility mappings exists.  The old and new names of the affected
functions are:

        Old name                                New name
 gnutls_openpgp_key_init                 gnutls_openpgp_crt_init
 gnutls_openpgp_key_deinit               gnutls_openpgp_crt_deinit
 gnutls_openpgp_key_import               gnutls_openpgp_crt_import
 gnutls_openpgp_key_export               gnutls_openpgp_crt_export
 gnutls_openpgp_key_get_key_usage        gnutls_openpgp_crt_get_key_usage
 gnutls_openpgp_key_get_fingerprint      gnutls_openpgp_crt_get_fingerprint
 gnutls_openpgp_key_get_pk_algorithm     gnutls_openpgp_crt_get_pk_algorithm
 gnutls_openpgp_key_get_name             gnutls_openpgp_crt_get_name
 gnutls_openpgp_key_get_version          gnutls_openpgp_crt_get_version
 gnutls_openpgp_key_get_creation_time    gnutls_openpgp_crt_get_creation_time
 gnutls_openpgp_key_get_expiration_time  gnutls_openpgp_crt_get_expiration_time
 gnutls_openpgp_key_get_id               gnutls_openpgp_crt_get_id
 gnutls_openpgp_key_check_hostname       gnutls_openpgp_crt_check_hostname
 gnutls_openpgp_send_key                 gnutls_openpgp_send_cert
 gnutls_openpgp_key_status_t             gnutls_openpgp_crt_status_t
 GNUTLS_OPENPGP_KEY                      GNUTLS_OPENPGP_CERT
 GNUTLS_OPENPGP_KEY_FINGERPRINT          GNUTLS_OPENPGP_CERT_FINGERPRINT
 gnutls_openpgp_key_t                    gnutls_openpgp_crt_t