The CryptoSys Encode API lets you carry out fast encoding and decoding in base64 and hexadecimal notation. It also includes a function that returns the CRC-32 checksum of a string of any length.
The API functions in the CryptoSys Encode package are called in a similar manner to the way you call Windows API functions from Visual Basic. They have the advantage of much greater speed and better security than interpreted Visual Basic code. You need to install the program on the client computer and declare the functions in your VB project (just copy and paste into a module and it's done). A full list of the declarations is provided. The Visual Basic functions automatically carry out the necessary allocations of memory for your Visual Basic strings and Byte arrays.
To call from a C/C++ program, there are a separate set of functions specifically for C/C++ programmers. See C/C++ Interface.
The CryptoSys Encode API system and this document were written by David Ireland and are copyright (c) 2002-3 by DI Management Services Pty Limited, all rights reserved.
This document may not be distributed or reproduced separately by any means without the express written permission of the author. The Trial, Personal and Single User versions of CryptoSys Encode are not licensed for distribution of any kind. The Developer version may only be distributed in accordance with the licence conditions.
The latest version of CryptoSys Encode may be obtained from <http://www.cryptosys.net/encode.html>.
It's a very convenient format to store and transfer nasty binary data between applications. It's a particularly useful for encrypted data. Base64 is also known as radix 64 encoding. Binary data encoded with base64 encoding looks like
/ty6mHZUMhA=This represents the 8 bytes
FE DC BA 98 76 54 32 10
A base64 string consists of the 64 characters A-Z, a-z, 0-9 and '/' and '+', and can be terminated by up to two '=' characters for padding. Each four base64 characters represent three bytes. A valid base64 string should always be an exact multiple of 4 characters long (excluding any non-base64 characters). Note that the occurrence of any '=' character denotes termination of the data.
Hexadecimal means a number expressed in base 16. The convention is that each digit can be between 0 and 15 in value and is represented by the characters 0-9 and A-F. It does not matter whether the letters are in upper- or lower-case.
| Hexadecimal | Decimal | Binary |
| 0 | 0 | 0000 |
| 1 | 1 | 0001 |
| 2 | 2 | 0010 |
| 3 | 3 | 0011 |
| 4 | 4 | 0100 |
| 5 | 5 | 0101 |
| 6 | 6 | 0110 |
| 7 | 7 | 0111 |
| 8 | 8 | 1000 |
| 9 | 9 | 1001 |
| A | 10 | 1010 |
| B | 11 | 1011 |
| C | 12 | 1100 |
| D | 13 | 1101 |
| E | 14 | 1110 |
| F | 15 | 1111 |
CRC-32 is a cyclic redundancy check that returns a 32-bit checksum. It is not keyed and is not one-way, but can provide a quick and useful check if data has changed. The CRC-32 algorithm used in CryptoSys Encode is the one specified in ISO 3309 and ITU-T V.42, and is used by WinZip, PKzip, PNG, gzip and Ethernet.
Use the setup.exe file to install
CryptoSys Encode onto your computer.
To uninstall, use Start > Settings > Control Panel > Add/Remove Programs.
To call from a Visual Basic project or VBA application, just copy and paste the
necessary declaration statements to a basic module in your application.
A full list is provided in the module diCrEncode.txt.
You can then call the functions you require
as you would a normal VB function. You do not make a reference to it from your project and
you do not register it.
Make sure you use the correct variable types.
Instructions on how to distribute to other users as part of your applications
are provided with the Developer Version.
To call from a C/C++ program, there are a separate set of functions specifically for C/C++ programmers. For more details, see C/C++ Interface.
B64_Encode - Encodes a string of binary characters into a base64 string.
B64_Decode - Decodes a base64 encoded string into a string of binary values.
B64_Filter - Filters unwanted characters from a base64 encoded string.
B64_EncodeBytes - Encodes an array of bytes into a base64 string.
B64_DecodeBytes - Decodes a base64 encoded string into Variant Byte array.
B64_DecodeIntoBytes - Decodes a base64 encoded string into an array of Bytes.
HEX_Encode - Encodes a string of binary characters into a hexadecimal string.
HEX_Decode - Decodes a string of hexadecimal characters into a string of binary values.
HEX_Filter - Filters unwanted characters from a hexadecimal string.
HEX_EncodeBytes - Encodes an array of bytes into a hexadecimal string.
HEX_DecodeBytes - Decodes a hexadecimal string into Variant Byte array.
HEX_DecodeIntoBytes - Decodes a hexadecimal string into an array of Bytes.
HEX_CRC32 - Creates a hexadecimal CRC-32 checksum from a string of binary values.
B64_Encode encodes a string of binary data into a string of base64 characters.
Public Declare Function B64_Encode Lib "diCrEnc.dll"
(sInput As String) As String
sOutput = B64_Encode(sInput)
| sInput | String of binary data to be encoded. |
String of base64 encoded data.
Dim sInput As String
Dim sOutput As String
' Put some binary data in a string
' this creates the 8-byte string 0xFEDCBA9876543210
sInput = Chr(&HFE) & Chr(&HDC) & Chr(&HBA) & Chr(&H98) & _
Chr(&H76) & Chr(&H54) & Chr(&H32) & Chr(&H10)
' Encode into base64
sOutput = B64_Encode(sInput)
Debug.Print sOutput
This should result in output as follows:
/ty6mHZUMhA=
B64_Decode decodes a base64 encoded string into a string of binary values.
Public Declare Function B64_Decode Lib "diCrEnc.dll"
(sInput As String) As String
sOutput = B64_Decode(sInput)
| sInput | String of base64 characters to be decoded. |
String of binary values.
Chr(61)) denotes termination of the data.
Dim sInput As String
Dim sOutput As String
' Get a base64 string
sInput = "/ty6mHZUMhA="
' Decode (i.e. convert back) to binary
sOutput = B64_Decode(sInput)
' Display in hex format
Debug.Print HEX_Encode(sOutput)
This should result in output as follows:
FEDCBA9876543210
B64_Filter filters unwanted characters from a base64 encoded string.
Public Declare Function B64_Filter Lib "diCrEnc.dll"
(sInput As String) As String
sOutput = B64_Filter(sInput)
| sInput | String of mixed base64 and other characters. |
String of base64 encoded data excluding any non-base64 characters.
Dim sInput As String
Dim sOutput As String
' Make a base64 string with extra chars in it
sInput = "/ty6mH" & vbCrLf & "[ ZUMhA= ]" & vbCrLf
sOutput = B64_Filter(sInput)
Debug.Print sOutput
' add some null chars, too
sInput = "/ty6mH" & Chr(0) & "[ ZUMhA= ]" & Chr(0)
sOutput = B64_Filter(sInput)
Debug.Print sOutput
This should result in output as follows:
/ty6mHZUMhA= /ty6mHZUMhA=where all non-base64 characters have been removed.
B64_EncodeBytes encodes an array of bytes into a base64 string.
Public Declare Function B64_EncodeBytes Lib "diCrEnc.dll"
(abBytes() As Byte) As String
sOutput = B64_Encode(abBytes)
| abBytes | Byte array of binary data to be encoded. |
String of base64 encoded data.
Dim abInput() As Byte
Dim sOutput As String
' Put some binary data in a byte array
' This creates 0xFEDCBA9876543210 the long way
ReDim abInput(7) ' NB 8 bytes long
abInput(0) = &HFE
abInput(1) = &HDC
abInput(2) = &HBA
abInput(3) = &H98
abInput(4) = &H76
abInput(5) = &H54
abInput(6) = &H32
abInput(7) = &H10
' Encode into base64
sOutput = B64_EncodeBytes(abInput)
Debug.Print sOutput
This should result in output as follows:
/ty6mHZUMhA=The above input array could have been created using
abInput = HEX_DecodeBytes("FEDCBA9876543210")
B64_DecodeBytes decodes a base64 encoded string into a Variant Byte array.
Public Declare Function B64_DecodeBytes Lib "diCrEnc.dll"
(sInput As String) As Variant
vntOutput = B64_DecodeBytes(sInput)
| sInput | String of base64 characters to be decoded. |
Variant array of Bytes.
Dim sInput As String
Dim vntOutput As Variant
Dim abBytes() As Byte
' Take a base64 string
sInput = "/ty6mHZUMhA="
' Decode (i.e. convert back) into binary values
vntOutput = B64_DecodeBytes(sInput)
' Get a proper Byte array from the Variant
abBytes() = vntOutput
' Display in hex format
Debug.Print HEX_EncodeBytes(abBytes)
This should result in output as follows:
/ty6mHZUMhA=
B64_DecodeIntoBytes
[Back to Top]
B64_DecodeIntoBytes decodes a base64 encoded string into an array of Bytes.
Public Declare Function B64_DecodeIntoBytes Lib "diCrEnc.dll"
(abBytes() As Byte, sInput As String) As Long
nLen = B64_DecodeIntoBytes(abOutput, sInput)
| abOutput | Byte array suitably dimension to receive output. |
| sInput | String of base64 data to be decoded. |
Long containing number of bytes in decoded array.
The B64_DecodeIntoBytes function is provided for those who
don't like Variant arrays and who prefer the more bold Win32-like API
functions that require the user to find out and then dimension the necessary
storage space. Each to his own...
Dim sInput As String
Dim abOutput() As Byte
Dim nLen As Long
' Take a base64 string
sInput = "/ty6mHZUMhA="
' Get the required length by sending an empty array
nLen = B64_DecodeIntoBytes(abOutput, sInput)
' IMPORTANT: user must check returned value of nLen
If (nLen > 0) Then
ReDim abOutput(nLen - 1)
nLen = B64_DecodeIntoBytes(abOutput, sInput)
Debug.Print HEX_EncodeBytes(abOutput)
End If
This should result in output as follows:
FEDCBA9876543210
HEX_Encode encodes a string of binary data into a string of hexadecimal characters.
Public Declare Function HEX_Encode Lib "diCrEnc.dll"
(sInput As String) As String
sOutput = HEX_Encode(sInput)
| sInput | String of binary data to be encoded. |
String of hexadecimal encoded data.
Dim sInput As String
Dim sOutput As String
' Put some binary data in a string
' this creates the 8-byte string 0xFEDCBA9876543210
sInput = Chr(&HFE) & Chr(&HDC) & Chr(&HBA) & Chr(&H98) & _
Chr(&H76) & Chr(&H54) & Chr(&H32) & Chr(&H10)
' Encode into hexadecimal
sOutput = HEX_Encode(sInput)
Debug.Print sOutput
This should result in output as follows:
FEDCBA9876543210This trivial example shows how to obtain a printable hexadecimal-encoded string from a string of any binary values.
HEX_Decode decodes a hexadecimal encoded string into a string of binary values.
Public Declare Function HEX_Decode Lib "diCrEnc.dll"
(sInput As String) As String
sOutput = HEX_Decode(sInput)
| sInput | String of hexadecimal characters to be decoded. |
String of binary values.
HEX_Decode("FED") will return &HFE, ignoring the trailing odd digit.
Dim sInput As String
Dim sOutput As String
' Get a hexadecimal string
sInput = "FEDCBA9876543210"
' Decode (i.e. convert back) to binary
sOutput = HEX_Decode(sInput)
' Display in hex format
Debug.Print HEX_Encode(sOutput)
This should result in output as follows:
FEDCBA9876543210If the results of decoding a hexadecimal string back into a binary string contain unprintable characters - as in our example above - using a command like
Debug.Print sOutput will display something, well,
unprintable. (The following example may or may not display correctly in your browser).
sInput = "FEDCBA9876543210"
sOutput = HEX_Decode(sInput)
Debug.Print sOutput
þܺ◊vT2♦
These examples are trivial. If you know what you want, the HEX_Decode function delivers what you need.
This example decodes printable characters.
Dim sInput As String
Dim sOutput As String
' Get a hexadecimal string of printable ASCII characters
sInput = "6162636465665a"
' Decode (i.e. convert back) to binary
sOutput = HEX_Decode(sInput)
' Display
Debug.Print sOutput
This should result in output as follows:
abcdefZ
HEX_Filter filters unwanted characters from a hexadecimal encoded string.
Public Declare Function HEX_Filter Lib "diCrEnc.dll"
(sInput As String) As String
sOutput = HEX_Filter(sInput)
| sInput | String of mixed hexadecimal and other characters. |
String of hexadecimal encoded data excluding any non-hexadecimal characters.
Dim sInput As String
Dim sOutput As String
' Make a hexadecimal string with extra chars in it
sInput = "FEDCB" & vbCrLf & "[ A9876543210 ]" & vbCrLf
sOutput = HEX_Filter(sInput)
Debug.Print sOutput
' add some null chars, too
sInput = "FEDCB" & Chr(0) & "[ A9876543210 ]" & Chr(0)
sOutput = HEX_Filter(sInput)
Debug.Print sOutput
This should result in output as follows:
FEDCBA9876543210 FEDCBA9876543210where all non-hexadecimal characters have been removed.
HEX_EncodeBytes encodes an array of bytes into a hexadecimal string.
Public Declare Function HEX_EncodeBytes Lib "diCrEnc.dll"
(abBytes() As Byte) As String
sOutput = HEX_Encode(abBytes)
| abBytes | Byte array of binary data to be encoded. |
String of hexadecimal encoded data.
Dim abInput() As Byte
Dim sOutput As String
' Put some binary data in a byte array
' This creates 0xFEDCBA9876543210 the long way
ReDim abInput(7) ' NB 8 bytes long
abInput(0) = &HFE
abInput(1) = &HDC
abInput(2) = &HBA
abInput(3) = &H98
abInput(4) = &H76
abInput(5) = &H54
abInput(6) = &H32
abInput(7) = &H10
' Encode into hexadecimal
sOutput = HEX_EncodeBytes(abInput)
Debug.Print sOutput
This should result in output as follows:
FEDCBA9876543210The above input array could have been created simply by using
abInput = HEX_DecodeBytes("FEDCBA9876543210")
and (for what it's worth with this trivial example) the result can be obtained directly by
Debug.Print HEX_EncodeBytes(HEX_DecodeBytes("FEDCBA9876543210"))
HEX_DecodeBytes decodes a hexadecimal encoded string into a Variant Byte array.
Public Declare Function HEX_DecodeBytes Lib "diCrEnc.dll"
(sInput As String) As Variant
vntOutput = HEX_DecodeBytes(sInput)
| sInput | String of hexadecimal characters to be decoded. |
Variant array of Bytes.
HEX_DecodeBytes("FED") will return &HFE,
ignoring the trailing odd digit.
Dim sInput As String
Dim vntOutput As Variant
Dim abBytes() As Byte
' Take a hexadecimal string
sInput = "FEDCBA9876543210"
' Decode (i.e. convert back) into binary values
vntOutput = HEX_DecodeBytes(sInput)
' Get a proper Byte array from the Variant
abBytes() = vntOutput
' Display in hex format
Debug.Print HEX_EncodeBytes(abBytes)
This should result in output as follows:
FEDCBA9876543210
HEX_DecodeIntoBytes
[Back to Top]
HEX_DecodeIntoBytes decodes a hexadecimal encoded string into an array of Bytes.
Public Declare Function HEX_DecodeIntoBytes Lib "diCrEnc.dll"
(abBytes() As Byte, sInput As String) As Long
nLen = HEX_DecodeIntoBytes(abOutput, sInput)
| abOutput | Byte array suitably dimension to receive output. |
| sInput | String of hexadecimal data to be decoded. |
Long containing number of bytes in decoded array.
The HEX_DecodeIntoBytes function is provided for those who
don't like Variant arrays and who prefer the more bold Win32-like API
functions that require the user to find out and then dimension the necessary
storage space. Each to his own...
Dim sInput As String
Dim abOutput() As Byte
Dim nLen As Long
' Take a hexadecimal string
sInput = "FEDCBA9876543210"
' Get the required length by sending an empty array
nLen = HEX_DecodeIntoBytes(abOutput, sInput)
' IMPORTANT: user must check returned value of nLen
If (nLen > 0) Then
' Allocate storage space in array (NB zero-based)
ReDim abOutput(nLen - 1)
nLen = HEX_DecodeIntoBytes(abOutput, sInput)
Debug.Print HEX_EncodeBytes(abOutput)
End If
This should result in output as follows:
FEDCBA9876543210
HEX_CRC32 creates a hexadecimal CRC-32 checksum from a string of binary values.
Public Declare Function HEX_CRC32 Lib "diCrEnc.dll"
(sInput As String) As String
sOutput = HEX_CRC32(sInput)
| sInput | String of binary data. |
String containing an 8-character CRC-32 checksum in hexadecimal format.
vbCrLf) is treated as two separate bytes of value Chr(13) and Chr(10).
Dim sInput As String
Dim sOutput As String
' Take a string we want to check
sInput = "123456789"
' Calculate CRC-32 checksum
sOutput = HEX_CRC32(sInput)
Debug.Print sOutput
This should result in output as follows:
CBF43926
A full set of the required declaration statements are provided in the module
diCrEncode.bas. Include this module in your VB or VBA project.
A copy of this file is installed by default in the directory
C:\Program Files\CryptoSysEncode
unless you selected a different directory on setup.
The functions decribed above are designed specifically for Visual Basic programmers. They use the Windows OLE automation functions to handle Visual Basic String and Array types, which removes the need to dimension variables before calling the functions.
There are a separate set of functions provided for C/C++ programmers. These require you to do all the work of making sure your output variables are the correct size before calling the functions. However, as a C programmer you will no doubt be used to it. We have included the hex conversion functions mainly for the sake of completeness, as C already has quite convenient conversion functions available. However, for large data sets, you should still find the algorithm used here to be faster than the internal C library functions. Remember that the only limit on the size of data that can be encoded is the amount of free memory on your system.
/* BASE64 ENCODING PROTOTYPES */ long _stdcall cB64_EncodeBytes(char *output, long out_len, unsigned char *input, long in_len); long _stdcall cB64_DecodeIntoBytes(unsigned char *output, long out_len, char *input); long _stdcall cB64_Filter(char *output, char *input, long len); /* HEXADECIMAL ENCODING PROTOTYPES */ long _stdcall cHEX_EncodeBytes(char *output, long out_len, unsigned char *input, long in_len); long _stdcall cHEX_DecodeIntoBytes(unsigned char *output, long out_len, char *input); long _stdcall cHEX_Filter(char *output, char *input, long len); /* CRC-32 PROTOTYPE */ long _stdcall cHEX_CRC32(char *output, unsigned char *input, long in_len);
Note the lower-case letter 'c' preceding each name here to differentiate from the functions in the Visual Basic interface.
We have used the ANSI standard char* and unsigned char* types here,
but could have used the Windows
LPSTR and LPBYTE instead.
There is a sample C program included that shows some simple example uses of each of these functions. The following list summarises the requirements and quirks:
cB64_EncodeBytes() encodes in_len bytes from input and writes a zero-terminated base64
string into output up to a maximum of out_len characters. The function returns
the number of characters in the base64 string.
If output is set as NULL or out_len as zero, the function returns the required length of
the base64 string including the termination zero. Use this returned value to allocate the required memory.
cB64_DecodeIntoBytes() decodes a zero-terminated base64
string in input and writes the resulting bytes into output
up to a maximum of out_len bytes. The function returns
the number of bytes written.
If output is set as NULL or out_len as zero, the function returns the maximum
number of bytes that might be output. Use this returned value to allocate the required memory. Note that
the final number of bytes may be less that this maximum value, so always check the final number returned after
conversion.
cB64_Filter() filters out any non-base64 characters from a
string of characters in input and writes the resulting valid characters into output
together with a terminating zero.
The function will examine exactly len characters in input including any
embedded NUL characters. The function returns the number of valid base64 characters written.
The input and output buffers may the same.
The cHEX_EncodeBytes(), cHEX_DecodeIntoBytes() and cHEX_Filter() functions do exactly the same except for hexadecimal encoding.
cHEX_CRC32() calculates the CRC-32 checksum for in_len bytes in input and returns
the value as a 32-bit long. If output is not NULL, the function will write the CRC checksum
as an 8-character hexadecimal string in output. Make sure output is either at least 9 characters
long or is NULL.
The source code used in CryptoSys Encode includes work adapted from original C source code "cod64.c" by Carl M. Ellison (C) 1995 but otherwise is all original code written by David Ireland. Much appreciation is given to Carl M. Ellison for making his work available. Thanks to Chris Thompson for help in debugging.
Version 2.0. 17 August 2003: added interface for C/C++ programmers.
Version 1.2. 24 November 2002: added notes that any '=' character in a base64 string denotes the
termination of data.
Version 1.1. 16 September 2002: added remarks about odd characters to HEX_Decode and HEX_DecodeBytes.
Version 1.0. First published 2 September 2002 by DI Management Systems Pty Limited.
Copyright © 2002-3 D.I. Management Services Pty Limited ABN 78 083 210 584,
Sydney, Australia.
All rights reserved.
<www.di-mgt.com.au>
<www.cryptosys.net>