Edit

Tutorial: Configure and query HSM operation audit logs for Azure Cloud HSM

Azure Cloud HSM supports HSM operation logging through Azure Monitor diagnostic settings. The HsmOperations log category contains tamper-evident records generated by the HSM firmware for management operations performed on your HSM partitions. Send these records to both a storage account and a Log Analytics workspace for centralized collection, analysis, monitoring, and retention.

HSM operation logging is the recommended logging strategy for security and compliance. It records management operations such as sign-ins, user management, key creation and deletion, key import and export, and backup and restore. The logs are retrieved from each HSM partition in batches, and each batch is signed by the HSM using the partition certificate key. All records from a batch share the same CorrelationId. The exported records also include the corresponding signature for the signed batch and the HSM public certificates, which can be used to verify the integrity and authenticity of the audit trail.

Azure Cloud HSM also provides the HsmServiceOperations event logging category. These service operation logs describe requests observed by the Cloud HSM service and can supplement HSM operation logs for troubleshooting. You can enable both categories in the same diagnostic setting, but use HsmOperations as the primary source for auditing operations recorded by the HSM.

In this tutorial, you:

  • Set up and configure HSM operation logs, including the creation of a storage account and a Log Analytics workspace.
  • Optionally enable service operation logs alongside HSM operation logs.
  • Query HSM operation logs to retrieve specific management operations.
  • Get a comprehensive list of management commands recorded by HSM operation logs.

Important

Diagnostic settings control where logs are exported.

Restrict access to the destination storage account and Log Analytics workspace. HSM operation records can include operational identifiers such as user IDs, session handles, key handles, and operation-specific details.

Prerequisites

Set up and configure HSM operation logs

Use the commands in the following sections to set up the resources that you want to monitor.

Create a storage account to store HSM operation logs

To retain HSM operation logs in a storage account, first create a resource group, and then create the storage account in that resource group.

az group create --name "<resource-group>" --location "<location>"

az storage account create \
  --name "<storage-account-name>" \
  --resource-group "<resource-group>" \
  --location "<location>" \
  --sku Standard_LRS \
  --kind StorageV2

Create a Log Analytics workspace

To create a Log Analytics workspace for storing and analyzing HSM operation logs, use the following command.

az monitor log-analytics workspace create \
  --resource-group "<resource-group>" \
  --workspace-name "<workspace-name>" \
  --location "<location>" \
  --retention-time "<NumOfDays>"

Note

The supported Log Analytics workspace retention time must be at least 30 days.

For more information about creating a Log Analytics workspace for Azure Monitor, see Create a Log Analytics workspace.

Enable diagnostic settings

To export Azure Cloud HSM operation logs, create a diagnostic setting with the HsmOperations category enabled. The following examples send logs to both a storage account and a Log Analytics workspace.

resourceId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.HardwareSecurityModules/cloudHsmClusters/<hsm-name>"

storageAccountId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>"

workspaceId="/subscriptions/<subscription-id>/resourcegroups/<resource-group>/providers/microsoft.operationalinsights/workspaces/<workspace-name>"

az monitor diagnostic-settings create \
  --resource $resourceId \
  --name "my-chsmAuditLogs" \
  --storage-account $storageAccountId \
  --workspace $workspaceId \
  --export-to-resource-specific true \
  --logs '[{"category":"HsmOperations","enabled":true}]'

To also collect service operation logs for troubleshooting, enable HsmServiceOperations alongside HsmOperations.

az monitor diagnostic-settings create \
  --resource $resourceId \
  --name "my-chsmAuditLogs" \
  --storage-account $storageAccountId \
  --workspace $workspaceId \
  --export-to-resource-specific true \
  --logs '[{"category":"HsmOperations","enabled":true},{"category":"HsmServiceOperations","enabled":true}]'

Verify the diagnostic setting

List the diagnostic settings for your Cloud HSM resource and confirm that the setting includes the storage account, Log Analytics workspace, Dedicated destination type, and enabled HsmOperations category. If you enabled service operation logs, also confirm that HsmServiceOperations is enabled.

resourceId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.HardwareSecurityModules/cloudHsmClusters/<hsm-name>"

az monitor diagnostic-settings list \
  --resource $resourceId \
  --output json

Verify the configuration of Cloud HSM operation logging

After you create the diagnostic setting and perform a supported management operation, allow time for the HSM to publish the signed audit batch and for Azure Monitor to ingest it.

Note

After you create a diagnostic setting, logs commonly appear in Log Analytics within several minutes. Azure resource-log ingestion can take approximately 20 minutes under normal conditions, and initial activation of a new diagnostic setting can occasionally take up to 90 minutes. Diagnostic settings don't backfill logs generated before the setting was created.

