Changes in 3.0 release
======================

cryptlib 3.1 will introduce a new function cryptFlushData() to replace the
current practice of calling cryptPushData() will all-null parameters, a change
required for languages like Delphi and VB which don't handle C null pointers
too well.  This function is already present in 3.0 for forwards-compatibility
purposes, it's recommended that you update your code to call cryptFlushData()
in place of cryptPushData() with null parameters (although the existing
cryptPushData() mechanism will still work).

The Unix randomness-gathering code will now check for and use EGD/PRNGD if
they're available.

The requirement that cryptlib be built via a network share under Windows has
been removed.

HTTP keyset access (CRYPT_KEYSET_HTTP) formerly required that the keyset be
opened without a name being given, with the full URL being specified as the key
ID to retrieve keys.  This was both somewhat inconsistent with the other keyset
types, and didn't work well with persistent connections, for example where
multiple certificates were being read from a single server.  This has been
changed so that the server URL is given when the keyset is opened as it is for
other keyset types, and a key ID is given when reading individual keys.  When
reading keys with a fixed URL (with no per-key ID), the special ID "[none]" can
be used to indicate that the server URL points directly at the certificate.  In
the simplest case the previous usage:

  cryptKeysetOpen( &cryptKeyset, CRYPT_UNUSED, CRYPT_KEYSET_HTTP, NULL,
                   CRYPT_KEYOPT_READONLY );
  cryptGetPublicKey( cryptKeyset, &cryptCert, CRYPT_KEYID_NAME,
                     "http://www.server.com/cert.der" );

now becomes:

  cryptKeysetOpen( &cryptKeyset, CRYPT_UNUSED, CRYPT_KEYSET_HTTP,
                   "http://www.server.com/cert.der", CRYPT_KEYOPT_READONLY );
  cryptGetPublicKey( cryptKeyset, &cryptCert, CRYPT_KEYID_NAME,
                     "[none]" );

Reading multiple certificates, for example via a CGI interface on the server,
is done with:

  cryptKeysetOpen( &cryptKeyset, CRYPT_UNUSED, CRYPT_KEYSET_HTTP,
                   "http://www.server.com/certstore.cgi",
                   CRYPT_KEYOPT_READONLY );
  cryptGetPublicKey( cryptKeyset, &cryptCert, CRYPT_KEYID_NAME,
                     "user1" );
  cryptGetPublicKey( cryptKeyset, &cryptCert, CRYPT_KEYID_NAME,
                     "user2" );
  cryptGetPublicKey( cryptKeyset, &cryptCert, CRYPT_KEYID_NAME,
                     "user3" );

Changes in 3.0 final beta
=========================

The cryptlib 3.0 final release divides the network timeout parameter into two
parts, a CRYPT_OPTION_NET_CONNECTTIMEOUT which is applied during the connection
setup process and a CRYPT_OPTION_NET_TIMEOUT which is applied during reads and
writes (although in practice writes are almost always instantaneous).  This
means that it's now possible to avoid nonblocking I/O if required.

Use of SSL/TLS client certificates is now enabled.

The final version of the S/MIME PasswordRecipientInfo (PWRI) RFC contained a
change in the way the key wrap algorithm is identified.  The cryptlib final
release produces a PWRI which follows the final RFC, but will also read the
older format produced by earlier versions of cryptlib.  If it's necessary to
generate PWRI data in the old format, you can change the "#if 1" in
keymgmt/asn1objs.c to "#if 0" to produce the older format.

Support for extended CMP user configurability via PKIUser objects has been
added, this allows user details to be pre-configured at the CA rather than
requiring the user to know them.

Changes in 3.0 beta 6
=====================

Beta 6 reduces the plethora of key generation functions by allowing the keysize
to be specified in the more standard way of setting the corresponding attribute
rather than having extraneous ...Ex() versions of the function which parallel
the standard form.  If you were previously using the standard or asynchronous
...Ex() functions:

	cryptGenerateKeyEx( cryptContext, keySize );

you can change to the newer form with a simple cut and paste:

	cryptSetAttribute( cryptContext, CRYPT_CTXINFO_KEYSIZE, keySize );
	cryptGenerateKey( cryptContext );

The table format for certificate stores has changed slightly to accomodate the
requirements of CMP servers (specifically the fact that they can cause things
to fail at inopportune moments), in order to handle this you need to recreate
the cert store (drop the previous table and create a new one with
CRYPT_KEYOPT_CREATE), if you need to move information across then create a new
table and insert into <newTable> select * from <oldTable> to copy the existing
certificates across.  The newly-created table will support the storing of extra
information needed to handle restarts during CMP operations.

