Cryptography Helpers

The API provides some helpers related to the cryptographic algorithm, which does rely on the OS CNG library.

Functions

HSDCError HSDCAPI HSDCIsBitLockerCapable (char **pJstr)

Checks if BitLocker Full Disk Encryption on system disk can be enabled.

HSDCError HSDCAPI HSDCEnableBitLocker (const wchar_t *pin, const char *unused)

Enables BitLocker Full Disk Encryption on a system disk if the option has been set by an administrator and if conditions are met (TPM, ...). On failure, an ERROR message is emitted by IDAC Agent Service (SComC) and centralized for Admin to take action.

HSDCError HSDCAPI HSDCCryptoHashBuffer (const wchar_t *algorithm, const unsigned char *buffer, unsigned int bufferLength, unsigned char *hash, unsigned int *hashLength)

Computes a buffer hash. While hash algorithms have known length (respectively 20, 32, 48 and 64), the caller can pass a null pointer for hash in order to get the hash length programmatically.

HSDCError HSDCAPI HSDCCryptoHashFile (const wchar_t *algorithm, const wchar_t *path, unsigned char *hash, unsigned int *hashLength)

Same as HSDCCryptoHashBuffer(), but the input is a filename from which the buffer is read.

HSDCError HSDCAPI HSDCCryptoGenerateKeyPair (const wchar_t *algorithm, unsigned char *privateKey, unsigned int *privateKeyLength, unsigned char *publicKey, unsigned int *publicKeyLength)

Generates a new asymmetric key pair. Obtains the required buffer lengths by passing the algorithm and pointers to zero.

HSDCError HSDCAPI HSDCCryptoSignBuffer (const wchar_t *algorithm, const unsigned char *buffer, unsigned int bufferLength, const unsigned char *privateKey, unsigned int privateKeyLength, unsigned char *signature, unsigned int *signatureLength)

Computes a digital signature of a buffer using an asymmetric key pair.

HSDCError HSDCAPI HSDCCryptoSignFile (const wchar_t *algorithm, const wchar_t *path, const unsigned char *privateKey, unsigned int privateKeyLength, unsigned char *signature, unsigned int *signatureLength)

Same as HSDCCryptoSignBuffer but the input is a filename from which the buffer is read.

HSDCError HSDCAPI HSDCCryptoCheckBufferSignature (const wchar_t *algorithm, const unsigned char *buffer, unsigned int bufferLength, const unsigned char *publicKey, unsigned int publicKeyLength, const unsigned char *signature, unsigned int signatureLength)

Validates whether the given signature was generated using the private equivalent of the given public key for the given buffer.

HSDCError HSDCAPI HSDCCryptoCheckFileSignature (const wchar_t *algorithm, const wchar_t *path, const unsigned char *publicKey, unsigned int publicKeyLength, const unsigned char *signature, unsigned int signatureLength)

Same as HSDCCryptoCheckBufferSignature(), but the input is a filename from which the buffer is read.

HSDCError HSDCAPI HSDCCryptoEncryptBuffer (const wchar_t *algorithm, const unsigned char *plain, unsigned int plainLength, const unsigned char *publicKey, unsigned int publicKeyLength, unsigned char *cipher, unsigned int *cipherLength)

Asymmetric encryption of buffer (used with RSA for symmetric key exchange).

HSDCError HSDCAPI HSDCCryptoDecryptBuffer (const wchar_t *algorithm, const unsigned char *cipher, unsigned int cipherLength, const unsigned char *privateKey, unsigned int privateKeyLength, unsigned char *plain, unsigned int *plainLength)

Asymmetric decryption of buffer (used with RSA for symmetric key exchange).

HSDCError HSDCAPI HSDCCryptoSymEncryptBuffer (const wchar_t *algorithm, const unsigned char *plain, unsigned int plainLength, const unsigned char *symKey, unsigned int symKeyLength, const unsigned char *iV, unsigned int iVLength, unsigned char *cipher, unsigned int *cipherLength)

Symmetric encryption of buffer with AES-256, supported modes are ECB, CTR and CBC.

HSDCError HSDCAPI HSDCCryptoSymDecryptBuffer (const wchar_t *algorithm, const unsigned char *cipher, unsigned int cipherLength, const unsigned char *symKey, unsigned int symKeyLength, const unsigned char *iV, unsigned int iVLength, unsigned char *plain, unsigned int *plainLength)

