$decode

Decrypt or decode data, or verify a message by means of a digital signature.

Decrypt or decode: $decode(Algorithm,Source {,Key {,Mode,InitializationVector} } )

Verify message with signature: $decode(Algorithm,Source,Key,Signature)

Parameters

Argument	Description
Algorithm	Decoding, decryption, or signature verification algorithm; see Supported Algorithms.
Source	Data to be decoded or decrypted. For signature verification, it is the message to be verified.
Key	Key used to decrypt the data; required if Algorithm specifies a block cipher, asymmetric encryption scheme or signature scheme. The length of the key must be appropriate to the algorithm. For decryption with asymmetric key algorithms, it must be a valid private key for the encryption scheme. For signature verification, it must be a valid public key for the signature scheme.
Mode	Block cipher mode of operation; required if Algorithm specifies a block cipher. One of: `ECB`—electronic code book (default) `CBC`—cipher-block chaining `CFB`—cipher feedback `OFB`—output feedback `CTR`—counter `CBC_CTS`—CBC cipher text stealing
InitializationVector	A unique data block, such as a time stamp or random number, used in combination with the Key. Required for all modes except `ECB`
Signature	Digital signature of a message

The Source, Key, and InitializationVector parameters can specify a string, variable, or field. If the data type of a variable or field is Raw, it is evaluated as data type raw. Otherwise, it is evaluated as data type string . Optional parameters are ignored if they are irrelevant.

Return Values

When $decode is used for message verification, the returned value a boolean value indicating true (1) or false (0).

Decoding and decryption algorithms return decoded or decrypted data in the Uniface raw data type.

The returned data may contain the null byte (0x00), so the return value is in the Uniface raw data type, which is able to handle this. If you need to get the data in the string data type, then you can convert it from raw to string data using $encode with the USTRING algorithm.

If an error occurs, $procerror contains a negative value that identifies the exact error. Some errors provide more detailed information in the ADDITIONAL list item in $procerrorcontext.

Values Commonly Returned in $procerror after `$encode` / $decode
Value	Error constant	Meaning
`-1780`	`UENCERR_NO_ALGORITHM`	Algorithm not found.
`-1781`	`UENCERR_NO_SOURCE`	Source not found.
`-1782`	`UENCERR_NO_KEY`	Key not found.
`-1783`	`UENCERR_NO_IV`	IV not found.
`-1784`	`UENCERR_INVALID_ALGORITHM`	Invalid algorithm name.
`-1785`	`UENCERR_INVALID_MODE`	Invalid mode name.
`-1786`	`UENCERR_INVALID_KEY_LENGTH`	Invalid key length. The key must have a specific length that depends on the algorithm.
`-1787`	`UENCERR_INVALID_HEX_FORMAT`	Source is invalid HEX format.
`-1788`	`UENCERR_INVALID_BASE64_FORMAT`	Source is invalid BASE64 format.
`-1789`	`UENCERR_INVALID_URL_FORMAT`	Source is invalid URL format.
`-1791`	`UENCERR_GENERAL`	Encode/decode general error
`-1792`	`UENCERR_INVALID_SOURCE`	Invalid source data
`-1793`	`UENCERR_INVALID_KEY`	Invalid key data
`-1794`	`UENCERR_INVALID_KEY_FORMAT`	Invalid key format, must be PEM format
`-1795`	`UENCERR_INVALID_PUBLIC_KEY`	Invalid public key
`-1796`	`UENCERR_INVALID_PRIVATE_KEY`	Invalid private key
`-1797`	`UENCERR_INVALID_IV`	Invalid IV data
`-1798`	`UENCERR_NO_SIGNATURE`	Signature data not found
`-1799`	`UENCERR_INVALID_SIGNATURE`	Invalid signature data

Use

Allowed in all component types.

Description

You can use $decode to:

Decrypt encrypted data, using the same key as was used to encrypt the data.
Decode data that was encoded using Base64, hexadecimal, or URL encoding schemes.
Verify a message by means of a digital signature. (You can use $encode to sign a message with a digital signature).

$decode supports a variety of commonly-used encryption and signature algorithms including encoding schemes, block ciphers, RSA encryption and signature schemes, and DSA (Digital Signature Algorithm). For more information, see Supported Cryptography Algorithms.

To decrypt the data, you need to provide the same Key, Mode and InitializationVector as was used to encrypt the data. Otherwise you get an incorrect result or an error.

Supported Algorithms

The Algorithm parameter specify must be an algorithm listed in one of the following tables, as a string.

Encoding Algorithms
Algorithm	Meaning
`BASE64`	Base64 encoding scheme
`HEX`	Hexadecimal encoding scheme
`URL`	URL encoding scheme Note: The plus sign `+` is decoded to a space ' '.

