Cryptography Lab Reference Manual

Zhang Luduo (张鲁夺) <support@zhangluduo.com>

Copyright (C) 2019 zhangluduo.com. All Rights Reserved.


Cryptography Lab Reference Manual                               May 2020
                                                            Version: 2.0
                         Author: Zhang Luduo, < support@zhangluduo.com >

Table of Contents
  1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . .  1
    1.1 What is CryptographyLab . . . . . . . . . . . . . . . . . . .  1
    1.2 Compile and test environment of ZmCrypto module . . . . . . .  2
    1.3 Getting started . . . . . . . . . . . . . . . . . . . . . . .  2
  2. Data type  . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
    2.1 struct BinaryData . . . . . . . . . . . . . . . . . . . . . .  2
    2.2 struct FileData . . . . . . . . . . . . . . . . . . . . . . .  2
    2.3 struct StringData . . . . . . . . . . . . . . . . . . . . . .  2
    2.4 enum CharacterSet . . . . . . . . . . . . . . . . . . . . . .  2
    2.5 enum ConvertFlag  . . . . . . . . . . . . . . . . . . . . . .  3
    2.6 enum CipherDataType . . . . . . . . . . . . . . . . . . . . .  3
    2.7 union struct CipherData . . . . . . . . . . . . . . . . . . .  3
    2.8 struct RsaKey . . . . . . . . . . . . . . . . . . . . . . . .  3
    2.9 enum CipherMode . . . . . . . . . . . . . . . . . . . . . . .  3
    2.10 enum PaddingMode . . . . . . . . . . . . . . . . . . . . . .  3
    2.11 enum CipherDirection . . . . . . . . . . . . . . . . . . . .  4
    2.12 int  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
    2.13 string . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
    2.14 bool . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
    2.15 byte*  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  3. Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
    3.1 NULL  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  4. Operator overload  . . . . . . . . . . . . . . . . . . . . . . .  4
    4.1 operator +  . . . . . . . . . . . . . . . . . . . . . . . . .  4
    4.2 operator -  . . . . . . . . . . . . . . . . . . . . . . . . .  4
    4.3 operator *  . . . . . . . . . . . . . . . . . . . . . . . . .  4
    4.4 operator /  . . . . . . . . . . . . . . . . . . . . . . . . .  4
    4.5 operator %  . . . . . . . . . . . . . . . . . . . . . . . . .  4
    4.6 operator -> . . . . . . . . . . . . . . . . . . . . . . . . .  4
  5. Functions  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
    5.1 $Inc  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
    5.2 $RsaCreateKey . . . . . . . . . . . . . . . . . . . . . . . .  5
    5.3 $RsaSetKey  . . . . . . . . . . . . . . . . . . . . . . . . .  5
    5.4 $RsaKeyToString . . . . . . . . . . . . . . . . . . . . . . .  5
    5.5 $RsaCheckPrivKey  . . . . . . . . . . . . . . . . . . . . . .  5
    5.6 $RsaCheckPubKey . . . . . . . . . . . . . . . . . . . . . . .  5
    5.7 $RsaesEncrypt . . . . . . . . . . . . . . . . . . . . . . . .  5
    5.8 $RsaesDecrypt . . . . . . . . . . . . . . . . . . . . . . . .  6
    5.9 $RsassaSignature  . . . . . . . . . . . . . . . . . . . . . .  6
    5.10 $RsassaVerify  . . . . . . . . . . . . . . . . . . . . . . .  6
    5.11 $Caesar  . . . . . . . . . . . . . . . . . . . . . . . . . .  6
    5.12 $BlockCipher . . . . . . . . . . . . . . . . . . . . . . . .  6
    5.13 $StreamCipher  . . . . . . . . . . . . . . . . . . . . . . .  7
    5.14 $Encoding  . . . . . . . . . . . . . . . . . . . . . . . . .  7
    5.15 $Decoding  . . . . . . . . . . . . . . . . . . . . . . . . .  8
    5.16 $Hash  . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
    5.17 $HMAC  . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
    5.18 $Checksum  . . . . . . . . . . . . . . . . . . . . . . . . .  9
    5.19 $FileData  . . . . . . . . . . . . . . . . . . . . . . . . .  9
    5.20 $BinaryData  . . . . . . . . . . . . . . . . . . . . . . . .  9
    5.21 $StringData  . . . . . . . . . . . . . . . . . . . . . . . .  9
    5.22 $BinaryToHexString . . . . . . . . . . . . . . . . . . . . .  9
    5.23 $TruncatedBinary . . . . . . . . . . . . . . . . . . . . . . 10
    5.24 $BinaryToString  . . . . . . . . . . . . . . . . . . . . . . 10
    5.25 $GetStringBytes  . . . . . . . . . . . . . . . . . . . . . . 10
    5.26 $ReadFile  . . . . . . . . . . . . . . . . . . . . . . . . . 10
    5.27 $WriteFile . . . . . . . . . . . . . . . . . . . . . . . . . 10
    5.28 $WriteNewFile  . . . . . . . . . . . . . . . . . . . . . . . 10
    5.29 $ShowBits  . . . . . . . . . . . . . . . . . . . . . . . . . 10
    5.30 $And . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
    5.31 $Or  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.32 $Not . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.33 $Xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.34 $HexStringFormat . . . . . . . . . . . . . . . . . . . . . . 11
    5.35 $Rand  . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.36 $IntToString . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.37 $MorseEncode . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.38 $MorseDecode . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.39 $PlayMorseCode . . . . . . . . . . . . . . . . . . . . . . . 11
    5.40 $PBKDF2  . . . . . . . . . . . . . . . . . . . . . . . . . . 11
    5.41 $BLAKE2sMAC  . . . . . . . . . . . . . . . . . . . . . . . . 12
    5.42 $BLAKE2bMA C . . . . . . . . . . . . . . . . . . . . . . . . 12
    5.43 $CBCMAC  . . . . . . . . . . . . . . . . . . . . . . . . . . 12
    5.44 $CMAC  . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
    5.45 $BinryStringToBinaryData . . . . . . . . . . . . . . . . . . 13
    5.46 $Rotl  . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
    5.47 $Rotr  . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
    5.48 $CCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
    5.49 $Help  . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
  6. BUG report technical support and feedback  . . . . . . . . . . . 14
  Appendix A. Test case in CryptographyLab  . . . . . . . . . . . . . 14
  Appendix B. Test vector in CryptographyLab  . . . . . . . . . . . . 14
  Appendix C. Performance of ZmCrypto module  . . . . . . . . . . . . 14
  Appendix D. Third party code  . . . . . . . . . . . . . . . . . . . 14
  Appendix E. Source code of ZmCrypto module  . . . . . . . . . . . . 14
  Appendix F. Frequently asked questions  . . . . . . . . . . . . . . 14

                   Cryptography Lab Reference Manual