Symmetric decryption of buffer with AES-256, supported modes are ECB, CTR and CBC.

HSDCError HSDCAPI HSDCCryptoBase32Encode (const unsigned char *raw, unsigned int rawLength, unsigned char *encoded, unsigned int *encodedLength)

Base 32 encoding for temporary offline policies and password recovery.

HSDCError HSDCAPI HSDCCryptoBase32Decode (const unsigned char *encoded, unsigned int encodedLength, unsigned char *raw, unsigned int *rawLength)

Base 32 decoding for temporary offline policies and password recovery.

Function Documentation

HSDCIsBitLockerCapable()

HSDCError HSDCAPI HSDCIsBitLockerCapable ( char ** pJstr )

Checks if BitLocker Full Disk Encryption on system disk can be enabled.

Parameters

pJstr

JSON report

HSDCEnableBitLocker()

HSDCError HSDCAPI HSDCEnableBitLocker ( const wchar_t * pin, const char * unused )

Enables BitLocker Full Disk Encryption on system disk if the option has been set by an administrator and if conditions are met (TPM, ...). On failure, an ERROR message is emitted by IDAC Agent Service (SComC) and centralized for Admin to take action.

Parameters

pin	PIN (password) used for TPM+PIN mode.
unused	Unused JSON settings.

HSDCCryptoHashBuffer()

HSDCError HSDCAPI HSDCCryptoHashBuffer ( const wchar_t * algorithm, const unsigned char * buffer, unsigned int bufferLength, unsigned char * hash, unsigned int * hashLength )

Computes a buffer hash.

While hash algorithms have known length (respectively 20, 32, 48 and 64), the caller can pass a null pointer for hash in order to get the hash length programmatically.

Parameters

algorithm	Identifies one of the hash algorithms (valid values are SHA1, SHA256, SHA384, SHA512, case insensitive and character '-' is ignored if present then for example Sha-256 is valid too).
buffer	Pointer to the data that must be hashed.
bufferLength	The length of the input buffer.
hash	[out] The hashed buffer values.
hashLength	[out] The length of the hash output.

Returns

HSDCErrorInvalidAlgorithm	Algorithm is not supported
HSDCErrorBufferTooSmall	Length of the hash buffer is too small and has been updated to match expectation
HSDCErrorFailed	Error when hashing

Below is a complete example for RSA 2048. We actually know the length of the algorithm in this case, but the example shows the mechanism for checking the length for completeness. LOGEXIT_ON_HSDCERR could be defined as a variadic macro.

Copy

unsigned int hashSize = 0; // can be any value
auto err = HSDCCryptoHashBuffer(L"sha-384", nullptr, nullptr, nullptr, &hashSize);
if (HSDCErrorBufferTooSmall != err) {
    abort("Failed to obtain size of hash. Error %s", HSDCErrorGetName(err));
}
std::vector<unsigned char> hashBuffer{ hashSize };
std::wstring toHash{ L"This is a secret" };
err = HSDCCryptoHashBuffer(L"sha-384", toHash.c_str(), toHash.size(), &hashBuffer[0], &hashSize);
if (HSDCErrorSuccess != err) {
    abort("Failed to execute the hash. Error %s", HSDCErrorGetName(err));
}

HSDCCryptoHashFile()

HSDCError HSDCAPI HSDCCryptoHashFile ( const wchar_t * algorithm, const wchar_t * path, unsigned char * hash, unsigned int * hashLength )

Same as HSDCCryptoHashBuffer(), but the input is a filename from which buffer is going to be read.

Parameters

algorithm	Identifies one of the hash algorithms.
path	Identifies the input file. Must point to a valid file even if only checking the hash size.
hash	[out] The hashed buffer values.
hashLength	[out] The length of the hash output.

Returns

HSDCErrorInvalidAlgorithm	Algorithm is not supported
HSDCErrorBufferTooSmall	Length of the hash buffer is too small and has been updated to match expectation
HSDCErrorFailed	Error when hashing
HSDCErrorAccessDenied	Read access to the file has been denied
HSDCErrorInvalidFile	Read access to the file failed

HSDCCryptoGenerateKeyPair()

