CryptoDeriveKey (FUN)

FUNCTION CryptoDeriveKey : RTS_IEC_RESULT

This Function derives a new key FROM an existing secret (key) AND an corresponding salt. The functions generates keys of the requested size which is given in pDerivedKey->ui32MaxLen. If setup properly this function provides a secure way to store passwords within the file system. By now two classes of algorithms can be use:

1. P_SHA(1, 256): This algorithm can be used to derive session keys from some kind of secret data. If this algorithm is used the pSpecificParameters is not evaluated an should be NULL. This algorithm is quite fast.

2. SCRYPT: This algorithm can be used to generate strong keys from weak passwords, or to store passwords in a secure way within the file system. This algorithm makes use of the pSpecificParameters and requires this parameter. Depending on the configuration given in pSpecificParameters this algorithm is time and memory consuming. For details see RFC-7914.

InOut:

Scope	Name	Type	Comment
Return	CryptoDeriveKey	RTS_IEC_RESULT	Result of the operation. ERR_OK: The key was derived successfully. ERR_INVALID_HANDLE: hAlgo was not a valid handle to derive keys. ERR_PARAMETER: One of the other parameters was invalid. ERR_FAILED: some internal error happend.
Input	hAlgo	RTS_IEC_HANDLE	Handle of the used algoritm. Should be one of RTSCRYPTOID_KDF_* algorithms.
	pKey	POINTER TO RtsByteString	The key that should be derived. The function reads pKey->ui32Len bytes of the given buffer.
	pSalt	POINTER TO RtsByteString	The SALT that should be used to derive the key. The function reads pSalt->ui32Len bytes of the given buffer.
	pSpecificParameters	POINTER TO RtsKdfParameter	Some additional algorithm specific parameters. By now only used for scrypt.
	pDerivedKey	POINTER TO RtsByteString	Destination where to store the derived key. The function generates a key with the size of pDerivedKey->ui32MaxLen. The size of the derived key will be stored in pDerivedKey->ui32Len.