Improve GTK-DOC coverage.

[gnutls.git] / doc / announcement-template.txt

We are proud to announce a new stable GnuTLS release: Version 2.8.0.

GnuTLS is a modern C library that implements the standard network
security protocol Transport Layer Security (TLS), for use by network
applications.  GnuTLS is developed for GNU/Linux, but works on many
Unix-like systems and comes with a binary installer for Windows.

The GnuTLS library is distributed under the terms of the GNU Lesser
General Public License version 2.1 (or later).  The "extra" GnuTLS
library (which contains TLS/IA support, LZO compression and Libgcrypt
FIPS-mode handler), the OpenSSL compatibility library, the self tests
and the command line tools are all distributed under the GNU General
Public License version 3.0 (or later).  The manual is distributed
under the GNU Free Documentation License version 1.3 (or later).

The project page of the library is available at:
  http://www.gnu.org/software/gnutls/

What's New
==========

Version 2.8.0 is the first stable release on the 2.8.x branch and is
the result of 7 months of work on the experimental 2.7.x branch.

** lib: Linker version scripts reduces number of exported symbols.
The linker version script now lists all exported ABIs explicitly, to
avoid accidentally exporting unintended functions.  Compared to
before, most symbols beginning with _gnutls* are no longer exported.
These functions have never been intended for use by applications, and
there were no prototypes for these function in the public header
files.  Thus we believe it is possible to do this without incrementing
the library ABI version which normally has to be done when removing an
interface.

** lib: Limit exported symbols on systems without LD linker scripts.
Before all symbols were exported.  Now we limit the exported symbols
to (for libgnutls and libgnutls-extra) gnutls* and (for libgnutls)
_gnutls*.  This is a superset of the actual supported ABI, but still
an improvement compared to before.  This is implemented using Libtool
-export-symbols-regex.  It is more portable than linker version
scripts.

** libgnutls: Fix namespace issue with version symbols.
The symbols LIBGNUTLS_VERSION, LIBGNUTLS_VERSION_MAJOR,
LIBGNUTLS_VERSION_MINOR, LIBGNUTLS_VERSION_PATCH, and
LIBGNUTLS_VERSION_NUMBER were renamed to GNUTLS_VERSION_NUMBER,
GNUTLS_VERSION_MAJOR, GNUTLS_VERSION_MINOR, GNUTLS_VERSION_PATCH, and
GNUTLS_VERSION_NUMBER respectively.  The old symbols will continue to
work but are deprecated.

** libgnutls: Fix namespace issue with version symbol for libgnutls-extra.
The symbol LIBGNUTLS_EXTRA_VERSION were renamed to
GNUTLS_EXTRA_VERSION.  The old symbol will continue to work but is
deprecated.

** libgnutls: Add functions to verify a hash against a certificate.
gnutls_x509_crt_verify_hash: ADDED
gnutls_x509_crt_get_verify_algorithm: ADDED

** gnutls-serv: Listen on all interfaces, including both IPv4 and IPv6.

** i18n: The GnuTLS gettext domain is now 'libgnutls' instead of 'gnutls'.
It is currently only used by the core library.  This will enable a new
domain 'gnutls' for translations of the command line tools.

** certtool: Query for multiple dnsName subjectAltName in interactive mode.
This applies both to generating certificates and certificate requests.

** gnutls-cli: No longer accepts V1 CAs by default during X.509 chain verify.
Use --priority NORMAL:%VERIFY_ALLOW_X509_V1_CA_CRT to permit V1 CAs to
be used for chain verification.

** gnutls-serv: No longer disable MAC padding by default.
Use --priority NORMAL:%COMPAT to disable MAC padding again.

** gnutls-cli: Certificate information output format changed.
The tool now uses libgnutls' functions to print certificate
information.  This avoids code duplication.

** libgnutls: New priority strings %VERIFY_ALLOW_SIGN_RSA_MD5
** and %VERIFY_ALLOW_X509_V1_CA_CRT.
They can be used to override the default certificate chain validation
behaviour.

** libgnutls: gnutls_x509_crt_print prints signature algorithm in oneline mode.

** libgnutls: gnutls_openpgp_crt_print supports oneline mode.

** libgnutls: gnutls_handshake when sending client hello during a
rehandshake, will not offer a version number larger than the current.

** libgnutls: New interface to get key id for certificate requests.
gnutls_x509_crq_get_key_id: ADDED.

** libgnutls: gnutls_x509_crq_print will now also print public key id.

** certtool: --verify-chain now prints results of using library verification.
Earlier, certtool --verify-chain used its own validation algorithm
which wasn't guaranteed to give the same result as the libgnutls
internal validation algorithm.  Now this command print a new final
line with header 'Chain verification output:' that contains the result
from using the internal verification algorithm on the same chain.

** libgnutls: Libgcrypt initialization changed.
If libgcrypt has not already been initialized, GnuTLS will now
initialize libgcrypt with disabled secure memory.  Initialize
libgcrypt explicitly in your application if you want to enable secure
memory.  Before GnuTLS initialized libgcrypt to use GnuTLS's memory
allocation functions, which doesn't use secure memory, so there is no
real change in behaviour.

** libgnutls: Small byte reads via gnutls_record_recv() optimized.

** gnutls-cli: Return non-zero exit code on error conditions.

** gnutls-cli: Corrected bug which caused a rehandshake request to be ignored.

** certtool: allow setting arbitrary key purpose object identifiers.

** libgnutls: Change detection of when to use a linker version script.
Use --enable-ld-version-script or --disable-ld-version-script to
override auto-detection logic.

** Fix warnings and build GnuTLS with more warnings enabled.

** New API to set X.509 credentials from PKCS#12 memory structure.
gnutls_certificate_set_x509_simple_pkcs12_mem: ADDED

** Old libgnutls.m4 and libgnutls-config scripts removed.
Please use pkg-config instead.

** libgnutls: Added functions to handle CRL extensions.
gnutls_x509_crl_get_authority_key_id: ADDED
gnutls_x509_crl_get_number: ADDED
gnutls_x509_crl_get_extension_oid: ADDED
gnutls_x509_crl_get_extension_info: ADDED
gnutls_x509_crl_get_extension_data: ADDED
gnutls_x509_crl_set_authority_key_id: ADDED
gnutls_x509_crl_set_number: ADDED

** libgnutls: Added functions to handle X.509 extensions in Certificate
Requests.
gnutls_x509_crq_get_key_rsa_raw: ADDED
gnutls_x509_crq_get_attribute_info: ADDED
gnutls_x509_crq_get_attribute_data: ADDED
gnutls_x509_crq_get_extension_info: ADDED
gnutls_x509_crq_get_extension_data: ADDED
gnutls_x509_crq_get_key_usage: ADDED
gnutls_x509_crq_get_basic_constraints: ADDED
gnutls_x509_crq_get_subject_alt_name: ADDED
gnutls_x509_crq_get_subject_alt_othername_oid: ADDED
gnutls_x509_crq_get_extension_by_oid: ADDED
gnutls_x509_crq_set_subject_alt_name: ADDED
gnutls_x509_crq_set_basic_constraints: ADDED
gnutls_x509_crq_set_key_usage: ADDED
gnutls_x509_crq_get_key_purpose_oid: ADDED
gnutls_x509_crq_set_key_purpose_oid: ADDED
gnutls_x509_crq_print: ADDED
gnutls_x509_crt_set_crq_extensions: ADDED

** certtool: Print and set CRL and CRQ extensions.

** minitasn1: Internal copy updated to libtasn1 v2.1.
GnuTLS should work fine with libtasn1 v1.x and that is still
supported.

** examples: Now released into the public domain.
This makes the license of the example code compatible with more
licenses, including the (L)GPL.

** The Texinfo and GTK-DOC manuals were improved.

** Several self-tests were added and others improved.

API/ABI changes in GnuTLS 2.8
=============================

No offically supported interfaces have been modified or removed.  The
library should be completely backwards compatible on both the source
and binary level.

The shared library no longer exports some symbols that have never been
officially supported, i.e., not mentioned in any of the header files.
The symbols are:

  _gnutls*
  gnutls_asn1_tab
  
Normally when symbols are removed, the shared library version has to
be incremented.  This leads to a significant cost for everyone using
the library.  Because none of the above symbols have ever been
intended for use by well-behaved applications, we decided that the it
would be better for those applications to pay the price rather than
incurring problems on the majority of applications.

If it turns out that applications have been using unofficial
interfaces, we will need to release a follow-on release on the v2.8
branch to exports additional interfaces.  However, initial testing
suggests that few if any applications have been using any of the
internal symbols.

Although not a new change compared to 2.6.x, we'd like to remind you
interfaces have been modified so that X.509 chain verification now
also checks activation/expiration times on certificates.  The affected
functions are:

