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