You can query Cloud HSM operation logs from the Azure portal via the Log Analytics workspace. HSM operation records are stored in the CloudHsmHardwareOperationAuditLogs table. If you also enabled HsmServiceOperations, those records are stored separately in the CloudHsmServiceOperationAuditLogs table.

You can also query Cloud HSM operation event logs by using the Azure CLI or Azure PowerShell.

workspaceCustomerId=$(az monitor log-analytics workspace show \
  --resource-group "<resource-group>" \
  --workspace-name "<workspace-name>" \
  --query customerId --output tsv)

az monitor log-analytics query \
  --workspace $workspaceCustomerId \
  --analytics-query 'CloudHsmHardwareOperationAuditLogs'

Registration error

If you get the error message "<subscription> is not registered to use microsoft.insights," your Azure subscription isn't registered to use the Microsoft.Insights resource provider. To resolve this problem, register the Microsoft.Insights provider in your subscription.

az provider register --namespace Microsoft.Insights

az provider show --namespace Microsoft.Insights --query "registrationState" --output table

After you run the command, ensure that the resource provider is registered. If it's still registering, you might need to wait a few moments and check again.

Query HSM operation logs

Run the following queries in the Log Analytics Logs editor in the Azure portal. To run them from the command line, replace the query text in the Azure CLI --analytics-query parameter or the Azure PowerShell -Query parameter shown in the preceding verification examples.

Use the following queries to retrieve HSM management operations from CloudHsmHardwareOperationAuditLogs. To list all management-operation records, run:

CloudHsmHardwareOperationAuditLogs
| where OperationName startswith "CN_"

The table can also contain signed-batch and certificate records whose operation names start with BATCH_. For details about the batch records and management operations that can appear, refer to the glossary of operations.

Login and session events

// Find login and session events.
CloudHsmHardwareOperationAuditLogs
| where OperationName in (
    "CN_LOGIN",
    "CN_LOGOUT",
    "CN_CLOSE_SESSION",
    "CN_CLOSE_ALL_SESSIONS",
    "CN_CLOSE_PARTITION_SESSIONS"
)
| project TimeGenerated, OperationName, ResultType, UserID, SessionHandle, HsmInstance, SequenceNumber

Events for creating and deleting users

// Find user creation and deletion events.
CloudHsmHardwareOperationAuditLogs
| where OperationName in (
    "CN_CREATE_USER",
    "CN_CREATE_CO",
    "CN_CREATE_APPLIANCE_USER",
    "CN_CREATE_PRE_OFFICER",
    "CN_DELETE_USER"
)
| project TimeGenerated, OperationName, ResultType, UserID, HsmInstance, SequenceNumber, AdditionalInfo

Events for key creation

// Find key creation events.
CloudHsmHardwareOperationAuditLogs
| where OperationName in (
    "CN_GENERATE_KEY",
    "CN_GENERATE_KEY_PAIR",
    "CN_GENERATE_PBE_KEY",
    "CN_GEN_KEY_ENC_KEY",
    "CN_GEN_PSWD_ENC_KEY",
    "CN_DERIVE_KEY"
)
| project TimeGenerated, OperationName, ResultType, UserID, HsmInstance, SequenceNumber, AdditionalInfo

Events for key deletion

// Find key deletion events.
CloudHsmHardwareOperationAuditLogs
| where OperationName in (
    "CN_DESTROY_OBJECT",
    "CN_TOMBSTONE_OBJECT",
    "CN_DELETE_TOMBSTONED_OBJECT"
)
| project TimeGenerated, OperationName, ResultType, UserID, HsmInstance, SequenceNumber, AdditionalInfo

Glossary of operations

HSM operation logging records the following batch records and HSM management commands. Read-only queries and operations that aren't listed here aren't captured in HsmOperations.

Session management

Operation name Description
CN_LOGIN Logs a user in to a partition.
CN_LOGOUT Logs a user out of a partition.
CN_CLOSE_SESSION Closes a specific session.
CN_CLOSE_ALL_SESSIONS Closes all sessions on a partition.
CN_APP_FINALIZE Finalizes an application session, such as PKCS#11 C_Finalize.
CN_CLOSE_PARTITION_SESSIONS Closes all sessions on a specific partition.
CN_ENCRYPT_SESSION Establishes an encrypted session.

Partition lifecycle

