wwEncryption::EncryptString - West Wind Client Tools

wwEncryption::EncryptString

Symmetric two-way encryption with using string key with TripleDES or AES encryption. There are number of configuration options for provider, cipher, IV and optional hash value.

Although many combinations are available on this complex method, for simple two-way encryption using this library on both ends, you can just use the defaults with the first two or three parameters.

lcOrig = "Hello World"
lcKey = "f$addawd/\333#adawuy@!ds"

*** Example using Default settings for TripleDES 
lcVal  = loEnc.EncryptString(lcOrig, lcKey)
? lcVal  && encrypted

lcOrig2  = loEnc.DecryptString(lcVal, lcKey)
? lcOrig2  && Hello World

This default usage uses:

TripleDES
ECB Cipher Mode
PaddingMode PKCS7 (can't be changed currently)
MD5 Key Hashing (to 16 bytes)
base64 Encoded binary result string

You can customize the Provider (TripleDES and AES), CipherMode.

You can also optionally provide a key hash and salt. Use the latter only if you're using this library on both ends, or if an external library requires it. It's not uncommon to see libraries that require MD5 or SHA256 pre-hashed keys.

Encryption implies two-way that uses EncryptString() and DecryptString() to encode and decode strings. The output from encryption is a binary string in base64 (default) or binHex format.

It's important that DecryptString() uses the same parameters as EncryptString() to ensure that encrypted values can be round tripped!

o.EncryptString(lcInput, 
                lcEncryptionKey, 
                llUseBinHex,
                lcProvider, 
                lcCipherMode,
                lcEncryptionKeyHashAlgorithm, 
                lcEncryptionKeyHashSalt,
                lcIvKey)

Return Value

Encrypted string. Result is a base64 or binHex encoded string of the binary encrypted data.

Parameters

lcInput
The string to encrypt.

lcEncryptionKey
Optional - A pass-phrase used to encrypt the string.

If this string is not set the default static value set in the DLL is used. You can set the global default value at application startup using wwEncryption::SetEncryptionKey

The Encryption key is hashed via MD5 hashing to provide a valid key size for processing

llUseBinHex
Determines if the result binary value is returned as binHex (.T.) or base64 (.F. or default) string value

lcProvider

TripleDES (default)
AES

lcCipherMode
Optional cipher mode used to encrypt the value. Defaults to ECB which expects 16 byte keys.

ECB - auto-sizes
CBC - 16 bytes, 24 bytes
CFB
CTS
OFB

The default used in wwEncryption use: ECB with MD5 encoding (no salt) which yields a 16 byte fixed length keys passed to the algorithm. When using other cipher modes be sure to check your specs for key length and hash encoding requirements as each mode has its own key size requirements.

more info

lcEncryptionHashAlgorithm
Optionally specify an encryption key algorithm to hash the key to a specific key size (ie. MD5 = 16 bytes). Uses the same modes available in ComputeHash(). Note that key sizes have to match the key requirements of the provider and cipher. ECB cipher commonly works with MD5 hashes to provide the 16 byte key which lets you use non-exact keys.

lcEncryptionKeyHashSalt
Optional salt used to compute a hash for the encryption key.

lcIvKey
Optional IV Vector for cipher modes (like CBC) that require IV byte sequences.

Remarks

There are many combinations of Encryption Provider, Ciphers, Hash formats and key lengths. Be sure you know what format is required for your scenario if you are not using this library for round trip conversions.

We recommend you don't call these methods directly in your application code, but rather create simple application specific Encrypt() and Decrypt() methods or functions that your application code calls and that to wrap up all the complexity of these two method calls in one place.

Example

DO wwEncryption

LOCAL loEnc as wwEncryption
loEnc = CREATEOBJECT("wwEncryption")

lcOrig = "Hello World"
? lcOrig

*** 32 byte key (works best with most formats)
lcKey = "12345678901234567890123456789012"
? lcKey
? LEN(lcKey)

*** Example using Default settings for TripleDES 
lcVal  = loEnc.EncryptString(lcOrig, lcKey)
? lcVal

lcOrig  = loEnc.DecryptString(lcVal, lcKey)
? lcOrig


*** TripleDES explicit
lcVal  = loEnc.EncryptString(lcOrig, lcKey, .F., "TripleDES", "ECB", "MD5")
? lcVal

lcOrig  = loEnc.DecryptString(lcVal, lcKey, .F., "TripleDES", "ECB", "MD5")
? lcOrig

*** AES Example

*** 16 byte IvKey
lcIvKey = "1234567890123456"

*** Key Size 24 or 16 bytes
lcKey2 = PADR(lcKey, 24)

lcVal  = loEnc.EncryptString(lcOrig, lcKey2, .F., "AES", "CBC","","",lcIvKey)
? lcVal

lcOrig  = loEnc.EncryptString(lcVal, lcKey2, .F., "AES", "CBC","","",lcIvKey)
? lcOrig

Return Value

Parameters

Remarks

Example

See also: