NCryptVerifyClaim, fonction (ncrypt.h)

Vérifie une revendication d’attestation de clé.

Syntaxe

SECURITY_STATUS NCryptVerifyClaim(
  [in]           NCRYPT_KEY_HANDLE hSubjectKey,
  [in, optional] NCRYPT_KEY_HANDLE hAuthorityKey,
  [in]           DWORD             dwClaimType,
  [in, optional] NCryptBufferDesc  *pParameterList,
  [in]           PBYTE             pbClaimBlob,
  [in]           DWORD             cbClaimBlob,
  [out]          NCryptBufferDesc  *pOutput,
  [in]           DWORD             dwFlags
);

Paramètres

[in] hSubjectKey

Handle de clé d’objet pour la revendication.

[in, optional] hAuthorityKey

Handle de clé d’autorité à utiliser lors de la vérification de la revendication. Ce paramètre est facultatif, car la clé d’autorité est autonome pour certains types de revendications.

[in] dwClaimType

Type de revendication.

[in, optional] pParameterList

Liste de paramètres facultative.

[in] pbClaimBlob

Objet blob de revendication d’entrée.

[in] cbClaimBlob

Taille, en octets, de la mémoire tampon pbClaimBlob.

[out] pOutput

Objet blob de sortie.

[in] dwFlags

NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG est un nouvel indicateur à définir lors de la vérification d’une revendication générée par VBS. Pour plus d’informations, consultez la section remarques.

Il n’existe actuellement aucun autre indicateur défini. Le paramètre dwFlags doit être défini sur 0 pour tous les autres types de vérification.

Valeur de retour

Retourne un code d’état qui indique la réussite ou l’échec de la fonction.

Voici quelques-uns des codes d’erreur qui peuvent être retournés par l’API de vérification lors de la vérification des revendications d’attestation de protection de clé VBS :

Retour du code	Signification
NTE_BAD_TYPE	Le paramètre d’entrée de type de revendication est différent du type de l’objet blob de revendication d’entrée.
STATUS_BAD_DATA	L’objet blob de revendication d’entrée n’est pas valide.
STATUS_NO_MEMORY	Échec de l’allocation de mémoire (requise pour la vérification de la revendication).
STATUS_INVALID_PARAMETER	L’absence d’un paramètre d’entrée obligatoire ou l’un des paramètres a une valeur illégale.
STATUS_FAIL_CHECK	Les vérifications de la revendication d’objet blob d’entrée ont échoué.
NTE_BAD_VER	La version de l’objet blob de revendication ne correspond pas à l’implémentation de vérification.
NTE_BAD_FLAGS	Les indicateurs fournis dans dwFlags ne sont pas pris en charge.

Remarques

Protection/attestation de clés privées à l’aide de la sécurité basée sur la virtualisation (VBS)

Note

Les informations relatives aux indicateurs VBS concernent le produit de préversion susceptible d’être sensiblement modifié avant sa publication commerciale. Microsoft n’offre aucune garantie, expresse ou implicite, en ce qui concerne les informations fournies ici.

Cette API permet d’activer une attestation avancée des clés de sécurité basées sur la protection des clés VBS, un module Windows pour la protection et l’attestation des clés privées à l’aide de VBS. L’attestation d’une clé de sécurité prouve l’association de cette clé à une clé ancrée, une clé d’attestation. Cette fonctionnalité peut améliorer le niveau de sécurité de la communication entre différentes entités en limitant l’utilisation des clés hors contexte.

L’API définit de nouveaux indicateurs pour prendre en charge la création et la vérification des revendications d’attestation en fonction des clés d’attestation dans la protection des clés VBS.

Voici types dwClaimType définis pour l’API :

Type de revendication	Description
NCRYPT_CLAIM_VBS_ROOT	Ce type indique que la revendication générée est produite par la clé racine VBS.
NCRYPT_CLAIM_VBS_IDENTITY	Ce type indique que la revendication générée est produite par une identité/attestation VBS. Cela signifie que la revendication est produite par une clé VBS élevée avec l’indicateur d’attestation NCRYPT_ALLOW_KEY_ATTESTATION_FLAG (voir les détails ci-dessous).