Operation name Description
CN_INIT_TOKEN Initializes or formats a partition.
CN_INIT_DONE Marks partition initialization as complete.
CN_ZEROIZE Zeroizes a partition.
CN_VENDOR_ZEROIZE Performs a vendor-specific zeroize operation.
CN_SET_NODEID Sets the partition node ID.
CN_SET_M_VALUE Sets the M value for M-of-N quorum.
CN_SET_POLICY Sets a partition policy.
CN_SET_HSM_CONFIG Sets the HSM hardware configuration.
CN_SET_KBK_PRIMARY Sets the Key Block Key (KBK) primary.
CN_PARTN_STORAGE_UPDATE Updates partition persistent storage.
CN_PARTN_STORAGE_DELETE Deletes a partition persistent-storage record.

User management

Operation name Description
CN_CREATE_USER Creates a Crypto User (CU).
CN_CREATE_CO Creates a Crypto Officer (CO).
CN_CREATE_APPLIANCE_USER Creates an appliance or service user.
CN_CREATE_PRE_OFFICER Creates a pre-officer.
CN_CHANGE_PSWD Changes a user's password or PIN.
CN_RENAME_PCO Renames a pre-officer.
CN_DELETE_USER Deletes a user.
CN_UNLOCK_CO Unlocks a locked-out Crypto Officer.
CN_GET_CHALLENGE_CO Gets a challenge for Crypto Officer unlock.
CN_SET_USER_ATTR Sets user attributes.
CN_UNLOCK_USER Unlocks a locked-out user.
CN_ALWAYS_AUTHORIZE_USER Configures an always-authorize user for M-of-N.
CN_REGISTER_AUTH_PUB_KEY Registers an authentication public key.
CN_SET_AUTH_PUB_KEY Sets an authentication public key.

Key generation

Operation name Description
CN_GENERATE_KEY Generates a symmetric key.
CN_GENERATE_KEY_PAIR Generates an asymmetric key pair.
CN_GENERATE_PBE_KEY Generates a password-based encryption key.
CN_GEN_KEY_ENC_KEY Generates a key-encryption key.
CN_GEN_PSWD_ENC_KEY Generates a password-encryption key.
CN_DERIVE_KEY Derives a key from a base key.

Key wrapping, import, and export

Operation name Description
CN_WRAP_KEY Wraps a key for protected export.
CN_WRAP_KEY2 Wraps a key with extended attributes.
CN_UNWRAP_KEY Unwraps a protected key.
CN_UNWRAP_KEY2 Unwraps a protected key with extended attributes.
CN_NIST_AES_WRAP Performs NIST AES key wrap.
CN_NIST_AES_WRAP_UNWRAP2 Performs NIST AES key wrap or unwrap.
CN_INSERT_MASKED_OBJECT Inserts a masked key object.
CN_EXTRACT_MASKED_OBJECT Extracts a masked key object.
CN_INSERT_MASKED_OBJECT_USER Inserts a masked object with user context.
CN_EXTRACT_MASKED_OBJECT_USER Extracts a masked object with user context.
CN_STORE_KBK_SHARE Stores a KBK share for M-of-N key protection.

Key and object lifecycle

Operation name Description
CN_CREATE_OBJECT Creates a key or data object.
CN_MODIFY_OBJECT Modifies object attributes.
CN_MODIFY_KEY_OWNER Transfers key ownership to another user.
CN_DESTROY_OBJECT Permanently deletes an object.
CN_TOMBSTONE_OBJECT Marks an object as tombstoned for synchronization.
CN_DELETE_TOMBSTONED_OBJECT Permanently removes a tombstoned object.
CN_SHARE_OBJECT Shares a key object with additional users.
CN_PARK_OBJECT Serializes an object for transfer.
CN_UNPARK_OBJECT Deserializes a parked object.

Backup and restore

Operation name Description
CN_BACKUP_BEGIN Begins a backup operation.
CN_BACKUP_CONFIG Backs up the partition configuration.
CN_BACKUP_USERS Backs up the user database.
CN_BACKUP_KEY Backs up keys.
CN_BACKUP_OBJECT Backs up objects.
CN_BACKUP_END Completes and finalizes a backup.
CN_RESTORE_BEGIN Begins a restore operation.
CN_RESTORE_END Completes a restore operation.
CN_CLONE_SOURCE_INIT Initializes a partition as a clone source.
CN_CLONE_TARGET_INIT Initializes a partition as a clone target.
CN_CLONE_SOURCE_STAGE1 Performs clone-source stage 1.
CN_CLONE_TARGET_STAGE1 Performs clone-target stage 1.

M-of-N token operations

