CryptoSys Home > Writing an interface in another programming language

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, FirmaSAT, and SC14N.

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`
SC14N	`diSc14n.dll`	`diSc14n.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(x86)\{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/64 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). "Unicode" (wide, multibyte) character strings are not supported.
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.
The output buffer for a String type will be terminated automatically by a zero (null) byte. You must allocate one extra space than the number of output characters.

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 (usually) 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 value, 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 without the terminating zero.
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.

Sample Definitions

The following definitions/declarations in C, VB6, C# and Delphi, respectively, should give you an idea of the various types to use for your language.

HASH_HexFromFile: Demonstrates output to an ANSI string; filename input parameter is a string.

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

VB6: 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

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

Delphi: function HASH_HexFromFile(szOutput : PAnsiChar; nOutChars : Integer; szFileName : AnsiString; nOptions : Integer) : Integer; stdcall; external 'diCrPKI.dll';
PBE_Kdf2: Demonstrates output to a byte array; input from byte arrays; must specify array lengths.

C: long __stdcall PBE_Kdf2(unsigned char *lpOutput, long nOutputLen, const unsigned char *lpPwd, long nPwdLen, const unsigned char *lpSalt, long nSaltLen, long nCount, long nOptions);

VB6: Public Declare Function PBE_Kdf2 Lib "diCrPKI.dll" (ByRef abDerivedKey As Byte, ByVal nKeyLen As Long, ByRef abPassword As Byte, ByVal nPwdLen As Long, ByRef abSalt As Byte, ByVal nSaltLen As Long, ByVal nCount As Long, ByVal nOptions As Long) As Long

C#: [DllImport("diCrPKI.dll",CharSet=CharSet.Ansi)] static extern int PBE_Kdf2(byte[] dk, int dkLen, byte[] pwd, int pwdLen, byte[] salt, int saltLen, int count, int nOptions);

Delphi: function PBE_Kdf2(lpOutput : PByte; nOutputLen : LongInt; lpPwd : PByte; nPwdLen : LongInt; lpSalt : PByte; nSaltLen : LongInt; nCount : LongInt; nOptions : LongInt) : LongInt; stdcall; external 'diCrPKI.dll';

Delphi

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

Python

See A Python interface to CryptoSys PKI Pro and A Python interface to SC14N.

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.

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.

ADW Modula-2

http://www.modula2.org/.

Interface for CryptoSys PKI: diCrPKI.mod and diCrPKI.def (zipped). By Dr Richard Koch.
Last updated: 3 June 2016 for version 11.1.0.

Download the free Modula-2 compiler ADWm2Free.16.zip from http://www.modula2.org/adwm2/download.php.

The 32-bit version of the required LIB file diCrPKI.lib should be installed by the CryptoSys PKI setup in the folder C:\Program Files (x86)\CryptoSysPKI\C (Use Start > All Programs > CryptoSysPKI > CryptoSys PKI Example Files > C.) The 64-bit version is in the CryptoSysPKI\X64 subfolder.

PureBasic

http://www.purebasic.com/ and http://www.purebasic.fr/english/.

Interface for CryptoSys PKI: diCrPKI.PBI (zipped). By Dr Richard Koch.
Last updated: 3 June 2016 for version 11.1.0.

D Programming Language

http://dlang.org/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 (zipped 4.2 kB). By Dr Richard Koch.
Last updated: 26 January 2014 for version 3.9.

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

Team Developer

Jeff Luther made an interface to CryptoSys API using Gupta Team Developer (TD v1.5).

These files are also available at the Team Developer Sample Vault.

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 15 January 2021.