1. Introduction

    1.1 What is CryptographyLab ?

                                                                [page 1]
------------------------------------------------------------------------
      CryptographyLab is a cryptographic analysis and learning tool for 
      programmers and fans. The CryptographyLab has built-in a lots of 
      cryptography algorithms. Including classical cipher algorithms 
      (such as Caesar cipher), HASH algorithm, block cipher algorithm, 
      stream cipher algorithm, public key cryptosystems, public Key 
      signature, MAC (Message Authentication Codes) and key derivation 
      functions etc.

      In addition, it has built-in some tool functions, including file 
      reading and writing functions, bit operation functions, 
      hexadecimal functions, digital certificate functions etc.

      The program contains follwing 3 modules:

        * ZmCrypto: It encapsulates all cryptography algorithms used by 
          CryptographyLab. And the ZmCrypto module is open source, it is
          written in standard C language and can be run on Windows and 
          Linux operating systems.
        
        * Exp: This module is used to grammar analyze for user input 
          function expressions.
        
        * UI: It's a simple MFC application. It provides two text 
          boxes, one is for user input, and an other one is for output
          the calculate result.

    1.2 Compile and test environment of ZmCrypto module

      - Ubuntu 16.04-i386 & gcc 5.4.0 & cmake 2.8
      - CentOS 6.4-x64 & gcc 4.4.7  & cmake 2.8
      - Windows8.1 64 bit version  & Visual studio 2013

    1.3 Getting started

      Here is a simple example, type following expression:

      $BinaryToHexString($Hash("SHA1", $StringData("zhangluduo", 
        MBCS)), U);

      The expression call $Hash function to calculate SHA1 digest of 
      "zhangluduo", and then call $BinaryToHexString function to 
      convert binary byte to an uppercase hex string.

      The output result is "13 56 06 51 9C 59 45 4C BE 7A 1D 17 C7 F8 
      E6 03 79 81 D9 3D "