gnutls_x509_crt_list_verify: CHANGED, checks activation/expiration times.
gnutls_certificate_verify_peers: Likewise.
gnutls_certificate_verify_peers2: Likewise.
GNUTLS_CERT_NOT_ACTIVATED: ADDED.
GNUTLS_CERT_EXPIRED: ADDED.
GNUTLS_VERIFY_DISABLE_TIME_CHECKS: ADDED.

This change in behaviour was made during the GnuTLS 2.6.x cycle, and
we gave our rationale for it in earlier release notes.

The following symbols have been added to the library:

gnutls_certificate_set_x509_simple_pkcs12_mem: ADDED
gnutls_x509_crl_get_authority_key_id: ADDED
gnutls_x509_crl_get_extension_data: ADDED
gnutls_x509_crl_get_extension_info: ADDED
gnutls_x509_crl_get_extension_oid: ADDED
gnutls_x509_crl_get_number: ADDED
gnutls_x509_crl_set_authority_key_id: ADDED
gnutls_x509_crl_set_number: ADDED
gnutls_x509_crq_get_attribute_data: ADDED
gnutls_x509_crq_get_attribute_info: ADDED
gnutls_x509_crq_get_basic_constraints: ADDED
gnutls_x509_crq_get_extension_by_oid: ADDED
gnutls_x509_crq_get_extension_data: ADDED
gnutls_x509_crq_get_extension_info: ADDED
gnutls_x509_crq_get_key_id: ADDED.
gnutls_x509_crq_get_key_purpose_oid: ADDED
gnutls_x509_crq_get_key_rsa_raw: ADDED
gnutls_x509_crq_get_key_usage: ADDED
gnutls_x509_crq_get_subject_alt_name: ADDED
gnutls_x509_crq_get_subject_alt_othername_oid: ADDED
gnutls_x509_crq_print: ADDED
gnutls_x509_crq_set_basic_constraints: ADDED
gnutls_x509_crq_set_key_purpose_oid: ADDED
gnutls_x509_crq_set_key_usage: ADDED
gnutls_x509_crq_set_subject_alt_name: ADDED
gnutls_x509_crt_get_verify_algorithm: ADDED
gnutls_x509_crt_set_crq_extensions: ADDED
gnutls_x509_crt_verify_hash: ADDED

The following interfaces have been added to the header files:

GNUTLS_VERSION: ADDED, replaces LIBGNUTLS_VERSION.
GNUTLS_VERSION_MAJOR: ADDED, replaces LIBGNUTLS_VERSION_MAJOR.
GNUTLS_VERSION_MINOR: ADDED, replaces LIBGNUTLS_VERSION_MINOR.
GNUTLS_VERSION_PATCH: ADDED, replaces LIBGNUTLS_VERSION_PATCH.
GNUTLS_VERSION_NUMBER: ADDED, replaces LIBGNUTLS_VERSION_NUMBER.
GNUTLS_EXTRA_VERSION: ADDED, replaces LIBGNUTLS_EXTRA_VERSION.

The following interfaces have been deprecated:

LIBGNUTLS_VERSION: DEPRECATED.
LIBGNUTLS_VERSION_MAJOR: DEPRECATED.
LIBGNUTLS_VERSION_MINOR: DEPRECATED.
LIBGNUTLS_VERSION_PATCH: DEPRECATED.
LIBGNUTLS_VERSION_NUMBER: DEPRECATED.
LIBGNUTLS_EXTRA_VERSION: DEPRECATED.

Getting the Software
====================

GnuTLS may be downloaded from one of the mirror sites or direct from
<ftp://ftp.gnu.org/gnu/gnutls/>.  The list of mirrors can be found at
<http://www.gnu.org/software/gnutls/download.html>.

Here are the BZIP2 compressed sources (6.0MB):

  ftp://ftp.gnu.org/gnu/gnutls/gnutls-2.8.0.tar.bz2
  http://ftp.gnu.org/gnu/gnutls/gnutls-2.8.0.tar.bz2

Here are OpenPGP detached signatures signed using key 0xB565716F:

  ftp://ftp.gnu.org/gnu/gnutls/gnutls-2.8.0.tar.bz2.sig
  http://ftp.gnu.org/gnu/gnutls/gnutls-2.8.0.tar.bz2.sig

Note, that we don't distribute gzip compressed tarballs.

In order to check that the version of GnuTLS which you are going to
install is an original and unmodified one, you should verify the OpenPGP
signature.  You can use the command

     gpg --verify gnutls-2.8.0.tar.bz2.sig