Support for the proposed AES algorithm is now included.  Since this hasn't been
finalised by NIST yet, it is strongly recommended that you not use it until the
AES FIPS has been published.  cryptlib will implement the form presented in the
final FIPS which may be incompatible with the current version.

SSL and TLS support (both client and server) is now enabled, thanks to
endergone Zwiebeltuete for his help in getting this going.

Changes in 3.0 beta 5
=====================

Beta 5 removes the configuration options CRYPT_OPTION_FIXSTRINGS and
CRYPT_OPTION_CHECKENCODING since they shouldn't be needed any more as the ASN.1
code has been modified to handle all but the most broken certificates out
there.

Under Unix the library is now called libcl rather than libcrypt to reduce
problems with naming conflicts on some systems.

Support for the creation of one-step certificates which automatically work for
any purpose has been added and is enabled by setting the certificate's
CRYPT_CERTINFO_XYZZY attribute, more details are given in the manual.

OCSP, TSP, and ssh server support is now enabled (this complements the OCSP,
TSP, and ssh client support added in beta 3 and beta 4).

Changes in 3.0 beta 4
=====================

Beta 4 removes the need to use the TCP4U library for the network interface and
should now have networking enabled automatically on Unix and Windows systems.
With the enhanced networking support comes support for ssh secure sessions and
CMP (Certificate Management Protocol).

The creation of arbitrary-format DN's containing any sort of component in any
order or combination is now supported via the CRYPT_CERTINFO_DN attribute.

Changes in 3.0 beta 3
=====================

Beta 3 required one unfortunate change to the object creation functions which
involves the addition of a parameter which specifies the user who is to own the
object.  For cryptlib 3.0 this means that as the second parameter for the
object creation functions (cryptCreateContext, cryptKeysetOpen,
cryptCreateEnvelope, etc etc) you should specify CRYPT_UNUSED for forwards
compatibility with cryptlib 3.1 and later releases.  The user parameter has
existed since the first 3.0 releases but until now has been hidden beneath the
cryptlib API, unfortunately it's necessary to un-hide this parameter which is
required by certain 3.1 features such as the CA management functionality.

The use of multiple certificates with the same DN/email address but different
key usage types is now supported (previous versions treated the appearance of
multiple certs issued to the same person as a duplicate cert problem, either
interpretation is valid but popular opinion seems to be that the beta 3
behaviour is better).  In order to support this in public key keysets you need
to recreate them (drop the previous table and create a new one with
CRYPT_KEYOPT_CREATE), if you need to move certificates across then create a new
table and insert into <newTable> select * from <oldTable> to copy the existing
certificates across.  The newly-created table will support the storing of
multiple identical certificates.

In order to take advantage of this capability with encrypted enveloping, you
need to add the recipient's public key with the CRYPT_ENVINFO_RECIPIENT option
which will allow cryptlib to automatically select the most appropriate
certificate.  The selection of an appropriate signature checking certificate is
handled automatically.

Handling of detached signatures with externally-supplied hash values is now
supported, see the manual for details.  This allows signature checking for
arbitrary data without it having to be hashed via the envelope.

Online certificate status checking via OCSP is now supported if you can manage
to find an OCSP responder anywhere.  Timestamping of signatures is also
supported, although you'll have even less chance of locating a TSA than an OCSP
responder.