Voici les types de mémoires tampons à définir dans pParameterList tampon lors de la vérification d’une revendication d’attestation :

• NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS

  Nouvelle structure à définir comme élément de sortie NCryptBuffer de type NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS dans paramètre de sortie NCryptBufferDesc de NCryptVerifyClaim avec dwClaimType défini sur NCRYPT_CLAIM_VBS_ROOT. La définition de la structure est la suivante :

  typedef struct _NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS
  {
      ULONG ulKeyFlags;
      ULONGLONG ullTrustletId;
      ULONG ulTrustletSecurityVersion;
      ULONG ulTrustletDebuggable;
  } NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS, *PNCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS;
  

  La structure comprend les éléments suivants :

  • ulKeyFlags : combinaison de valeurs NCRYPT_VBS_KEY_FLAG_* définies pour la clé d’identité.
  • ullTrustletId : entier d’identificateur codé en dur dans les métadonnées de stratégie du trustlet VBS qui a créé la revendication.
  • ulTrustletSecurityVersion : numéro de version de sécurité du trustlet VBS qui a créé la revendication. Cette version reflète les mises à jour de sécurité appliquées au trustlet et implique donc le niveau de sécurité.
  • ulTrustletDebuggable : indication si le trustlet VBS qui a créé la revendication est débogueur. Une valeur 1 indique que le trustlet est débogueur et qu’un 0 indique un trustlet non débogueurable

  Si d’autres éléments informatifs sont nécessaires à l’avenir, une nouvelle structure et un type de structure correspondant sont définis.

  Note

  Ce paramètre de sortie doit être libéré une fois qu’il n’est plus référencé.

• NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS

  Nouvelle structure à définir comme élément de sortie NCryptBuffer de type NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS dans paramètre de sortie NCryptBufferDesc de NCryptVerifyClaim avec dwClaimType défini sur NCRYPT_CLAIM_VBS_IDENTITY. La définition de la structure est la suivante :

  typedef struct _NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS
  {
      ULONG ulKeyFlags;
      LPCWSTR pszSignatureHashAlg;
      ULONG ulPaddingScheme;
      LPCWSTR pszPaddingHashAlg;
      ULONG ulPaddingSalt;
  } NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS, *PNCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS;
  

  La structure comprend les éléments suivants :

  • ulKeyFlags : combinaison de valeurs NCRYPT_VBS_KEY_FLAG_* définies pour la clé d’identité.
  • pszSignatureHashAlg : pointeur vers une chaîne Unicode de l’algorithme de hachage de signature de revendication.
  • ulPaddingScheme - Schéma de remplissage de l’algorithme de signature utilisé par la création de revendication dans BCryptSignHash.
  • pszPaddingHashAlg : pointeur vers une chaîne Unicode de l’algorithme de hachage de remplissage de revendication utilisé par le biais de la création de revendications dans BCryptSignHash.
  • ulPaddingSalt - Sel de remplissage de l’algorithme de signature utilisé par la création de revendication dans BCryptSignHash.

  Si d’autres éléments informatifs sont nécessaires à l’avenir, une nouvelle structure et un type de structure correspondant sont définis.

  Note

  Ce paramètre de sortie doit être libéré une fois qu’il n’est plus référencé. L’exemple de code permettant de libérer ce paramètre est fourni dans l’exemple de code ci-dessous.

• NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS

  Nouveau type de mémoire tampon à définir dans un paramètre NCryptBuffer dans le NCryptBufferDescparamètre *pOutput de NCryptVerifyClaim. Ce type indique que le NCryptBuffer inclut la structure de données NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS.

• NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS

  Nouveau type de mémoire tampon à définir dans un paramètre NCryptBuffer dans le NCryptBufferDescparamètre *pOutput de NCryptVerifyClaim. Ce type indique que le NCryptBuffer inclut la structure de données NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS.

• NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG

  Il s’agit d’un nouvel indicateur à définir dans le dwFlags paramètre d’entrée lors de la vérification d’une revendication générée par VBS. Lorsque cet indicateur est défini NCryptVerifyClaim produit le paramètre de sortie NCryptBufferDesc avec un type de mémoire tampon de paramètre NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS interne ou NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS.

  Le tableau suivant décrit la relation entre les types de structure de données d’entrée et de sortie, dans un scénario réussi avec NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG:

  Entrée	Sortie
  dwClaimType = NCRYPT_CLAIM_VBS_ROOT	NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS type de mémoire tampon avec une structure informative NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS interne.
  dwClaimType = NCRYPT_CLAIM_VBS_IDENTITY	NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS type de mémoire tampon avec une structure informative NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS interne.

Exemples

Cet exemple illustre l’utilisation de l’API existante pour vérifier les revendications d’attestation générées avec NCryptCreateClaim.

L’API de vérification peut être appelée localement (sur l’ordinateur qui a généré l’objet blob de revendication) ou à distance. La procédure de vérification nécessite ces éléments, correspondant aux clés de génération de revendication :

• Objet blob de revendication
• Objet blob de clé d’attestation publique
• Objet blob de clé de jeton public (usage général)

L’API de vérification produit l’une des structures informatives de sortie NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS ou NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS si l’indicateur d’entrée NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG est défini. La mémoire de ces structures est libérée à la fin du flux de code pour éviter les fuites de mémoire.