Supported Block Ciphers
Algorithm	Meaning
`AES`	Advanced Encryption Standard
`RIJNDAEL`	Same as AES
`DES`	Data Encryption Standard
`TDES`	Triple Data Encryption Algorithm (TDEA) as known as Triple DES
`DES_EDE3`	Same as TDES
`DES_EDE2`	Variant of TDES with 16 byte key length
`DESX`	Variant of DES by XORing extra keys
`DES_XEX3`	Same as DESX
`BLOWFISH`	Blowfish
`TWOFISH`	Twofish

For more information, see Block Ciphers.

Supported RSA Algorithms
Algorithm	Meaning
`RSAES_OAEP_SHA1`	RSA Encryption Scheme based on Optimal Asymmetric Encryption Padding with SHA-1 hash function
`RSAES_OAEP_SHA224`	RSA Encryption Scheme based on Optimal Asymmetric Encryption Padding with SHA-224 hash function
`RSAES_OAEP_SHA256`	RSA Encryption Scheme based on Optimal Asymmetric Encryption Padding with SHA-256 hash function
`RSAES_OAEP_SHA384`	RSA Encryption Scheme based on Optimal Asymmetric Encryption Padding with SHA-384 hash function
`RSAES_OAEP_SHA512`	RSA Encryption Scheme based on Optimal Asymmetric Encryption Padding with SHA-512 hash function
`RSAES_PKCS1V15`	RSA Encryption Scheme based on PKCS #1 v1.5
`RSASSA_PSS_SHA1`	RSA Signature Scheme with Appendix based on Probabilistic Signature Scheme with SHA-1 hash function
`RSASSA_PSS_SHA224`	RSA Signature Scheme with Appendix based on Probabilistic Signature Scheme with SHA-224 hash function
`RSASSA_PSS_SHA256`	RSA Signature Scheme with Appendix based on Probabilistic Signature Scheme with SHA-256 hash function
`RSASSA_PSS_SHA384`	RSA Signature Scheme with Appendix based on Probabilistic Signature Scheme with SHA-384 hash function
`RSASSA_PSS_SHA512`	RSA Signature Scheme with Appendix based on Probabilistic Signature Scheme with SHA-512 hash function
`RSASSA_PKCS1V15_MD2`	RSA Signature Scheme with Appendix based on PKCS #1 v1.5 with MD2 hash function. This is only for compatibility.
`RSASSA_PKCS1V15_MD5`	RSA Signature Scheme with Appendix based on PKCS #1 v1.5 with MD5 hash function. This is only for compatibility.
`RSASSA_PKCS1V15_SHA1`	RSA Signature Scheme with Appendix based on PKCS #1 v1.5 with SHA-1 hash function
`RSASSA_PKCS1V15_SHA224`	RSA Signature Scheme with Appendix based on PKCS #1 v1.5 with SHA-224 hash function
`RSASSA_PKCS1V15_SHA256`	RSA Signature Scheme with Appendix based on PKCS #1 v1.5 with SHA-256 hash function
`RSASSA_PKCS1V15_SHA384`	RSA Signature Scheme with Appendix based on PKCS #1 v1.5 with SHA-384 hash function
`RSASSA_PKCS1V15_SHA512`	RSA Signature Scheme with Appendix based on PKCS #1 v1.5 with SHA-512 hash function

For more information, see RSA Asymmetric Key Cryptography.

Supported DSA Algorithms
Algorithm	Meaning
`DSA_SHA1`	Digital Signature Algorithm with SHA-1 hash function
`DSA_SHA224`	Digital Signature Algorithm with SHA-224 hash function
`DSA_SHA256`	Digital Signature Algorithm with SHA-256 hash function
`DSA_SHA384`	Digital Signature Algorithm with SHA-384 hash function
`DSA_SHA512`	Digital Signature Algorithm with SHA-512 hash function

For more information, see Digital Signature Algorithm (DSA).

Encrypt and Decrypt String Data

$decode returns raw data, so you can use $encode with the USTRING algorithm to convert it to a string data type using Uniface internal encoding, UTF-8.

vEnc = $encode("BLOWFISH", "~home", "secret key")  ;encrypt the data
vRawData = $decode("BLOWFISH", vEnc, "secret key") ;decrypt the data
vStrgData = $encode("USTRING", vRawData)           ;convert the decrypted data from Raw to String

Version	Change
9.4.01	Introduced
9.5.01 E101	Added support for HMAC SHA224, SHA256, SHA384, SHA512
9.5.01 E103	Added support for asymmetric key cryptography