Miraplacid Scripting Components Manual

  
 

Common information

Nowadays, information cannot be protected only by firewall or only by anti-virus software. Bad guys constantly invent new types of threats. They do it faster than Internet Security companies come up with appropriate protection. So all the sense is in a big trouble unless it is properly encrypted.
For e-commerce sites, using cryptography for collected users' information like credit card numbers is a must.

Private information should be protected from:
  • Hackers
  • Trojan "spy" viruses
  • Malicious users of the same service
  • Other hosting users (if site is hosted on some hosting)
  • Hosting administrators
  • Your site administrators (in the case of trusted e-commerce sites and when user's private information could be used only with user's permission)
Miraplacid Crypto Scripting Components provides easy access to several cyptography technologies.
MSCCrypto 2.0 includes:
  • RSA public key algorithm (512/1024/2048 bits key size)
  • AES symmetric block algorithm (128/192/256 bits key size)
  • Blowfish symmetric block algorithm (64 to 448 bits key size)
  • Twofish symmetric block algorithm (128/192/256 bits key size)
  • Cast5 (Cast 128) symmetric block algorithm (128 bits key size)
  • TripleDES symmetric block algorithm (192 bits key size)
  • MD5 hash (128 bits hash)
  • SHA1 hash (160 bits hash)
  • Ripemd hash (160 bits hash)
  • 32-bit CRC checksum algorithm
  • 24-bit CRC checksum algorithm
Which algorithm will fit your needs?
  • If the information will be encrypted and decrypted by the same client it make sense to use symmetric algorithm.
  • If the information will be encrypted by Alice and decrypted by Bob, use Public Key algorithm (RSA):
    1. Generate Keypair (means, Private and Public key) for Bob.
      (This should be done once, then private and public keys should be stored in the system. It is recommended to encrypt Bob's Private key using some symmetric algorithm, which key will be derived from Bob's password. Password should not be stored in the system in plain form.
      Public keys should be stored unencrypted, so it must be available to other users of the system.
    2. Generate symmetric random key for the encryption session.
    3. Encrypt the information with this key.
    4. Encrypt the session key with Bob's Public key.
    5. When Bob log in to the system, he enters his password. System decrypts his Private key, decrypts session key and the message. Bob can now read the message from Alice.
    Using symmetric session keys together with Public key algorithms is a common technique because Public key algorithms are much slower than symmetric ones and should not be used for encryption of large amounts of data.
Note: Component designed for Apartment threading model. Therefore, the best scope of their using is ASP page level scope. Using components of version 2.0 in Application and Session scopes may cause problems with your ASP Server (IIS or Chili) productivity.
To learn more about ASP execution scopes, see your ASP Server manual.

Common notes for symmetric algorithms
Symmetric algorithms (AES, Blowfish, Twofish, Cast and TripleDES) use the same key for both encryption and decryption. They slice data into blocks of a particular length and encrypt blocks. Some "padding" data (of length your_data_length%alg_block_length) can be added to the end of the last block. Use function ExtractBlobFromBlob from MSCCryptoMisc to cut "padding" data in decoder.
Another important parameters of symmetric algorithms:
  • Mode. This parameter determines behaviour of encryption/decryption engine. Available modes in MSCCrypto 2.0 are:
    • ECB (Electronic Codebook). If the same block is encrypted twice with the same key, the resulting ciphertext blocks are also the same. This information could be useful for an attacker.
    • CBC (Cipher Block Chaining). A ciphertext block is obtained by first XORing the plaintext block with the previous ciphertext block, and encrypting the resulting value. This way adds cryptographic strength to your ciphertext.
    Default mode is ECB.
    Numeric values for these modes are: ECB=1, CBC=2.
  • Filler. This is a "padding" byte, which to be used by the encryption algoritm to fill up last block of data to get complete block. Default value is 0.
  • Keygen(key,salt) procedure. Generates a key of size length from salt value. Salt may be a password or some random data of arbitrary length. Salt data will be used as-is for key generation procedure; if its length will not be enough, necessary amount of Filler bytes will be appended; if it will be too long, it will be truncated.
    To generate random data, you may use Random or Keygen methods of MSCCryptoMisc.

Miraplacid MSCCryptoAES 2.0

MSCCryptoAES is based on Rijndael algorithm, which was selected by NIST to be final standard of Advanced Encryption Standard (AES).
The algorithm was developed by two Belgian cryptographers, Joan Daemen and Vincent Rijmen.
Block size is 16 bytes.

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoAES");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoAES")

