NCryptVerifyClaim-Funktion (ncrypt.h)

Überprüft einen Schlüsselnachweisanspruch.

Syntax

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

Parameter

[in] hSubjectKey

Das Betreffschlüsselhandle für den Anspruch.

[in, optional] hAuthorityKey

Der Autoritätsschlüsselhandle, das beim Überprüfen des Anspruchs verwendet werden soll. Dieser Parameter ist optional, da der Autoritätsschlüssel für bestimmte Anspruchstypen eigenständig ist.

[in] dwClaimType

Der Anspruchstyp.

[in, optional] pParameterList

Eine optionale Parameterliste.

[in] pbClaimBlob

Das Eingabeanspruchs-BLOB.

[in] cbClaimBlob

Die Größe des pbClaimBlob- Puffers in Byte.

[out] pOutput

Das Ausgabe-BLOB.

[in] dwFlags

NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG ist ein neues Kennzeichen, das während der Überprüfung eines von VBS generierten Anspruchs festgelegt werden soll. Weitere Informationen finden Sie im Abschnitt Anmerkungen.

Es sind derzeit keine anderen Flags definiert. Der dwFlags Parameter sollte für alle anderen Überprüfungstypen auf 0 festgelegt werden.

Rückgabewert

Gibt einen Statuscode zurück, der den Erfolg oder Fehler der Funktion angibt.

Im Folgenden finden Sie einige der Fehlercodes, die beim Überprüfen von VBS-Schlüsselschutznachweisansprüchen von der Überprüfungs-API zurückgegeben werden können:

Bemerkungen

Schützen/Bestätigen privater Schlüssel mithilfe der virtualisierungsbasierten Sicherheit (VBS)

Diese API unterstützt die Aktivierung eines erweiterten Nachweises von Sicherheitsschlüsseln basierend auf dem VBS-Schlüsselschutz, einem Windows-Modul zum Schutz und Nachweis privater Schlüssel mithilfe von VBS. Der Nachweis eines Sicherheitsschlüssels beweist die Zuordnung dieses Schlüssels zu einem verankerten Schlüssel, auch als Nachweisschlüssel bezeichnet. Diese Funktion kann die Sicherheitsstufe der Kommunikation zwischen verschiedenen Entitäten verbessern, indem die Verwendung von Nichtkontextschlüsseln eingeschränkt wird.

Die API definiert neue Flags zur Unterstützung der Erstellung und Überprüfung von Nachweisansprüchen basierend auf Attestationsschlüsseln im VBS-Schlüsselschutz.

Im Folgenden werden dwClaimType- Typen aufgeführt, die für die API definiert sind:

Im Folgenden sind Puffertypen aufgeführt, die beim Überprüfen eines Nachweisanspruchs in pParameterList Puffer festgelegt werden:

• NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS

  Eine neue Struktur, die als NCryptBuffer Element vom Typ festgelegt werden soll, NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS in NCryptBufferDesc Ausgabeparameter von NCryptVerifyClaim mit dwClaimType auf NCRYPT_CLAIM_VBS_ROOTfestgelegt. Die Strukturdefinition lautet:

  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;
  

  Die Struktur enthält die folgenden Elemente:

  • ulKeyFlags – Eine Kombination aus NCRYPT_VBS_KEY_FLAG_* Werten, die für den Identitätsschlüssel festgelegt wurden.
  • ullTrustletId – Eine hartcodierte ID-Ganzzahl in den Richtlinienmetadaten des VBS Trustlet, das den Anspruch erstellt hat.
  • ulTrustletSecurityVersion – Die Sicherheitsversionsnummer des VBS Trustlet, das den Anspruch erstellt hat. Diese Version gibt an, welche Sicherheitsupdates auf das Trustlet angewendet wurden, und impliziert folglich die Sicherheitsstufe.
  • ulTrustletDebuggable – Ein Hinweis, ob das VBS Trustlet, das den Anspruch erstellt hat, debuggierbar ist. Ein 1 Wert gibt an, dass das Trustlet debuggierbar ist, und ein 0 gibt an, dass kein debuggables Trustlet vorhanden ist.

  Wenn in Zukunft weitere informative Elemente erforderlich sind, wird eine neue Struktur und ein entsprechender Strukturtyp definiert.

  Anmerkung

  Dieser Ausgabeparameter muss freigegeben werden, nachdem auf ihn nicht mehr verwiesen wird.

• NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS

  Eine neue Struktur, die als NCryptBuffer Element vom Typ festgelegt werden soll, NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS in NCryptBufferDesc Ausgabeparameter von NCryptVerifyClaim mit dwClaimType auf NCRYPT_CLAIM_VBS_IDENTITYfestgelegt. Die Strukturdefinition lautet:

  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;
  

  Die Struktur enthält die folgenden Elemente:

  • ulKeyFlags – Eine Kombination aus NCRYPT_VBS_KEY_FLAG_* Werten, die für den Identitätsschlüssel festgelegt wurden.
  • pszSignatureHashAlg – Ein Zeiger auf eine Unicode-Zeichenfolge des Anspruchssignaturhashalgorithmus.
  • ulPaddingScheme - Padding-Schema des Signaturalgorithmus, das durch die Anspruchserstellung in BCryptSignHashverwendet wurde.
  • pszPaddingHashAlg - Ein Zeiger auf eine Unicode-Zeichenfolge des Anspruchsabstand-Hashalgorithmus, der durch die Erstellung von Ansprüchen in BCryptSignHashverwendet wird.
  • ulPaddingSalt - Padding Salt des Signaturalgorithmus, der durch die Anspruchserstellung in BCryptSignHashverwendet wurde.

  Wenn in Zukunft weitere informative Elemente erforderlich sind, wird eine neue Struktur und ein entsprechender Strukturtyp definiert.

  Anmerkung

  Dieser Ausgabeparameter muss freigegeben werden, nachdem auf ihn nicht mehr verwiesen wird. Der Beispielcode zum Freigeben dieses Parameters wird im Codebeispiel untenangegeben.

• NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS

  Ein neuer Puffertyp, der in einem Parameter festgelegt werden soll, NCryptBuffer im NCryptBufferDesc*pOutput Parameter von NCryptVerifyClaim. Dieser Typ gibt an, dass die NCryptBuffer- die Datenstruktur NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILSenthält.

• NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS

  Ein neuer Puffertyp, der in einem Parameter festgelegt werden soll, NCryptBuffer im NCryptBufferDesc*pOutput Parameter von NCryptVerifyClaim. Dieser Typ gibt an, dass die NCryptBuffer- die Datenstruktur NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILSenthält.

• NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG

  Dies ist ein neues Kennzeichen, das während der Überprüfung eines von VBS generierten Anspruchs im dwFlags Eingabeparameter festgelegt werden soll. Wenn dieses Flag NCryptVerifyClaim festgelegt wird, erzeugt den NCryptBufferDesc Ausgabeparameter mit einem internen NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS- oder NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS Parameterpuffertyp.

  In der folgenden Tabelle wird die Beziehung zwischen den Eingabe- und Ausgabedatenstrukturtypen in einem erfolgreichen Szenario mit NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAGbeschrieben:

  Eingabe	Ausgabe
  dwClaimType = NCRYPT_CLAIM_VBS_ROOT	NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS Puffertyp mit interner NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS informativer Struktur.
  dwClaimType = NCRYPT_CLAIM_VBS_IDENTITY	NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS Puffertyp mit interner NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS informativer Struktur.

Beispiele

In diesem Beispiel wird die Verwendung der vorhandenen API veranschaulicht, um die Nachweisansprüche zu überprüfen, die mit NCryptCreateClaimgeneriert wurden.

Die Überprüfungs-API kann lokal (auf dem Computer, auf dem das Anspruchs-Blob generiert wurde) oder remote aufgerufen werden. Für das Überprüfungsverfahren sind diese Elemente erforderlich, die den Anspruchsgenerierungsschlüsseln entsprechen:

• Anspruchs-BLOB
• Blob mit öffentlichem Nachweisschlüssel
• Öffentliches Token (allgemeines) Schlüssel-BLOB

Die Überprüfungs-API erzeugt eine der ausgabe informativen Strukturen NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS oder NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS, wenn das Eingabekennzeichnungs-NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG festgelegt ist. Der Speicher dieser Strukturen wird am Ende des Codeflusses freigegeben, um Speicherverluste zu vermeiden.

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

Anforderungen