HSDCError HSDCAPI HSDCCryptoGenerateKeyPair ( const wchar_t * algorithm, unsigned char * privateKey, unsigned int * privateKeyLength, unsigned char * publicKey, unsigned int * publicKeyLength )

Generates a new asymmetric key pair.

Obtains the required buffer lengths by passing the algorithm and pointers to zero.

Parameters

algorithm	Identifies one of the asymmetric algorithms. Valid values are RSA2048, ECDSA256, ECDSA384, ECDSA521, case insensitive. Character '-' is ignored if present.
privateKey	[out] Pointer to the private key buffer which is going to be generated.
privateKeyLength	[out] Length of the private key in bytes.
publicKey	[out] Pointer to the public key buffer which is going to be generated.
publicKeyLength	[out] Length of the public key in bytes.

Returns

HSDCErrorInvalidAlgorithm	Algorithm is not supported
HSDCErrorBufferTooSmall	Length of the hash buffer is too small and has been updated to match expectation
HSDCErrorFailed	Error when hashing

Below is a complete example for RSA 2048. We actually know the length of the algorithm in this case but the example shows the mechanism for checking the length for completeness. LOGEXIT_ON_HSDCERR could be defined as a variadic macro.

Copy

unsigned int privKeySize, pubKeySize;
LOGEXIT_ON_HSDCERR(
    HSDCCryptoGenerateKeyPair(L"rsa2048", nullptr, &privKeySize, nullptr, &pubKeySize),
    L"Failed to obtain size of keys");
std::vector<byte> privKey(privKeySize), pubKey(pubKeySize);
LOGEXIT_ON_HSDCERR(
    HSDCCryptoGenerateKeyPair(L"rsa2048", &privKey[0], &privKeySize, &pubKey[0], &pubKeySize),
    L"Failed to generate key pair");
privKey.shrink_to_fit();
pubKey.shrink_to_fit();
auto privKeyFile = outputDir + algorithmType + L"_priv.key";
auto pubKeyFile = outputDir + algorithmType + L"_pub.key";
LOGEXIT_ON_HSDCERR(WriteFile(privKeyFile.c_str(), &privKey[0], privKey.size()), L"Failed private key write {}", privKeyFile);
LOGEXIT_ON_HSDCERR(WriteFile(pubKeyFile.c_str(), &pubKey[0], pubKey.size()), L"Failed public key write {}", pubKeyFile);

HSDCCryptoSignBuffer()

HSDCError HSDCAPI HSDCCryptoSignBuffer ( const wchar_t * algorithm, const unsigned char * buffer, unsigned int bufferLength, const unsigned char * privateKey, unsigned int privateKeyLength, unsigned char * signature,unsigned int * signatureLength )

Compute a digital signature of a buffer using asymmetric key pair.

Parameters

algorithm	Identifies one of the asymmetric algorithms. Valid values are RSA2048, ECDSA256, ECDSA384, ECDSA521, case insensitive. Character '-' is ignored if present.
buffer	Pointer to the buffer which is going to be signed.
bufferLength	Length of the buffer.
privateKey	Pointer to the private key buffer used for signing.
privateKeyLength	Length of the private key in bytes.
signature	[out] Pointer to the buffer into which the signature will be generated.
signatureLength	[out] Length of the signature in bytes.

Returns

HSDCErrorInvalidAlgorithm	Algorithm is not supported
HSDCErrorBufferTooSmall	Length of the hash buffer is too small and has been updated to match expectation
HSDCErrorFailed	Error when hashing

HSDCCryptoSignFile()

HSDCError HSDCAPI HSDCCryptoSignFile ( const wchar_t * algorithm, const wchar_t * path, const unsigned char * privateKey, unsigned int privateKeyLength, unsigned char * signature, unsigned int * signatureLength )

Same as HSDCCryptoSignBuffer, but the input is a filename from which buffer is going to be read.

Parameters

algorithm	Identifies one of the asymmetric algorithms. Valid values are RSA2048, ECDSA256, ECDSA384, ECDSA521, case insensitive. Character '-' is ignored if present.
path	Path of the file to read.
privateKey	Pointer to the private key buffer used for signing.
privateKeyLength	Length of the private key in bytes.
signature	[out] Pointer to the buffer into which the signature will be generated.
signatureLength	[out] Length of the signature in bytes.

Returns

HSDCErrorInvalidAlgorithm	Algorithm is not supported
HSDCErrorBufferTooSmall	Length of the hash buffer is too small and has been updated to match expectation
HSDCErrorFailed	Error when hashing
HSDCErrorAccessDenied	Read access to the file has been denied
HSDCErrorInvalidFile	Read access to the file failed

HSDCCryptoCheckBufferSignature()

HSDCError HSDCAPI HSDCCryptoCheckBufferSignature ( const wchar_t * algorithm, const unsigned char * buffer, unsigned int bufferLength, const unsigned char * publicKey, unsigned int publicKeyLength, const unsigned char * signature, unsigned int signatureLength )

Validates whether the given signature was generated using the private equivalent of the given public key for the given buffer.

Parameters

algorithm	Identifies one of the asymmetric algorithms that was used to sign the buffer.
buffer	Pointer to the buffer which was previously signed by the private key of the pair.
bufferLength	Length of the signed buffer.
publicKey	Pointer to the public key buffer.
publicKeyLength	Length of the public key in bytes.
signature	The signature to validate.
signatureLength	Length of the signature in bytes.

Returns

HSDCErrorSuccess	The signature was generated using the private key related to publicKey and algorithm against buffer
HSDCErrorFailed	The signature was NOT generated using the private key related to publicKey and algorithm against buffer
HSDCErrorInvalidAlgorithm	The algorithm given is not recognized

HSDCCryptoCheckFileSignature()

HSDCError HSDCAPI HSDCCryptoCheckFileSignature ( const wchar_t * algorithm, const wchar_t * path, const unsigned char * publicKey, unsigned int publicKeyLength, const unsigned char * signature, unsigned int signatureLength )

Same as HSDCCryptoCheckBufferSignature(), but the input is a filename from which the buffer is read.

Parameters

algorithm	Identifies one of the asymmetric algorithms, which was used to sign the buffer.
path	Path to the file to check.
publicKey	Pointer to the public key buffer.
publicKeyLength	Length of the public key in bytes.
signature	The signature to validate.
signatureLength	Length of the signature in bytes.

Returns

HSDCErrorSuccess	The signature was generated using the private key related to publicKey and algorithm against buffer
HSDCErrorFailed	The signature was NOT generated using the private key related to publicKey and algorithm against buffer
HSDCErrorInvalidAlgorithm	The algorithm given is not recognized
HSDCErrorAccessDenied	Read access to the file has been denied
HSDCErrorInvalidFile	Read access to the file failed

HSDCCryptoEncryptBuffer()

HSDCError HSDCAPI HSDCCryptoEncryptBuffer ( const wchar_t * algorithm, const unsigned char * plain, unsigned int plainLength, const unsigned char * publicKey, unsigned int publicKeyLength, unsigned char * cipher, unsigned int * cipherLength )

Asymmetric encryption of buffer (used with RSA for symmetric key exchange).

Parameters

algorithm	An asymmetric encryption algorithm. Only RSA2048 is supported.
plain	Buffer containing unencrypted data.
plainLength	Length of the plain buffer.
publicKey	The key with which to encrypt the plain data.
publicKeyLength	Length of the publicKey buffer.
cipher	[out] Pointer to the buffer into which the encrypted version of plain will be written.
cipherLength	Length of the cipher buffer. If this is too small, then HSDCErrorBufferTooSmall is returned and this value is set to the required length.

HSDCCryptoDecryptBuffer()

HSDCError HSDCAPI HSDCCryptoDecryptBuffer ( const wchar_t * algorithm, const unsigned char * cipher, unsigned int cipherLength, const unsigned char * privateKey, unsigned int privateKeyLength, unsigned char * plain, unsigned int * plainLength )

Asymmetric encryption of buffer (used with RSA for symmetric key exchange).

Parameters

algorithm	An asymmetric encryption algorithm. Only RSA2048 is supported.
cipher	Buffer containing encrypted data.
cipherLength	Length of the cipher buffer.
privateKey	The key with which to encrypt the plain data.
privateKeyLength	Length of the publicKey buffer.
plain	[out] Pointer to the buffer into which the decrypted version of `plain` will be written.
plainLength	Length of the plain buffer. If this is too small, then HSDCErrorBufferTooSmall is returned and this value is set to the required length.