Object reference


Method Parameters Return Value Description
KeyGen MSCBlob salt, Long length None See Common notes for symmetric algorithms
Valid length values are 16(128 bits), 24(196 bits), 32(256 bits).
Encrypt MSCBlob src MSCBlob Encrypts src and returns encrypted data. Before applying, a key must be generated or imported.
Decrypt MSCBlob src MSCBlob Decrypts src and returns decrypted data. Before applying, a key must be generated or imported. Resulting data may contain some Filler symbols at the tail.

Property Type Description
Key MSCBlob Read/Write property. Can be used for export/import cryptographic key in internal format.
Filler Long See Common notes for symmetric algorithms
Mode Long See Common notes for symmetric algorithms

Miraplacid MSCCryptoBlowfish 2.0

Blowfish was designed by Bruce Schneier.
It is a block cipher with variable length keys (up to 448 bits).
Block size is 8 bytes.

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoBlowfish");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoBlowfish")

Object reference


Method Parameters Return Value Description
KeyGen MSCBlob ,Long None See Common notes for symmetric algorithms
Valid length values are between 8(64 bits) and 56(448 bits).
Encrypt MSCBlob src MSCBlob Encrypts src and returns encrypted data. Before applying, a key must be generated or imported.
Decrypt MSCBlob src MSCBlob Decrypts src and returns decrypted data. Before applying, a key must be generated or imported. Resulting data may contain some Filler symbols at the tail.

Property Type Description
Key MSCBlob Read/Write property. Can be used for export/import cryptographic key in internal format.
Filler Long See Common notes for symmetric algorithms
Mode Long See Common notes for symmetric algorithms

Miraplacid MSCCryptoTwofish 2.0

Twofish is a new block cipher designed by Counterpane (whose CEO is Bruce Schneier).
The design is highly delicate, with many alternative ways of implementation.
Block size is 16 bytes.

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoTwofish");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoTwofish")

Object reference


Method Parameters Return Value Description
KeyGen MSCBlob ,Long None See Common notes for symmetric algorithms
Valid length values are 16(128 bits), 24(196 bits), 32(256 bits).
Encrypt MSCBlob src MSCBlob Encrypts src and returns encrypted data. Before applying, a key must be generated or imported.
Decrypt MSCBlob src MSCBlob Decrypts src and returns decrypted data. Before applying, a key must be generated or imported. Resulting data may contain some Filler symbols at the tail.

Property Type Description
Key MSCBlob Read/Write property. Can be used for export/import cryptographic key in internal format.
Filler Long See Common notes for symmetric algorithms
Mode Long See Common notes for symmetric algorithms

Miraplacid MSCCryptoCast 2.0

CAST5 is a block cipher developed by Carlisle Adams and Stafford Tavares. It is a fast cipher with variable length keys (between 40 and 128 bits in multiples of 8 bits) and 64-bit blocks. It has no known weaknesses.
Block size is 8 bytes.

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoCast");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoCast")

Object reference


Method Parameters Return Value Description
KeyGen MSCBlob ,Long None See Common notes for symmetric algorithms
Valid length value is 16(128 bits).
Encrypt MSCBlob src MSCBlob Encrypts src and returns encrypted data. Before applying, a key must be generated or imported.
Decrypt MSCBlob src MSCBlob Decrypts src and returns decrypted data. Before applying, a key must be generated or imported. Resulting data may contain some Filler symbols at the tail.

Property Type Description
Key MSCBlob Read/Write property. Can be used for export/import cryptographic key in internal format.
Filler Long See Common notes for symmetric algorithms
Mode Long See Common notes for symmetric algorithms

Miraplacid MSCCryptoTripleDES 2.0

Data Encryption Standard: a 64 bit block cipher with 16 iterations giving a 56 bit key.
DES, a long-standing US encryption standard is no longer considered secure. In the meantime, the recommendation is to use Triple-DES (3DES). This uses the same DES algorithm but increases the keyspace sufficiently to make a brute force attack infeasible.
Block size is 8 bytes.

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoTripleDES");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoTripleDES")

Object reference


