Merge pull request #53031 from R-C-Stewart/refresh-security-storage

End to end module refresh

Author: JillGrant615

learn-pr/wwl-azure/security-storage/includes/1-introduction.md

@@ -1,21 +1,21 @@
-This module is designed to provide administrators with the knowledge and skills required to plan and implement comprehensive security measures for Azure storage resources, safeguarding data integrity, confidentiality, and availability.
+This module is designed to provide administrators with the knowledge and skills required to plan and implement comprehensive security measures for Azure storage resources, safeguarding data integrity, confidentiality, and availability. You learn how to apply Zero Trust security principles to Azure Storage. Zero Trust security ensures every access request is verified and that data is protected through multiple layers of defense.
 
 ## Scenario
 
-Imagine you are an Azure storage administrator responsible for managing storage resources in your organization's Azure environment. Your organization relies on Azure storage services for storing sensitive data, and you need to ensure that this data is protected against unauthorized access and data security threats.
+Imagine you're an Azure storage administrator responsible for managing storage resources in your organization's Azure environment. Your organization handles sensitive customer data, financial records, and intellectual property across various Azure storage services. Recent security audits and compliance requirements demand that you implement robust security controls, including identity-based authentication, encryption key management, and data protection policies. You need to ensure that this data is protected against unauthorized access, accidental deletion, and emerging security threats while maintaining compliance with industry regulations.
 
 ## Learning objectives
 
-By the end of this module, you will be able to:
+By the end of this module, you'll be able to:
 
- -  Plan and implement security strategies for Azure storage resources to protect data at rest and in transit.
- -  Configure access control for storage accounts to manage permissions effectively.
- -  Manage the life cycle of storage account access keys to maintain security.
- -  Select and configure appropriate methods for access to Azure Files, Blob Storage, Tables, and Queues based on specific use cases.
- -  Implement security measures such as soft delete, backups, versioning, and immutable storage to protect against data security threats.
- -  Configure Bring Your Own Key (BYOK) to enhance data encryption and key management.
- -  Enable double encryption at the Azure Storage infrastructure level to provide an additional layer of security.
+- Plan and implement security strategies for Azure storage resources based on Zero Trust principles to protect data at rest and in transit.
+- Configure identity-based access control using Microsoft Entra ID for storage accounts to manage permissions effectively.
+- Manage the lifecycle of storage account access keys and implement key rotation policies to maintain security.
+- Select and configure appropriate authentication methods for Azure Files, Blob Storage, Tables, and Queues based on specific use cases and security requirements.
+- Implement comprehensive data protection measures including soft delete, backups, versioning, immutable storage, and point-in-time restore to protect against data loss and security threats.
+- Configure customer-managed encryption keys using Bring Your Own Key (BYOK) with Azure Key Vault to enhance data encryption and key management control.
+- Enable infrastructure encryption (double encryption) at the Azure Storage infrastructure level to provide another layer of security for compliance requirements.
 
 ## Goals
 
-The module aims to equip you with the knowledge and expertise necessary to design, implement, and manage a comprehensive security strategy for Azure storage resources. Participants will be able to secure data at rest and in transit, manage access control effectively, and implement encryption and data protection measures to ensure the security of critical data assets.
+This module equips you with the knowledge and expertise necessary to design, implement, and manage a comprehensive security strategy for Azure storage resources aligned with modern security best practices. You learn to apply defense-in-depth principles by implementing multiple layers of security controls. Upon completion, you are able to secure data at rest and in transit using encryption. You can manage access control effectively through identity-based authentication and role-based access control (RBAC). Then you implement automated key rotation and lifecycle management, and configure advanced data protection measures to meet organizational security and compliance requirements. You explore how to make informed decisions about authorization methods, balancing security requirements with operational needs, while following Microsoft's recommended security baseline for Azure Storage.

learn-pr/wwl-azure/security-storage/includes/10-bring-your-own-key-specification.md

@@ -1,67 +1,66 @@
 ## Scenario
 
