MacAlgorithmProvider MacAlgorithmProvider MacAlgorithmProvider MacAlgorithmProvider 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, IMacAlgorithmProvider2
public sealed class MacAlgorithmProvider : IMacAlgorithmProvider, IMacAlgorithmProvider2
Public NotInheritable Class MacAlgorithmProvider Implements IMacAlgorithmProvider, IMacAlgorithmProvider2
// This class does not provide a public constructor.
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 AlgorithmName

Gets the name of the open MAC algorithm.

public : Platform::String AlgorithmName { get; }
public string AlgorithmName { get; }
Public ReadOnly Property AlgorithmName As string
var string = macAlgorithmProvider.algorithmName;
Value
Platform::String string string string

Algorithm name.

Remarks

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

MacLength MacLength MacLength MacLength

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

public : unsigned int MacLength { get; }
public uint MacLength { get; }
Public ReadOnly Property MacLength As uint
var uint = macAlgorithmProvider.macLength;
Value
unsigned int uint uint uint

Number of bytes in the MAC.

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) 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
var cryptographicHash = macAlgorithmProvider.createHash(keyMaterial);
Parameters
keyMaterial
IBuffer 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.

CreateKey(IBuffer) 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
var cryptographicKey = macAlgorithmProvider.createKey(keyMaterial);
Parameters
keyMaterial
IBuffer IBuffer IBuffer IBuffer

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

Returns

OpenAlgorithm(String) 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
var macAlgorithmProvider = Windows.Security.Cryptography.Core.MacAlgorithmProvider.openAlgorithm(algorithm);
Parameters
algorithm
Platform::String String String String

Algorithm name.

Returns

Represents a provider that implements MAC algorithms.

Remarks

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