2 Data type

  2.1 struct BinaryData

    struct BinaryData
    {
      [private] byte* Data;
      [private] int Size;
    };

    The BinaryData structure represents a piece of memory, usually it is
    used to binary data input or output of algorithms. 

  2.2 struct FileData

    struct FileData
    {
      [public] string FileName;
    };

    The FileData structure represents a file on disk. usually it is
    used to input or output a file of algorithms. 

  2.3 struct StringData

    struct StringData
    {
      [public] string TheString;
      [private] CharacterSet TheCharacterSet;
    };

    The StringData structure represents a string, in program the string 
    will be convert to binary data, so you need to specify a character 
    set for string used. Because different character set have different 
    data in memory.
    
    For example: "我爱你中国", the data in the UNICODE character set is 
    0x11 62 31 72 60 4F 2D 4E FD 56, in the UTF-8 character set, the 
    data is 0xE6 88 91 E7 88 B1 E4 BD A0 E4 B8 AD E5 9B BD, in the MBCS
    (Multi-Byte Chactacter System) character set, the data is 
    0xCE D2 B0 AE C4 E3 D6 D0 B9 FA.

    To get the binary data of a string in memory, you can call 
    $GetStringBytes function.

  2.4 enum CharacterSet

    enum CharacterSet
    {
      UTF8,
      UNICODE,
      MBCS,
                                                                [page 2]
------------------------------------------------------------------------
    };

    The CharacterSet enumeration used to specify encoding for string 
    in memory.

  2.5 enum ConvertFlag

    enum ConvertFlag
    {
      U, // To Uppercase
      L, // To Lowercase
    };

    The ConvertFlag enumeration used to convert binary data to 
    hexadecimal string, 'U' that will be convert to upper case, or 'L' 
    that will be convert to lower case.

  2.6 enum CipherDataType

    enum CipherDataType
    {
      BINRAY,
      FILE,
      STRING
    };

    The CipherDataType enumeration used to specify the type of 'union 
    struct CipherData' internal member.

  2.7 union struct CipherData

    union struct CipherData
    {
      [public] FileData   f;
      [public] BinaryData b;
      [public] StringData s;
      [hidden] CipherDataType Type;
    };

    The CipherData is a very important data type. Usually it is used to 
    input or output of algorithms. It has three members, however only 
    one member variable(f, b or s) works at a time. The variable 'Type'
    specifies which member is used.
  
    Normally, the input or output of an algorithm can be use three types
    of data. One is binary data, you can call $BinaryData function like 
    this $BinaryData(0x11 22 33 44). One is String data, you can call 
    $StringData function like this $StringData("HelloWorld", UTF8); And 
    the other is file data, you can call $FileData like this 
    $FileData("D:\Document\MyFile.txt");

  2.8 struct RsaKey

    struct RsaKey
    {
      [hidden] int bits;
      [hidden] BinaryData  n; 
      [hidden] BinaryData  e; 
      [hidden] BinaryData  d; 
      [hidden] BinaryData  p; 
      [hidden] BinaryData  q; 
      [hidden] BinaryData dp; 
      [hidden] BinaryData dq; 
      [hidden] BinaryData qp;
    };

    The RsaKey structure used to RSA alorithm.

  2.9 enum CipherMode

    enum CipherMode
    {
      ECB, // Electronic Code Book
      CBC, // Cipher Block Chaining
      CFB, // Cipher Feed Back
      OFB, // Output Feed Back
      CTR, // Counter
    };

    The CipherMode enumeration used to a block cipher algorithm.

  2.10 enum PaddingMode

    enum PaddingMode
    {
      NONE,     // No padding is done.
      PKCS7,    // The PKCS #7 padding string consists of a sequence of 
                // bytes, each of which is equal to the total number of 
                // padding bytes added. 
      ZEROS,    // The padding string consists of bytes set to zero.
      ANSIX923, // The ANSIX923 padding string consists of a sequence of 
                // bytes filled with zeros before the length.
      ISO10126, // The ISO10126 padding string consists of random data 
                // before the length.
    };

    Most plain text messages do not consist of a number of bytes that 
    completely fill blocks. Often, there are not enough bytes to fill 
                                                                [page 3]
------------------------------------------------------------------------
    the last block. When this happens, a padding string is added to the 
    text. For example, if the block length is 64 bits and the last 
    block contains only 40 bits, 24 bits of padding are added.
    
    Some encryption standards specify a particular padding scheme. The 
    following example shows how these modes work. Given a blocklength of
    8, a data length of 9, the number of padding octets equal to 7, and 
    the data equal to FF FF FF FF FF FF FF FF FF:

    Data: FF FF FF FF FF FF FF FF FF    
    X923 padding: FF FF FF FF FF FF FF FF FF 00 00 00 00 00 00 07    
    PKCS7 padding: FF FF FF FF FF FF FF FF FF 07 07 07 07 07 07 07    
    ISO10126 padding: FF FF FF FF FF FF FF FF FF 7D 2A 75 EF F8 EF 07

  2.11 enum CipherDirection

    enum CipherDirection
    {
      ENCRYPT,
      DECRYPT,
    };

    ENCRYPT is used for encryption algorithm, DECRYPT is used for 
    decryption algorithm.

  2.12 int

    int

    An integer type, in Cryptographylab it's a 64-bit integer. 

  2.13 string

    string

    See 2.3 struct StringData.

  2.14 bool

    bool (true || false)

    A boolean value type.

  2.15 byte*

    byte*

    See 2.1 struct BinaryData.

3 Constant

  3.1 NULL

    NULL

    A NULL value represents an empty BinaryData structure.

4 Operator overload

  4.1 operator +

    int operator + (int, int);
    string operator + (string, string);
    BinaryData operator + (BinaryData, BinaryData);

  4.2 operator -

    int operator - (int, int);

  4.3 operator *

    int operator * (int, int);

  4.4 operator /

    int operator / (int, int);

  4.5 operator %

    int operator % (int, int);

  4.6 operator ->

    < Type > operator -> ();

    This operator is used to access public member variables in the
    structure.

5 Functions

  5.1 $Inc

    BinaryData $Inc(BinaryData _Binary
    );

    BinaryData $Inc(BinaryData _Binary, 
      int LoopCount
    );
                                                                [page 4]
