Windows.System.Profile: add Remarks to HardwareToken, SystemIdentification, AnalyticsVersionInfo, HardwareIdentification

windows.system.profile/analyticsversioninfo_devicefamily.md

@@ -16,8 +16,23 @@ Gets a string that represents the type of device the application is running on.
 The device family.
 
 ## -remarks
-The values of this property will change over time as new device families are released. You should not depend on the value of this property, it is intended for analytics use only. For example, you could prioritize marketing activities based on data that more of your customers are using one device-family versus another device-family.
+The values of this property may change over time as new device families are introduced. You should not use this property to make runtime decisions; it is intended for analytics use only. For example, you could prioritize marketing activities based on data showing which device family the majority of your customers use.
+
+The following values are currently defined:
+
+| Value | Device family |
+|-------|---------------|
+| `Windows.Desktop` | Desktop PCs and tablets |
+| `Windows.Holographic` | Mixed-reality headsets (HoloLens) |
+| `Windows.IoT` | IoT devices |
+| `Windows.Mobile` | Mobile devices (deprecated) |
+| `Windows.Team` | Surface Hub |
+| `Windows.Universal` | Universal (all devices) |
+| `Windows.Xbox` | Xbox consoles |
+
+For more information about device families, see [Device families overview](/uwp/extension-sdks/device-families-overview).
 
 ## -examples
 
 ## -see-also
+[Device families overview](/uwp/extension-sdks/device-families-overview)

windows.system.profile/hardwareidentification.md

@@ -13,7 +13,11 @@ public class HardwareIdentification
 Provides the ability to obtain a hardware identifier that represents the current hardware.
 
 ## -remarks
-See [Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10)) for more information.
+The Application Specific Hardware ID (ASHWID) encodes characteristics of up to nine hardware component types: processor, memory, disk device, network adapter, audio adapter, docking station, mobile broadband, Bluetooth, and system BIOS. The byte stream uses 4-byte groups where the first 2 bytes identify the component type and the next 2 bytes contain its value.
+
+The ASHWID **can contain multiple records of the same component type**. For example, a device with three physical disk drives produces three disk-device records; a docked tablet may produce additional network adapter and audio adapter records. Your cloud service should account for this variation when comparing ASHWIDs across sessions.
+
+The ASHWID format is described in detail in [Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10)).
 
 <!-- confirmed -->
 > [!NOTE]
@@ -78,4 +82,4 @@ Dim certificate As Windows.Storage.Streams.IBuffer = packageSpecificToken.Certif
 ```
 
 ## -see-also
-[Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10))
+[Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10))

windows.system.profile/hardwaretoken_certificate.md

@@ -16,7 +16,13 @@ Gets the certificate that is used to sign the [Id](hardwaretoken_id.md) and is u
 The certificate used to sign the [Id](hardwaretoken_id.md).
 
 ## -remarks
+The buffer contains a **PKCS#7 formatted certificate chain**, not a single certificate. The chain is rooted at the *Microsoft Assurance Designation Root 2011* certificate. The leaf certificate carries the extended key usage (EKU) OID `1.3.6.1.4.1.311.10.5.40`.
+
+When validating this chain in a cloud service, enable revocation checking for all certificates in the chain. The *Microsoft Assurance Designation Root 2011* root certificate must be present in the trusted root store on the server.
+
+For the full cloud-side verification workflow, see [Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10)).
 
 ## -examples
 
 ## -see-also
+[HardwareToken.Signature](hardwaretoken_signature.md), [HardwareToken.Id](hardwaretoken_id.md), [Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10))

windows.system.profile/hardwaretoken_signature.md

@@ -16,7 +16,13 @@ Gets the digital signature of hardware [Id](hardwaretoken_id.md) that helps veri
 The digital signature of [Id](hardwaretoken_id.md).
 
 ## -remarks
+The signature allows a cloud service to verify that the [Id](hardwaretoken_id.md) was genuinely generated by Windows and has not been tampered with. Verification uses the public key from the [Certificate](hardwaretoken_certificate.md) property.
+
+If a nonce was passed to [HardwareIdentification.GetPackageSpecificToken](hardwareidentification_getpackagespecifictoken_1192424865.md), the nonce is incorporated into the signed data. This allows the cloud service to confirm the freshness of the response and guard against replay attacks.
+
+For the full cloud-side verification workflow, including certificate chain validation and revocation checking, see [Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10)).
 
 ## -examples
 
 ## -see-also
+[HardwareToken.Certificate](hardwaretoken_certificate.md), [HardwareToken.Id](hardwaretoken_id.md), [Guidance on using the App Specific Hardware ID (ASHWID) to implement per-device app logic](/previous-versions/windows/apps/jj553431(v=win.10))

windows.system.profile/systemidentification_getsystemidforuser_459524648.md

@@ -20,14 +20,16 @@ The [User](../windows.system/user.md) data to use for creating the system ID. If
 A [SystemIdentificationInfo](systemidentificationinfo.md) object for this system, based on the user ID.
 
 ## -remarks
-The identifier returned by this method is specific to a user on the current device and allows for correlation of usage across different applications running on the same device for a particular user. Apps that are not multi-user-aware should only pass `null` into this method, which gets the current user's ID. 
+The identifier returned by this method is specific to a user on the current device and allows for correlation of usage across different applications running on the same device for a particular user. Apps that are not multi-user-aware should only pass `null` into this method, which gets the current user's ID.
 
 Use of this method is restricted by the **userSystemId** capability, which is a restricted capability requiring Microsoft approval. Please note that most callers should instead use the [Windows.System.Profile.SystemIdentification.GetSystemIdForPublisher](systemidentification_getsystemidforpublisher_728928815.md) method instead as it is more appropriate for the large majority of use cases and does not require a restricted capability. If you do not need to obtain an ID that is shared across apps built by different publishers, you should not use this method.
 
+> [!NOTE]
+> This method returns a hardware-based identifier intended for device correlation. To access the properties of the current user (such as display name or account name), use [Windows.System.User.GetDefault](../windows.system/user_getdefault_846721868.md) (available from Windows 10, version 2104) instead.
+
 ## -examples
 
 ## -see-also
 
-
 ## -capabilities
 userSystemId