EncryptAndAuthenticate | encryptAndAuthenticate method

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 (Windows 10 device family)

Device family

Universal, introduced version 10.0.10240.0

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.Security.Cryptography.Core
Windows::Security::Cryptography::Core [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.Security.Cryptography.Core
Windows::Security::Cryptography::Core [C++]

Metadata

Windows.winmd

See also

CryptographicEngine
EncryptedAndAuthenticatedData
SymmetricKeyAlgorithmProvider

 

 

Show:
© 2016 Microsoft