------------------------------------------------------------------------

    Add one to the given binary data. For example: 
    05 04 03 02 01 FF + 1 the result is 05 04 03 02 02 00.

    Parameters
      _Binary   - Data to be calculated, add one start the lowest byte.
      LoopCount - Number of loop calculations.

  5.2 $RsaCreateKey

    RsaKey $RsaCreateKey(int KeyBits
    );

    This function create a valid RSA key using the 'KeyBits'.

    Remarks
      This function supports following RSA key bits, 512, 1024, 1536, 
      1792, 2048, 2560, 3072, 4096. To quickly generate random RSA key
      use the 64-bit version of CryptographyLab.

  5.3 $RsaSetKey

    RsaKey $RsaSetKey(string nHex, 
      string eHex
    ); 

    RsaKey $RsaSetKey(BinaryData n, 
      BinaryData e
    );

    These two functions are used for set up an RSA public key.

    RsaKey $RsaSetKey(string nHex, 
      string eHex, 
      string dHex, 
      string pHex, 
      string qHex, 
      string dpHex, 
      string dqHex, 
      string qpHex
    );

    RsaKey $RsaSetKey(string n, 
      BinaryData e, 
      BinaryData d, 
      BinaryData p, 
      BinaryData q, 
      BinaryData dp, 
      BinaryData dq, 
      BinaryData qp
    );

    These two functions are used for set up an RSA private key.

    Remarks
      n  - modulus INTEGER                         ,
      e  - publicExponent INTEGER                  ,
      d  - privateExponent INTEGER                 ,
      p  - prime1 INTEGER                          ,
      q  - prime2 INTEGER                          ,
      dp - exponent1 INTEGER d mod (p-1)           ,
      dq - exponent2 INTEGER d mod (q-1)           ,
      qp - coefficient INTEGER (inverse of q) mod p,

  5.4 $RsaKeyToString

    string $RsaKeyToString(RsaKey key
    );

    This function converts an RSA key to hexadecimal string.

  5.5 $RsaCheckPrivKey

    bool $RsaCheckPrivKey(RsaKey key
    );

    This function check the given RSA key is valid private key.

  5.6 $RsaCheckPubKey

    bool $RsaCheckPubKey(RsaKey key
    );

    This function check the given RSA key is valid public key.

  5.7 $RsaesEncrypt

    CipherData $RsaesEncrypt(string Scheme /* "OAEP" || "PKCS1_V15" */, 
      RsaKey Key, 
      CipherData Input, 
      CipherData Output, 
      [string Hash, [CipherData Label]]
    );

    This function uses RSA algorithm to encrypt data.

    Parameters
      Scheme - Set to "OAEP" or "PKCS1_V15"
                                                                [page 5]
------------------------------------------------------------------------
      Key    - A valid RSA public key.
      Input  - This is the data that will be encrypted.
      Output - This is the result of data encrypted.
      Hash   - Select a HASH altorithm for MGF function. 
      Label  - optional label to be associated with the message; The 
               value can be the empty string.

    Remarks
      If you choose the "PKCS1_V15" encryption scheme, then the 'Hash' 
      and 'Label' parameters are not required. For "OAEP" encryption
      scheme, you must set 'Hash' to "MD2", "MD5", "SHA1", "SHA256", 
      "SHA384" or "SHA512", 

      For more information.see rfc2313 or rfc3447.

  5.8 $RsaesDecrypt

    CipherData $RsaesDecrypt(
      string Scheme /* "OAEP" || "PKCS1_V15" */, 
      RsaKey Key, 
      CipherData Input, 
      CipherData Output, 
      [string Hash, [CipherData Label]]
    );

    Remarks
      See 5.7 $RsaesEncrypt.

  5.9 $RsassaSignature

    BinaryData $RsassaSignature(
      string Scheme /* "PSS"  || "PKCS1_V15" */, 
      RsaKey Key,
      CipherData Input, 
      string Hash
    );

    This function uses the RSA algorithm to sign data.

    Parameters
      Scheme - Set to "PSS" or "PKCS1_V15"
      Key    - A valid RSA private key.
      Input  - The message to be signed.
      Hash   - Select a HASH altorithm for MGF function. 

    Remarks
      For "PKCS1_V15" signature scheme, you must set 'Hash' to "MD2", 
      "MD4" or "MD5". For "PSS" signature scheme, you must set 'Hash' to
      "MD2", "MD5", "SHA1", "SHA1", "SHA256", "SHA384", "SHA512".

      See rfc2313 or rfc3447 for more information.

  5.10 $RsassaVerify

    bool $RsassaVerify(string Scheme /* "PSS"  || "PKCS1_V15" */, 
      RsaKey Key, 
      CipherData InputData, 
      CipherData SignatureData, 
      string Hash
    );

    Remarks
      See 5.9 $RsassaSignature, or rfc2313, rfc3447 for more information.

  5.11 $Caesar

    string $Caesar(string s, 
      int Key, 
      CipherDirection d
    );

    This function implement the Caesar cipher of classic.

    Remarks
      This function supports following characters, a-z, A-Z, 0-9, 0x20 
      and ~ ! @ # $ % ^ & * ( ) _ + - = [ ] \ { } | ; ' : " , . / < > ? 

  5.12 $BlockCipher

    CipherData $BlockCipher(string _Algorithm,
      CipherData      _Key, 
      CipherData      _Iv, 
      CipherMode      _Mode, 
      Padding         _Padding, 
      CipherData      _Input, 
      CipherData      _Output, 
      CipherDirection _Direction
    );

    This function calls the specified block cipher algorithm to encrypt 
    or decrypt data.

    Parameters
      _Algorithm  - A block cipher name.
      _Key        - A string, binary or a file key data for you specify 
                    cipher. The length of key data must be valid. E.g 
                    AES, the valid key length is 16 bytes, 24 bytes or 
                    32 bytes.
                                                                [page 6]
