Mac​Algorithm​Provider Mac​Algorithm​Provider Mac​Algorithm​Provider Class

Definition

Represents a message authentication code (MAC). A MAC uses symmetric key cryptography to prevent message tampering. For more information, see MACs, hashes, and signatures.

public : sealed class MacAlgorithmProvider : IMacAlgorithmProvider, IMacAlgorithmProvider2public sealed class MacAlgorithmProvider : IMacAlgorithmProvider, IMacAlgorithmProvider2Public NotInheritable Class MacAlgorithmProvider Implements IMacAlgorithmProvider, IMacAlgorithmProvider2
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

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

namespace SampleMacAlgorithmProvider
{
    sealed partial class MacAlgProviderApp : Application
    {
        public MacAlgProviderApp()
        {
            // Initialize the application.
            this.InitializeComponent();

            // Initialize the hashing process.
            String strMsg = "This is a message to be authenticated";
            String strAlgName = MacAlgorithmNames.HmacSha384;
            IBuffer buffMsg;
            CryptographicKey hmacKey;
            IBuffer buffHMAC;

            // Create a hashed message authentication code (HMAC)
            this.CreateHMAC(
                strMsg,
                strAlgName,
                out buffMsg,
                out hmacKey,
                out buffHMAC);

            // Verify the HMAC.
            this.VerifyHMAC(
                buffMsg,
                hmacKey,
                buffHMAC);
        }

        void CreateHMAC(
            String strMsg,
            String strAlgName,
            out IBuffer buffMsg,
            out CryptographicKey hmacKey,
            out IBuffer buffHMAC)
        {
            // Create a MacAlgorithmProvider object for the specified algorithm.
            MacAlgorithmProvider objMacProv = MacAlgorithmProvider.OpenAlgorithm(strAlgName);

            // Demonstrate how to retrieve the name of the algorithm used.
            String strNameUsed = objMacProv.AlgorithmName;

            // Create a buffer that contains the message to be signed.
            BinaryStringEncoding encoding = BinaryStringEncoding.Utf8;
            buffMsg = CryptographicBuffer.ConvertStringToBinary(strMsg, encoding);

            // Create a key to be signed with the message.
            IBuffer buffKeyMaterial = CryptographicBuffer.GenerateRandom(objMacProv.MacLength);
            hmacKey = objMacProv.CreateKey(buffKeyMaterial);

            // Sign the key and message together.
            buffHMAC = CryptographicEngine.Sign(hmacKey, buffMsg);

            // Verify that the HMAC length is correct for the selected algorithm
            if (buffHMAC.Length != objMacProv.MacLength)
            {
                throw new Exception("Error computing digest");
            }
         }

        public void VerifyHMAC(
            IBuffer buffMsg,
            CryptographicKey hmacKey,
            IBuffer buffHMAC)
        {
            // The input key must be securely shared between the sender of the HMAC and 
            // the recipient. The recipient uses the CryptographicEngine.VerifySignature() 
            // method as follows to verify that the message has not been altered in transit.
            Boolean IsAuthenticated = CryptographicEngine.VerifySignature(hmacKey, buffMsg, buffHMAC);
            if (!IsAuthenticated)
            {
                throw new Exception("The message cannot be verified.");
            }
        }
    }
}

Remarks

You create a MacAlgorithmProvider object by calling the static OpenAlgorithm method and specifying one of the following algorithm names:

  • HMAC_MD5
  • HMAC_SHA1
  • HMAC_SHA256
  • HMAC_SHA384
  • HMAC_SHA512
  • AES_CMAC

Properties

AlgorithmName AlgorithmName AlgorithmName

Gets the name of the open MAC algorithm.

public : PlatForm::String AlgorithmName { get; }public string AlgorithmName { get; }Public ReadOnly Property AlgorithmName As string
Value
PlatForm::String string string

Algorithm name.

Attributes

Remarks

You must call the OpenAlgorithm method before calling this property. The following algorithm names are supported:

MacLength MacLength MacLength

Gets the length, in bytes, of the message authentication code.

public : unsigned short MacLength { get; }public uint MacLength { get; }Public ReadOnly Property MacLength As uint
Value
unsigned short uint uint

Number of bytes in the MAC.

Attributes

Remarks

You should verify that the length of the computed HMAC equals the length supported by the specified algorithm. For more information, see the following example.

Methods

CreateHash(IBuffer) CreateHash(IBuffer) CreateHash(IBuffer)

Creates a CryptographicHash object that supports incremental hash operations.

public : CryptographicHash CreateHash(IBuffer keyMaterial)public CryptographicHash CreateHash(IBuffer keyMaterial)Public Function CreateHash(keyMaterial As IBuffer) As CryptographicHash
Parameters
keyMaterial
IBuffer IBuffer IBuffer

Random data used to help generate the hash. You can call the GenerateRandom method to create the random data.

Returns

A CryptographicHash object that supports incremental hash operations.

Attributes

CreateKey(IBuffer) CreateKey(IBuffer) CreateKey(IBuffer)

Creates a symmetric key that can be used to create the MAC value.

public : CryptographicKey CreateKey(IBuffer keyMaterial)public CryptographicKey CreateKey(IBuffer keyMaterial)Public Function CreateKey(keyMaterial As IBuffer) As CryptographicKey
Parameters
keyMaterial
IBuffer IBuffer IBuffer

Random data used to help generate the key. You can call the GenerateRandom method to create the random data.

Returns
Attributes

OpenAlgorithm(String) OpenAlgorithm(String) OpenAlgorithm(String)

Creates a MacAlgorithmProvider object and opens the specified algorithm for use.

public : static MacAlgorithmProvider OpenAlgorithm(PlatForm::String algorithm)public static MacAlgorithmProvider OpenAlgorithm(String algorithm)Public Static Function OpenAlgorithm(algorithm As String) As MacAlgorithmProvider
Parameters
algorithm
PlatForm::String String String

Algorithm name.

Returns

Represents a provider that implements MAC algorithms.

Attributes

Remarks

The following algorithm names are supported for use in the MacAlgorithmProvider class: