Key Property
The key used for HMAC and AES.
Syntax
jwt.getKey([callback]) jwt.setKey( key_Buffer, [callback])
Default Value
""
Callback
The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).
The callback for the getKey([callback]) method is defined as:
function(err, buffer){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'buffer' is the value returned by the method.
The callback for the setKey([callback]) method is defined as:
function(err){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'err' has 2 properties which hold detailed information:
err.code err.message
Remarks
This property specifies the key used when signing with an HMAC algorithm or encrypting with an AES algorithm.
Signing
This property is applicable when SigningAlgorithm is set to an HMAC algorithm.
It is recommended that the length of the key be equal to or larger than the hash size of the algorithm. Use of keys shorter than the hash size is discouraged.
Sizes (in bytes)
SHA1 | SHA224 | SHA256 | SHA384 | SHA512 | MD5 | RIPEMD160 | |
Recommended Key Size | 20 | 28 | 32 | 48 | 64 | 16 | 20 |
Hash Size | 20 | 28 | 32 | 48 | 64 | 16 | 20 |
Block Size | 64 | 64 | 64 | 128 | 128 | 64 | 64 |
Key Length Details
As mentioned above it is recommended to use a key size equal to the hash size. Use of keys larger than the hash size does not typically significantly increase the function strength. Keys of any length are technically valid however see the below processing rules to understand how keys of varying lengths are treated:
- If the key length is equal to the hash size (recommended) it is used without modification.
- If the key length is less than the hash size it is used without modification.
- If the key length is less than or equal to the block size it is used without modification.
- If the key length is larger than the block size is it first hashed with the same algorithm.
Encrypting
When EncryptionAlgorithm is set to an AES algorithm this property must hold the symmetric key used for encryption and decryption. The size of the key must match the size of the algorithm. For instance when selecting the algorithm A256GCMKW (AES 256) the size of the key must also be 256 bits (32 bytes).
In the case where EncryptionAlgorithm is set to Direct this key is used directly with the algorithm specified by ContentEncryptionAlgorithm and must be an appropriate size for the selected ContentEncryptionAlgorithm.
Data Type
Buffer