------------------------------------------------------------------------
      _Iv         - Initialization Vector. For ECB cipher mode set the 
                   value to be $BinaryData(NULL), for other cipher mode,
                   set to a valid IV. It's length is same as length of 
                   block size of the block cipher.
      _Mode      - Set to following modes ECB, CBC, CFB, OFB or CTR.
      _Padding   - Set to following padding scheme NONE, PKCS7,  ZEROS, 
                   ANSIX923, ISO10126.
      _Input     - The input data for cipher, you can choose a string, 
                   binary data or a file.
      _Output    - The output result for cipher, you can choose a string, 
                   binary data or a file. When you specify output data type
                   is string or binary, you must set to value is NULL, 
                   like this $StringData(UTF8 /* UNICODE | MBCS*/) or 
                   $BinaryData(NULL)
      _Direction - Set to ENCRYPT or DECRYPT.
    
    Remarks
      This function supports following algorithms  (case insensitive),
      "aes",
      "des",
      "blowfish",
      "sm4" || "sm-4",
      "twofish",
      "camellia",
      "cast-128" || "cast128",
      "cast-256" || "cast256",
      "tea",
      "xtea",
      "3des" || "3-des" || "des3" || "des-3",
      "idea",
      "seed",
      "safer-k64",
      "safer-k128",
      "serpent",
      "mars",
      "rc2",
      "rc5",
      "rc6",
      "3way" || "3-way" || "three-way" || "threeway"

  5.13 $StreamCipher

    CipherData $StreamCipher(string Algorithm, 
      CipherData Key, 
      CipherData Input, 
      CipherData Output, 
      CipherDirection _Direction
    );

    CipherData $StreamCipher(string Algorithm, 
      CipherData Key, 
      CipherData Iv, 
      CipherData Input, 
      CipherData Output, 
      CipherDirection _Direction
    );

    This function calls the specified stream cipher algorithm to encrypt
    or decrypt data.

    Parameters
      Algorithm  - A stream cipher name.
      Key        - A string, binary or a file key data for you specify 
                    cipher. The length of key data must be valid. E.g 
                    "ARC4" the valid key length between 1 and 256 bytes.
      Iv         - Initialization Vector. 
      Input      - The input data for cipher, you can choose a string, 
                   binary data or a file.
      Output     - The output result for cipher, you can choose a string, 
                   binary data or a file. When you specify output data type
                   is string or binary, you must set to value is NULL, 
                   like this $StringData(UTF8 /* UNICODE | MBCS*/) or 
                   $BinaryData(NULL)
      Direction  - Set to ENCRYPT or DECRYPT

    Remarks
      This function supports following algorithms (case insensitive),
      "arc4", "salsa20", "xsalsa20".

  5.14 $Encoding

    CipherData $Encoding(string Algorithm, 
      CipherData Input, 
      CipherData Output
    );

    CipherData $Encoding(string Algorithm, 
      CipherData Input, 
      CipherData Output, 
      string Param
    ); 

    This function calls the specified encoding algorithm to encode the 
    data.

    Parameters
      Algorithm  - Set to "base32", "base64" or "base58".
      Input      - Data to be encoded.
                                                                [page 7]
