/
TpmAtt.h
834 lines (747 loc) · 29.4 KB
/
TpmAtt.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
/*++
THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE.
Copyright (c) Microsoft Corporation. All rights reserved.
Module Name:
TpmAtt.h
Abstract:
Definitions, types and prototypes for TpmAtt.dll.
--*/
#ifdef _MSC_VER
#pragma once
#endif
#ifndef TPMATT_H
#define TPMATT_H
#define DllExport __declspec(dllexport)
// Platform attestation properties
#define PCP_ATTESTATION_PROPERTIES_CONTAINS_BOOT_COUNT (0x00000001)
#define PCP_ATTESTATION_PROPERTIES_CONTAINS_EVENT_COUNT (0x00000002)
#define PCP_ATTESTATION_PROPERTIES_EVENT_COUNT_NON_CONTIGUOUS (0x00000004)
#define PCP_ATTESTATION_PROPERTIES_INTEGRITY_SERVICES_DISABLED (0x00000008)
#define PCP_ATTESTATION_PROPERTIES_TRANSITION_TO_WINLOAD (0x00000010)
#define PCP_ATTESTATION_PROPERTIES_TRANSITION_TO_WINRESUME (0x00000020)
#define PCP_ATTESTATION_PROPERTIES_TRANSITION_TO_OTHER (0x00000040)
#define PCP_ATTESTATION_PROPERTIES_BOOT_DEBUG_ON (0x00000100)
#define PCP_ATTESTATION_PROPERTIES_OS_DEBUG_ON (0x00000200)
#define PCP_ATTESTATION_PROPERTIES_CODEINTEGRITY_OFF (0x00000400)
#define PCP_ATTESTATION_PROPERTIES_TESTSIGNING_ON (0x00000800)
#define PCP_ATTESTATION_PROPERTIES_BITLOCKER_UNLOCK (0x00001000)
#define PCP_ATTESTATION_PROPERTIES_OS_SAFEMODE (0x00002000)
#define PCP_ATTESTATION_PROPERTIES_OS_WINPE (0x00004000)
#define PCP_ATTESTATION_PROPERTIES_OS_HV (0x00008000)
// Key attestation properties
#define PCP_KEY_PROPERTIES_NON_MIGRATABLE (0x80000000)
#define PCP_KEY_PROPERTIES_PIN_PROTECTED (0x40000000)
#define PCP_KEY_PROPERTIES_PCR_PROTECTED (0x20000000)
#define PCP_KEY_PROPERTIES_SIGNATURE_KEY (0x00000001)
#define PCP_KEY_PROPERTIES_ENCRYPTION_KEY (0x00000002)
#define PCP_KEY_PROPERTIES_GENERIC_KEY (0x00000003)
#define PCP_KEY_PROPERTIES_STORAGE_KEY (0x00000004)
#define PCP_KEY_PROPERTIES_IDENTITY_KEY (0x00000005)
typedef enum PCP_KEY_FLAGS_WIN8 {
PCP_KEY_FLAGS_WIN8_authRequired = 0x00000001
} PCP_KEY_FLAGS_WIN8;
typedef enum PCP_KEY_FLAGS {
PCP_KEY_FLAGS_authRequired = 0x00000001
} PCP_KEY_FLAGS;
#define BCRYPT_PCP_KEY_MAGIC 'MPCP' // Platform Crypto Provider Magic
#define PCPTYPE_TPM12 (0x00000001)
#define PCPTYPE_TPM20 (0x00000002)
// SHA related constants
#ifndef SHA1_DIGEST_SIZE
#define SHA1_DIGEST_SIZE (20)
#endif
#ifndef SHA256_DIGEST_SIZE
#define SHA256_DIGEST_SIZE (32)
#endif
#ifndef MAX_DIGEST_SIZE
#define MAX_DIGEST_SIZE (64)
#endif
#ifndef TPM_API_ALG_ID_SHA1
#define TPM_API_ALG_ID_SHA1 ((UINT16)0x0004)
#endif
#ifndef TPM_API_ALG_ID_SHA256
#define TPM_API_ALG_ID_SHA256 ((UINT16)0x000B)
#endif
#ifndef TPM_API_ALG_ID_SHA384
#define TPM_API_ALG_ID_SHA384 ((UINT16)0x000C)
#endif
typedef struct PCP_KEY_BLOB_WIN8 // Storage structure for 2.0 keys
{
DWORD magic;
DWORD cbHeader;
DWORD pcpType;
DWORD flags;
ULONG cbPublic;
ULONG cbPrivate;
ULONG cbMigrationPublic;
ULONG cbMigrationPrivate;
ULONG cbPolicyDigestList;
ULONG cbPCRBinding;
ULONG cbPCRDigest;
ULONG cbEncryptedSecret;
ULONG cbTpm12HostageBlob;
} PCP_KEY_BLOB_WIN8, *PPCP_KEY_BLOB_WIN8;
typedef struct PCP_20_KEY_BLOB // Storage structure for 2.0 keys
{
DWORD magic;
DWORD cbHeader;
DWORD pcpType;
DWORD flags;
ULONG cbPublic;
ULONG cbPrivate;
ULONG cbMigrationPublic;
ULONG cbMigrationPrivate;
ULONG cbPolicyDigestList;
ULONG cbPCRBinding;
ULONG cbPCRDigest;
ULONG cbEncryptedSecret;
ULONG cbTpm12HostageBlob;
USHORT pcrAlgId;
} PCP_20_KEY_BLOB, *PPCP_20_KEY_BLOB;
typedef struct PCP_KEY_BLOB
{
DWORD magic;
DWORD cbHeader;
DWORD pcpType;
DWORD flags;
ULONG cbTpmKey;
} PCP_KEY_BLOB, *PPCP_KEY_BLOB;
#define PCP_PLATFORM_ATTESTATION_MAGIC 'SDAP' // Platform Attestation Data Structure
typedef struct _PCP_PLATFORM_ATTESTATION_BLOB {
ULONG Magic;
ULONG Platform;
ULONG HeaderSize;
ULONG cbPcrValues;
ULONG cbQuote;
ULONG cbSignature;
ULONG cbLog;
} PCP_PLATFORM_ATTESTATION_BLOB, *PPCP_PLATFORM_ATTESTATION_BLOB;
#define PCP_PLATFORM_ATTESTATION_MAGIC2 '2DAP' // Platform Attestation Data Structure, version 2
typedef struct _PCP_PLATFORM_ATTESTATION_BLOB2 {
ULONG Magic;
ULONG Platform;
ULONG HeaderSize;
ULONG cbPcrValues;
ULONG cbQuote;
ULONG cbSignature;
ULONG cbLog;
ULONG PcrAlgorithmId;
} PCP_PLATFORM_ATTESTATION_BLOB2, *PPCP_PLATFORM_ATTESTATION_BLOB2;
#define PCP_KEY_ATTESTATION_MAGIC 'SDAK' // Key Attestation Data Structure
typedef struct _PCP_KEY_ATTESTATION_BLOB {
ULONG Magic;
ULONG Platform;
ULONG HeaderSize;
ULONG cbKeyAttest;
ULONG cbSignature;
ULONG cbKeyBlob;
} PCP_KEY_ATTESTATION_BLOB, *PPCP_KEY_ATTESTATION_BLOB;
// TPM info location
#define TPM_STATIC_CONFIG_DATA L"System\\CurrentControlSet\\services\\TPM"
#define TPM_STATIC_CONFIG_QUOTE_KEYS L"SYSTEM\\CurrentControlSet\\Services\\Tpm\\PlatformQuoteKeys"
#define TPM_STATIC_CONFIG_KEYATTEST_KEYS L"SYSTEM\\CurrentControlSet\\Services\\Tpm\\KeyAttestationKeys"
#define TPM_VOLATILE_CONFIG_DATA L"System\\CurrentControlSet\\Control\\IntegrityServices"
// SIPA event structures
//
// Describes the VSM/SMART identity public key.
//
typedef struct tag_SIPAEVENT_VSM_IDK_RSA_INFO
{
//
// Length of the RSA IDK modulus in bits.
//
ULONG32 KeyBitLength;
//
// Length of the RSA IDK public exponent in bytes.
//
ULONG32 PublicExpLengthBytes;
//
// Length of the modulus field in bytes.
//
ULONG32 ModulusSizeBytes;
//
// The layout of the PublicKeyData field is as follows:
// PublicExponent[PublicExpLengthBytes] in Big-endian.
// Modulus[ModulusSizeBytes] in Big-endian.
//
BYTE PublicKeyData[ANYSIZE_ARRAY];
} SIPAEVENT_VSM_IDK_RSA_INFO, *PSIPAEVENT_VSM_IDK_RSA_INFO;
//
// Payload structure for the SIPAEVENT_VSM_IDK_INFO event.
//
typedef struct tag_SIPAEVENT_VSM_IDK_INFO_PAYLOAD
{
//
// Specifies the algorithm used for IDK. Should be one of VSM_IDK_ALG_ID values.
//
ULONG32 KeyAlgID;
//
// Algorithm-specific description of the public key.
//
union
{
//
// Description of the RSA public key.
//
SIPAEVENT_VSM_IDK_RSA_INFO RsaKeyInfo;
} DUMMYUNIONNAME;
} SIPAEVENT_VSM_IDK_INFO_PAYLOAD, *PSIPAEVENT_VSM_IDK_INFO_PAYLOAD;
//
// Payload structure used to carry information about any policy blob.
//
typedef struct tag_SIPAEVENT_SI_POLICY_PAYLOAD
{
//
// Policy version
//
ULONGLONG PolicyVersion;
//
// Indicates the length (in bytes) of the policy name stored as part of VarLengthData.
//
UINT16 PolicyNameLength;
//
// Indicates hash algorithm ID used to produce policy digest.
// Contains one of the TPM_ALG_ID values, typically the TPM_ALG_SHA256.
//
UINT16 HashAlgID;
//
// Indicates the hash digest length (in bytes). Digest is stored as part of VarLengthData.
//
UINT32 DigestLength;
//
// VarLengthData layout is:
//
// (Policy name is stored as a WCHAR string with a terminating zero).
// BYTE PolicyName[PolicyNameLength].
//
// BYTE Digest[DigestLength]
//
_Field_size_bytes_(PolicyNameLength + DigestLength)
BYTE VarLengthData[ANYSIZE_ARRAY];
} SIPAEVENT_SI_POLICY_PAYLOAD, *PSIPAEVENT_SI_POLICY_PAYLOAD;
//
// Payload structure used to carry information about revocation lists.
//
typedef struct tag_SIPAEVENT_REVOCATION_LIST_PAYLOAD
{
//
// Creation time.
//
LONGLONG CreationTime;
//
// Indicates the hash digest length (in bytes).
//
UINT32 DigestLength;
//
// Indicates hash algorithm ID used to produce the revocation list digest.
// Contains one of the TPM_ALG_ID values, typically the TPM_ALG_SHA256.
//
UINT16 HashAlgID;
//
// Hash digest of the revocation list.
//
_Field_size_bytes_(DigestLength)
BYTE Digest[ANYSIZE_ARRAY];
} SIPAEVENT_REVOCATION_LIST_PAYLOAD, *PSIPAEVENT_REVOCATION_LIST_PAYLOAD;
// WBCL parser APIs
#pragma pack(push,1)
#define TPM_AVAILABLE_PLATFORM_PCRS (24)
//
// These values are aligned with TPM 2.0 ALG_ID.
//
typedef UINT16 WBCL_DIGEST_ALG_ID;
#define WBCL_DIGEST_ALG_ID_SHA_1 0x0004
#define WBCL_DIGEST_ALG_ID_SHA_2_256 0x000B
#define WBCL_DIGEST_ALG_ID_SHA_2_384 0x000C
#define WBCL_DIGEST_ALG_ID_SHA_2_512 0x000D
//
// These values are aligned with the TPM 2.0 algorithm bitmap
//
#define WBCL_DIGEST_ALG_BITMAP_SHA_1 0x00000001
#define WBCL_DIGEST_ALG_BITMAP_SHA_2_256 0x00000002
#define WBCL_DIGEST_ALG_BITMAP_SHA_2_384 0x00000004
#define WBCL_DIGEST_ALG_BITMAP_SHA_2_512 0x00000008
//
// An iterator object for WBCL log.
//
typedef struct _WBCL_Iterator
{
// Pointer to the first element of the log.
PVOID firstElementPtr;
// Log size in bytes.
UINT32 logSize;
// Pointer to the current element of the log.
PVOID currentElementPtr;
// Size of the current log entry pointed to by currentElementPtr.
UINT32 currentElementSize;
// Size of the digest field of event log entries.
UINT16 digestSize;
// Indicates the log format.
UINT16 logFormat;
// number of algorithms stored in the following digest table.
UINT32 numberOfDigests;
// points to the table in the header that contains the mapping of algorithm ids to digest sizes.
PVOID digestSizes;
// Hash algorithm ID used for the log. The value corresponds to one of the TPM 2.0 ALG_ID values.
WBCL_DIGEST_ALG_ID hashAlgorithm;
} WBCL_Iterator, *PWBCL_Iterator;
#pragma pack(pop)
#if defined(__cplusplus)
extern "C" {
#endif
// WBCL parser functions (wbcl.h)
DllExport HRESULT WbclApiInitIterator(
_In_ PVOID pLogBuffer,
_In_ UINT32 logSize,
_Out_ WBCL_Iterator* pWbclIterator);
DllExport HRESULT WbclApiGetCurrentElement(
_In_ WBCL_Iterator* pWbclIterator,
_Out_ UINT32* pcrIndex,
_Out_ UINT32* eventType,
_Outptr_opt_result_bytebuffer_(pWbclIterator->digestSize) BYTE** ppDigest,
_Out_opt_ UINT32* pcbElementDataSize,
_Outptr_opt_result_bytebuffer_(*pcbElementDataSize) BYTE** ppbElementData
);
DllExport HRESULT WbclApiMoveToNextElement(
_In_ WBCL_Iterator* pWbclIterator);
#ifndef NCRYPT_PCP_PLATFORM_BINDING_PCRALGID_PROPERTY
#define NCRYPT_PCP_PLATFORM_BINDING_PCRALGID_PROPERTY L"PCP_PLATFORM_BINDING_PCRALGID"
#endif
// Internal helper functions
/// <summary>
/// Calculate SHA hash or HMAC.
/// </summary>
/// <param name="pszAlgId">BCrypt algorithm string.</param>
/// <param name="pbKey">pointer to Optional HMAC key.</param>
/// <param name="cbKey">size of Optional HMAC key.</param>
/// <param name="pbData">pointer to Data to be hashed.</param>
/// <param name="cbData">size of Data to be hashed.</param>
/// <param name="pbResult">Upon successful return, pointer to the digest.</param>
/// <param name="cbResult">Initial size of digest buffer.</param>
/// <param name="pcbResult">pointer to actually used size of digest buffer.</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
///</returns>
DllExport HRESULT TpmAttiShaHash(
LPCWSTR pszAlgId,
_In_reads_opt_(cbKey) PBYTE pbKey,
UINT32 cbKey,
_In_reads_(cbData) PBYTE pbData,
UINT32 cbData,
_Out_writes_to_opt_(cbResult, *pcbResult) PBYTE pbResult,
UINT32 cbResult,
_Deref_out_range_(0,cbResult) PUINT32 pcbResult
);
/// <summary>
/// Release all hash providers.
/// </summary>
DllExport void TpmAttiReleaseHashProviders();
/// <summary>
/// Obtain the TPM version of the platform.
/// </summary>
/// <param name="pTpmVersion">Pointer to variable that will receive TPM version</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttiGetTpmVersion(
_Out_ PUINT32 pTpmVersion
);
/// <summary>
/// Calculate a bank of SHA-1 PCRs from a given TCG log.
/// </summary>
/// <param name="pbEventLog">pointer to EventLog to be parsed.</param>
/// <param name="cbEventLog">size of EventLog to be parsed.</param>
/// <param name="pbSwPcr">Pointer to PCR bank.</param>
/// <param name="pPcrMask">PCR mask that will indicate for which PCRs were log entries present</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
HRESULT TpmAttiComputeSoftPCRs(
_In_reads_(cbEventLog) PBYTE pbEventLog,
UINT32 cbEventLog,
UINT16 pcrAlgId,
_Inout_updates_bytes_(cbSwPcr) PBYTE pbSwPcr,
UINT32 cbSwPcr,
_Out_opt_ PUINT32 pPcrMask
);
/// <summary>
/// Filter eventlog to contain only entries that are specified in the PCRMask.
/// </summary>
/// <param name="pbEventLog">pointer to EventLog to be filtered.</param>
/// <param name="cbEventLog">size of EventLog to be filtered.</param>
/// <param name="pcrMask">filter mask.</param>
/// <param name="pbOutput">Upon successful return, contains the digest</param>
/// <param name="cbOutput">input size of the digest buffer</param>
/// <param name="pcbResult">output size of the digest buffer</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
HRESULT TpmAttiFilterLog(
_In_reads_(cbEventLog) PBYTE pbEventLog,
UINT32 cbEventLog,
UINT32 pcrMask,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
// API functions
/// <summary>
/// Retrieve BCrypt key handle from IDBinding. This function is typically called on a server.
/// </summary>
/// <param name="pbIdBinding">pointer to IDBinding from Client.</param>
/// <param name="cbIdBinding">size of IDBinding from Client.</param>
/// <param name="hRsaAlg">Provider handle in which the handle should be opened.</param>
/// <param name="phAikPub">Upon successful return, contains handle to key</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttPubKeyFromIdBinding(
_In_reads_(cbIdBinding) PBYTE pbIdBinding,
UINT32 cbIdBinding,
BCRYPT_ALG_HANDLE hRsaAlg,
_Out_ BCRYPT_KEY_HANDLE* phAikPub
);
/// <summary>
/// Generate Activation Blob from IDBinding, with a given secret. If a nonce is provided,
/// it will be validated with the nonce in the IDBinding
/// </summary>
/// <param name="hEkPub">Public key to encrypt the activation.</param>
/// <param name="pbIdBinding">pointer to IDBinding from the client.</param>
/// <param name="cbIdBinding">size of IDBinding from the client.</param>
/// <param name="pbNonce">pointer to Nonce provided to the client for key creation.</param>
/// <param name="cbNonce">size of Nonce provided to the client for key creation.</param>
/// <param name="pbSecret">pointer to Secret to be wrapped in activation.</param>
/// <param name="cbSecret">size of Secret to be wrapped in activation.</param>
/// <param name="pbOutput">Upon successful return, contains the activation blob.</param>
/// <param name="cbOutput">input size of activation blob</param>
/// <param name="pcbResult">output size of activation blob.</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttGenerateActivation(
BCRYPT_KEY_HANDLE hEkPub,
_In_reads_(cbIdBinding) PBYTE pbIdBinding,
UINT32 cbIdBinding,
_In_reads_opt_(cbNonce) PBYTE pbNonce,
UINT32 cbNonce,
_In_reads_(cbSecret) PBYTE pbSecret,
UINT16 cbSecret,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
/// <summary>
/// Generate platform attestation blob with provided AIK over the PCRs indicated and an optional nonce
/// </summary>
/// <param name="hAik">AIK key handle, fully authorized if required.</param>
/// <param name="pcrMask">Filter for events.</param>
/// <param name="pbNonce">pointer to Nonce provided to be included in signature.</param>
/// <param name="cbNonce">size of Nonce provided to be included in signature.</param>
/// <param name="pbOutput">Upon successful return, contains the attestation blob.</param>
/// <param name="cbOutput">input size of attestation blob buffer.</param>
/// <param name="pcbResult">output size of attestation blob.</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttGeneratePlatformAttestation(
NCRYPT_KEY_HANDLE hAik,
UINT32 pcrMask,
_In_reads_opt_ (cbNonce) PBYTE pbNonce,
UINT32 cbNonce,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
/// <summary>
/// Integrity verification of a platform attestation. This operation is typically done on a server.
/// </summary>
/// <param name="hAik">AIKPub handle for signature validation</param>
/// <param name="pbNonce">Optional nonce verification that was provided by the server to ensure that the attestation is fresh.</param>
/// <param name="cbNonce">size of optional nonce.</param>
/// <param name="pbAttestation">pointer to Attestation blob</param>
/// <param name="cbAttestation">size of Attestation blob</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttValidatePlatformAttestation(
BCRYPT_KEY_HANDLE hAik,
_In_reads_opt_ (cbNonce) PBYTE pbNonce,
UINT32 cbNonce,
_In_reads_ (cbAttestation) PBYTE pbAttestation,
UINT32 cbAttestation
);
/// <summary>
/// Read and return all platform counters
/// </summary>
/// <param name="pOsBootCount">OS Boot counter - insecure index for log files.</param>
/// <param name="pOsResumeCount">OS Resume counter - insecure index for log files.</param>
/// <param name="pCurrentTpmBootCount">TPM 2.0 backed counter, not available on 1.2.</param>
/// <param name="pCurrentTpmEventCount">TPM backed monotonic counter.</param>
/// <param name="pCurrentTpmCounterId">Counter ID on 1.2 TPMs.</param>
/// <param name="pInitialTpmBootCount">TPM 2.0 backed counter, not available on 1.2 when the platform was booted.</param>
/// <param name="pInitialTpmEventCount">TPM backed monotonic counter when the platform was booted.</param>
/// <param name="pInitialTpmCounterId">Counter ID on 1.2 TPMs when the platform was booted.</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttGetPlatformCounters(
_Out_opt_ PUINT32 pOsBootCount,
_Out_opt_ PUINT32 pOsResumeCount,
_Out_opt_ PUINT64 pCurrentTpmBootCount,
_Out_opt_ PUINT64 pCurrentTpmEventCount,
_Out_opt_ PUINT64 pCurrentTpmCounterId,
_Out_opt_ PUINT64 pInitialTpmBootCount,
_Out_opt_ PUINT64 pInitialTpmEventCount,
_Out_opt_ PUINT64 pInitialTpmCounterId
);
/// <summary>
/// Obtain a log from the archive on the disk. The log is selected by the OS boot and resume counter
/// </summary>
/// <param name="OsBootCount">Selector for boot index</param>
/// <param name="OsResumeCount">Selector for resume index</param>
/// <param name="pbOutput">Upon successful return, contains the requested log.</param>
/// <param name="cbOutput">input size of log buffer</param>
/// <param name="pcbResult">output size of log buffer</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttGetPlatformLogFromArchive(
UINT32 OsBootCount,
UINT32 OsResumeCount,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
/// <summary>
/// Turn a log with a trust point into an attestation blob, so it can be validated as any other attestation blob
/// </summary>
/// <param name="pbLog">pointer to Event log with trust point</param>
/// <param name="cbLog">size of Event log with trust point</param>
/// <param name="szAikNameRequested">Optional AIK name selection, if multiple AIK are registered</param>
/// <param name="pszAikName">
/// Upon successful return, contains a pointer to the AIK name that signed the trust point.
/// This is a pointer into pbLog, cbLog and does not need to be explicitly freed.
/// </param>
/// <param name="pbAikPubDigest">pointer to receive AIK pub digest.</param>
/// <param name="pbOutput">Upon successful return, contains the attestation blob.</param>
/// <param name="cbOutput">input size of attestation blob buffer.</param>
/// <param name="pcbResult">output size of attestation blob buffer.</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttCreateAttestationfromLog(
_In_reads_(cbLog) PBYTE pbLog,
UINT32 cbLog,
_In_reads_z_(MAX_PATH) PWSTR szAikNameRequested,
_Outptr_result_z_ PWSTR* pszAikName,
_Out_writes_all_opt_(SHA1_DIGEST_SIZE) PBYTE pbAikPubDigest,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
/// <summary>
/// Parse an attestation blob and return specific properties from it
/// </summary>
/// <param name="pbAttestation">pointer to Event log with trust point.</param>
/// <param name="cbAttestation">size of Event log with trust point.</param>
/// <param name="pEventCount">Starting event count in the log.</param>
/// <param name="pEventIncrements">Number of event increments in the log.</param>
/// <param name="pEventCounterId">Event counter ID - only valid on 1.2.</param>
/// <param name="pBootCount">Power-up counter - only valid on 2.0.</param>
/// <param name="pdwPropertyFlags">Property flags for this attestation.</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttGetPlatformAttestationProperties(
_In_reads_(cbAttestation) PBYTE pbAttestation,
UINT32 cbAttestation,
_Out_opt_ PUINT64 pEventCount,
_Out_opt_ PUINT64 pEventIncrements,
_Out_opt_ PUINT64 pEventCounterId,
_Out_opt_ PUINT64 pBootCount,
_Out_opt_ PUINT32 pdwPropertyFlags
);
/// <summary>
/// Generate a key attestation. Both keys have to be on the TPM within the same provider handle.
/// </summary>
/// <param name="hAik">Key to sign the attestation - has to be fully authorized if necessary</param>
/// <param name="hKey">Key to be attested - has to be fully authorized if necessary</param>
/// <param name="pbNonce">pointer to optional nonce included in the signature</param>
/// <param name="cbNonce">size of optional nonce</param>
/// <param name="pbOutput">Upon successful return, contains the key certification blob.</param>
/// <param name="cbOutput">input size of certification blob buffer</param>
/// <param name="pcbResult">output size of certification blob buffer</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttGenerateKeyAttestation(
NCRYPT_KEY_HANDLE hAik,
NCRYPT_KEY_HANDLE hKey,
_In_reads_opt_(cbNonce) PBYTE pbNonce,
UINT32 cbNonce,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
/// <summary>
/// Get a key attestation that was created by the provider.
/// </summary>
/// <param name="hKey">Key to be attested - has to be fully authorized if necessary</param>
/// <param name="szAikNameRequested">Optional AIK name selection, if multiple AIK are registered</param>
/// <param name="pszAikName">
/// Upon successful return, contains a pointer to the AIK name that signed the trust point.
/// This is a pointer into pbLog, cbLog and does not need to be explicitly freed.
/// </param>
/// <param name="pbAikPubDigest">pointer to receive AIK pub digest.</param>
/// <param name="pbOutput">Upon successful return, contains the key certification blob.</param>
/// <param name="cbOutput">input size of certification blob buffer</param>
/// <param name="pcbResult">output size of certification blob buffer</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttCreateAttestationfromKey(
NCRYPT_KEY_HANDLE hKey,
_In_reads_z_(MAX_PATH) PWSTR szAikNameRequested,
_Out_writes_z_(MAX_PATH) PWSTR szAikName,
_Out_writes_all_opt_(SHA1_DIGEST_SIZE) PBYTE pbAikPubDigest,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
/// <summary>
/// Integrity validation of a key certification. Usually done on a server.
/// </summary>
/// <param name="hAik">Public key to validate the attestation.</param>
/// <param name="pbNonce">Optional nonce validated with certification if provided.</param>
/// <param name="cbNonce">size of optional nonce.</param>
/// <param name="pbAttestation">Key certification blob.</param>
/// <param name="cbAttestation">size of key certification blob.</param>
/// <param name="pcrMask">Expected pceMask of key. Validated with pcrMask in the key.</param>
/// <param name="pcrTable">
/// All 24 PCRs that the pcr digest is validated with.
/// This is used to check the PCR policy a key is bound to.
/// </param>
/// <param name="cbPcrTable">size of PCR table</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttValidateKeyAttestation(
BCRYPT_KEY_HANDLE hAik,
_In_reads_opt_(cbNonce) PBYTE pbNonce,
UINT32 cbNonce,
_In_reads_(cbAttestation) PBYTE pbAttestation,
UINT32 cbAttestation,
UINT32 pcrMask,
UINT16 pcrAlgId,
_In_reads_opt_(cbPcrTable) PBYTE pcrTable,
UINT32 cbPcrTable
);
/// <summary>
/// Retrieve a public key handle and key property flags form a key attestation. This function is usually called on a server.
/// </summary>
/// <param name="pbAttestation">Validated attestation blob.</param>
/// <param name="cbAttestation">size of validated attestation blob.</param>
/// <param name="pPropertyFlags">Upon successful return, contains the key property flags.</param>
/// <param name="hAlg">Provider that should be used to open the key handle in.</param>
/// <param name="phKey">Upon successful return, contains the public key handle</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttGetKeyAttestationProperties(
_In_reads_(cbAttestation) PBYTE pbAttestation,
UINT32 cbAttestation,
_Out_opt_ PUINT32 pPropertyFlags,
BCRYPT_ALG_HANDLE hAlg,
_Out_opt_ BCRYPT_KEY_HANDLE* phKey
);
/// <summary>
/// Wrap a platform key with a given set of policies for a particular target machine. This function is usually called on a server.
/// </summary>
/// <param name="hInKey">Handle to an exportable key pair.</param>
/// <param name="hStorageKey">Public storage key that will be the new parent of inKey. Has to be a storage key.</param>
/// <param name="tpmVersion">Selector if a 1.2 or 2.0 key blob is to be created.</param>
/// <param name="keyUsage">Key usage restriction.</param>
/// <param name="pbPIN">Optional user PIN value that the key should be bound to.</param>
/// <param name="cbPIN">size of optional PIN value</param>
/// <param name="pcrMask">Optional PCRMask the key will be bound to</param>
/// <param name="pcrTable">PCR table of 24 digests that will be used to calculate the PCR digest with the pcrMask</param>
/// <param name="cbPcrTable">size of PCR table</param>
/// <param name="pbOutput">Upon successful return, contains the wrapped key blob.</param>
/// <param name="cbOutput">input size of key blob</param>
/// <param name="pcbResult">output size of key blob</param>
/// <returns>
/// S_OK - Success.
/// E_INVALIDARG - Parameter error.
/// E_FAIL - Internal consistency error.
/// Others as propagated by called functions.
/// </returns>
DllExport HRESULT TpmAttWrapPlatformKey(
NCRYPT_KEY_HANDLE hInKey,
BCRYPT_KEY_HANDLE hStorageKey,
UINT32 tpmVersion,
UINT32 keyUsage,
_In_reads_opt_(cbPIN) PBYTE pbPIN,
UINT32 cbPIN,
UINT32 pcrMask,
UINT16 pcrAlgId,
_In_reads_opt_(cbPcrTable) PBYTE pcrTable,
UINT32 cbPcrTable,
_Out_writes_to_opt_(cbOutput, *pcbResult) PBYTE pbOutput,
UINT32 cbOutput,
_Deref_out_range_(0,cbOutput) PUINT32 pcbResult
);
#if defined(__cplusplus)
}
#endif
#endif //TPMATT_H