-A Key Vault customer would like to securely transfer a key from their on-premises Hardware Security Module (HSM) outside Azure, into the HSM backing Azure Key Vault. The process of importing a key generated outside Key Vault is referred to as Bring Your Own Key (BYOK).
+A Key Vault customer would like to securely transfer a key from their on-premises Hardware Security Module (HSM) outside Azure, into the HSM backing Azure Key Vault. The process of importing a key generated outside Key Vault is referred to as **Bring Your Own Key (BYOK)**.
+
+**Why BYOK matters for security**: Many organizations require control over their encryption keys for compliance, regulatory requirements, or security policies. BYOK allows you to maintain control over the entire key lifecycle, from generation to destruction, while using Azure's cloud infrastructure. Also, BYOK aligns with Zero Trust principles by maintaining cryptographic separation between your key material and cloud providers until you explicitly authorize the transfer.
 
 The following are the requirements:
 
- -  The key to be transferred never exists outside an HSM in plain text form.
- -  Outside an HSM, the key to be transferred is always protected by a key held in the Azure Key Vault HSM.
+- **The key to be transferred never exists outside an HSM in plain text form** - Ensuring that even during the transfer process, the key material remains protected.
+- **Outside an HSM, the key to be transferred is always protected by a key held in the Azure Key Vault HSM** - Providing cryptographic assurance that only Azure Key Vault can unwrap the imported key.
 
 ## Terminology
 
 | **Key Name**           | **Key Type**                    | **Origin**          | **Description**                                         |
 | ---------------------- | ------------------------------- | ------------------- | ------------------------------------------------------- |
-| Key Exchange Key (KEK) | RSA                             | Azure Key Vault HSM | An HSM backed RSA key pair generated in Azure Key Vault |
-| Wrapping Key           | AES                             | Vendor HSM          | An \[ephemeral\] AES key generated by HSM on-premises   |
+| Key Exchange Key (KEK) | RSA                             | Azure Key Vault HSM | An HSM-backed RSA key pair generated in Azure Key Vault |
+| Wrapping Key           | AES                             | Vendor HSM          | An ephemeral AES key generated by on-premises HSM   |
 | Target Key             | RSA, EC, AES (Managed HSM only) | Vendor HSM          | The key to be transferred to the Azure Key Vault HSM    |
 
-Key Exchange Key (KEK): This is a customer-generated, HSM-backed key within the key vault intended for the import of the BYOK (Bring Your Own Key) key. The KEK should have the following properties:
+**Key Exchange Key (KEK)**: A customer-generated, HSM-backed key within the key vault intended for the import of the BYOK (Bring Your Own Key) key. The KEK should have the following properties:
 
- -  It must be an RSA-HSM key, with a size of 4096-bit, 3072-bit, or 2048-bit.
- -  Its key operations (key\_ops) are limited to 'import', allowing its use exclusively during the BYOK process.
- -  It must reside in the same vault where the Target Key is to be imported.
+- **It must be an RSA-HSM key**, with a key size of 4,096 bits (recommended), 3,072 bits, or 2,048 bits.
+- **Its key operations (key_ops) are limited to 'import'**, allowing its use exclusively during the BYOK process. This restriction minimizes the attack surface.
+- **It must reside in the same vault where the Target Key is to be imported**, ensuring proper key vault isolation.
 
 ## User steps
 
 To perform a key transfer:
 
-1.  Generate KEK.
-2.  Retrieve the public key of the KEK.
-3.  Using HSM vendor provided BYOK tool, import the KEK into the target HSM and exports the Target Key protected by the KEK.
-4.  Import the protected Target Key to Azure Key Vault.
+1. **Generate KEK** - Create a Key Exchange Key in Azure Key Vault.
+2. **Retrieve the public key of the KEK** - Download the public portion for use with your HSM vendor tools.
+3. **Using HSM vendor-provided BYOK tool**, import the KEK into the target HSM and export the Target Key protected by the KEK.
+4. **Import the protected Target Key to Azure Key Vault** - Complete the transfer using Azure CLI or PowerShell.
 