------------------------------------------------------------------------
      Output     - The result of encoding.
      Param      - optional "LineSize:%d".

    Remarks
      This function supports following algorithms (case insensitive),
      "base32", "base64", "base58".

  5.15 $Decoding

    CipherData $Decoding(string Algorithm, 
      CipherData Input, 
      CipherData Output
    );

    This function calls the specified decoding algorithm to decode the 
    data.

    Parameters
      Algorithm  - Set to "base32", "base64" or "base58".
      Input      - Data to be decoded.
      Output     - The result of decoding.

    Remarks
      This function supports following algorithms (case insensitive),
      "base32", "base64", "base58".

  5.16 $Hash

    BinaryData $Hash(string Algorithm, 
      CipherData Input, 
      int IterateCount
    );

    BinaryData $Hash(string Algorithm, 
      CipherData Input
    );

    BinaryData $Hash(String Algorithm, 
      CipherData Input
      [, CipherData Key 
      [, int IterateCount]
      ]
    );

    This function calls the specified hash algorithm to calculate the
    message data.

    Parameters
      Input        - Message data.
      Key          - You can be use a key for keyd hash alorithm, E.g 
                     BLAKE2 or BLAKE2B.
      IterateCount - This function supports iterative operations when
                     'IterateCount' > 1.

    Remarks
      This function supports following algorithms (case insensitive),
      "md2",
      "md4",
      "md5",
      "ed2k",
      "sha1",
      "sha224" || "sha-224" || "sha2-224",
      "sha256" || "sha-256" || "sha2-256",
      "sha384" || "sha-384" || "sha2-384",
      "sha512" || "sha-512" || "sha2-512",
      "sha3-224",
      "sha3-256",
      "sha3-384",
      "sha3-512",
      "md6-224",
      "md6-256",
      "md6-384",
      "md6-512",
      "tiger",
      "whirlpool",
      "ripemd128" || "ripemd-128",
      "ripemd160" || "ripemd-160",
      "ripemd256" || "ripemd-256",
      "ripemd320" || "ripemd-320",
      "sm3",
      "blake2s-128",
      "blake2s-160",
      "blake2s-224",
      "blake2s-256",
      "blake2b-160",
      "blake2b-256",
      "blake2b-384",
      "blake2b-512"

  5.17 $HMAC

    BinaryData $HMAC(string Hash, 
      CipherData Key, 
      CipherData Input
    );

    This function calls the specified hash algorithm to generate an 
    HMAC.
                                                                [page 8]
------------------------------------------------------------------------

    Remarks
      This function supports following hash algorithms, 
      (case insensitive),
      "md2",
      "md4",
      "md5",
      "ed2k",
      "sha1",
      "sha224" || "sha-224" || "sha2-224",
      "sha256" || "sha-256" || "sha2-256",
      "sha384" || "sha-384" || "sha2-384",
      "sha512" || "sha-512" || "sha2-512",
      "sha3-224",
      "sha3-256",
      "sha3-384",
      "sha3-512",
      "md6-224",
      "md6-256",
      "md6-384",
      "md6-512",
      "tiger",
      "whirlpool",
      "ripemd128" || "ripemd-128",
      "ripemd160" || "ripemd-160",
      "ripemd256" || "ripemd-256",
      "ripemd320" || "ripemd-320",
      "sm3",
      "blake2s-128",
      "blake2s-160",
      "blake2s-224",
      "blake2s-256",
      "blake2b-160",
      "blake2b-256",
      "blake2b-384",
      "blake2b-512"

  5.18 $Checksum

    BinaryData $Checksum(string Algorithm, 
      CipherData Input, 
      int IterateCount
    );

    BinaryData $Checksum(string Algorithm, 
      CipherData Input
    );

    This function calls the specified checksum algorithm for data 
    calculation.

    Remarks
      This function supports following checksum algorithms, 
      (case insensitive),
      "adler32" || "adler-32",
      "crc32" || "crc-32",

  5.19 $FileData

    CipherData $FileData(string FileName
    );

    This function is used for the input file data of other functions.

  5.20 $BinaryData

    CipherData $BinaryData(
    );

    CipherData $BinaryData(byte* _Data
    );

    This function is used for the input binary data of other functions.
    If you want to input NULL, you can call this function like this 
    "$BinaryData()" or "$BinaryData(NULL)". Otherwise, you should enter
    a hexadecimal number like this "0x11 22 33 44".

  5.21 $StringData

    CipherData $StringData(CharacterSet _Set
    );

    CipherData $StringData(string s, 
      CharacterSet _Set
    );

    This function is used for the input string data of other functions.

  5.22 $BinaryToHexString

    string $BinaryToHexString(BinaryData _Data, 
      ConvertFlag _Flag
    );

    string $BinaryToHexString(BinaryData _Data, 
      ConvertFlag _Flag, 
      int LineSize
    );
                                                                [page 9]
------------------------------------------------------------------------

    string $BinaryToHexString(BinaryData _Data, 
      ConvertFlag _Flag, 
      int LineSize, 
      bool AddSpace
    );

    This function converts the binary data to hexadecimal format string.

    Parameter
      _Data    - The binary data to be converted.
      _Flag    - Upper case ot lower case.
      LineSize - Number of characters per line, not including the 
                 terminating blank(SPACE) character.
      AddSpace - A blank character needs to be inserted between 
                 each byte.

  5.23 $TruncatedBinary

    BinaryData $TruncatedBinary(
      BinaryData _Data, int Offset
    );

    BinaryData $TruncatedBinary(
      BinaryData _Data, 
      int Offset, 
      int Counnt
    );

    The function is used to truncate a segment of binary data.

    Parameter
      _Data   - Binary data to be truncated.
      Offset  - Offset to be truncated.
      Counnt  - The number of bytes to truncated.

  5.24 $BinaryToString

    string $BinaryToString(BinaryData _Data, 
      CharacterSet _Set
    );

    This function is used to convert binary data into a string. You 
    should be noted that the character set must be specified correctly, 
    otherwise garbled characters may appear.

  5.25 $GetStringBytes

    Binary $GetStringBytes(StringData _stringData
    );

    This function return the binary data in the memory 
    where the string is located.

  5.26 $ReadFile

    BinaryData $ReadFile(string FileName, 
      int BytesToRead, 
      int Offset
    );

    This function reads data from an existing file.
    
    Parameter
      FileName     - File to be reads.
      BytesToRead  - nNumberOfBytesToRead,
      Offset       - 

  5.27 $WriteFile 

    bool $WriteFile(string FileName, 
      BinaryData _Data, 
      int Offset
    );

    This function writes data to an existing file.

  5.28 $WriteNewFile

    bool $WriteNewFile(string FileName, 
      BinaryData _Data
    );

    This function create a new file, and then writes data.

  5.29 $ShowBits

    string $ShowBits(BinaryData _Data
    );

    This function converts each bit in binary into string.

  5.30 $And

    BinaryData $And(BinaryData _Data1, 
      BinaryData _Data2
    );

                                                               [page 10]
------------------------------------------------------------------------
    Performs a logical and on two binary data.

  5.31 $Or

    BinaryData $Or(BinaryData _Data1, 
      byte* _Data2
    );

    Performs a logical or on two binary data.

  5.32 $Not

    BinaryData $Not(BinaryData _Data1
    );

    Performs a logical nor on one binary data.

  5.33 $Xor

    BinaryData $Xor(BinaryData _Data1, 
      BinaryData _Data2
    );

    Performs a logical xor on two binary data.

  5.34 $HexStringFormat

    string $HexStringFormat(string Hex
    );

    This function converts a hexadecimal string into two statements that
	can be used directly in the C/C++ language. Like this 
	"\x11\x22\x33\x44" or {0x11, 0x22, 0x33, 0x44}.

  5.35 $Rand

    string $Rand(int Count, 
      string Option
    );

    This function generates some random characters based on input 
    options.

    Remarks
      This function supports one or more of following option,
      "N", 0-9
      "C", A-Z
      "c", a-z
      "H", 0-9 || A-F
      "h", 0-9 || a-f
      "O", ~ ! @ # $ % ^ & ( ) _ + - = { } [ ] ; , .

  5.36 $IntToString

    string $IntToString(int n
    );

    string $IntToString(int n, int Width
    );

    The $IntToString function converts an integer to a string.

    Parameters
      n     - the integer.
      Width - Optional number that specifies the minimum number of 
              characters output. If characters count less then the 
              'Width', some zero('0') padding before for output.

  5.37 $MorseEncode

    string $MorseEncode(string s
    );

    This function converts English characters to Morse code.

  5.38 $MorseDecode

    string $MorseDecode(string s
    );

    This function converts Morse code to English characters.

  5.39 $PlayMorseCode

    string $PlayMorseCode(string s
    );

    This function Play the ticking sound of the given Morse code.
	
  5.40 $PBKDF2

    BinaryData $PBKDF2(string HMAC, 
      CipherData P, 
      CipherData S, 
      int c, 
      int 
      dkLen
    );
                                                               [page 11]
