BOOL WINAPI AesEncryptString(
	LPCTSTR lpszPassword,
	LPCTSTR lpszInputString,
	LONG nInputLength
	LPCTSTR lpszOutputString,
	LONG nMaxLength
);

The AesEncryptString function encrypts the contents of a string.

Parameters

lpszPassword

A pointer to a null terminated string of characters that will be used to generate the encryption key. Passwords are case sensitive and must match exactly when decrypting data that was previously encrypted using this function. This parameter may be NULL or a zero-length string, in which case a default internal hash value is used. Password strings that exceed 215 characters will be truncated.

lpszInputString

A pointer to a null terminated string which contains the text to be encrypted. If the Unicode version of this function is called, the string is automatically UTF-8 encoded prior to being encrypted.

nInputLength

The number of characters in the input string which will be encrypted. If this value is -1, the length of the input string is determined automatically by counting the number of of characters up to the terminating null byte. Note that with Unicode strings, this value must represent the number of characters in the string, not the number of bytes allocated for the string.

lpszOutputString

A pointer to the buffer which will contain a base64 encoded encrypted string when the function returns. This memory must be allocated by the application and be large enough to contain all of the encrypted data. The amount encrypted data returned will always be larger than the amount of data specified by nInputLength. If the output string buffer is not large enough, the function will fail. This parameter cannot be NULL.

nMaxLength

The maximum number of characters that can be copied to the output string buffer. The output buffer must be large enough to store the complete encrypted string which is encoded using base64 and terminated with a null character. This value must be greater than zero. If the output string buffer is not large enough, the function will fail.

Return Value

A non-zero value is returned if the string was successfully encrypted. A zero value indicates that the string could not be encrypted. To get extended error information, call GetLastError.

Remarks

The AesEncryptString function will encrypt a string using a 256-bit AES (Advanced Encryption Standard) algorithm and returns a copy of the encrypted data as a base64 encoded string to the caller. The password (or passphrase) provided by the caller is used to generate a SHA-256 hash value which is used as part of the encryption process. The identical password is required to decrypt the data using the AesDecryptString function.

It is recommended that most applications specify a password value. If the lpszPassword parameter is NULL or specifies a zero-length string, a default internal hash value is used. This means that any other application which uses a NULL password value will be able to decrypt the data. If the Unicode version of this function is called, the lpszPassword value will be encoded using UTF-8 prior to the hash value being generated.

Due to how the SHA-256 hash is generated, the encrypted data cannot be decrypted using another third-party library with the same password value. It can only be decrypted using the AesDecryptString function.

The amount of encrypted data returned by this function will always be larger than original unencrypted data. If your application dynamically allocates a block of memory to store the encrypted string, provide a maximum output string size that is at least several hundred bytes larger than the unencrypted data. If the output string is not large enough, the function will fail and the GetLastError function will return ERROR_INSUFFICIENT_BUFFER.

The string provided to this function cannot contain embedded nulls and and should not be used to encrypt binary data. If you wish to encrypt binary data, use the AesEncryptBuffer function. It will perform the same 256-bit AES encryption and return the encrypted data into an buffer provided by the caller.

If you wish to encrypt the contents of a file, use the AesEncryptFile function.

This function uses the Microsoft CryptoAPI and the RSA AES cryptographic provider. This provider may not be available in some languages, countries or regions. The availability of this provider may also be constrained by cryptography export restrictions imposed by the United States or other countries. If the required cryptographic provider is not available, the function will fail.

Example

BOOL bIsEncrypted = FALSE;
LPCTSTR lpszPassword = _T("NFr-E{Ki3_1w0iV+LI@z");
LPCTSTR lpszPlainText = _T("The quick brown fox jumped over the lazy dog.");
TCHAR szEncryptedText[MAX_STRING_LENGTH];

bIsEncrypted = AesEncryptString(lpszPassword,
                                lpszPlainText,
                                -1,
                                szEncryptedText,
                                MAX_STRING_LENGTH);

if (bIsEncrypted)
{
    _tprintf(_T("The encrypted string is \"%s\"\n"), szEncryptedText);
}

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: csncdv11.lib
Unicode: Implemented as Unicode and ANSI versions

See Also

AesDecryptString, AesEncryptBuffer, AesEncryptFile

Copyright © 2025 Catalyst Development Corporation. All rights reserved.