# jBC ENCRYPT() / DECRYPT() functions

Updated: 11/30/2021, 7:00:45 PM
Created: 11/30/2021, 7:00:45 PM
Last Updated By: Jake Tuttle
Read Time: 5 minute(s)

Beginning with jBASE 5.8, the following information applies to the jBC ENCRYPT() and DECRYPT() functions.

In addition to the symmetric ciphers supported in previous jBASE releases, support has been added for:

  • Hashing (MD5, SHA1, SHA256, SHA384, SHA512)
  • Digital signature (RSA, HMAC)
  • Signature verification (RSA, HMAC)
  • Optional IV for symmetric ciphers
ENCRYPT(string, key, method, {extra, {password}})
DECRYPT(string, key, method, {extra})
1
2

The ENCRYPT function encrypts, hashes or signs a string. The DECRYPT function decrypts a string or verifies a digital signature.

The extra and password arguments are optional, and are used for certain ciphers and signature algorithms.

# Status Code

The ENCRYPT and DECRYPT functions will set a status code that can be checked using the STATUS() function. It is recommended that the status always be checked when using ENCRYPT and DECRYPT functions. The following status codes are used:

  • 0 indicates successful operation
  • 1 indicates the method is not recognized
  • 2 indicates the encryption operation failed

In the case of status code 2, the SYSTEM(0) function will return the last error code from the OpenSSL encryption library.

# Initialization Vector

Many ciphers support the use of an initialization vector or IV. The IV should be used for block ciphers, and should be a string of random bytes sized to match the block size of the cipher. If the IV is shorter than the block size, it is padded with zero bytes. If it is longer, the extra bytes are discarded. The IV can be shared with the recipient of the encrypted message and does not need to be secret.

# Hashing

The ENCRYPT function can produce a hash, or message digest, of an input string, returning a fixed-size hash of the input. The key argument is not used for the hash methods. The DECRYPT function will fail when used with a hash method.

# Digital Signatures

Digital signatures are supported using HMAC (keyed-hash message authentication code) or RSA public/private key pair. The ENCRYPT function is used to produce the signature of the supplied message, and the return value is the signature. The DECRYPT function is used to verify the signature, and the return value is 1 if the signature is verified or 0 if it is not. When verifying the signature, pass the signature in the extra argument.

If the BASE64 flag is included in the signature algorithm method (e.g. JBASE_SIGN_RSA_SHA256_BASE64), the signature returned by ENCRYPT is base64-encoded, and the signature supplied to DECODE should be base64-encoded.

For HMAC signatures, the key is a string of random bytes. For RSA signature generation, the key is an RSA private key in PEM format. If the private key is encrypted (password-protected), supply the password needed to decrypt the key in the password argument. For RSA signature verification, the key is an RSA public key in PEM format.

# Supported Algorithms

The following symmetric ciphers are supported:

  • JBASE_CRYPT_GENERAL General purpose encryption scheme
  • JBASE_CRYPT_AES128 AES 128 bit algorithm in CBC mode
  • JBASE_CRYPT_AES128_CTR AES 128 bit algorithm in CTR mode
  • JBASE_CRYPT_AES256 AES 256 bit algorithm in CBC mode
  • JBASE_CRYPT_AES256_CTR AES 256 bit algorithm in CTR mode
  • JBASE_CRYPT_AES alias for JBASE_CRYPT_AES256
  • JBASE_CRYPT_AES_CTR alias for JBASE_CRYPT_AES256_CTR
  • JBASE_CRYPT_ROT13 Simple ROT13 algorithm (key is not used)
  • JBASE_CRYPT_XOR11 XOR MOD11 algorithm (uses the first character of a key as a seed value)
  • JBASE_CRYPT_RC2 RC2 algorithm in CBC mode
  • JBASE_CRYPT_DES DES algorithm in CBC mode
  • JBASE_CRYPT_3DES Three key triple DES algorithm in CBC mode
  • JBASE_CRYPT_BLOWFISH Blowfish algorithm in CBC mode

The following hashing algorithms are supported:

  • JBASE_SECUREHASH_SHA1 Secure hash algorithm 1
  • JBASE_SECUREHASH_SHA256 Secure hash algorithm 2, 256 bits
  • JBASE_SECUREHASH_SHA384 Secure hash algorithm 2, 384 bits
  • JBASE_SECUREHASH_SHA512 Secure hash algorithm 2, 512 bits
  • JBASE_SECUREHASH_MD5 MD5 message*digest algorithm

The following RSA signature algorithms are supported:

  • JBASE_SIGN_RSA_SHA1 RSA digital signature using SHA1 hash algorithm
  • JBASE_SIGN_RSA_SHA256 RSA digital signature using SHA256 hash algorithm
  • JBASE_SIGN_RSA_SHA384 RSA digital signature using SHA384 hash algorithm
  • JBASE_SIGN_RSA_SHA512 RSA digital signature SHA512 hash algorithm
  • JBASE_SIGN_RSA_MD5 RSA digital signature using MD5 hash algorithm

The following HMAC signature algorithms are supported:

  • JBASE_SIGN_HMAC_SHA1 Keyed hash message authentication code using SHA1 hash algorithm
  • JBASE_SIGN_HMAC_SHA256 Keyed hash message authentication code using SHA256 hash algorithm
  • JBASE_SIGN_HMAC_SHA384 Keyed hash message authentication code using SHA384 hash algorithm
  • JBASE_SIGN_HMAC_SHA512 Keyed hash message authentication code using SHA512 hash algorithm
  • JBASE_SIGN_HMAC_MD5 Keyed hash message authentication code using MD5 hash algorithm

The following encodings are supported:

  • JBASE_CRYPT_BASE64

When used with ENCRYPT, returns the input string encoded using base64. When used with DECRYPT, decodes the base64 input string into its original (binary) content.

  • JBASE_CRYPT_BASE64_MASK

The base64 mask can be combined with any of the cipher, hash or signature methods. Each of the above constants has a _BASE64 version available. For example to use ASE256 with base64 encoding, use the JBASE_CRYPT_AES256_BASE64 method.

For symmetric ciphers, when the _BASE64 version is used, the ENCRYPT function returns the encrypted result using encoded in base64. For DECRYPT, the input string is decoded from base64 before decryption. For hash methods, the ENCRYPT function returns the hash encoded in base64. For signature algorithms, the ENCRYPT function returns the signature is encoded in base64, and the signature is passed to the DECRYPT function encoded in base64.

# WARNING!

Several of the cipher methods supported by the ENCRYPT function are considered insecure by modern standards. These ciphers are included only for compatibility with existing applications. These insecure ciphers should not be used when developing new applications:

  • JBASE_CRYPT_GENERAL
  • JBASE_CRYPT_ROT13
  • JBASE_CRYPT_XOR11
  • JBASE_CRYPT_DES
  • JBASE_CRYPT_3DES

Due to small block size or small key size, these ciphers are not recommended for new applications:

  • JBASE_CRYPT_RC2
  • JBASE_CRYPT_BLOWFISH

For best security, AES ciphers are recommended:

  • JBASE_CRYPT_AES128
  • JBASE_CRYPT_AES128_CTR
  • JBASE_CRYPT_AES256
  • JBASE_CRYPT_AES256_CTR
  • JBASE_CRYPT_AES
  • JBASE_CRYPT_AES_CTR

Back to Encryption