HSDCCryptoSymEncryptBuffer()

HSDCError HSDCAPI HSDCCryptoSymEncryptBuffer ( const wchar_t * algorithm, const unsigned char * plain, unsigned int plainLength, const unsigned char * symKey, unsigned int symKeyLength, const unsigned char * iV, unsigned int iVLength, unsigned char * cipher, unsigned int * cipherLength )

Symmetric encryption of buffer with AES-256, supported modes are ECB, CTR and CBC.

Parameters

algorithm	Identifies one of the asymmetric algorithms(valid values are AES256ECB, AES256CTR and AES256CBC, case insensitive and character '-' is ignored if present).
plain	Pointer to the plain text data that must be encrypted.
plainLength	Length of the plain text buffer in bytes.
symKey	Pointer to the symmetric key buffer.
symKeyLength	Length of the symmetric key in bytes(valid value is 32).
iV	Pointer to the initialization vector buffer.
iVLength	Length of the initialization vector in bytes(valid value is 16).
cipher	[out] Pointer to the output buffer into which the encrypted data will be written.
cipherLength	[out] Length of the cipher text buffer in bytes.

HSDCCryptoSymDecryptBuffer()

HSDCError HSDCAPI HSDCCryptoSymDecryptBuffer ( const wchar_t * algorithm, const unsigned char * cipher, unsigned int cipherLength, const unsigned char * symKey, unsigned int symKeyLength, const unsigned char * iV, unsigned int iVLength, unsigned char * plain, unsigned int * plainLength )

Symmetric decryption of buffer with AES-256, supported modes are ECB, CTR and CBC.

Parameters

algorithm	Identifies one of the asymmetric algorithms(valid values are AES256ECB, AES256CTR and AES256CBC, case insensitive and character '-' is ignored if present).
cipher	Pointer to the buffer from which the encrypted data will be read.
cipherLength	Length of the cipher text buffer in bytes.
symKey	Pointer to the symmetric key buffer.
symKeyLength	Length of the symmetric key in bytes(valid value is 32).
iV	Pointer to the initialization vector buffer.
iVLength	Length of the initialization vector in bytes(valid value is 16).
plain	[out] Pointer to the buffer that the plain text data will be decrypted into.
plainLength	[out] Length of the plain text buffer in bytes.

HSDCCryptoBase32Encode()

HSDCError HSDCAPI HSDCCryptoBase32Encode ( const unsigned char * raw, unsigned int rawLength, unsigned char * encoded, unsigned int * encodedLength )

Base 32 encoding for temporary offline policies and password recovery.

Parameters

raw	Pointer to the data that must be encoded.
rawLength	Length of the data buffer in bytes.
encoded	[out] Pointer to the buffer receiving the encoded data.
encodedLength	[out] Length of the buffer receiving the encoded data in bytes.

HSDCCryptoBase32Decode()

HSDCError HSDCAPI HSDCCryptoBase32Decode ( const unsigned char * encoded, unsigned int encodedLength, unsigned char * raw, unsigned int * rawLength )

Base 32 decoding for temporary offline policies and password recovery.

Parameters

encoded	Pointer to the buffer containing the encoded data.
encodedLength	Length of the buffer with the encoded data in bytes.
raw	[out] Pointer to the buffer to receive the decoded data.
rawLength	[out] Length of the raw buffer in bytes.

Cryptography Helpers

Functions

Function Documentation

HSDCIsBitLockerCapable()

Parameters

HSDCEnableBitLocker()

Parameters

HSDCCryptoHashBuffer()

Parameters

Returns

HSDCCryptoHashFile()

Parameters

Returns

HSDCCryptoGenerateKeyPair()

See also

Parameters

Returns

HSDCCryptoSignBuffer()

Parameters

Returns

HSDCCryptoSignFile()

Parameters

Returns

HSDCCryptoCheckBufferSignature()

Parameters

Returns

HSDCCryptoCheckFileSignature()

Parameters

Returns

HSDCCryptoEncryptBuffer()

Parameters

HSDCCryptoDecryptBuffer()

Parameters

HSDCCryptoSymEncryptBuffer()

Parameters

HSDCCryptoSymDecryptBuffer()

Parameters

HSDCCryptoBase32Encode()

Parameters

HSDCCryptoBase32Decode()

Parameters