-Customers use the BYOK tool and documentation provided by HSM vendor to complete Steps 3. It produces a Key Transfer Blob (a ".byok" file).
+Customers use the BYOK tool and documentation provided by the HSM vendor to complete Step 3. This process produces a Key Transfer Blob (a ".byok" file) that securely encapsulates the encrypted key material.
 
 ## HSM constraints
 
-The existing HSM may apply constraints on key that they manage, including:
+The existing HSM may apply constraints on keys that they manage, including:
 
- -  The HSM may need to be configured to allow key wrap-based export<br>
- -  The target key may need to be marked **Cryptoki Attribute (CKA)**\_EXTRACTABLE for the HSM to allow controlled export
- -  In some cases, the KEK and wrapping key may need to be marked as CKA\_TRUSTED, which allows it to be used to wrap keys in the HSM.
+- The HSM needs to be configured to allow key wrap-based export.
+- The target key is marked **CKA_EXTRACTABLE** (Cryptoki Attribute) for the HSM to allow controlled export.
+- In some cases, the KEK and wrapping key are marked as **CKA_TRUSTED**, which allows them to be used to wrap keys in the HSM.
 
 The configuration of source HSM is, generally, outside the scope of this specification. Microsoft expects the HSM vendor to produce documentation accompanying their BYOK tool to include any such configuration steps.
 
 > [!NOTE]
-> Several of these steps can be performed using other interfaces such as Azure PowerShell and Azure portal. They can also be performed programmatically using equivalent functions in Key Vault SDK.
+> These steps can be performed using multiple interfaces including Azure CLI (shown in examples), Azure PowerShell, and the Azure portal. They can also be performed programmatically using the Azure Key Vault SDK for automated deployment scenarios.
 
 ### Generate KEK
 
-Use the **az keyvault key create** command to create KEK with key operations set to import. Note down the key identifier 'kid' returned from the below command.
+Use the **az keyvault key create** command to create KEK with key operations set to import. Note the key identifier ('kid') returned from this command, as you need it for subsequent operations.
 
 ```azurecli
 az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --vault-name ContosoKeyVaultHSM
-
-
-
-
 ```
 
-Services support different KEK lengths; Azure SQL, for instance, only supports key lengths of 2048 or 3072 bytes.
+> [!IMPORTANT]
+> Different Azure services support different KEK lengths. For example, Azure SQL supports key lengths of 2048 bits or 3072 bits only. Always verify the key size requirements for your specific service before generating the KEK.
 
-### Retrieve the public key of the KEK<br>
+### Retrieve the public key of the KEK
 
-Download the public key portion of the KEK and store it into a PEM file.
+Download the public key portion of the KEK and store it as a PEM (Privacy-Enhanced Mail) file. This file is used with your HSM vendor's BYOK tool.
 
 ```azurecli
 az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem
@@ -71,24 +70,52 @@ az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --fil
 
 ```
 
-## Generate key transfer blob using HSM vendor provided BYOK tool<br>
+## Generate key transfer blob using HSM vendor-provided BYOK tool
 
-Use the HSM Vendor provided BYOK tool to create a key transfer blob (stored as a ".byok" file). KEK public key as a **.Privacy-Enhanced Mail** (.pem file) will be one of the inputs to this tool.
+Use the HSM vendor-provided BYOK tool to create a key transfer blob (stored as a ".byok" file). The KEK public key, in **Privacy-Enhanced Mail** (.pem) format is one of the inputs to this tool. Consult your HSM vendor's specific documentation for detailed instructions on using their BYOK tool.
 
 ### Key Transfer Blob
 
-Long term, Microsoft would like to use PKCS\#11 CKM\_RSA\_AES\_KEY\_WRAP mechanism to transfer the target key to Azure Key Vault since this mechanism produces a single blob and, more importantly, the intermediate AES key is handled by the two HSMs and is guaranteed to be ephemeral. This mechanism isn't presently available in some HSMs but the combination of protecting the target key with CKM\_AES\_KEY\_WRAP\_PAD using an AES key and protecting the AES key with CKM\_RSA\_PKCS\_OAEP produces an equivalent blob.
+Long term, Microsoft would like to use PKCS\#11 CKM\_RSA\_AES\_KEY\_WRAP mechanism to transfer the target key to Azure Key Vault. The PKCS#11 mechanism produces a single blob and, more importantly, the intermediate AES key is handled by the two HSMs and is guaranteed to be ephemeral.
 
 The target key plaintext depends on the key type:
 
