About key, IV, and nonce encoding

The GeneXusSecurityAPI's modules use different symmetric keys, IVs, and nonces.

The majority of them specify a hexadecimal string as input. It means a literal hex representation of bits that is different from a UTF (or other character encodings) representation of bits.

Verify if your key is hexa or another encoding before using it and if it is compliant with the algorithm specification. If it is not or is on a wrong encoding, the execution could fail or it could return the wrong result.

The easiest way to discover the encoding is by counting the characters to find out if it reaches the expected length for the algorithm or a given length if a specific encoding is used.

To change the encoding, you can use the HexaEncoder object on this module.

Hexadecimal representation 

Hexadecimal representation, also known as Hex or Hexa is a base 16 numerical system made up of 16 symbols.

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F

It does not distinguish capital letters from small letters, A is the same as a.

On computer systems, it is translated to the binary numerical system using 4 bits by symbol as shown on the following table:

Then, the binary interpretation of a sample key will be as follows:

In conclusion, a hexadecimal key made up of 16 characters will translate to a 64-bit key.

UTF representation

UTF encoding or Unicode Translation Format is a coding system for character sets.

It defines 3 types of encodings:

• UTF-8 − It comes in 8-bit units (bytes); a character in UTF8 can have between 1 to 4 bytes, making UTF8 variable length.
• UTF-16 − It comes in 16-bit units (shorts); it can be 1 or 2 shorts long, making UTF16 variable length.
• UTF-32 − It comes in 32-bit units (longs). It is a fixed-width format and is always 1 "long" in length.

About UTF-8

It is the most commonly used in computer systems and allows representing common language symbols and control characters.

The most common alphabetical symbols are represented by 8 bits (1 Byte) as shown in this table.

So, it is really different from the hexa representation and distinguishes capital letters from small letters: A(01000001) is not the same as a(01100001).

Translating the hexa example key from UTF-8 to binary:

In conclusion, the same string key interpreted as UTF-8 is a 128-bit key and it will change if capital letters are replaced with small letters, as shown in the next example.

 

Troubleshooting

Related errors classified by the module's object:

• SymmetricBlockCipher
  • Error codes between SB022 and SB030
• SymmetricStreamCipher
  • Error codes between SS007 and SS012
• CMAC
  • Error codes CM003 and CM004
• HMAC
  • Error codes HS 002 and HS003
• JWTOptions and JWTCreator
  • Error code OP001