Condividi tramite

Funzione NCryptVerifyClaim (ncrypt.h)

  • Articolo

Verifica un'attestazione di attestazione della chiave.

Sintassi

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

Parametri

[in] hSubjectKey

Handle della chiave dell'oggetto per l'attestazione.

[in, optional] hAuthorityKey

Handle della chiave dell'autorità da usare per la verifica dell'attestazione. Questo parametro è facoltativo perché la chiave dell'autorità è autonoma per determinati tipi di attestazione.

[in] dwClaimType

Tipo di attestazione.

[in, optional] pParameterList

Elenco di parametri facoltativo.

[in] pbClaimBlob

BLOB dell'attestazione di input.

[in] cbClaimBlob

Dimensioni, in byte, del buffer pbClaimBlob .

[out] pOutput

BLOB di output.

[in] dwFlags

NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG è un nuovo flag da impostare durante la verifica di un'attestazione generata da VBS. Per altre informazioni, vedere la sezione osservazioni .

Attualmente non sono definiti altri flag. Il parametro dwFlags deve essere impostato su per tutti gli altri tipi di verifica.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

Di seguito sono riportati alcuni dei codici di errore che possono essere restituiti dall'API di verifica durante la verifica delle attestazioni di attestazione della protezione della chiave VBS:

Codice restituito Significato
NTE_BAD_TYPE Il parametro di input del tipo di attestazione è diverso dal tipo di BLOB dell'attestazione di input.
STATUS_BAD_DATA Il BLOB dell'attestazione di input non è valido.
STATUS_NO_MEMORY L'allocazione della memoria (richiesta per la verifica dell'attestazione) non è riuscita.
STATUS_INVALID_PARAMETER Manca un parametro di input obbligatorio o uno dei parametri ha un valore non valido.
STATUS_FAIL_CHECK I controlli dell'attestazione BLOB di input non sono riusciti.
NTE_BAD_VER La versione del BLOB attestazione non corrisponde all'implementazione della verifica.
NTE_BAD_FLAGS I flag forniti in dwFlags non sono supportati.

Osservazioni

Protezione/attestazione di chiavi private tramite la sicurezza basata su virtualizzazione (VBS)

Nota

Le informazioni relative ai flag VBS riguardano il prodotto in versione non definitiva che potrebbe essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non fornisce alcuna garanzia, espressa o implicita, in relazione alle informazioni fornite qui.

Questa API consente di abilitare un'attestazione avanzata delle chiavi di sicurezza in base alla protezione della chiave VBS, un modulo di Windows per la protezione e l'attestazione di chiavi private usando la sicurezza basata su vbs. L'attestazione di una chiave di sicurezza dimostra l'associazione di questa chiave a una chiave ancorata, ovvero una chiave di attestazione. Questa funzionalità può migliorare il livello di sicurezza della comunicazione tra entità diverse limitando l'utilizzo delle chiavi fuori contesto.

L'API definisce nuovi flag per supportare la creazione e la verifica delle attestazioni di attestazione in base alle chiavi di attestazione nella protezione della chiave VBS.

Di seguito sono riportati tipi di dwClaimType definiti per l'API:

Tipo di attestazione Descrizione
NCRYPT_CLAIM_VBS_ROOT Questo tipo indica che l'attestazione generata viene prodotta dalla chiave radice VBS.
NCRYPT_CLAIM_VBS_IDENTITY Questo tipo indica che l'attestazione generata viene prodotta da un'identità/attestazione VBS. Ciò significa che l'attestazione viene prodotta da una chiave VBS con privilegi elevati con il flag di attestazione NCRYPT_ALLOW_KEY_ATTESTATION_FLAG (vedere i dettagli di seguito).