- -  For an RSA key, the private key ASN.1 DER encoding \[RFC3447\] wrapped in PKCS\#8 \[RFC5208\]
- -  For an EC key, the private key ASN.1 DER encoding \[RFC5915\] wrapped in PKCS\#8 \[RFC5208\]
- -  For an octet key, the raw bytes of the key
+- For an RSA key, the private key ASN.1 DER encoding \[RFC3447\] wrapped in PKCS\#8 \[RFC5208\]
+- For an EC key, the private key ASN.1 DER encoding \[RFC5915\] wrapped in PKCS\#8 \[RFC5208\]
+- For an octet key, the raw bytes of the key
 
 The bytes for the plaintext key are then transformed using the CKM\_RSA\_AES\_KEY\_WRAP mechanism:
 
- -  An ephemeral AES key is generated and encrypted with the wrapping RSA key using RSA-OAEP with SHA1.
- -  The encoded plaintext key is encrypted using the AES key using AES Key Wrap with Padding.
- -  The encrypted AES key and the encrypted plaintext key are concatenated to produce the final ciphertext blob.
+- An ephemeral AES key is generated and encrypted with the wrapping RSA key using RSA-OAEP with SHA1.
+- The encoded plaintext key is encrypted using the AES key using AES Key Wrap with Padding.
+- The encrypted AES key and the encrypted plaintext key are concatenated to produce the final ciphertext blob.
 
 The format of the transfer blob uses JSON Web Encryption compact serialization (RFC7516) primarily as a vehicle for delivering the required metadata to the service for correct decryption.
+
+## Best practices for implementing BYOK
+
+When implementing Bring Your Own Key for Azure Key Vault, consider these security and operational recommendations:
+
+- **Use the largest key size supported** - Generate KEKs with 4096-bit key sizes whenever possible, as they provide the strongest cryptographic protection. Only use smaller key sizes when required by specific service constraints.
+
+- **Limit KEK key operations** - Always restrict KEK operations to 'import' only. You minimize the attack surface and ensures the KEK can't be misused for other cryptographic operations.
+
+- **Maintain HSM security certifications** - Ensure your on-premises HSM meets FIPS 140-2 Level 2 or higher certification standards, matching or exceeding Azure Key Vault's security level.
+
+- **Secure the transfer process** - Protect the .byok file during transfer to Azure. While the key material is encrypted, the file should still be treated as sensitive and transmitted over secure channels.
+
+- **Document your BYOK implementation** - Maintain detailed documentation of which keys were imported via BYOK, their purposes, and the HSM configurations used. Documentation is critical for compliance audits and disaster recovery.
+
+- **Test the import process** - Before importing production keys, test the entire BYOK workflow with test keys to ensure compatibility between your HSM vendor's tools and Azure Key Vault.
+
+- **Plan for key rotation** - Establish procedures for rotating BYOK keys. While you can't export keys from Azure Key Vault, you can import new versions and update dependent services.
+
+- **Use Managed HSM for sensitive workloads** - For highly regulated environments requiring single-tenant HSM isolation, consider Azure Key Vault Managed HSM, which supports BYOK and provides enhanced control.
+
+- **Implement access controls** - Use Azure role based access control (RBAC) to restrict who can perform BYOK operations. Separate the permissions for creating KEKs from permissions who can import target keys.
+
+- **Enable audit logging** - Turn on Azure Key Vault logging and monitoring to track all BYOK operations, including KEK generation, key downloads, and target key imports. Integrate logs with Azure Monitor or a SIEM solution.
+
+- **Verify vendor support** - Before purchasing or implementing an HSM solution, verify that the vendor provides a BYOK tool compatible with Azure Key Vault's current requirements.
+
+- **Consider hybrid architectures carefully** - BYOK is ideal when you need to maintain keys on-premises initially and then migrate to Azure, or when regulatory requirements mandate specific key generation procedures.