CryptoSys Home > API > A Python interface to CryptoSys API

A Python interface to CryptoSys API

This page describes the Python3 interface to the core CryptoSys API library. Latest version 6.22.1.post1 released 2024-01-08.

Introduction

The Python interface to CryptoSys API is really handy because you can easily do calculations in its REPL environment (read-eval-print loop) without having to compile each time.

For a handy quick guide to the methods available see the Python CryptoSys API Cross Reference.

Installation

Automatic install from PyPi (recommended)

> pip install crsysapi
Collecting crsysapi
  Downloading crsysapi-6.22.1.post1.tar.gz (30 kB)
...
Successfully built crsysapi
Installing collected packages: crsysapi
Successfully installed crsysapi-6.22.1

To upgrade if an older version is already installed:

> pip install --upgrade crsysapi

Make sure you have the latest version of PIP installed (always use the full Python command - don't try to use pip to install itself)

> python -m pip install --upgrade pip

Manual install

Download the distribution file crsysapi-x.x.x.tar.gz^† from the Python Package Index (PyPi).
Open a command line console in the same directory as the download file, then type
```
pip install crsysapi-x.x.x.tar.gz
```
where "x.x.x" is the current version number.

† Previously this was a .zip file. The PyPI people seem to have now standardized on using .tar.gz files.

System requirements

Python 3.6 or above must be installed on your system. CryptoSys API v6.22.1 or above must also be installed. This is available from https://www.cryptosys.net/api.html. The Python interface works on both Windows and Linux x86-64 platforms.

Using in the Python REPL

Here are some simple examples calling CryptoSys API functions from the Python REPL.

>>> from crsysapi import *  # @UnusedWildImport
>>> Gen.version() # "hello world!" for CryptoSys API
62201
>>> Hash.hex_from_data(b'abc') # compute SHA-1 hash in hex of 'abc' as bytes
'a9993e364706816aba3e25717850c26c9cd0d89d'
>>> Hash.hex_from_string('abc', Hash.Alg.SHA256)   # same but over a string and using SHA-256
'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
>>> h = Hash.data(b'abc')   # h is a byte array (bytes->bytes)
>>> print(Cnv.tohex(h))     # display the byte array in hex
A9993E364706816ABA3E25717850C26C9CD0D89D

The stricter way using the crsysapi prefix.

>>> import crsysapi
>>> crsysapi.Gen.version() # Underlying core CryptoSys API dll
62201
>>> crsysapi.__version__  # crsysapi.py module version
6.22.1.0000
>>> crsysapi.Hash.hex_from_data(b'abc') # compute SHA-1 hash in hex of 'abc' as bytes
'a9993e364706816aba3e25717850c26c9cd0d89d'
>>> crsysapi.Hash.hex_from_string('abc', crsysapi.Hash.Alg.SHA256)   # same but over a string and using SHA-256
'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
>>> h = crsysapi.Hash.data(b'abc')   # h is a byte array (bytes->bytes)
>>> print(crsysapi.Cnv.tohex(h))     # display the byte array in hex
A9993E364706816ABA3E25717850C26C9CD0D89D

Note that crsysapi.Gen.version() gives the version number of the underlying core (native) CryptoSys API DLL, and crsysapi.__version__ gives the version of the Python crsysapi package.

Caution: using Python 3 means we have to be careful and differentiate between arguments expected to be byte arrays and arguments expected as strings. In Python 3 you will get an exception if you use the wrong type.

>>> Hash.hex_from_data('abc')  # Woops! String type is not a bytes array in py 3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Python38\lib\site-packages\crsysapi.py", line 1876, in hex_from_data
    nc = _didll.HASH_HexFromBytes(None, 0, bytes(data), len(data), alg)
TypeError: string argument without an encoding
>>> Hash.hex_from_data('abc'.encode())  # OK - string encoded into bytes array
'a9993e364706816aba3e25717850c26c9cd0d89d'
>>> Hash.hex_from_data(b'abc')  # Or simply write directly as a byte array
'a9993e364706816aba3e25717850c26c9cd0d89d'

Test files and examples

There is set of examples in the test script test/test_crsysapi.py provided with the latest download from PyPi (download the file crsysapi-x.x.x.tar.gz and unzip it to get the files and test directory structure).

You can cut and paste the parts you want to get started writing your own code.

Running the tests

The tests in test/test_crsysapi.py demonstrate the use of each of the classes and methods using known test vectors where possible. The script and test files are available in the download from PyPi.

The test program creates all the input files it needs in the subdirectory ./work. If the work folder does not exist it will be created.

This structure is already setup in the distribution file, so unzip the file crsysapi-x.x.x.zip and open a command line prompt in the test sub-directory. Then do one of the following.

```
python test_crsysapi.py
```

py.test -v

...
test_crsysapi.py::test_error_lookup PASSED
test_crsysapi.py::test_cnv PASSED
test_crsysapi.py::test_cipher PASSED
test_crsysapi.py::test_cipher_hex PASSED
...

Open the file test_crsysapi.py using IDLE and select Run > Run Module (F5).

The output should look something like this

crsysapi version = 6.22.1.0000
API core version = 62201
module_name = C:\WINDOWS\SYSTEM32\diCryptoSys.DLL
compile_time = Jan  7 2024 16:20:06
platform = X64
Working in directory: xxxx\test\work
DOING ALL TESTS...

LOOKUP SOME ERROR CODES...
error_lookup(0)=OK, success, no error (SUCCESS_NO_ERROR)

--[cut]--

DETAILS OF CORE DLL...
DLL Version=62201 [X64] Lic=D Compiled=[Jan  7 2024 16:20:06]
[Licensed Developer Edition]
[C:\WINDOWS\SYSTEM32\diCryptoSys.DLL]
crsysapi.__version__= 6.22.1.0000
ALL DONE.

[Go to top]

Revision History

See Revision History

[Go to top]

Contact us

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

This page last updated 15 August 2025