From c0c65015f92c30b79dc2164de97ce872cff49fb6 Mon Sep 17 00:00:00 2001 From: Isaiah Inuwa Date: Fri, 20 Feb 2026 10:55:55 -0600 Subject: [PATCH] Copy documentation comments from header files --- .../win_webauthn/src/plugin/types.rs | 72 ++++++++++++++++--- .../win_webauthn/src/types/mod.rs | 24 ++++--- 2 files changed, 77 insertions(+), 19 deletions(-) diff --git a/apps/desktop/desktop_native/win_webauthn/src/plugin/types.rs b/apps/desktop/desktop_native/win_webauthn/src/plugin/types.rs index 2d954271b93..482b09464f7 100644 --- a/apps/desktop/desktop_native/win_webauthn/src/plugin/types.rs +++ b/apps/desktop/desktop_native/win_webauthn/src/plugin/types.rs @@ -34,12 +34,13 @@ use crate::{ #[repr(C)] #[derive(Debug, Copy, Clone)] pub struct WEBAUTHN_CTAPCBOR_AUTHENTICATOR_OPTIONS { + /// Version of this structure, to allow for modifications in the future. dwVersion: u32, - // LONG lUp: +1=TRUE, 0=Not defined, -1=FALSE + /// "up" option: +1=TRUE, 0=Not defined, -1=FALSE lUp: i32, - // LONG lUv: +1=TRUE, 0=Not defined, -1=FALSE + /// "uv" option: +1=TRUE, 0=Not defined, -1=FALSE lUv: i32, - // LONG lRequireResidentKey: +1=TRUE, 0=Not defined, -1=FALSE + /// "rk" option: +1=TRUE, 0=Not defined, -1=FALSE lRequireResidentKey: i32, } @@ -98,10 +99,12 @@ pub(super) struct WEBAUTHN_PLUGIN_ADD_AUTHENTICATOR_OPTIONS { /// The data should be encoded as `UTF16(BASE64(UTF8(svg_text)))`. pub(super) pwszDarkThemeLogoSvg: *const u16, + /// CTAP CBOR-encoded authenticatorGetInfo response (size) pub(super) cbAuthenticatorInfo: u32, /// CTAP CBOR-encoded authenticatorGetInfo output pub(super) pbAuthenticatorInfo: *const u8, + /// Count of supported RP IDs pub(super) cSupportedRpIds: u32, /// List of supported RP IDs (Relying Party IDs). /// @@ -250,13 +253,21 @@ fn webauthn_plugin_free_add_authenticator_response( #[repr(C)] #[derive(Debug, Copy, Clone)] pub(super) struct WEBAUTHN_PLUGIN_CREDENTIAL_DETAILS { + /// Credential Identifier bytes (size) pub credential_id_byte_count: u32, + /// Credential Identifier bytes (data, required) pub credential_id_pointer: *const u8, + /// Identifier for the RP (required) pub rpid: *const u16, + /// Friendly name of the Relying Party (required) pub rp_friendly_name: *const u16, + /// User Identifier bytes (size) pub user_id_byte_count: u32, + /// User Identifier bytes (data, required) pub user_id_pointer: *const u8, + /// Detailed account name (e.g., "john.p.smith@example.com") pub user_name: *const u16, + /// Friendly name for the user account (e.g., "John P. Smith") pub user_display_name: *const u16, } @@ -452,23 +463,37 @@ pub enum WebAuthnPluginRequestType { #[repr(C)] #[derive(Debug, Copy, Clone)] pub(super) struct WEBAUTHN_CTAPCBOR_MAKE_CREDENTIAL_REQUEST { + /// Version of this structure, to allow for modifications in the future. pub dwVersion: u32, + /// Input RP ID size (raw UTF-8 bytes before conversion) pub cbRpId: u32, + /// Input RP ID data (bytes hashed in Authenticator Data) pub pbRpId: *const u8, + /// Client Data Hash size pub cbClientDataHash: u32, + /// Client Data Hash data pub pbClientDataHash: *const u8, + /// RP Information pub pRpInformation: *const WEBAUTHN_RP_ENTITY_INFORMATION, + /// User Information pub pUserInformation: *const WEBAUTHN_USER_ENTITY_INFORMATION, + /// Crypto Parameters pub WebAuthNCredentialParameters: WEBAUTHN_COSE_CREDENTIAL_PARAMETERS, + /// Credentials used for exclusion pub CredentialList: WEBAUTHN_CREDENTIAL_LIST, + /// CBOR extensions map size pub cbCborExtensionsMap: u32, + /// CBOR extensions map data pub pbCborExtensionsMap: *const u8, + /// Authenticator Options (Optional) pub pAuthenticatorOptions: *const WebAuthnCtapCborAuthenticatorOptions, // Pin Auth (Optional) /// Indicates zero length PinAuth is included in the request pub fEmptyPinAuth: BOOL, + /// Pin Auth size pub cbPinAuth: u32, + /// Pin Auth data pub pbPinAuth: *const u8, /// "hmac-secret": true extension @@ -479,7 +504,9 @@ pub(super) struct WEBAUTHN_CTAPCBOR_MAKE_CREDENTIAL_REQUEST { /// "prf" extension pub lPrfExt: i32, + /// HMAC secret salt values size pub cbHmacSecretSaltValues: u32, + /// HMAC secret salt values data pub pbHmacSecretSaltValues: *const u8, /// "credProtect" extension. Nonzero if present @@ -493,6 +520,7 @@ pub(super) struct WEBAUTHN_CTAPCBOR_MAKE_CREDENTIAL_REQUEST { /// "credBlob" extension. Nonzero if present pub cbCredBlobExt: Option, + /// "credBlob" extension data pub pbCredBlobExt: *const u8, /// "largeBlobKey": true extension @@ -506,6 +534,7 @@ pub(super) struct WEBAUTHN_CTAPCBOR_MAKE_CREDENTIAL_REQUEST { /// "json" extension. Nonzero if present pub cbJsonExt: u32, + /// "json" extension data pub pbJsonExt: *const u8, } @@ -948,61 +977,82 @@ pub(super) struct WEBAUTHN_CTAPCBOR_HMAC_SALT_EXTENSION { /// Version of this structure, to allow for modifications in the future. pub _dwVersion: u32, - // Platform's key agreement public key + /// Platform's key agreement public key pub _pKeyAgreement: *const WEBAUTHN_CTAPCBOR_ECC_PUBLIC_KEY, + /// Encrypted salt size pub _cbEncryptedSalt: u32, + /// Encrypted salt data pub _pbEncryptedSalt: *const u8, + /// Salt authentication size pub _cbSaltAuth: u32, + /// Salt authentication data pub _pbSaltAuth: *const u8, } #[repr(C)] #[derive(Debug, Copy, Clone)] pub(super) struct WEBAUTHN_CTAPCBOR_GET_ASSERTION_REQUEST { + /// Version of this structure, to allow for modifications in the future. pub dwVersion: u32, - pub pwszRpId: *const u16, // PCWSTR + /// RP ID (after UTF-8 to Unicode conversion) + pub pwszRpId: *const u16, + /// Input RP ID size (raw UTF-8 bytes before conversion) pub cbRpId: u32, /// Raw UTF-8 bytes before conversion to UTF-16 in pwszRpId. These are the /// bytes to be hashed in the Authenticator Data. pub pbRpId: *const u8, + /// Client Data Hash size pub cbClientDataHash: u32, + /// Client Data Hash data pub pbClientDataHash: *const u8, + /// Credentials used for inclusion pub CredentialList: WEBAUTHN_CREDENTIAL_LIST, + /// CBOR extensions map size pub cbCborExtensionsMap: u32, + /// CBOR extensions map data pub pbCborExtensionsMap: *const u8, + /// Authenticator Options (Optional) pub pAuthenticatorOptions: *const WebAuthnCtapCborAuthenticatorOptions, // Pin Auth (Optional) /// Zero length PinAuth is included in the request pub fEmptyPinAuth: BOOL, + /// Pin Auth size pub cbPinAuth: u32, + /// Pin Auth data pub pbPinAuth: *const u8, - // HMAC Salt Extension (Optional) + /// HMAC Salt Extension (Optional) pub pHmacSaltExtension: *const WEBAUTHN_CTAPCBOR_HMAC_SALT_EXTENSION, - // PRF Extension + /// PRF Extension / HMAC secret salt values size pub cbHmacSecretSaltValues: u32, + /// PRF Extension / HMAC secret salt values data pub pbHmacSecretSaltValues: *const u8, + /// Pin protocol pub dwPinProtocol: u32, - //"credBlob": true extension + /// "credBlob": true extension pub lCredBlobExt: i32, - //"largeBlobKey": true extension + /// "largeBlobKey": true extension pub lLargeBlobKeyExt: i32, - //"largeBlob" extension + /// "largeBlob" extension operation pub dwCredLargeBlobOperation: u32, + /// Large blob compressed size pub cbCredLargeBlobCompressed: u32, + /// Large blob compressed data pub pbCredLargeBlobCompressed: *const u8, + /// Large blob original size pub dwCredLargeBlobOriginalSize: u32, - // "json" extension. Nonzero if present + /// "json" extension size. Nonzero if present pub cbJsonExt: u32, + /// "json" extension data pub pbJsonExt: *const u8, } diff --git a/apps/desktop/desktop_native/win_webauthn/src/types/mod.rs b/apps/desktop/desktop_native/win_webauthn/src/types/mod.rs index 8c5bdeab366..c09822c0e14 100644 --- a/apps/desktop/desktop_native/win_webauthn/src/types/mod.rs +++ b/apps/desktop/desktop_native/win_webauthn/src/types/mod.rs @@ -327,9 +327,12 @@ impl UserEntityInformation<'_> { #[repr(C)] #[derive(Debug, Copy, Clone)] pub struct WEBAUTHN_COSE_CREDENTIAL_PARAMETER { + /// Version of this structure, to allow for modifications in the future. dwVersion: u32, - pwszCredentialType: NonNull, // LPCWSTR - lAlg: i32, // LONG - COSE algorithm identifier + /// Well-known credential type specifying a credential to create. + pwszCredentialType: NonNull, + /// Well-known COSE algorithm specifying the algorithm to use for the credential. + lAlg: i32, } impl WEBAUTHN_COSE_CREDENTIAL_PARAMETER { @@ -443,23 +446,23 @@ pub(crate) struct WEBAUTHN_CREDENTIAL_ATTESTATION { // Following fields have been added in WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_7 pub(crate) pHmacSecret: *const WEBAUTHN_HMAC_SECRET_SALT, - // ThirdPartyPayment Credential or not. + /// ThirdPartyPayment Credential or not. pub(crate) bThirdPartyPayment: BOOL, // // Following fields have been added in WEBAUTHN_CREDENTIAL_ATTESTATION_VERSION_8 // - // Multiple WEBAUTHN_CTAP_TRANSPORT_* bits will be set corresponding to - // the transports that are supported. + /// Multiple WEBAUTHN_CTAP_TRANSPORT_* bits will be set corresponding to + /// the transports that are supported. pub(crate) dwTransports: u32, - // UTF-8 encoded JSON serialization of the client data. + /// UTF-8 encoded JSON serialization of the client data. pub(crate) cbClientDataJSON: u32, // _Field_size_bytes_(cbClientDataJSON) pub(crate) pbClientDataJSON: *const u8, - // UTF-8 encoded JSON serialization of the RegistrationResponse. + /// UTF-8 encoded JSON serialization of the RegistrationResponse. pub(crate) cbRegistrationResponseJSON: u32, // _Field_size_bytes_(cbRegistrationResponseJSON) pub(crate) pbRegistrationResponseJSON: *const u8, @@ -594,10 +597,15 @@ impl TryFrom> for CredentialId { #[repr(C)] #[derive(Debug, Copy, Clone)] pub(crate) struct WEBAUTHN_CREDENTIAL_EX { + /// Version of this structure, to allow for modifications in the future. dwVersion: u32, + /// Size of pbID. cbId: u32, + /// Unique ID for this particular credential. pbId: *const u8, - pwszCredentialType: *const u16, // LPCWSTR + /// Well-known credential type specifying what this particular credential is. + pwszCredentialType: *const u16, + /// Transports. 0 implies no transport restrictions. dwTransports: u32, }