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

[Simon Josefsson]

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:

  DEFAULT
  EXPORT
  PERFORMANCE
  SECURITY

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
gnutls_set_default_priority2() interface.

Thoughts?  Nikos?

/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, 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:

 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 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
 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