ActiveX DLL for CryptoSys API

An ActiveX DLL interface for CryptoSys API is included in the standard installation packages for the Developer and Trial Server versions. This will allow you to call selected CryptoSys API functions using COM, VBScript and ASP.

The full VB6 source code for the ActiveX DLL is included along with some test ASP pages and a test EXE project. You can amend and add more functionality as you wish.

The files should be found in the directory

C:\Program Files\CryptoSys\COM

unless you installed it in a different location on setup.

We don't explicitly support this ActiveX DLL. It is provided as a free add-on for Licensed users of CryptoSys API with no warranties. It works for us in our test environments. We've put a lot of effort into making sure it's something we can be proud of, but IIS is a strict and capricious master whose demands in a strange environment we can't always anticipate. If it works for you, please use it.

Hint: If you have been calling the ActiveX interface from ASP pages using IIS on your own machine, you will not be able to install a new version using the setup program. You will need to stop IIS first:

net stop w3svc

If you find a bug or would like to suggest improvements to the code, please contact us. We'll keep this project up to date and will acknowledge useful suggestions.

General Notes
Classes and Methods
Installation
- Registry setting for IIS Server
Using with the Personal Version
What happened to the apiocxtrial.exe program?
Notes on ActiveX Programming with IIS

CryptoSys API Downloads

Developer Version (requires licence)
Trial Server Version

General Notes

To simplify matters when working in a VBScript/ASP environment, we've only used functions that require all their parameters to be passed as hexadecimal strings. Hexadecimal-encoded data are unambiguous and easily handled in VBScript programming as simple string types, as well as being straightforward to pass as arguments in a URL address. There are a few exceptions for the hash and pbkdf functions which take "straight" text input. It just remains to educate the user why something as simple as "abc" is now "616263". (If you don't understand that, give up now.)

Most functions return a string. If the function fails - perhaps because the input was invalid - the function returns an empty string. The current code doesn't handle errors specifically (it could, but we haven't got around to it yet).

Classes and Methods

The classes and methods available for the ActiveX interface are detailed in the manual.

Installation

See also Using with COM/ASP in the manual.

Install CryptoSys API on the target machine*. Use the Developer or Server Test Version; the Personal Version will not work with IIS or ASP.
Copy the ActiveX file diCryptOCX.dll into a suitable directory on the target machine, e.g. C:\myfolderhere.
Open a command line window (Start > Run > cmd) and type
```
REGSVR32 "C:\myfolderhere\diCryptOCX.dll"
```
You should get the response DllRegisterServer in diCryptOCX.dll succeeded.

Either in a VB project set a reference to diCryptOCX.dll

Dim oGen = New diCryptoOCX.gen
Debug.Print "Version=" & oGen.Version

Or In an ASP page

Dim oGen
Set oGen = Server.CreateObject("diCryptOCX.gen")
Response.Write "Version=" & oGen.Version

* The ActiveX DLL is a wrapper that calls the core functions from the Win32 DLL in a safe manner. The Win32 file diCryptoSys.dll must exist in a directory in the library search path on the target computer. Refer to the notes in the file distrib.txt supplied with the Developer version or install using the setup program provided. Note that the setup program does not register the ActiveX DLL - that must be done separately by following the instructions above.

Registry Setting for IIS Server

If you are using CryptoSys API on an IIS Server, we recommend you make the following registry setting and set the NoMessageBox DWORD value to '1' to disable pop-up messages from appearing in the unlikely event that a critical error occurs. A critical error means that someone has interfered with the core DLL or the random number generator has failed. A critical error should never happen, but it pays to be sure.

Key: [HKEY_LOCAL_MACHINE\Software\DI Management\CryptoSys\Options]
Value Name: NoMessageBox
Data Type: REG_DWORD
Data: 1 = MessageBoxes disabled, 0 = MessageBoxes enabled (default)

If you want to set or change this setting, you can use one of these two registry editor files. You will need administrator privileges.

To turn the message box back on: apiEventMsgBoxOn.zip
To turn the message box off: apiEventMsgBoxOff.zip

For more details refer to the section Optional Registry Settings in the manual (0.5 MB).

Using with the Personal Version

The ASP tests will not work with the free Personal Version of CryptoSys API. Please use the Server Trial Version to evaluate.

What happened to the apiocxtrial.exe program?

As of release 3.1 in January 2006, the ApiOcxTrial.exe program has been replaced by the Server Trial Version, which avoids all the palaver of registering on-line in earlier releases.

Notes on making an ActiveX DLL to use in IIS or a multi-threaded environment

Microsoft recommends that you do the following when making an ActiveX DLL to be used with IIS

In Project Properties select Apartment Threaded and check Unattended Execution and Retain in Memory. See Microsoft article
- Q241896: Threading Issues with Visual Basic 6.0 ActiveX Components.
Avoid using Private Declare statements in class modules. Instead, create a TLB file and set Project References to it. Refer to:
- Q189133: How To Make C DLL More Accessible to VB with a Type Library
- Q143258: How To Create Constants and DLL Declarations in a Type Library

We have followed these recommendations in the provided ActiveX project. The file diCryptoSys.tlb is included in the downloaded source code. If you would like another function added to the TLB file, please contact us. In the short term, you can always use a Private Declare statement to add an extra function.

Despite all efforts to make them thread-safe, it is still not good practice to use the stateful "Init-Update-Final" functions in a live IIS project.

This page last updated: 13 September 2007