This checks whether the signature file matches the source file.  You
should see a message indicating that the signature is good and made by
that signing key.  Make sure that you have the right key, either by
checking the fingerprint of that key with other sources or by checking
that the key has been signed by a trustworthy other key.  The signing
key can be identified with the following information:

pub   1280R/B565716F 2002-05-05 [expires: 2010-04-21]
      Key fingerprint = 0424 D4EE 81A0 E3D1 19C6  F835 EDA2 1E94 B565 716F
uid                  Simon Josefsson <simon@josefsson.org>
uid                  Simon Josefsson <jas@extundo.com>
sub   1280R/4D5D40AE 2002-05-05 [expires: 2010-04-21]

The key is available from:
  http://josefsson.org/key.txt
  dns:b565716f.josefsson.org?TYPE=CERT

Alternatively, after successfully verifying the OpenPGP signature of
this announcement, you could verify that the files match the following
checksum values.  The values are for SHA-1 and SHA-224 respectively:

d1693e611aa7270f14bc500bd56ef529ffcb1703  gnutls-2.8.0.tar.bz2

5e5bc180293b0854b7e8c27a5eb55f172579b346fba61b2d4b0b0c61  gnutls-2.8.0.tar.bz2

Documentation
=============

The manual is available online at:

  http://www.gnu.org/software/gnutls/documentation.html

In particular the following formats are available:

 HTML: http://www.gnu.org/software/gnutls/manual/html_node/index.html
 PDF: http://www.gnu.org/software/gnutls/manual/gnutls.pdf

For developers there is a GnuTLS API reference manual formatted using
the GTK-DOC tools:

  http://www.gnu.org/software/gnutls/reference/gnutls-gnutls.html

Community
=========

If you need help to use GnuTLS, or want to help others, you are invited
to join our help-gnutls mailing list, see:

  http://lists.gnu.org/mailman/listinfo/help-gnutls

If you wish to participate in the development of GnuTLS, you are invited
to join our gnutls-dev mailing list, see:

  http://lists.gnu.org/mailman/listinfo/gnutls-devel

Windows installer
=================

GnuTLS has been ported to the Windows operating system, and a binary
installer is available.  The installer contains DLLs for application
development, manuals, examples, and source code.  The installer uses
libgpg-error v1.7, libgcrypt v1.4.4, libtasn1 v2.2, and GnuTLS v2.8.0.

For more information about GnuTLS for Windows:
  http://josefsson.org/gnutls4win/

The Windows binary installer and PGP signature:
  http://josefsson.org/gnutls4win/gnutls-2.8.0.exe (15MB)
  http://josefsson.org/gnutls4win/gnutls-2.8.0.exe.sig

The checksum values for SHA-1 and SHA-224 are:

8a86a846cbdc16b6c21442c706854a5c02416336  gnutls-2.8.0.exe

555afa0c1524d8ad05a12384e1bd1b09da720b03058f0089dc812cfc  gnutls-2.8.0.exe

A ZIP archive containing the Windows binaries:
  http://josefsson.org/gnutls4win/gnutls-2.8.0.zip (5.3MB)
  http://josefsson.org/gnutls4win/gnutls-2.8.0.zip.sig

A Debian mingw32 package is also available:
  http://josefsson.org/gnutls4win/mingw32-gnutls_2.7.10-1_all.deb (4.8MB)

The checksum values for SHA-1 and SHA-224 are:

b141f97c196d408bf12b8a58ede6bda8fb291be6  mingw32-gnutls_2.8.0-1_all.deb

541e2fca8248460b419e2224a138b292020de1724c86c77b9478da93  mingw32-gnutls_2.8.0-1_all.deb

Internationalization
====================

The GnuTLS library messages have been translated into Czech, Dutch,
French, German, Malay, Polish, Swedish, and Vietnamese.  We welcome the
addition of more translations.

Support
=======

Improving GnuTLS is costly, but you can help!  We are looking for
organizations that find GnuTLS useful and wish to contribute back.  You
can contribute by reporting bugs, improve the software, or donate money
or equipment.

Commercial support contracts for GnuTLS are available, and they help
finance continued maintenance.  Simon Josefsson Datakonsult AB, a
Stockholm based privately held company, is currently funding GnuTLS
maintenance.  We are always looking for interesting development
projects.  See http://josefsson.org/ for more details.

The GnuTLS service directory is available at:

  http://www.gnu.org/software/gnutls/commercial.html

Happy Hacking,
Simon