1 // Copyright (c) Microsoft Corporation. All rights reserved. 2 // Licensed under the MIT License. 3 4 #ifndef __WEBAUTHN_H_ 5 #define __WEBAUTHN_H_ 6 7 #pragma once 8 9 #include <winapifamily.h> 10 11 #pragma region Desktop Family or OneCore Family 12 #if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP | WINAPI_PARTITION_SYSTEM) 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 #ifndef WINAPI 19 #define WINAPI __stdcall 20 #endif 21 22 #ifndef INITGUID 23 #define INITGUID 24 #include <guiddef.h> 25 #undef INITGUID 26 #else 27 #include <guiddef.h> 28 #endif 29 30 //+------------------------------------------------------------------------------------------ 31 // API Version Information. 32 // Caller should check for WebAuthNGetApiVersionNumber to check the presence of relevant APIs 33 // and features for their usage. 34 //------------------------------------------------------------------------------------------- 35 36 #define WEBAUTHN_API_VERSION_1 1 37 // WEBAUTHN_API_VERSION_1 : Baseline Version 38 // Data Structures and their sub versions: 39 // - WEBAUTHN_RP_ENTITY_INFORMATION : 1 40 // - WEBAUTHN_USER_ENTITY_INFORMATION : 1 41 // - WEBAUTHN_CLIENT_DATA : 1 42 // - WEBAUTHN_COSE_CREDENTIAL_PARAMETER : 1 43 // - WEBAUTHN_COSE_CREDENTIAL_PARAMETERS : Not Applicable 44 // - WEBAUTHN_CREDENTIAL : 1 45 // - WEBAUTHN_CREDENTIALS : Not Applicable 46 // - WEBAUTHN_CREDENTIAL_EX : 1 47 // - WEBAUTHN_CREDENTIAL_LIST : Not Applicable 48 // - WEBAUTHN_EXTENSION : Not Applicable 49 // - WEBAUTHN_EXTENSIONS : Not Applicable 50 // - WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS : 3 51 // - WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS : 4 52 // - WEBAUTHN_COMMON_ATTESTATION : 1 53 // - WEBAUTHN_CREDENTIAL_ATTESTATION : 3 54 // - WEBAUTHN_ASSERTION : 1 55 // Extensions: 56 // - WEBAUTHN_EXTENSIONS_IDENTIFIER_HMAC_SECRET 57 // APIs: 58 // - WebAuthNGetApiVersionNumber 59 // - WebAuthNIsUserVerifyingPlatformAuthenticatorAvailable 60 // - WebAuthNAuthenticatorMakeCredential 61 // - WebAuthNAuthenticatorGetAssertion 62 // - WebAuthNFreeCredentialAttestation 63 // - WebAuthNFreeAssertion 64 // - WebAuthNGetCancellationId 65 // - WebAuthNCancelCurrentOperation 66 // - WebAuthNGetErrorName 67 // - WebAuthNGetW3CExceptionDOMError 68 69 #define WEBAUTHN_API_VERSION_2 2 70 // WEBAUTHN_API_VERSION_2 : Delta From WEBAUTHN_API_VERSION_1 71 // Added Extensions: 72 // - WEBAUTHN_EXTENSIONS_IDENTIFIER_CRED_PROTECT 73 // 74 75 #define WEBAUTHN_API_CURRENT_VERSION WEBAUTHN_API_VERSION_2 76 77 //+------------------------------------------------------------------------------------------ 78 // Information about an RP Entity 79 //------------------------------------------------------------------------------------------- 80 81 #define WEBAUTHN_RP_ENTITY_INFORMATION_CURRENT_VERSION 1 82 83 typedef struct _WEBAUTHN_RP_ENTITY_INFORMATION { 84 // Version of this structure, to allow for modifications in the future. 85 // This field is required and should be set to CURRENT_VERSION above. 86 DWORD dwVersion; 87 88 // Identifier for the RP. This field is required. 89 PCWSTR pwszId; 90 91 // Contains the friendly name of the Relying Party, such as "Acme Corporation", "Widgets Inc" or "Awesome Site". 92 // This field is required. 93 PCWSTR pwszName; 94 95 // Optional URL pointing to RP's logo. 96 PCWSTR pwszIcon; 97 } WEBAUTHN_RP_ENTITY_INFORMATION, *PWEBAUTHN_RP_ENTITY_INFORMATION; 98 typedef const WEBAUTHN_RP_ENTITY_INFORMATION *PCWEBAUTHN_RP_ENTITY_INFORMATION; 99 100 //+------------------------------------------------------------------------------------------ 101 // Information about an User Entity 102 //------------------------------------------------------------------------------------------- 103 #define WEBAUTHN_MAX_USER_ID_LENGTH 64 104 105 #define WEBAUTHN_USER_ENTITY_INFORMATION_CURRENT_VERSION 1 106 107 typedef struct _WEBAUTHN_USER_ENTITY_INFORMATION { 108 // Version of this structure, to allow for modifications in the future. 109 // This field is required and should be set to CURRENT_VERSION above. 110 DWORD dwVersion; 111 112 // Identifier for the User. This field is required. 113 DWORD cbId; 114 _Field_size_bytes_(cbId) 115 PBYTE pbId; 116 117 // Contains a detailed name for this account, such as "john.p.smith@example.com". 118 PCWSTR pwszName; 119 120 // Optional URL that can be used to retrieve an image containing the user's current avatar, 121 // or a data URI that contains the image data. 122 PCWSTR pwszIcon; 123 124 // For User: Contains the friendly name associated with the user account by the Relying Party, such as "John P. Smith". 125 PCWSTR pwszDisplayName; 126 } WEBAUTHN_USER_ENTITY_INFORMATION, *PWEBAUTHN_USER_ENTITY_INFORMATION; 127 typedef const WEBAUTHN_USER_ENTITY_INFORMATION *PCWEBAUTHN_USER_ENTITY_INFORMATION; 128 129 //+------------------------------------------------------------------------------------------ 130 // Information about client data. 131 //------------------------------------------------------------------------------------------- 132 133 #define WEBAUTHN_HASH_ALGORITHM_SHA_256 L"SHA-256" 134 #define WEBAUTHN_HASH_ALGORITHM_SHA_384 L"SHA-384" 135 #define WEBAUTHN_HASH_ALGORITHM_SHA_512 L"SHA-512" 136 137 #define WEBAUTHN_CLIENT_DATA_CURRENT_VERSION 1 138 139 typedef struct _WEBAUTHN_CLIENT_DATA { 140 // Version of this structure, to allow for modifications in the future. 141 // This field is required and should be set to CURRENT_VERSION above. 142 DWORD dwVersion; 143 144 // Size of the pbClientDataJSON field. 145 DWORD cbClientDataJSON; 146 // UTF-8 encoded JSON serialization of the client data. 147 _Field_size_bytes_(cbClientDataJSON) 148 PBYTE pbClientDataJSON; 149 150 // Hash algorithm ID used to hash the pbClientDataJSON field. 151 LPCWSTR pwszHashAlgId; 152 } WEBAUTHN_CLIENT_DATA, *PWEBAUTHN_CLIENT_DATA; 153 typedef const WEBAUTHN_CLIENT_DATA *PCWEBAUTHN_CLIENT_DATA; 154 155 //+------------------------------------------------------------------------------------------ 156 // Information about credential parameters. 157 //------------------------------------------------------------------------------------------- 158 159 #define WEBAUTHN_CREDENTIAL_TYPE_PUBLIC_KEY L"public-key" 160 161 #define WEBAUTHN_COSE_ALGORITHM_ECDSA_P256_WITH_SHA256 -7 162 #define WEBAUTHN_COSE_ALGORITHM_ECDSA_P384_WITH_SHA384 -35 163 #define WEBAUTHN_COSE_ALGORITHM_ECDSA_P521_WITH_SHA512 -36 164 165 #define WEBAUTHN_COSE_ALGORITHM_RSASSA_PKCS1_V1_5_WITH_SHA256 -257 166 #define WEBAUTHN_COSE_ALGORITHM_RSASSA_PKCS1_V1_5_WITH_SHA384 -258 167 #define WEBAUTHN_COSE_ALGORITHM_RSASSA_PKCS1_V1_5_WITH_SHA512 -259 168 169 #define WEBAUTHN_COSE_ALGORITHM_RSA_PSS_WITH_SHA256 -37 170 #define WEBAUTHN_COSE_ALGORITHM_RSA_PSS_WITH_SHA384 -38 171 #define WEBAUTHN_COSE_ALGORITHM_RSA_PSS_WITH_SHA512 -39 172 173 #define WEBAUTHN_COSE_CREDENTIAL_PARAMETER_CURRENT_VERSION 1 174 175 typedef struct _WEBAUTHN_COSE_CREDENTIAL_PARAMETER { 176 // Version of this structure, to allow for modifications in the future. 177 DWORD dwVersion; 178 179 // Well-known credential type specifying a credential to create. 180 LPCWSTR pwszCredentialType; 181 182 // Well-known COSE algorithm specifying the algorithm to use for the credential. 183 LONG lAlg; 184 } WEBAUTHN_COSE_CREDENTIAL_PARAMETER, *PWEBAUTHN_COSE_CREDENTIAL_PARAMETER; 185 typedef const WEBAUTHN_COSE_CREDENTIAL_PARAMETER *PCWEBAUTHN_COSE_CREDENTIAL_PARAMETER; 186 187 typedef struct _WEBAUTHN_COSE_CREDENTIAL_PARAMETERS { 188 DWORD cCredentialParameters; 189 _Field_size_(cCredentialParameters) 190 PWEBAUTHN_COSE_CREDENTIAL_PARAMETER pCredentialParameters; 191 } WEBAUTHN_COSE_CREDENTIAL_PARAMETERS, *PWEBAUTHN_COSE_CREDENTIAL_PARAMETERS; 192 typedef const WEBAUTHN_COSE_CREDENTIAL_PARAMETERS *PCWEBAUTHN_COSE_CREDENTIAL_PARAMETERS; 193 194 //+------------------------------------------------------------------------------------------ 195 // Information about credential. 196 //------------------------------------------------------------------------------------------- 197 #define WEBAUTHN_CREDENTIAL_CURRENT_VERSION 1 198 199 typedef struct _WEBAUTHN_CREDENTIAL { 200 // Version of this structure, to allow for modifications in the future. 201 DWORD dwVersion; 202 203 // Size of pbID. 204 DWORD cbId; 205 // Unique ID for this particular credential. 206 _Field_size_bytes_(cbId) 207 PBYTE pbId; 208 209 // Well-known credential type specifying what this particular credential is. 210 LPCWSTR pwszCredentialType; 211 } WEBAUTHN_CREDENTIAL, *PWEBAUTHN_CREDENTIAL; 212 typedef const WEBAUTHN_CREDENTIAL *PCWEBAUTHN_CREDENTIAL; 213 214 typedef struct _WEBAUTHN_CREDENTIALS { 215 DWORD cCredentials; 216 _Field_size_(cCredentials) 217 PWEBAUTHN_CREDENTIAL pCredentials; 218 } WEBAUTHN_CREDENTIALS, *PWEBAUTHN_CREDENTIALS; 219 typedef const WEBAUTHN_CREDENTIALS *PCWEBAUTHN_CREDENTIALS; 220 221 //+------------------------------------------------------------------------------------------ 222 // Information about credential with extra information, such as, dwTransports 223 //------------------------------------------------------------------------------------------- 224 225 #define WEBAUTHN_CTAP_TRANSPORT_USB 0x00000001 226 #define WEBAUTHN_CTAP_TRANSPORT_NFC 0x00000002 227 #define WEBAUTHN_CTAP_TRANSPORT_BLE 0x00000004 228 #define WEBAUTHN_CTAP_TRANSPORT_TEST 0x00000008 229 #define WEBAUTHN_CTAP_TRANSPORT_INTERNAL 0x00000010 230 #define WEBAUTHN_CTAP_TRANSPORT_FLAGS_MASK 0x0000001F 231 232 #define WEBAUTHN_CREDENTIAL_EX_CURRENT_VERSION 1 233 234 typedef struct _WEBAUTHN_CREDENTIAL_EX { 235 // Version of this structure, to allow for modifications in the future. 236 DWORD dwVersion; 237 238 // Size of pbID. 239 DWORD cbId; 240 // Unique ID for this particular credential. 241 _Field_size_bytes_(cbId) 242 PBYTE pbId; 243 244 // Well-known credential type specifying what this particular credential is. 245 LPCWSTR pwszCredentialType; 246 247 // Transports. 0 implies no transport restrictions. 248 DWORD dwTransports; 249 } WEBAUTHN_CREDENTIAL_EX, *PWEBAUTHN_CREDENTIAL_EX; 250 typedef const WEBAUTHN_CREDENTIAL_EX *PCWEBAUTHN_CREDENTIAL_EX; 251 252 //+------------------------------------------------------------------------------------------ 253 // Information about credential list with extra information 254 //------------------------------------------------------------------------------------------- 255 256 typedef struct _WEBAUTHN_CREDENTIAL_LIST { 257 DWORD cCredentials; 258 _Field_size_(cCredentials) 259 PWEBAUTHN_CREDENTIAL_EX *ppCredentials; 260 } WEBAUTHN_CREDENTIAL_LIST, *PWEBAUTHN_CREDENTIAL_LIST; 261 typedef const WEBAUTHN_CREDENTIAL_LIST *PCWEBAUTHN_CREDENTIAL_LIST; 262 263 //+------------------------------------------------------------------------------------------ 264 // Hmac-Secret extension 265 //------------------------------------------------------------------------------------------- 266 267 #define WEBAUTHN_EXTENSIONS_IDENTIFIER_HMAC_SECRET L"hmac-secret" 268 // Below type definitions is for WEBAUTHN_EXTENSIONS_IDENTIFIER_HMAC_SECRET 269 // MakeCredential Input Type: BOOL. 270 // - pvExtension must point to a BOOL with the value TRUE. 271 // - cbExtension must contain the sizeof(BOOL). 272 // MakeCredential Output Type: BOOL. 273 // - pvExtension will point to a BOOL with the value TRUE if credential 274 // was successfully created with HMAC_SECRET. 275 // - cbExtension will contain the sizeof(BOOL). 276 // GetAssertion Input Type: Not Supported 277 // GetAssertion Output Type: Not Supported 278 279 //+------------------------------------------------------------------------------------------ 280 // credProtect extension 281 //------------------------------------------------------------------------------------------- 282 283 #define WEBAUTHN_USER_VERIFICATION_ANY 0 284 #define WEBAUTHN_USER_VERIFICATION_OPTIONAL 1 285 #define WEBAUTHN_USER_VERIFICATION_OPTIONAL_WITH_CREDENTIAL_ID_LIST 2 286 #define WEBAUTHN_USER_VERIFICATION_REQUIRED 3 287 288 typedef struct _WEBAUTHN_CRED_PROTECT_EXTENSION_IN { 289 // One of the above WEBAUTHN_USER_VERIFICATION_* values 290 DWORD dwCredProtect; 291 // Set the following to TRUE to require authenticator support for the 292 // credProtect extension 293 BOOL bRequireCredProtect; 294 } WEBAUTHN_CRED_PROTECT_EXTENSION_IN, *PWEBAUTHN_CRED_PROTECT_EXTENSION_IN; 295 typedef const WEBAUTHN_CRED_PROTECT_EXTENSION_IN* 296 PCWEBAUTHN_CRED_PROTECT_EXTENSION_IN; 297 298 #define WEBAUTHN_EXTENSIONS_IDENTIFIER_CRED_PROTECT L"credProtect" 299 // Below type definitions is for WEBAUTHN_EXTENSIONS_IDENTIFIER_CRED_PROTECT 300 // MakeCredential Input Type: WEBAUTHN_CRED_PROTECT_EXTENSION_IN. 301 // - pvExtension must point to a WEBAUTHN_CRED_PROTECT_EXTENSION_IN struct 302 // - cbExtension will contain the 303 // sizeof(WEBAUTHN_CRED_PROTECT_EXTENSION_IN). 304 // MakeCredential Output Type: DWORD. 305 // - pvExtension will point to a DWORD with one of the above 306 // WEBAUTHN_USER_VERIFICATION_* values 307 // if credential was successfully created with CRED_PROTECT. 308 // - cbExtension will contain the sizeof(DWORD). 309 // GetAssertion Input Type: Not Supported 310 // GetAssertion Output Type: Not Supported 311 312 //+------------------------------------------------------------------------------------------ 313 // Information about Extensions. 314 //------------------------------------------------------------------------------------------- 315 typedef struct _WEBAUTHN_EXTENSION { 316 LPCWSTR pwszExtensionIdentifier; 317 DWORD cbExtension; 318 PVOID pvExtension; 319 } WEBAUTHN_EXTENSION, *PWEBAUTHN_EXTENSION; 320 typedef const WEBAUTHN_EXTENSION *PCWEBAUTHN_EXTENSION; 321 322 typedef struct _WEBAUTHN_EXTENSIONS { 323 DWORD cExtensions; 324 _Field_size_(cExtensions) 325 PWEBAUTHN_EXTENSION pExtensions; 326 } WEBAUTHN_EXTENSIONS, *PWEBAUTHN_EXTENSIONS; 327 typedef const WEBAUTHN_EXTENSIONS *PCWEBAUTHN_EXTENSIONS; 328 329 //+------------------------------------------------------------------------------------------ 330 // Options. 331 //------------------------------------------------------------------------------------------- 332 333 #define WEBAUTHN_AUTHENTICATOR_ATTACHMENT_ANY 0 334 #define WEBAUTHN_AUTHENTICATOR_ATTACHMENT_PLATFORM 1 335 #define WEBAUTHN_AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM 2 336 #define WEBAUTHN_AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM_U2F_V2 3 337 338 #define WEBAUTHN_USER_VERIFICATION_REQUIREMENT_ANY 0 339 #define WEBAUTHN_USER_VERIFICATION_REQUIREMENT_REQUIRED 1 340 #define WEBAUTHN_USER_VERIFICATION_REQUIREMENT_PREFERRED 2 341 #define WEBAUTHN_USER_VERIFICATION_REQUIREMENT_DISCOURAGED 3 342 343 #define WEBAUTHN_ATTESTATION_CONVEYANCE_PREFERENCE_ANY 0 344 #define WEBAUTHN_ATTESTATION_CONVEYANCE_PREFERENCE_NONE 1 345 #define WEBAUTHN_ATTESTATION_CONVEYANCE_PREFERENCE_INDIRECT 2 346 #define WEBAUTHN_ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT 3 347 348 #define WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS_VERSION_1 1 349 #define WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS_VERSION_2 2 350 #define WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS_VERSION_3 3 351 #define WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS_CURRENT_VERSION WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS_VERSION_3 352 353 typedef struct _WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS { 354 // Version of this structure, to allow for modifications in the future. 355 DWORD dwVersion; 356 357 // Time that the operation is expected to complete within. 358 // This is used as guidance, and can be overridden by the platform. 359 DWORD dwTimeoutMilliseconds; 360 361 // Credentials used for exclusion. 362 WEBAUTHN_CREDENTIALS CredentialList; 363 364 // Optional extensions to parse when performing the operation. 365 WEBAUTHN_EXTENSIONS Extensions; 366 367 // Optional. Platform vs Cross-Platform Authenticators. 368 DWORD dwAuthenticatorAttachment; 369 370 // Optional. Require key to be resident or not. Defaulting to FALSE; 371 BOOL bRequireResidentKey; 372 373 // User Verification Requirement. 374 DWORD dwUserVerificationRequirement; 375 376 // Attestation Conveyance Preference. 377 DWORD dwAttestationConveyancePreference; 378 379 // Reserved for future Use 380 DWORD dwFlags; 381 382 // 383 // The following fields have been added in WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS_VERSION_2 384 // 385 386 // Cancellation Id - Optional - See WebAuthNGetCancellationId 387 GUID *pCancellationId; 388 389 // 390 // The following fields have been added in WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS_VERSION_3 391 // 392 393 // Exclude Credential List. If present, "CredentialList" will be ignored. 394 PWEBAUTHN_CREDENTIAL_LIST pExcludeCredentialList; 395 396 } WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS, *PWEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS; 397 typedef const WEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS *PCWEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS; 398 399 400 #define WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_1 1 401 #define WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_2 2 402 #define WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_3 3 403 #define WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_4 4 404 #define WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_CURRENT_VERSION WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_4 405 406 typedef struct _WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS { 407 // Version of this structure, to allow for modifications in the future. 408 DWORD dwVersion; 409 410 // Time that the operation is expected to complete within. 411 // This is used as guidance, and can be overridden by the platform. 412 DWORD dwTimeoutMilliseconds; 413 414 // Allowed Credentials List. 415 WEBAUTHN_CREDENTIALS CredentialList; 416 417 // Optional extensions to parse when performing the operation. 418 WEBAUTHN_EXTENSIONS Extensions; 419 420 // Optional. Platform vs Cross-Platform Authenticators. 421 DWORD dwAuthenticatorAttachment; 422 423 // User Verification Requirement. 424 DWORD dwUserVerificationRequirement; 425 426 // Reserved for future Use 427 DWORD dwFlags; 428 429 // 430 // The following fields have been added in WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_2 431 // 432 433 // Optional identifier for the U2F AppId. Converted to UTF8 before being hashed. Not lower cased. 434 PCWSTR pwszU2fAppId; 435 436 // If the following is non-NULL, then, set to TRUE if the above pwszU2fAppid was used instead of 437 // PCWSTR pwszRpId; 438 BOOL *pbU2fAppId; 439 440 // 441 // The following fields have been added in WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_3 442 // 443 444 // Cancellation Id - Optional - See WebAuthNGetCancellationId 445 GUID *pCancellationId; 446 447 // 448 // The following fields have been added in WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS_VERSION_4 449 // 450 451 // Allow Credential List. If present, "CredentialList" will be ignored. 452 PWEBAUTHN_CREDENTIAL_LIST pAllowCredentialList; 453 454 } WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS, *PWEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS; 455 typedef const WEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS *PCWEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS; 456 457 458 //+------------------------------------------------------------------------------------------ 459 // Attestation Info. 460 // 461 //------------------------------------------------------------------------------------------- 462 #define WEBAUTHN_ATTESTATION_DECODE_NONE 0 463 #define WEBAUTHN_ATTESTATION_DECODE_COMMON 1 464 // WEBAUTHN_ATTESTATION_DECODE_COMMON supports format types 465 // L"packed" 466 // L"fido-u2f" 467 468 #define WEBAUTHN_ATTESTATION_VER_TPM_2_0 L"2.0" 469 470 typedef struct _WEBAUTHN_X5C { 471 // Length of X.509 encoded certificate 472 DWORD cbData; 473 // X.509 encoded certificate bytes 474 _Field_size_bytes_(cbData) 475 PBYTE pbData; 476 } WEBAUTHN_X5C, *PWEBAUTHN_X5C; 477 478 // Supports either Self or Full Basic Attestation 479 480 // Note, new fields will be added to the following data structure to 481 // support additional attestation format types, such as, TPM. 482 // When fields are added, the dwVersion will be incremented. 483 // 484 // Therefore, your code must make the following check: 485 // "if (dwVersion >= WEBAUTHN_COMMON_ATTESTATION_CURRENT_VERSION)" 486 487 #define WEBAUTHN_COMMON_ATTESTATION_CURRENT_VERSION 1 488 489 typedef struct _WEBAUTHN_COMMON_ATTESTATION { 490 // Version of this structure, to allow for modifications in the future. 491 DWORD dwVersion; 492 493 // Hash and Padding Algorithm 494 // 495 // The following won't be set for "fido-u2f" which assumes "ES256". 496 PCWSTR pwszAlg; 497 LONG lAlg; // COSE algorithm 498 499 // Signature that was generated for this attestation. 500 DWORD cbSignature; 501 _Field_size_bytes_(cbSignature) 502 PBYTE pbSignature; 503 504 // Following is set for Full Basic Attestation. If not, set then, this is Self Attestation. 505 // Array of X.509 DER encoded certificates. The first certificate is the signer, leaf certificate. 506 DWORD cX5c; 507 _Field_size_(cX5c) 508 PWEBAUTHN_X5C pX5c; 509 510 // Following are also set for tpm 511 PCWSTR pwszVer; // L"2.0" 512 DWORD cbCertInfo; 513 _Field_size_bytes_(cbCertInfo) 514 PBYTE pbCertInfo; 515 DWORD cbPubArea; 516 _Field_size_bytes_(cbPubArea) 517 PBYTE pbPubArea; 518 } WEBAUTHN_COMMON_ATTESTATION, *PWEBAUTHN_COMMON_ATTESTATION; 519 typedef const WEBAUTHN_COMMON_ATTESTATION *PCWEBAUTHN_COMMON_ATTESTATION; 520 521 #define WEBAUTHN_ATTESTATION_TYPE_PACKED L"packed" 522 #define WEBAUTHN_ATTESTATION_TYPE_U2F L"fido-u2f" 523 #define WEBAUTHN_ATTESTATION_TYPE_TPM L"tpm" 524 #define WEBAUTHN_ATTESTATION_TYPE_NONE L"none" 525 526 #define WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_1 1 527 #define WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_2 2 528 #define WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_3 3 529 #define WEBAUTHN_CREDENTIAL_ATTESTATION_CURRENT_VERSION WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_3 530 531 typedef struct _WEBAUTHN_CREDENTIAL_ATTESTATION { 532 // Version of this structure, to allow for modifications in the future. 533 DWORD dwVersion; 534 535 // Attestation format type 536 PCWSTR pwszFormatType; 537 538 // Size of cbAuthenticatorData. 539 DWORD cbAuthenticatorData; 540 // Authenticator data that was created for this credential. 541 _Field_size_bytes_(cbAuthenticatorData) 542 PBYTE pbAuthenticatorData; 543 544 // Size of CBOR encoded attestation information 545 //0 => encoded as CBOR null value. 546 DWORD cbAttestation; 547 //Encoded CBOR attestation information 548 _Field_size_bytes_(cbAttestation) 549 PBYTE pbAttestation; 550 551 DWORD dwAttestationDecodeType; 552 // Following depends on the dwAttestationDecodeType 553 // WEBAUTHN_ATTESTATION_DECODE_NONE 554 // NULL - not able to decode the CBOR attestation information 555 // WEBAUTHN_ATTESTATION_DECODE_COMMON 556 // PWEBAUTHN_COMMON_ATTESTATION; 557 PVOID pvAttestationDecode; 558 559 // The CBOR encoded Attestation Object to be returned to the RP. 560 DWORD cbAttestationObject; 561 _Field_size_bytes_(cbAttestationObject) 562 PBYTE pbAttestationObject; 563 564 // The CredentialId bytes extracted from the Authenticator Data. 565 // Used by Edge to return to the RP. 566 DWORD cbCredentialId; 567 _Field_size_bytes_(cbCredentialId) 568 PBYTE pbCredentialId; 569 570 // 571 // Following fields have been added in WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_2 572 // 573 574 WEBAUTHN_EXTENSIONS Extensions; 575 576 // 577 // Following fields have been added in WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_3 578 // 579 580 // One of the WEBAUTHN_CTAP_TRANSPORT_* bits will be set corresponding to 581 // the transport that was used. 582 DWORD dwUsedTransport; 583 584 } WEBAUTHN_CREDENTIAL_ATTESTATION, *PWEBAUTHN_CREDENTIAL_ATTESTATION; 585 typedef const WEBAUTHN_CREDENTIAL_ATTESTATION *PCWEBAUTHN_CREDENTIAL_ATTESTATION; 586 587 588 //+------------------------------------------------------------------------------------------ 589 // authenticatorGetAssertion output. 590 //------------------------------------------------------------------------------------------- 591 592 #define WEBAUTHN_ASSERTION_CURRENT_VERSION 1 593 594 typedef struct _WEBAUTHN_ASSERTION { 595 // Version of this structure, to allow for modifications in the future. 596 DWORD dwVersion; 597 598 // Size of cbAuthenticatorData. 599 DWORD cbAuthenticatorData; 600 // Authenticator data that was created for this assertion. 601 _Field_size_bytes_(cbAuthenticatorData) 602 PBYTE pbAuthenticatorData; 603 604 // Size of pbSignature. 605 DWORD cbSignature; 606 // Signature that was generated for this assertion. 607 _Field_size_bytes_(cbSignature) 608 PBYTE pbSignature; 609 610 // Credential that was used for this assertion. 611 WEBAUTHN_CREDENTIAL Credential; 612 613 // Size of User Id 614 DWORD cbUserId; 615 // UserId 616 _Field_size_bytes_(cbUserId) 617 PBYTE pbUserId; 618 } WEBAUTHN_ASSERTION, *PWEBAUTHN_ASSERTION; 619 typedef const WEBAUTHN_ASSERTION *PCWEBAUTHN_ASSERTION; 620 621 //+------------------------------------------------------------------------------------------ 622 // APIs. 623 //------------------------------------------------------------------------------------------- 624 625 DWORD 626 WINAPI 627 WebAuthNGetApiVersionNumber(); 628 629 HRESULT 630 WINAPI 631 WebAuthNIsUserVerifyingPlatformAuthenticatorAvailable( 632 _Out_ BOOL *pbIsUserVerifyingPlatformAuthenticatorAvailable); 633 634 635 HRESULT 636 WINAPI 637 WebAuthNAuthenticatorMakeCredential( 638 _In_ HWND hWnd, 639 _In_ PCWEBAUTHN_RP_ENTITY_INFORMATION pRpInformation, 640 _In_ PCWEBAUTHN_USER_ENTITY_INFORMATION pUserInformation, 641 _In_ PCWEBAUTHN_COSE_CREDENTIAL_PARAMETERS pPubKeyCredParams, 642 _In_ PCWEBAUTHN_CLIENT_DATA pWebAuthNClientData, 643 _In_opt_ PCWEBAUTHN_AUTHENTICATOR_MAKE_CREDENTIAL_OPTIONS pWebAuthNMakeCredentialOptions, 644 _Outptr_result_maybenull_ PWEBAUTHN_CREDENTIAL_ATTESTATION *ppWebAuthNCredentialAttestation); 645 646 647 HRESULT 648 WINAPI 649 WebAuthNAuthenticatorGetAssertion( 650 _In_ HWND hWnd, 651 _In_ LPCWSTR pwszRpId, 652 _In_ PCWEBAUTHN_CLIENT_DATA pWebAuthNClientData, 653 _In_opt_ PCWEBAUTHN_AUTHENTICATOR_GET_ASSERTION_OPTIONS pWebAuthNGetAssertionOptions, 654 _Outptr_result_maybenull_ PWEBAUTHN_ASSERTION *ppWebAuthNAssertion); 655 656 void 657 WINAPI 658 WebAuthNFreeCredentialAttestation( 659 _In_opt_ PWEBAUTHN_CREDENTIAL_ATTESTATION pWebAuthNCredentialAttestation); 660 661 void 662 WINAPI 663 WebAuthNFreeAssertion( 664 _In_ PWEBAUTHN_ASSERTION pWebAuthNAssertion); 665 666 HRESULT 667 WINAPI 668 WebAuthNGetCancellationId( 669 _Out_ GUID* pCancellationId); 670 671 HRESULT 672 WINAPI 673 WebAuthNCancelCurrentOperation( 674 _In_ const GUID* pCancellationId); 675 676 // 677 // Returns the following Error Names: 678 // L"Success" - S_OK 679 // L"InvalidStateError" - NTE_EXISTS 680 // L"ConstraintError" - HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED), 681 // NTE_NOT_SUPPORTED, 682 // NTE_TOKEN_KEYSET_STORAGE_FULL 683 // L"NotSupportedError" - NTE_INVALID_PARAMETER 684 // L"NotAllowedError" - NTE_DEVICE_NOT_FOUND, 685 // NTE_NOT_FOUND, 686 // HRESULT_FROM_WIN32(ERROR_CANCELLED), 687 // NTE_USER_CANCELLED, 688 // HRESULT_FROM_WIN32(ERROR_TIMEOUT) 689 // L"UnknownError" - All other hr values 690 // 691 PCWSTR 692 WINAPI 693 WebAuthNGetErrorName( 694 _In_ HRESULT hr); 695 696 HRESULT 697 WINAPI 698 WebAuthNGetW3CExceptionDOMError( 699 _In_ HRESULT hr); 700 701 702 #ifdef __cplusplus 703 } // Balance extern "C" above 704 #endif 705 706 #endif // WINAPI_FAMILY_PARTITION 707 #pragma endregion 708 709 #endif // __WEBAUTHN_H_ 710