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:
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.
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.
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.
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.
nOptionsparameter 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_EncryptBytesExfunction 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.
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.