Writing an interface in another programming language

This page shows how you can write an interface in another programming language to our cryptographic products CryptoSys API, CryptoSys PKI and FirmaSAT.

You can call any of the functions in the core DLLs for CryptoSys API, CryptoSys PKI or FirmaSAT. You call the functions in exactly the same way you call functions in the Win32 API, such as GetUserNameA from the Advapi32 library. If your programming language allows you to call such Win32 API functions, then you can use the same techniques to call our functions.

The Core DLLs

The core Win32 DLLs are

Product	Core DLL	C include file
CryptoSys API	`diCryptoSys.dll`	`diCryptoSys.h`
CryptoSys PKI	`diCrPKI.dll`	`diCrPKI.h`
FirmaSAT	`diFirmaSat2.dll`	`diFirmaSat2.h`

Parameters and Types

The best place to see the parameters and types for all the functions is in the relevant C include file. Even if you do not program in C, you should be able to work out what you require for your language. You may also get more ideas by looking at the Using Delphi page, or the Sample Definitions and Examples below.

The latest version of the C include file is included in the downloaded installation distribution and should be in the directory C:\Program Files\{CryptoSys|CryptoSysPKI|FirmaSAT}\C. Be careful, the linked copies above may be out of date.

Type used in C	Description
`long`	A signed 32-bit integer, passed by value
`[const] char *sz`	ANSI string: a string of single-byte non-zero characters terminated by a zero byte
`[const] unsigned char *lp`	Byte array: an ordered sequence of single-byte values of any value in the range [0,255]
`void *lp`	Alternative for byte array.

The const qualifier indicates an input-only parameter. No const qualifier for a string or byte array indicates an output parameter. You must allocate storage for these output variables.

Notes for programmers

All of the core DLLs are simple Win32 DLLs, not ActiveX or COM or .NET.
You will need to set an external reference to the relevant DLL. Windows should find the DLL automatically. For more information on the directories searched and the order in which they are searched, do a search in MSDN for help on "Search Path Used by Windows to Locate a DLL".
All integers used are 32-bit signed integer types.
All strings passed must be ANSI strings (LPSTR).
The return value is always a signed 32-bit integer. You will need to check the manual for the significance of the return value for each individual function.

Common Problems

The most common problems in writing interfaces are:

Using a local 64-bit integer instead of a 32-bit one. A `long' in C is only a 32-bit signed int. All return values are signed 32-bit integers. Check that the "INT" or "INTEGER" type in your language is a 32-bit one. If not, use one that is.
Passing Unicode UTF-16 strings. The strings must be 8-bit-character ANSI strings terminated by a zero character. If your language works with native Unicode strings, you may need to convert to ANSI before calling. Some languages (e.g. VB6) automatically convert native Unicode strings to ANSI when passing to a DLL. If your system passes the length of the string as part of the string, you will need to convert to a type that doesn't, perhaps a byte array. But make sure it is terminated by a zero byte: add an extra one if necessary.
Handling byte arrays. In some languages, this is the same as a String type.
Failing to allocate storage for output strings and byte arrays before calling. The library does not carry out any memory allocation for the output. It expects the programmer to have done this already. You must allocate an extra character for an output string to receive the terminating null character.

Delphi

See the page Using Delphi with CryptoSys API, CryptoSys PKI and FirmaSAT for more details and some sample code.

Visual FoxPro

See the Visual FoxPro Interface page.

Clarion

See the page Using Clarion with FirmaSAT for an interface to FirmaSAT kindly provided by M. C. Peter Ralph N. Tolentino. Clarion users should be able to use this example to create interfaces to CryptoSys PKI and CryptoSys API.

Sample Definitions

Compare the following definitions/declarations in C, VB6, C Sharp and Delphi, respectively:

HASH_HexFromFile: long _stdcall HASH_HexFromFile(char *szOutput, long nOutChars, const char *szFileName, long nOptions);

Public Declare Function HASH_HexFromFile Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strFileName As String, ByVal nOptions As Long) As Long

[DllImport("diCrPKI.dll",CharSet=CharSet.Ansi)] static extern int HASH_HexFromFile(StringBuilder sbHexDigest, int digLen, string strFileName, int flags);

function HASH_HexFromFile(szOutput : PAnsiChar; nOutChars : Integer; szFileName : AnsiString; nOptions : Integer) : Integer; stdcall; external 'diCrPKI.dll';
TDEA_BytesMode: long _stdcall TDEA_BytesMode(unsigned char *lpOutput, const unsigned char *lpInput, long nBytes, const unsigned char *lpKey, long fEncrypt, const char *szMode, const unsigned char *lpIV);

Public Declare Function TDEA_BytesMode Lib "diCrPKI.dll" (ByRef abOutput As Byte, ByRef abInput As Byte, ByVal nDataLen As Long, ByRef abKey As Byte, ByVal fEncrypt As Long, ByVal strMode As String, ByRef abIV As Byte) As Long

[DllImport("diCrPKI.dll",CharSet=CharSet.Ansi)] static extern int TDEA_BytesMode(byte[] output, byte[] input, int nbytes, byte[] key, int bEncrypt, string strMode, byte[] iv);

function TDEA_BytesMode(lpOutput : PByte; lpInput : PByte; nBytes : Integer; lpKey : PByte; fEncrypt : Integer; szMode : AnsiString; lpIV : PByte) : Integer; stdcall; external 'diCrPKI.dll';

Examples by Others

Here are some example interfaces provided by others. We have not tested these. They may have been written for older versions of CryptoSys PKI but will still be compatible with the latest version. They come with no support or warranties whatsoever. Please make your own checks and use at your own risk.

PowerBuilder Script

Jorge Perez has provided a script in PowerBuilder that uses some of the DLL functions in CryptoSys PKI. This is the same example for SAT Mexico that we prepared using VB6. It should give any Powerbuilder user the necessary information to use any of the functions in the Toolkit. (Comment: It seems the code includes a procedure rsaReadPrivateKey which is not included. You'll have to figure out how to call the function RSA_ReadEncPrivateKey.)

Example interface: powerbuilder.sat.txt
Last updated: 10 March 2006

D Programming Language

http://www.digitalmars.com/d/index.html
D is a general purpose systems and applications programming language. It is a higher level language than C++, but retains the ability to write high performance code and interface directly with the operating system API's and with hardware.

Interface for CryptoSys PKI: diCrPKID.d which includes a port of the .NET C# classes, and a zip file with the associated lib file and a QAD set of tests. By Dr Richard Koch.
Last updated: 12 September 2006 for version 2.9.

Stony Brook Iso Modula-2

http://www.modula2.org/sb/index.php

Interface for CryptoSys PKI: diCrPKI.mod and diCrPKI.def, or in a zipped file which includes a modula-2-compatible diCrPKI.lib file. By Dr Richard Koch.
Last updated: 17 April 2005.

PowerBASIC

http://www.powerbasic.com/.

Interface for CryptoSys PKI: diCrPKI-powerbasic.txt. By Dr Richard Koch.
Last updated: 24 February 2005.

Team Developer

Jeff Luther has produced an interface to CryptoSys API using Team Developer (TD v1.5). See Jeff's Code Samples and scroll down to find CRYPTOGRAPHIC SAMPLES.

Disclaimer

Our CryptoSys products are offered primarily with interfaces using the C/C++, C#, VB6/VBA and VB.NET languages. We don't offer to support any other interfaces or languages. We will try and help if we can. Please make whatever checks you need to before purchase.

Contact

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

This page first published 25 June 2010. Last updated 27 October 2011