------------------------------------------------------------------------

    This function implements the 'PBKDF2' algorithm in rfc2898, for more
    information, see rfc2898.txt (PKCS #5: Password-Based Cryptography 
    Specification Version 2.0).
               
    Parameters
      HMAC  - PRF.
      P     - password, an octet string.
      S     - salt, an octet string.
      c     - iteration count, a positive integer.
      dkLen - intended length in octets of the derived key, a positive 
              integer.

    Remarks
      This function supports following HMAC algorithms (case 
      insensitive):
      "hmac-md2"
      "hmac-md4"
      "hmac-md5"
      "hmac-ed2k"
      "hmac-sha1"
      "hmac-sha224"
      "hmac-sha256"
      "hmac-sha384"
      "hmac-sha512"
      "hmac-sha3-224"
      "hmac-sha3-256"
      "hmac-sha3-384"
      "hmac-sha3-512"
      "hmac-md6-224"
      "hmac-md6-256"
      "hmac-md6-384"
      "hmac-md6-512"
      "hmac-tiger"
      "hmac-whirlpool"
      "hmac-ripemd128" || "hmac-ripemd-128"
      "hmac-ripemd160" || "hmac-ripemd-160"
      "hmac-ripemd256" || "hmac-ripemd-256"
      "hmac-ripemd320" || "hmac-ripemd-320"
      "hmac-sm3"

  5.41 $BLAKE2sMAC

    BinaryData $BLAKE2sMAC(int DigestSize, 
      CipherData Input, 
      CipherData Key
    );

    BLAKE2s can function as both a hash and keyed hash, the function 
    $BLAKE2sMAC implement keyed hash for BLAKE2s alorithm.

  5.42 $BLAKE2bMAC

    BinaryData $BLAKE2bMAC(int DigestSize, 
      CipherData Input, 
      CipherData Key
    );

    BLAKE2b can function as both a hash and keyed hash, the function 
    $BLAKE2bMAC implement keyed hash for BLAKE2b alorithm.

  5.43 $CBCMAC

    BinaryData $CBCMAC(String CipherName, 
      CipherData Key, 
      CipherData Message
    );

    CBC-MAC is compatible with FIPS 113. The MAC is secure only for 
    fixed length messages. 

    Remarks
	  This function supports following algorithms (case insensitive):
      "aes",
      "des",
      "blowfish",
      "sm4" || "sm-4",
      "twofish",
      "camellia",
      "cast-128" || "cast128",
      "cast-256" || "cast256",
      "tea",
      "xtea",
      "3des" || "3-des" || "des3" || "des-3",
      "idea",
      "seed",
      "safer-k64",
      "safer-k128",
      "serpent",
      "mars",
      "rc2",
      "rc5",
      "rc6",
      "3way" || "3-way" || "three-way" || "threeway",

  5.44 $CMAC

    BinaryData $CMAC(String CipherName, 
                                                               [page 12]
------------------------------------------------------------------------
      CipherData Key, 
      CipherData Message
    );

    The CMAC (Cipher-based Message Authentication Code) algorithm 
    implementation reference from rfc4493.txt, 

    Remarks
	  This function supports following algorithms (case insensitive):
      "aes",
      "des",
      "blowfish",
      "sm4" || "sm-4",
      "twofish",
      "camellia",
      "cast-128" || "cast128",
      "cast-256" || "cast256",
      "tea",
      "xtea",
      "3des" || "3-des" || "des3" || "des-3",
      "idea",
      "seed",
      "safer-k64",
      "safer-k128",
      "serpent",
      "mars",
      "rc2",
      "rc5",
      "rc6",
      "3way" || "3-way" || "three-way" || "threeway",

  5.45 $BinryStringToBinaryData

    Binary $BinryStringToBinaryData(
      string s
    );

    This function convert from binary string (like this 
    "01000110 10001111") to a BinaryData data type.

  5.46 $Rotl

  BinaryData $Rotl(
    BinaryData _Data, 
    int Shift
  );

  Rotates bits to the left.
  Parameters
    _Data - value
    Shift - Value to be rotated.

  5.47 $Rotr

  BinaryData $Rotr(
    BinaryData _Data, 
    int Shift
  );

  Rotates bits to the right.
  Parameters
    _Data - value
    Shift - Value to be rotated.

  5.48 $Help

  CipherData $CCM(
    String Algorithm,
    CipherData Key, 
    CipherData Iv, 
    CipherData AAD, 
    CipherData Input, 
    CipherData Output, 
    int TagLen, 
    CipherDirection _Direction
  );

  CCM is a generic authenticated encryption block cipher mode. CCM is 
  only defined for use with 128-bit block ciphers, such as AES [AES]. 
  The CCM design principles can easily be applied to other block sizes, 
  but these modes will require their own specifications.

  Parameters
    Algorithm  - A block cipher name, the block size must be 16.
    Key        - A string, binary or a file key data for you specify 
                 cipher. The length of key data must be valid. E.g 
                 AES, the valid key length is 16 bytes, 24 bytes or 
                 32 bytes.
    Iv         - Initialization Vector. You must set to a valid IV. 
                 It's length must be between 7 and 13.
    AAD        - Additional authenticated data.
    Input      - The input data for cipher, you can choose a string, 
                 binary data or a file.
    Output     - The output result for cipher, you can choose a string, 
                 binary data or a file. When you specify output data type
                 is string or binary, you must set to value is NULL, 
                 like this $StringData(UTF8 /* UNICODE | MBCS*/) or 
                 $BinaryData(NULL)
                                                               [page 13]
------------------------------------------------------------------------
    TagLen     - The MAC result value. Its length must be between 4 
                 and 16, and be an integer multiple of 2.
    _Direction - Set to ENCRYPT or DECRYPT.

  Remarks
    This function supports following algorithms  (case insensitive),
      "aes",
      "sm4" || "sm-4",
      "twofish",
      "camellia",
      "cast-256" || "cast256",
      "seed",
      "serpent",
      "mars",
      "rc6",

  5.49 $Help

    string $Help(string Keyword
    );

    Input keywords you want to help content, E.g "AES", "ECB" etc..

    Remarks
      Input a keyword, this function searches for content related this 
      keyword and displays. But currently no implemented.

6 BUG report technical support and feedback

  In case you want to contact me PRIVATELY, here's my PGP Key

  -----BEGIN PGP PUBLIC KEY BLOCK-----
  Version: GnuPG v1.4.9 (MingW32)

  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
  =HtCm
  -----END PGP PUBLIC KEY BLOCK-----

Appendix A. Test case in CryptographyLab

  http://zhangluduo.com/cryptographylab/testcase.html

Appendix B. Test vector in CryptographyLab

  http://zhangluduo.com/cryptographylab/testvector.html

Appendix C. Performance of Crypto module

  http://zhangluduo.com/cryptographylab/performance.html

Appendix D. Third party code

  http://zhangluduo.com/cryptographylab/3rdcode.html

Appendix E. Source code of Crypto module

  http://zhangluduo.com/cryptographylab/cryptosource.html

Appendix F. Frequently asked questions

  http://zhangluduo.com/cryptographylab/faq.html



                                                               [page 14]
------------------------------------------------------------------------

Copyright © 2019 Zhang Luduo .

All rights reserved.