CryptographicEngine.EncryptAndAuthenticate | encryptAndAuthenticate method
Performs authenticated encryption.
Syntax
var encryptedAndAuthenticatedData = Windows.Security.Cryptography.Core.CryptographicEngine.encryptAndAuthenticate(key, data, nonce, authenticatedData);
Parameters
- key
-
Type: CryptographicKey
Symmetric key to use for encryption.
- data
-
Type: IBuffer
Data to be encrypted and authenticated.
- nonce
-
Type: IBuffer
Nonce to be used. A nonce is a variable that has minimal chance of repeating. For example, you can use a random value that is newly generated for each use, a time stamp, a sequence number, or some combination of these. The Microsoft GCM implementation requires a 12-byte nonce. The CCM implementation requires a 7- to 13- byte nonce.
- authenticatedData
-
Type: IBuffer
Authenticated data. This can be Null.
Return value
Type: EncryptedAndAuthenticatedData
The encrypted and authenticated data.
If the method fails, authentication fails; if the method succeeds, the authentication succeeded as well.
Remarks
Authenticated encryption encrypts and authenticates content in one operation. An authenticator, also called a tag, is used during encryption and the output of the process contains a tag-ciphertext pair. For more information, see the AuthenticationTag and EncryptedData properties. The decryption process verifies the ciphertext against the tag.
You can use an authenticated encryption algorithm after calling the OpenAlgorithm method on the SymmetricKeyAlgorithmProvider class and specifying the name of the algorithm to open. The following algorithm names are supported for authenticated encryption and decryption:
For a complete sample that contains the following code example, see the EncryptedAndAuthenticatedData class.
Examples
public EncryptedAndAuthenticatedData AuthenticatedEncryption(
String strMsg,
String strAlgName,
UInt32 keyLength,
out BinaryStringEncoding encoding,
out IBuffer buffNonce,
out CryptographicKey key)
{
// Open a SymmetricKeyAlgorithmProvider object for the specified algorithm.
SymmetricKeyAlgorithmProvider objAlgProv = SymmetricKeyAlgorithmProvider.OpenAlgorithm(strAlgName);
// Create a buffer that contains the data to be encrypted.
encoding = BinaryStringEncoding.Utf8;
IBuffer buffMsg = CryptographicBuffer.ConvertStringToBinary(strMsg, encoding);
// Generate a symmetric key.
IBuffer keyMaterial = CryptographicBuffer.GenerateRandom(keyLength);
key = objAlgProv.CreateSymmetricKey(keyMaterial);
// Generate a new nonce value.
buffNonce = GetNonce();
// Encrypt and authenticate the message.
EncryptedAndAuthenticatedData objEncrypted = CryptographicEngine.EncryptAndAuthenticate(
key,
buffMsg,
buffNonce,
null);
return objEncrypted;
}
IBuffer GetNonce()
{
// Security best practises require that an ecryption operation not
// be called more than once with the same nonce for the same key.
// A nonce value can be predictable, but must be unique for each
// secure session.
NonceBytes[0]++;
for (int i = 0; i < NonceBytes.Length - 1; i++)
{
if (NonceBytes[i] == 255)
{
NonceBytes[i + 1]++;
}
}
return CryptographicBuffer.CreateFromByteArray(NonceBytes);
}
Requirements
|
Minimum supported client | Windows 8 |
|---|---|
|
Minimum supported server | Windows Server 2012 |
|
Namespace |
|
|
Metadata |
|
See also
Build date: 12/4/2012
