CryptoSys Home > API > Looking back 20 years

Looking back 20 years

We released the first version of CryptoSys API in September 2001. Amazingly, in the last 20 years we've not had one valid bug report about the core functions.

Here is a copy of the Original manual for CryptoSys API v1.0 Sept 2001.

At the time we released version 1.0:

Rijndael had just won the competition for AES. The final FIPS specification was yet to be released, but we included AES anyway.
Triple DES was still the recommended block cipher. Even single DES was still common.
MD5 was still in common use as a hash function, although there was a strong push to replace it with SHA-1.
SHA-256 had just been standardized. The SHA-224 variant came much later.
Bruce Schneier's Blowfish cipher was a big favourite.
VB6 was probably the world's most popular programming language.
C# and VB.NET had not yet been released.

At the time our focus was on the VB6 and VBA market, even though the code was written in pure ANSI C. The Microsoft "CrAPI" had an awful interface and was frequently unavailable for users. It was only later that someone suggested we explicitly add a C/C++ interface to the core functions, which we did. Our .NET interface came later, obviously.

Thoughts and lessons learned

The "raw" core interfaces

The "raw" core interfaces written in ANSI C were based on the standard Windows Win32 API functions, which meant they could be directly called from VB6 and VBA programs, and did not allocate memory internally which could cause memory leaks. These are, though, messy to use and require the user to allocate and free memory directly.

However, this is more than made up by the fact that the core functions can easily be incorporated into other languages which have proper garbage disposal, like C# and Delphi. These interfaces can be made simple and easy for end users. We still use this method of core Win32-API-like functions in our latest products.

We admit we should have released a full proper VBA interface with wrapper functions much earlier.

Generic functions vs algorithm-specific

At the time we released it, it seemed a good idea to have a different set of functions for each algorithm: one for MD5, one for AES-128, one for AES-256, and so forth. From a marketing point of view, this was probably a good move, as people looking for a specific algorithm, say SHA-256, would google and find there was an explicit function in the toolkit with the exact name they wanted.

However, in the longer term this became unsustainable as more cryptographic algorithms were introduced. If you wanted to add a new feature, say a new function that accepted hex-encoded parameters, then you had to add this for every algorithm.

So now there is a complete set of generic functions in the toolkit such as "Cipher" and "Hash", which reduces the number of functions and makes adding a new algorithm as simple as adding an extra option flag. We've still kept the original algorithm-specific functions because we know many users still use them, but they don't get any feature updates. We'd say that users today are more sophisticated and knowledgable about cryptography, so such generic naming may not be so offputting.

The Manual

We made a big rod for our back with the manual. The current manual in its whole HTML form is over 50,000 lines long and is over 2 MB in size. We have a whole suite of tools written in Perl to massage and update the manual, and then split it up into separate pages and tree form. See the documentation page for the current manual and check the link above for the original manual from 20 years ago.

In general, we'd say it takes about ten times longer to update the manual than to actually write the code to add a new algorithm. Having set the precedent always to include a code sample in VBA for each new function meant a lot of extra coding and testing. However this did have the big advantage that it often exposed errors before release, so perhaps a good discipline to have.

These days, with much better documentation tools available like Doxygen, you can cut down the necessity to write a separate document. Even so, we still haven't found a decent documenting tool for VBA, so we wrote our own.

Option flags

When we first wrote the toolkit, there were many functions for which we didn't include a nOptions parameter because we thought there would never be any circumstance where it would be needed. Boy, were wrong on that point. To add a new feature by adding an extra option flag was a simple matter (with virtually no extra documentation to write). But if you had to add a new function with an extra options parameter, then you had to write up documentation for the entire new function. Plus you had to come up with an new name, usually with an "Ex" at the end. We were about to add a CIPHER_EncryptBytesEx function until we happened to notice how it looked when all in upper case.

Upshot: always include an nOptions parameter for all new core functions. These are easy to make optional in interfaces with other languages.

Contact us

For more information or to comment on this page, please send us a message.

This page first created 27 September 2021. Last updated 9 October 2021.