HRESULT VerifyClaim(
       BCRYPT_RSAKEY_BLOB *pAttestPublicKeyBlob,
       BCRYPT_RSAKEY_BLOB *pTokenPublicKeyBlob,
       PBYTE pRootClaim,
       DWORD rootClaimSize,
       PBYTE pIdentityClaim,
       DWORD identityClaimSize)
{

    HRESULT hr = S_OK;
    DWORD bytesWritten = 0;

    NCRYPT_PROV_HANDLE provider = NULL;

    if (FAILED(hr = NCryptOpenStorageProvider(&provider, MS_KEY_STORAGE_PROVIDER, 0)))
    {
        wprintf(L"Error opening storage provider in NCryptOpenStorageProvider: 0x%X\n", hr);
        goto cleanup;
    }

    NCRYPT_KEY_HANDLE attestPublicKey = NULL;

    if (FAILED(hr = NCryptImportKey(
                       provider,
                       NULL,
                       BCRYPT_RSAPUBLIC_BLOB,
                       NULL,
                       &attestPublicKey,
                       (PBYTE)pAttestPublicKeyBlob,
                       GetRsaPublicKeyBlobSize(pAttestPublicKeyBlob),
                       0)))
    {
        wprintf(L"Unable to create a key handle for attestation public key blob with NCryptImportKey(): 0x%X\n", hr);
        goto cleanup;
    }

    NCRYPT_KEY_HANDLE tokenPublicKey = NULL;

    if (FAILED(hr = NCryptImportKey(
                       provider,
                       NULL,
                       BCRYPT_RSAPUBLIC_BLOB,
                       NULL,
                       &tokenPublicKey,
                       (PBYTE)pTokenPublicKeyBlob,
                       GetRsaPublicKeyBlobSize(pTokenPublicKeyBlob),
                       0)))
    {
        wprintf(L"Unable to create a key handle for token public key blob with NCryptImportKey(): 0x%X\n", hr);
        goto cleanup;
    }

    NCryptBufferDesc rootOutput{};

    // Verify the VBS root claim using the attestation/identity public key
    if (FAILED(hr = NCryptVerifyClaim(
                       attestPublicKey,
                       NULL,
                       NCRYPT_CLAIM_VBS_ROOT, // Created claim by IDKS (VBS root signing key)
                       NULL, // parameters
                       pRootClaim,
                       rootClaimSize,
                       &rootOutput,
                       NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG /*dwFlags*/)))
    {
        switch (hr)
        {
            case STATUS_OBJECT_TYPE_MISMATCH:
                wprintf(L"The dwClaimType parameter’s value is different than the claim’s type.\n-----\n", hr);
                break;
            case STATUS_BAD_DATA:
                wprintf(L"Something wrong in one of the data structures. E.g. Magic value mismatch\n-----\n", hr);
                break;
            case STATUS_NO_MEMORY:
                wprintf(L"Memory allocation failed\n-----\n", hr);
                break;
            case STATUS_INVALID_PARAMETER:
                wprintf(L"Missing mandatory parameter or one of the parameters has a bad value.\n-----\n", hr);
                break;
            case STATUS_FAIL_CHECK:
                wprintf(L"One of the claim checks has failed.\n-----\n", hr);
                break;
            default:
                wprintf(L"Unable to verify VBS root claim from NCryptVerifyClaim(): 0x%X\n-----\n", hr);
        }
        goto cleanup;
    }

    PNCryptBuffer pRootOutBuffer;
    DWORD count;

    // Look into the retrieved VBS root claim details
    for (count = 0; count < rootOutput.cBuffers; ++count)
    {
        pRootOutBuffer = rootOutput.pBuffers[count];
        if (pRootOutBuffer->BufferType == NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS)
        {
            PNCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS pDetails =
            (PNCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS) pRootOutBuffer->pvBuffer;
            wprintf(L"The claim trustlet id is: %lu\n-----\n", pDetails->ullTrustletId);
            wprintf(L"The claim trustlet Security Version number is: %llu\n-----\n", pDetails->ulTrustletSecurityVersion);
        }
    }

    NCryptBufferDesc identityOutput{};

    // Verify the identity claim using the attestation/identity and token public keys
    if (FAILED(hr = NCryptVerifyClaim(
                        tokenPublicKey,
                        attestPublicKey,
                        NCRYPT_CLAIM_VBS_IDENTITY, // Claim created by an attestation/identity key
                        NULL, // parameters
                        pIdentityClaim,
                        identityClaimSize,
                        &identityOutput,
                        NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG /*dwFlags*/)))
    {
        wprintf(L"Unable to verify identity claim from NCryptVerifyClaim(): 0x%X\n-----\n", hr);
        goto cleanup;
    }

    PNCryptBuffer pIdentityOutBuffer;

    // Look into the retrieved identity claim details
    for (count = 0; count < identityOutput.cBuffers; ++count)
    {
        pIdentityOutBuffer = identityOutput.pBuffers[count];
        if (pIdentityOutBuffer->BufferType == NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS)
        {
            PNCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS pDetails =
            (PNCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS) pIdentityOutBuffer->pvBuffer;
            wprintf(L"The claim hash algorithm is: %S\n-----\n", pDetails-> pszSignatureHashAlg);
            wprintf(L"The claim padding scheme is: %lu\n-----\n", pDetails->ulPaddingScheme);
        }
    }

    wprintf(L"Verify claim for root and identity types passed successfully\n");

    cleanup:

    if (provider != NULL)
    {
        NCryptFreeObject(provider);
    }
    if (attestPublicKey != NULL)
    {
        CryptDestroyKey(attestPublicKey);
    }
    if (tokenPub != NULL)
    {
        CryptDestroyKey(tokenPublicKey);
    }
    if (rootOutput.pBuffers != NULL)
    {
        for (count = 0; count < rootOutput.cBuffers; ++count)
        {
            NCryptFreeBuffer(rootOutput.pBuffers[count].pvBuffer);
        }
        NCryptFreeBuffer(rootOutput.pBuffers);
    }

    if (identityOutput.pBuffers != NULL)
    {
        for (count = 0; count < identityOutput.cBuffers; ++count)
        {
            NCryptFreeBuffer(identityOutput.pBuffers[count].pvBuffer);
        }
        NCryptFreeBuffer(identityOutput.pBuffers);
    }

    return hr;
}

DWORD GetRsaPublicKeyBlobSize(BCRYPT_RSAKEY_BLOB* publicKeyBlob)
{
    return sizeof(BCRYPT_RSAKEY_BLOB) +
                publicKeyBlob->cbModulus +
                publicKeyBlob->cbPublicExp;
}

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 10 [applications de bureau | Applications UWP]
serveur minimum pris en charge	Windows Server 2016 [applications de bureau | Applications UWP]
plateforme cible	Windows
d’en-tête	ncrypt.h
bibliothèque	Ncrypt.lib
DLL	Ncrypt.dll