CryptographicEngine.EncryptAndAuthenticate Method

Reference

Definition

Namespace:: Windows.Security.Cryptography.Core

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Performs authenticated encryption.

public:
 static EncryptedAndAuthenticatedData ^ EncryptAndAuthenticate(CryptographicKey ^ key, IBuffer ^ data, IBuffer ^ nonce, IBuffer ^ authenticatedData);

 static EncryptedAndAuthenticatedData EncryptAndAuthenticate(CryptographicKey const& key, IBuffer const& data, IBuffer const& nonce, IBuffer const& authenticatedData);

public static EncryptedAndAuthenticatedData EncryptAndAuthenticate(CryptographicKey key, IBuffer data, IBuffer nonce, IBuffer authenticatedData);

function encryptAndAuthenticate(key, data, nonce, authenticatedData)

Public Shared Function EncryptAndAuthenticate (key As CryptographicKey, data As IBuffer, nonce As IBuffer, authenticatedData As IBuffer) As EncryptedAndAuthenticatedData

Parameters

key: CryptographicKey

Symmetric key to use for encryption.

data: IBuffer

Data to be encrypted and authenticated.

nonce: 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: IBuffer

Authenticated data. This can be Null.

Returns

EncryptedAndAuthenticatedData

The encrypted and authenticated data.If the method fails, authentication fails; if the method succeeds, the authentication succeeded as well.

Examples

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

}

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.

Applies to

Jaa