Di seguito sono riportati i tipi di buffer da impostare in buffer pParameterList durante la verifica di un'attestazione di attestazione:

  • NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS

    Nuova struttura da impostare come elemento NCryptBuffer di tipo NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS in NCryptBufferDesc parametro di output di NCryptVerifyClaim con dwClaimType impostato su NCRYPT_CLAIM_VBS_ROOT. La definizione della struttura è:

    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 struttura include questi elementi:

    • ulKeyFlags: combinazione di valori NCRYPT_VBS_KEY_FLAG_* impostati per la chiave identity.
    • ullTrustletId: intero identificatore hardcoded nei metadati dei criteri del trustlet VBS che ha creato l'attestazione.
    • ulTrustletSecurityVersion : numero di versione di sicurezza del trustlet VBS che ha creato l'attestazione. Questa versione riflette gli aggiornamenti della sicurezza applicati al trustlet e di conseguenza implica il livello di sicurezza.
    • ulTrustletDebuggable: indica se il Trustlet VBS che ha creato l'attestazione è debugbile. Un valore 1 indica che il trustlet è debugbile e un 0 indica un trustlet non di cui è possibile eseguire il debug

    Se in futuro sono necessari ulteriori elementi informativi, verrà definita una nuova struttura e un tipo di struttura corrispondente.

    Nota

    Questo parametro di output deve essere rilasciato dopo che non viene più fatto riferimento.

  • NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS

    Nuova struttura da impostare come elemento NCryptBuffer di tipo NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS in parametro di output NCryptBufferDesc di NCryptVerifyClaim con dwClaimType impostato su NCRYPT_CLAIM_VBS_IDENTITY. La definizione della struttura è:

    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 struttura include questi elementi:

    • ulKeyFlags: combinazione di valori NCRYPT_VBS_KEY_FLAG_* impostati per la chiave identity.
    • pszSignatureHashAlg: puntatore a una stringa Unicode dell'algoritmo hash della firma attestazione.
    • ulPaddingScheme - Schema padding dell'algoritmo di firma usato tramite la creazione di attestazioni in BCryptSignHash.
    • pszPaddingHashAlg: puntatore a una stringa Unicode dell'algoritmo hash di riempimento attestazione usato tramite la creazione di attestazioni in BCryptSignHash.
    • ulPaddingSalt- Riempimento dell'algoritmo di firma usato tramite la creazione di attestazioni in BCryptSignHash.

    Se in futuro sono necessari ulteriori elementi informativi, verrà definita una nuova struttura e un tipo di struttura corrispondente.

    Nota

    Questo parametro di output deve essere rilasciato dopo che non viene più fatto riferimento. Il codice di esempio per il rilascio di questo parametro viene fornito nell'esempio di codice seguente.

  • NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS

    Nuovo tipo di buffer da impostare in un parametro NCryptBuffer nel NCryptBufferDesc*pOutput parametro di NCryptVerifyClaim. Questo tipo indica che il NCryptBuffer include la struttura dei dati NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS.

  • NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS

    Nuovo tipo di buffer da impostare in un parametro NCryptBuffer nel NCryptBufferDesc*pOutput parametro di NCryptVerifyClaim. Questo tipo indica che il NCryptBuffer include la struttura dei dati NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS.

  • NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG

    Si tratta di un nuovo flag da impostare nel dwFlags parametro di input durante la verifica di un'attestazione generata da VBS. Quando questo flag viene impostato NCryptVerifyClaim genera il parametro di output NCryptBufferDesc con un tipo di buffer dei parametri interno NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS o NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS.

    Nella tabella seguente viene descritta la relazione tra i tipi di struttura di dati di input e di output, in uno scenario riuscito con NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG:

    Immissione Prodotto
    dwClaimType = NCRYPT_CLAIM_VBS_ROOT NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_ROOT_DETAILS tipo di buffer con struttura informativa interna NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS.
    dwClaimType = NCRYPT_CLAIM_VBS_IDENTITY NCRYPTBUFFER_VBS_ATTESTATION_STATEMENT_IDENTITY_DETAILS tipo di buffer con struttura informativa interna NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS.

Esempi

Questo esempio illustra l'utilizzo dell'API esistente per verificare le attestazioni di attestazione generate in con NCryptCreateClaim.

L'API di verifica può essere richiamata in locale (nel computer che ha generato il BLOB di attestazioni) o in remoto. La procedura di verifica richiede questi elementi, corrispondenti alle chiavi di generazione delle attestazioni:

  • BLOB di attestazioni
  • BLOB di chiavi di attestazione pubblica
  • BLOB di chiavi del token pubblico (utilizzo generico)

L'API di verifica produce una delle strutture informative di output NCRYPT_VBS_ROOT_KEY_ATTESTATION_CLAIM_DETAILS o NCRYPT_VBS_IDENTITY_KEY_ATTESTATION_CLAIM_DETAILS se è impostato il flag di input NCRYPT_VBS_RETURN_CLAIM_DETAILS_FLAG. La memoria di queste strutture viene liberata alla fine del flusso di codice per evitare perdite di memoria.

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

Fabbisogno

Requisito Valore
client minimo supportato Windows 10 [app desktop | App UWP]
server minimo supportato Windows Server 2016 [app desktop | App UWP]
piattaforma di destinazione Finestre
intestazione ncrypt.h
libreria Ncrypt.lib
dll Ncrypt.dll