Support for mSQL has been dropped since MySQL is now GPL'd and provides far
more functionality than mSQL (even cryptlib 2.x was pushing the limits of mSQL,
with cryptlib 3.x it's not really sufficient any more).

Changes in 3.0 beta 2
=====================

Beta 2 has three minor API changes over beta 1 which are intended to clarify
areas which have caused problems for users in the past.

The first change is that the third, usually unnecessary, parameter for
cryptCreateContext() has been eliminated:

  cryptCreateContext( &cryptContext, cryptAlgo );

Only the conventional-encryption algorithms required the encryption mode
parameter, the default is CBC but if another value is required you can specify
it using the CRYPT_CTXINFO_MODE attribute:

  cryptSetAttribute( cryptContext, CRYPT_CTXINFO_MODE, cryptMode );

This attribute isn't required for anything except conventional encryption
algorithms, and even then it's only required for the use of encryption modes
other than the default mode of CBC.  This change simplifies the creation of
contexts, since there's no longer any need to juggle CRYPT_USE_DEFAULT,
CRYPT_MODE_PKC, CRYPT_MODE_NONE, or any of the other special cases which were
used for algorithms which don't have different encryption modes.

The second change (which probably won't affect most users since it's rather
obscure) is that previously when loading raw public keys with the
CRYPT_PKCINFO_RSA or CRYPT_PKCINFO_DLP structure the attribute used was
CRYPT_CTXINFO_KEY and the length was given as CRYPT_UNUSED.  This required a
number of special-case checks in the code and made error-checking of user-
supplied data impossible because it wasn't possible to determine how much data
was being passed in.

In beta 2 this attribute now follows the pattern for every other attribute in
that it's necessary to give the structure size (ie sizeof( CRYPT_PKCINFO_xxx ))
as the length parameter rather than CRYPT_UNUSED.  In addition the attribute
for key components is now CRYPT_CTXINFO_KEY_COMPONENTS to make explicit the
fact that what's being loaded is a composite structure containing multiple
components, not just a single byte string as with CRYPT_CTXINFO_KEY.

Similarly, the length parameter when using cryptEncrypt()/cryptDecrypt() for
public-key encryption is now the key/data length in bytes rather than
CRYPT_UNUSED, following the standard pattern of requiring an actual length
rather than using magic values.

The third change is that the functionality of cryptCreateEnvelopeEx() has been
folded into cryptCreateEnvelope(), which now takes a second parameter
specifying the type of envelope to create

  cryptCreateEnvelope( &cryptEnvelope, formatType );

The envelope buffer size can optionally be specified with the
CRYPT_ATTRIBUTE_BUFFERSIZE attribute once the envelope has been created:

  cryptSetAttribute( cryptEnvelope, CRYPT_ATTRIBUTE_BUFFERSIZE, size );

although this should only be necessary in special cases when enveloping larger-
than-usual data quantities.  This change both simplifies the interface and
makes it easier for cryptlib to efficiently handle resources, since it can
allocate a small envelope buffer when enveloping begins rather than having to
create a one-size-fits-all one on envelope creation.

In addition to these changes, beta 2 includes the ability to read the label for
the private key which is required for de-enveloping data, so you can use the
key name in prompts when asking the user for a password.  You can do this with:

  char label[ CRYPT_MAX_TEXTSIZE + 1 ];
  int labelLength;

  cryptGetAttributeString( cryptEnvelope, CRYPT_ENVINFO_PRIVATEKEY_LABEL,
                           label, &labelLength );
  label[ labelLength ] = '\0';

See the manual for more information on this.

Changes in 3.0 beta 1
=====================

cryptlib 3.0 features a large number of improvements over 2.1, the most visible
one being that there is now a unified object model which applies to all
cryptlib objects, so that the old object-type-specific functions like
cryptGetCertComponentString() and cryptSetEnvelopeComponentNumeric() have been
replaced by cryptSetAttribute() which works across all object types.  This
means that cryptlib 3.0 has a much simpler interface than 2.1 did (even with
all the features added in 3.0, the manual is 25 pages shorter than the 2.1
manual).  You can find more information on new features at
http://www.cs.auckland.ac.nz/~pgut001/cryptlib/new30.html (also available via
the download section of the cryptlib page).

Backwards compatibility with 2.1 is maintained through the use of the 2.1
include file capi.h, which contains macros which map the 3.0 functions and
attributes back to 2.1 versions.  Three of the more obscure functions don't
translate cleanly, these are documented at the start of capi.h.  If you've got
existing 2.1 code then it should work with 3.0 with a recompile.

This is a beta release of the code, some sections are still subject to change
because the standards they are based on haven't been finalised yet. The most
obvious one is the PKCS #15 keyset format, when the cryptlib code was frozen
the PKCS #15 file format existed only in an informal manner so that some of the
data formatting used by cryptlib is speculative and will probably change when
the standard stabilises.  What this means in practice is that you shouldn't
store any long-term keys in file keysets since the format will have to change
in the future to track changes in the standard.

To a lesser extent, the compressed-data and password-protected-data formats are
based on S/MIME drafts which may also be changed at some point.

Finally, the AS/400, MVS, and VM/CMS versions have somewhat specialised
requirements (some of this is covered in the manual), please contact me before
trying to do anything with these versions.