Method Parameters Return Value Description
KeyGen MSCBlob ,Long None See Common notes for symmetric algorithms
Valid length value is 24(192 bits).
Encrypt MSCBlob src MSCBlob Encrypts src and returns encrypted data. Before applying, a key must be generated or imported.
Decrypt MSCBlob src MSCBlob Decrypts src and returns decrypted data. Before applying, a key must be generated or imported. Resulting data may contain some Filler symbols at the tail.

Property Type Description
Key MSCBlob Read/Write property. Can be used for export/import cryptographic key in internal format.
Filler Long See Common notes for symmetric algorithms
Mode Long See Common notes for symmetric algorithms

Miraplacid MSCCryptoPGP 2.0

PGP (Pretty Good Privacy) is a worldwide well-known tool for keeping sensitive information secure.
Technically, this is a set of symmetric and public key algorithms, hashes and data representation algorithms and formats. Current version of MSCCryptoPGP is fully compatible with OpenPGP and its clones, but only in symmetric encryption, like mcrypt.
MSCCryptoPGP does not support PGP public key operations, so you may exchange only symmetrically encrypted data between MSCCryptoPGP and other PGP-compliant software.

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoPGP");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoPGP")

Object reference


Method Parameters Return Value Description
Init LONG hash, LONG alg, LONG mode, LONG passes None Initializes PGP object. Parameters are:
  • hash - hash function will be used for key generation. Valid values are: 1 (MD5 hash), 2 (SHA1 hash) and 3 (Ripemd hash).
  • alg - symmetric encryption algorithms will be used by PGP. Valid values are:
    • 2 - TripleDES, keylength 128 bit
    • 3 - Cast5, keylength 128 bit
    • 4 - Blowfish, keylength 128 bit
    • 7 - AES, keylength 128 bit
    • 8 - AES, keylength 192 bit
    • 9 - AES, keylength 256 bit
    • 10 - Twofish, keylength 256 bit
    Other symmetric algorithms are not supported.
  • mode - PGP key generation mode.
    • 1 - simple key generation. Only password will be used in key generation procedure.
    • 2 - salted key generation. Password and salt value will be used for key generation.
    • 3 - iterated nad salted key generation. Password will be generated with salt value and iterated several times to make the key stronger.
  • passes - how many iterations should be done if mode = 3.
This method may not be called. In this case, default values will be applied.
Defaults are: hash = SHA1, alg = Blowfish, mode = 3, passes = 96.
Encrypt MSCBlob src MSCBlob Encrypts src and returns encrypted data. Before applying, a password must be set.
Decrypt MSCBlob src MSCBlob Decrypts src and returns decrypted data. Before applying, a password must be set.
Unlike other MSCCrypto* symmetric ciphers, MSCCryptoPGP does not add padding bytes to the tail.
Enarmor MSCBlob src String Makes PGP armored text message from encrypted data. May be used for including encrypted data to any textual content or transport (email).
Dearmor String src MSCBlob Makes binary encrypted data from PGP armored text. Tests contents of the message for format and CRC errors.

Property Type Description
Password MSCBlob Read only property. PGP key will be derived from this values using parameters set in Init procedure (or defaults)

Miraplacid MSCCryptoRSA 2.0

 RSA (Rivest-Shamir-Adleman) is the most commonly used public key algorithm.
RSA can be used both for encryption and for digital signatures. It uses two different keys: public and secret. Key length used in RSA is actually length in bits of modulo N, big number for encryption/decryption calculations.
To make data manipulations, you have to generate or import previously exported keys.
For encryption and signature verification procedures, public key required. For decryption and sign procedures, private key required.
You may not know private key of some other person. In this case, you will import to MSCCryptoRSA object his public key and you will be able to perform encrypt and verify operations only.
Another important part of RSA encryption scheme is Initialization Vector (IV). This is a set of data that will be used by RSA engine together with your data in encryption/decryption procedures. IV must be identical in both encryption and decryption procedures with the same data. This will allow you to increase your privacy (RSA produces different encrypted data with different IVs and the same input) and implement "sessions" in encryption/decryption process.
You don't have to set this value if you don't need this feature. Default value works good.
MSCCryptoRSA is an exact implementation of RFC 2437 "PKCS #1: RSA Cryptography Specifications Version 2.0".

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoRSA");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoRSA")

Object reference