Operation name Description
CN_APPROVE_TOKEN Approves an M-of-N authorization token.
CN_GET_TOKEN Retrieves an M-of-N token.
CN_DELETE_TOKEN Deletes an M-of-N token.
CN_TOKEN_TIMEOUT Records an M-of-N token timeout.

Firmware and secure application operations

Operation name Description
CN_SMAPP_DELETE Deletes a secure application.
CN_SMAPP_CTRL Controls a secure application.
CN_SMAPP_UPDATE_BEGIN Begins a secure-application update.
CN_SMAPP_UPDATE Writes secure-application update data.
CN_SMAPP_UPDATE_END Finalizes a secure-application update.
CN_SMAPP_DELETE_FILE Deletes a secure-application file.
CN_SMAPP_WRITE_SFRAM Writes to SFRAM.
CN_SMAPP_READ_SFRAM Reads from SFRAM.
CN_SMAPP_WRITE_DATA Writes secure-application data.
CN_SMAPP_READ_DATA Reads secure-application data.

Batch integrity and certificate records

All records in the same batch share a CorrelationId. Use this value to associate the HSM management-operation records with the corresponding signature and public certificate records.

Operation name Description
BATCH_BINARY_SIGNATURE Contains the HSM-generated signature and SHA-256 hash for the batch. Use the signature and certificate chain to verify the batch's integrity and authenticity.
BATCH_PARTITION_IDENTITY_CERT Contains the partition identity certificate signed by the HSM.
BATCH_HSM_DEVICE_CERT Contains the certificate that identifies the HSM device.
BATCH_HSM_MANUFACTURER_ROOT_CERT Contains the HSM manufacturer root certificate, which is the trust anchor for the HSM certificate chain.
BATCH_HSM_OWNER_AUTH_CERT Contains the HSM Owner Authentication Certificate, which identifies the hardware owner.

Download HSM operation logs for signature verification

Download the HSM operation logs as a JSON file to use them for signature verification. The exported file must contain every record for each included CorrelationId, including the batch signature and certificate records. Don't add take or limit to these queries because doing so can export an incomplete signed batch.

Download logs from the last seven days for a resource

Replace the placeholders with the values for your Cloud HSM resource and Log Analytics workspace. The query identifies batches that have records from the last seven days, and then exports every record for those batches so they remain complete. The _ResourceId filter is case-insensitive.

resourceGroupName="<resource-group>"
workspaceName="<workspace-name>"
resourceId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.HardwareSecurityModules/cloudHsmClusters/<hsm-name>"
outputFile="./logs/CloudHsmOperationLogsLast7Days.json"

mkdir -p ./logs

workspaceCustomerId=$(az monitor log-analytics workspace show \
  --resource-group "$resourceGroupName" \
  --workspace-name "$workspaceName" \
  --query customerId \
  --output tsv)

query=$(cat <<EOF
let recentBatches =
    CloudHsmHardwareOperationAuditLogs
    | where TimeGenerated >= ago(7d)
    | where _ResourceId =~ "$resourceId"
    | distinct CorrelationId;
CloudHsmHardwareOperationAuditLogs
| where _ResourceId =~ "$resourceId"
| where CorrelationId in (recentBatches)
EOF
)

az monitor log-analytics query \
  --workspace "$workspaceCustomerId" \
  --analytics-query "$query" \
  --output json > "$outputFile"

Download all logs for a given correlation ID

Use this query to download one complete signed batch. All records that have the specified CorrelationId are written to the output file, regardless of their order.

resourceGroupName="<resource-group>"
workspaceName="<workspace-name>"
correlationId="<correlation-id>"
outputFile="./logs/CloudHsmOperationLogsByCorrelationId.json"

mkdir -p ./logs

workspaceCustomerId=$(az monitor log-analytics workspace show \
  --resource-group "$resourceGroupName" \
  --workspace-name "$workspaceName" \
  --query customerId \
  --output tsv)

query=$(cat <<EOF
CloudHsmHardwareOperationAuditLogs
| where CorrelationId == "$correlationId"
EOF
)

az monitor log-analytics query \
  --workspace "$workspaceCustomerId" \
  --analytics-query "$query" \
  --output json > "$outputFile"

Next step: Signature verification of the downloaded logs

Use the Azure Cloud HSM audit log utilities to verify the integrity and authenticity of the downloaded HSM operation logs.

  1. Go to the Microsoft Azure Cloud HSM SDK repository.
  2. Open the Utilities folder.
  3. Download the .zip package named AzureCloudHSM-AuditLogUtils.
  4. Extract the package and follow its included instructions to verify the downloaded log file's batch signatures and certificate chain.

Related content

  • Last updated on