Key Property
The key used for HMAC and AES.
Syntax
ANSI (Cross Platform) int GetKey(char* &lpKey, int &lenKey);
int SetKey(const char* lpKey, int lenKey); Unicode (Windows) INT GetKey(LPSTR &lpKey, INT &lenKey);
INT SetKey(LPCSTR lpKey, INT lenKey);
@property (nonatomic,readwrite,assign,getter=key,setter=setKey:) NSString* key; - (NSString*)key; - (void)setKey:(NSString*)newKey;
@property (nonatomic,readwrite,assign,getter=keyB,setter=setKeyB:) NSData* keyB; - (NSData*)keyB; - (void)setKeyB:(NSData*)newKey;
#define PID_JWT_KEY 24 IPWORKSAUTH_EXTERNAL void* IPWORKSAUTH_CALL IPWorksAuth_JWT_Get(void *lpObj, int propid, int arridx, int *lpcbVal, int64 *lpllVal); IPWORKSAUTH_EXTERNAL int IPWORKSAUTH_CALL IPWorksAuth_JWT_Set(void *lpObj, int propid, int arridx, const void *val, int cbVal);
Default Value
""
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
Binary String