Method Parameters Return Value Description
SetIV MSCBlob src None Sets Initialization Vector for encryption/decryption session. For mode detailed explanation, see above.
KeyGen MSCBlob salt1, MSCBlob salt2, Long length None Derives RSA keypair (public and private key) from salt1 and salt2 initial values. These values can be a username/password pair or some random data of arbitrary length. To generate random data, you may use Random method of MSCCryptoMisc.
Length of RSA keys determined by length parameter. Valid lengths are 64(512 bits), 128(1024 bits), 256(2048 bits).
Encrypt MSCBlob src MSCBlob Encrypts src and returns encrypted data. Before applying, a keypair must be generated or public key imported.
Decrypt MSCBlob src MSCBlob Decrypts src and returns decrypted data. Before applying, a keypair must be generated or private key imported.
Sign MSCBlob src MSCBlob Returns RSA digital signature for src. Length of signature will be equal to the length of RSA key. Before applying, a keypair must be generated or private key imported.
Verify MSCBlob msg, MSCBlob sign Long Verifies whether signature sign is a valid RSA signature for message msg produced with current keypair. Before applying, a keypair must be generated or public key imported.
Returns 1(true) if signature verified successfully, 0(false) if not.

Property Type Description
PublicKey MSCBlob Read/Write property. Can be used for export/import public key.
PrivateKey MSCBlob Read/Write property. Can be used for export/import private key.

Miraplacid MSCCryptoMisc 2.0

 MSCCryptoMisc includes cryptographic hash algorithms, CRC32 algorithm and random data generator.
Hash algorithms produce message digests (digital signatures) of fixed lengths from messages of arbitrary length.
Hash algorithms included into MSCCrypto:
  • SHA1 (Secure Hash Algorithm).This is a cryptographic hash algorithm published by the United States Government. It produces 160 bit hash value.
  • MD5 (Message Digest Algorithm 5) is a cryptographic hash algorithm developed at RSA Laboratories. It produces 128 bit hash value.
  • Ripemd (Ripemd-160) was developed in the framework of the EU project RIPE (RACE Integrity Primitives Evaluation, 1988-1992). It is intended to be used as a secure replacement for the 128-bit hash functions MD4, MD5, and RIPEMD. It produces 160 bit hash value.
Other methods are described below.

Component creation

To create component, use following constructions
  • JScript: var obj = Server.CreateObject("Miraplacid.MSCCryptoMisc");
  • VBScript: set obj = Server.CreateObject("Miraplacid.MSCCryptoMisc")

Object reference


Method Parameters Return Value Description
MD5 MSCBlob src MSCBlob Calculates and returns MD5 digest from message src.
SHA1 MSCBlob src MSCBlob Calculates and returns SHA1 digest from message src.
Ripemd MSCBlob src MSCBlob Calculates and returns Ripemd digest from message src.
Random Long length MSCBlob Returns pseudo-random data of length.
Keygen LONG hash, LONG length, MSCBlob password, MSCBlob salt, LONG passes MSCBlob Universal key generation procedure. Parameters are:
  • hash - hash function will be used for key generation. Valid values are: 1 (MD5 hash), 2 (SHA1 hash) and 3 (Ripemd hash).
    If hash = 0, default Miraplacid keygen will be used (MD5 + SHA1).
  • length - length of resulting key, in bytes.
  • password - password will be used for key generation.
  • salt - salt value for key generation. If salt = null or empty MSCBLob, simple key generation will be used.
  • passes - number of passes for iterated and salted key generation. Does not matter if salt is not used.
CRC32 MSCBlob Long Calculates and returns CRC32 checksum of message src.
CRC24 MSCBlob Long Calculates and returns CRC24 checksum of message src.
InsertLongToBlob MSCBlob blob,Long pos,Long value None Inserts Long value (32 bit) into Blob (blob) at position pos.
ExtractLongFromBlob MSCBlob blob,Long pos Long Extracts Long value (32 bit) from Blob blob from position pos.
InsertBlobToBlob MSCBlob dst,Long pos,MSCBlob src None Inserts Blob src into another Blob dst to position pos with its length. This method would help you to encrypt data using symmetric algorithms. On decryption, you may just use ExtractBlobFromBlob with decrypted value to extract only needed information, without any trailing filler bytes.
Also, these pair of methods allows you to pack several Blobs into one.
ExtractBlobFromBlob MSCBlob src,Long pos MSCBlob Extracts Blob from another Blob src from position pos.

 
 
Technical Support   Copyright © 2001 - 2005 by Miraplacid