EncryptedAndAuthenticatedData Class

Definition

public ref class EncryptedAndAuthenticatedData sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class EncryptedAndAuthenticatedData final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class EncryptedAndAuthenticatedData

Public NotInheritable Class EncryptedAndAuthenticatedData

Inheritance

Object Platform::Object IInspectable EncryptedAndAuthenticatedData

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute

Windows requirements

Examples

using Windows.Security.Cryptography;
using Windows.Security.Cryptography.Core;
using Windows.Storage.Streams;

namespace SampleEncryptedAndAuthenticatedData
{
    sealed partial class EncryptedAuthenticatedDataApp : Application
    {
        // Initialize a static nonce value.
        static byte[] NonceBytes = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };

        public EncryptedAuthenticatedDataApp()
        {
            // Initialize the application.
            this.InitializeComponent();

            // Initialize the encryption method.
            String strMsg = "This is a message.";   // Message to encrypt and authenticate.
            String strAlgName = SymmetricAlgorithmNames.AesGcm;
            UInt32 keyLength = 32;                  // Length of the key, in bytes
            BinaryStringEncoding encoding;          // Binary encoding
            IBuffer buffNonce;                      // Nonce
            CryptographicKey key;                   // Symmetric key

            // Encrypt and authenticate the message.
            EncryptedAndAuthenticatedData objEncrypted = this.AuthenticatedEncryption(
                strMsg,
                strAlgName,
                keyLength,
                out encoding,
                out buffNonce,
                out key);

            // Decrypt the encrypted data.
            this.AuthenticatedDecryption(
                strAlgName,
                key,
                objEncrypted,
                encoding,
                buffNonce);
        }

        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;

        }

        public void AuthenticatedDecryption(
            String strAlgName, 
            CryptographicKey key,
            EncryptedAndAuthenticatedData objEncrypted,
            BinaryStringEncoding encoding, 
            IBuffer buffNonce)
        {
            // Declare a buffer to contain the decrypted data.
            IBuffer buffDecrypted;

            // Open a SymmetricKeyAlgorithmProvider object for the specified algorithm.
            SymmetricKeyAlgorithmProvider objAlgProv = SymmetricKeyAlgorithmProvider.OpenAlgorithm(strAlgName);

            // The input key must be securely shared between the sender of the encrypted message
            // and the recipient. The nonce must also be shared but does not need to be shared
            // in a secure manner. If the sender encodes the message string to a buffer, the
            // binary encoding method must also be shared with the recipient.
            // The recipient uses the DecryptAndAuthenticate() method as follows to decrypt the 
            // message, authenticate it, and verify that it has not been altered in transit.
            buffDecrypted = CryptographicEngine.DecryptAndAuthenticate(
                key,
                objEncrypted.EncryptedData,
                buffNonce,
                objEncrypted.AuthenticationTag,
                null);

            // Convert the decrypted buffer to a string (for display). If the sender created the
            // original message buffer from a string, the sender must tell the recipient what 
            // BinaryStringEncoding value was used. Here, BinaryStringEncoding.Utf8 is used to
            // convert the message to a buffer before encryption and to convert the decrypted
            // buffer back to the original plaintext.
            String strDecrypted = CryptographicBuffer.ConvertBinaryToString(encoding, buffDecrypted);

        }

        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);
        }
    }
}

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:

• AES_GCM
• AES_CCM

Properties

Applies to

See also

• CryptographicEngine
• DecryptAndAuthenticate(CryptographicKey, IBuffer, IBuffer, IBuffer, IBuffer)
• EncryptAndAuthenticate(CryptographicKey, IBuffer, IBuffer, IBuffer)
• SymmetricKeyAlgorithmProvider