Merge pull request #180

docs: Documentation edits for SCP

Author: DennisDyallo

Yubico.YubiKey/docs/users-manual/application-security-domain/security-domain-certificates.md

@@ -71,13 +71,7 @@ var caIds = session.GetSupportedCaIdentifiers(
 
 ### Certificate allowlists
 
-Use of the allowlist can provide the following benefits: 
-- A strong binding to one (or multiple) OCE(s) 
-- Protection against compromised OCEs 
-It is recommended to use the allowlist also as a revocation mechanism for OCE certificates. However, if the 
-allowlist is used in this way, special care shall be taken never to empty/remove the allowlist (i.e. if created, the 
-allowlist shall always contain at least one certificate) because no restrictions apply (i.e. all certificates are 
-accepted) once an allowlist is removed. 
+Use of the allowlist will create strong binding to one or multiple OCE(s)
 
 Control which certificates can be used for authentication by maintaining an allowlist of serial numbers:
 
@@ -122,7 +116,7 @@ session.StoreCaIssuer(oceRef, skiBytes);
 
 ### SCP11b
 
-- Simplest variant, no mutual authentication
+- No mutual authentication
 - Suitable when host authentication isn't required
 
 Example setup:
@@ -139,37 +133,19 @@ session.StoreCertificates(keyRef, new[] { deviceCert });
 ### SCP11c
 
 - Mutual authentication
-- Similar to SCP11a but with additional features
-- such as offline scripting usage (See [GlobalPlatform SCP11 Specification Annex B](https://globalplatform.org/specs-library/secure-channel-protocol-11-amendment-f/))
+- Similar to SCP11a but with additional features such as offline scripting usage  
+  (See [GlobalPlatform SCP11 Specification Annex B](https://globalplatform.org/specs-library/secure-channel-protocol-11-amendment-f/))
 
 ## Security considerations
 
 1. **Certificate Validation**
 
    - Verify certificate chains completely
-   - Check certificate revocation status
-   - Validate certificate purposes and extensions
-   - Ensure proper key usage constraints
 
 2. **Access Control**
 
-   - Use allowlists in production environments
+   - Consider using allowlists in production environments
    - Regularly review and update allowlists
-   - Monitor for unauthorized certificate usage
-   - Document certificate authorization policies
-
-3. **Certificate Lifecycle**
-
-   - Plan for certificate renewal
-   - Handle certificate revocation
-   - Maintain certificate inventory
-   - Test certificate rotation procedures
-
-4. **Storage Limitations**
-   - Be aware of YubiKey storage constraints
-   - Optimize certificate chain length
-   - Consider certificate compression if needed
-   - Monitor available storage space
 
 > [!IMPORTANT]
 > Most certificate operations require an authenticated session. Operations are typically only available when using SCP11a or SCP11c variants.
@@ -181,11 +157,11 @@ session.StoreCertificates(keyRef, new[] { deviceCert });
 1. Generate or obtain required certificates
 2. Store certificate chain on YubiKey
 3. Configure CA information if needed
-4. Set up allowlist for production use
+4. Optionally, set up an allowlist
 
 ```csharp
 // Example of complete setup
-using var session = new SecurityDomainSession(yubiKeyDevice, scp03Params);
+using var session = new SecurityDomainSession(yubiKeyDevice, Scp03KeyParameters.DefaultKey);
 var keyRef = KeyReference.Create(ScpKeyIds.Scp11A, kvn);
 
 // Store full chain
@@ -214,17 +190,13 @@ session.StoreAllowlist(keyRef, newAllowedSerials);
 ### Troubleshooting
 
 1. **Certificate Loading Issues**
-
    - Verify certificate format (X.509 v3)
    - Check certificate chain order
-   - Ensure sufficient storage space
    - Validate key references
 
-2. **Authentication Problems**
-   - Verify certificate trust chain
+2. **Authentication Problems**  
+   - Verify certificates
    - Check allowlist configuration
-   - Confirm proper SCP variant usage
-   - Validate certificate dates
 
 > [!NOTE]
 > For additional details on secure channel establishment and certificate usage, refer to the [Secure Channel Protocol (SCP)](xref:UsersManualScp) documentation.

Yubico.YubiKey/docs/users-manual/application-security-domain/security-domain-keys.md

@@ -18,9 +18,11 @@ limitations under the License. -->
 
 # Security Domain key management
 
-The Security Domain supports management of both symmetric (SCP03) and asymmetric (SCP11) keys. This document describes the key types, their usage, and management operations.
+The Security Domain supports management of both symmetric (SCP03) and asymmetric (SCP11) keys. This document describes
+the key types, their usage, and management operations.
 
-For protocol details and secure channel implementation, see the [Secure Channel Protocol (SCP)](xref:UsersManualScp) documentation.
+For protocol details and secure channel implementation, see the [Secure Channel Protocol (SCP)](xref:UsersManualScp)
+documentation.
 
 ## Key types
 
@@ -33,28 +35,30 @@ The Security Domain manages two main types of keys:
 
 Each SCP03 key set consists of three AES-128 keys that work together to secure communications:
 
-| Key Type | Purpose |
-|----------|---------|
-| Key-ENC | Channel encryption key for securing messages |
-| Key-MAC | Channel MAC key for message authentication |
-| Key-DEK | Data encryption key for sensitive data |
+| Key Type | Key ID (KID) | Purpose                                      |
+|----------|--------------|----------------------------------------------|
+| Key-ENC  | 0x1          | Channel encryption key for securing messages |
+| Key-MAC  | 0x2          | Channel MAC key for message authentication   |
+| Key-DEK  | 0x3          | Data encryption key for sensitive data       |
 
 ### Managing SCP03 keys
 
 ```csharp
 // Put a new SCP03 key set
-var keyRef = KeyReference.Create(ScpKeyIds.Scp03, 0x01);  // KVN=1
+var kvn = 0x01;
+var keyRef = KeyReference.Create(ScpKeyIds.Scp03, kvn);
 var staticKeys = new StaticKeys(keyDataMac, keyDataEnc, keyDataDek);
-session.PutKey(keyRef, staticKeys);  // 0 means new key
+session.PutKey(keyRef, staticKeys); 
 
 // Replace existing keys
 var newKeys = new StaticKeys(newMacKey, newEncKey, newDekKey);
-session.PutKey(keyRef, newKeys, currentKvn);
+session.PutKey(keyRef, newKeys, kvnToReplace);
 ```
 
 ### Key Version Numbers (KVN)
 
 SCP03 key sets are identified by Key Version Numbers:
+
 - Default key set: KVN=0xFF (publicly known, no security)
 - Each YubiKey can store up to three custom SCP03 key sets
 
@@ -64,7 +68,8 @@ SCP03 key sets are identified by Key Version Numbers:
 ## SCP11 key management
 
 SCP11 uses NIST P-256 elliptic curve cryptography. Keys can be:
-- Generated on the YubiKey (recommended)
+
+- Generated on the YubiKey
 - Imported from external sources
 
 ### Generating keys
@@ -115,21 +120,22 @@ session.Reset();
 ```
 
 > [!WARNING]
-> Resetting removes all custom keys and restores factory defaults (within the Security Domain). Ensure you have backups before resetting.
+> Resetting removes all custom keys and restores factory defaults (within the Security Domain). Ensure you have backups
+> before resetting.
 
 ## Key rotation
 
-Regular key rotation is recommended for security. Here are typical rotation procedures:
+Here are some simple key rotation procedures:
 
 ### SCP03 key rotation
 
 ```csharp
 // Authenticate with current keys
-using var session = new SecurityDomainSession(yubiKeyDevice, currentScp03Params);
+using var session = new SecurityDomainSession(yubiKeyDevice, scpParams);
 
 // Replace with new keys
 var newKeyRef = KeyReference.Create(ScpKeyIds.Scp03, keyVersionNumber);
-session.PutKey(newKeyRef, newStaticKeys, currentKvn);
+session.PutKey(newKeyRef, newStaticKeys, kvnToReplace);
 ```
 
 ### SCP11 key rotation
@@ -139,32 +145,24 @@ using var session = new SecurityDomainSession(yubiKeyDevice, scpParams);
 
 // Generate new key pair
 var newKeyRef = KeyReference.Create(ScpKeyIds.Scp11B, keyVersionNumber);
-var newPublicKey = session.GenerateEcKey(newKeyRef, oldKvn); // Replaces oldKvn
+var newPublicKey = session.GenerateEcKey(newKeyRef, kvnToReplace);
 ```
 
 ## Security considerations
 
 1. **Key Protection**
-   - Store keys securely
-   - Use unique keys per device when possible
-   - Consider using SCP11 for mutual authentication
-   - Avoid storing sensitive keys in source code or configuration files
+    - Use unique keys per device when possible
+    - Consider using SCP11 for mutual authentication
 
 2. **Key Version Management**
-   - Track which keys are loaded on each YubiKey
-   - Track KVNs in use
-
-3. **Recovery Planning**
-   - Maintain backup keys
-   - Document key recovery procedures
-   - Test recovery processes regularly
-   - Keep track of key histories
+    - Track which keys are loaded on each YubiKey
+    - Track KVNs in use
 
-4. **Default Keys**
-   - Default SCP03 keys provide no security
-   - Replace default keys in production environments
-   - Cannot retain default keys alongside custom keys
-   - Use proper key management in production
+3. **Default Keys**
+    - Default SCP03 keys provide no security
+    - Replace default keys in production environments
+    - Cannot retain default keys alongside custom keys
 
 > [!IMPORTANT]
-> The YubiKey provides no metadata about installed keys beyond what's available through `GetKeyInformation()`. Your application must track additional key management details.
+> The YubiKey provides no metadata about installed keys beyond what's available through `GetKeyInformation()`. Your
+> application must track additional key management details.

Yubico.YubiKey/docs/users-manual/application-security-domain/security-domain-tasks.md

@@ -73,11 +73,12 @@ var publicKey = session.GenerateEcKey(keyRef);
 session.StoreCertificates(keyRef, certificateChain);
 
 // Configure CA for SCP11a/c
+var oceSubjectKeyIdentifier = GetSkiFromCertificate(oceCertCa);
 var caRef = KeyReference.Create(OceKid, kvn);
-session.StoreCaIssuer(caRef, skiBytes);
+session.StoreCaIssuer(caRef, oceSubjectKeyIdentifier);
 ```
 
-### 3. Set up access control
+### 3. Set up access control (Optional)
 
 ```csharp
 // Configure certificate allowlist
@@ -95,7 +96,7 @@ using var session = new SecurityDomainSession(yubiKeyDevice, currentScp03Params)
 
 // Replace with new keys
 var newKeyRef = KeyReference.Create(ScpKeyIds.Scp03, newKvn);
-session.PutKey(newKeyRef, newStaticKeys, currentKvn);
+session.PutKey(newKeyRef, newStaticKeys, kvnToReplace);
 ```
 
 ### Rotating SCP11 keys
@@ -105,7 +106,7 @@ using var session = new SecurityDomainSession(yubiKeyDevice, scpParams);
 
 // Generate new key pair
 var newKeyRef = KeyReference.Create(ScpKeyIds.Scp11B, newKvn);
-var newPublicKey = session.GenerateEcKey(newKeyRef, oldKvn); // Will be replaced
+var newPublicKey = session.GenerateEcKey(newKeyRef, kvnToReplace); // Will be replaced
 ```
 
 ## Recovery operations
@@ -210,7 +211,7 @@ var keyInfo = verifySession.GetKeyInformation();
 
 1. **Monitor Key Status**
 ```csharp
-// Check key information regularly
+// Check key information
 var keyInfo = session.GetKeyInformation();
 foreach (var key in keyInfo)
 {
@@ -231,34 +232,4 @@ foreach (var cert in certificates)
         PlanCertificateRenewal(cert);
     }
 }
-```
-
-## Troubleshooting
-
-### Key issues
-
-1. **Unable to Authenticate**
-   - Verify key version numbers
-   - Check key reference values
-   - Confirm key components
-
-2. **Failed Key Import**
-   - Validate key formats
-   - Check authentication status
-   - Verify available space
-   - Confirm key compatibility
-
-### Certificate issues
-
-1. **Certificate Chain Problems**
-   - Verify chain order
-   - Check CA configuration
-   - Validate certificate formats
-
-2. **Access Control Issues**
-   - Check allowlist configuration
-   - Verify certificate serials
-   - Validate certificate dates
-
-> [!NOTE]
-> Always maintain detailed logs of key and certificate operations for troubleshooting.
+```

Yubico.YubiKey/docs/users-manual/sdk-programming-guide/secure-channel-protocol.md

@@ -283,7 +283,8 @@ Standard YubiKeys are manufactured with a default key set (KVN=0xFF):
    slot 3:   --empty--
 ```
 
-The default keys are publicly known (0x40 41 42 ... 4F) and provide no security. You should replace them in production environments.
+> [!IMPORTANT]
+> The default keys are publicly known (0x40 41 42 ... 4F) and provide no security. You should replace them in production environments.
 
 ### Managing key sets
 
@@ -324,27 +325,29 @@ session.Reset();
 
 4. **Multiple Key Sets:**
    - After default keys are replaced, can have 1-3 custom key sets
-   - Each must have unique KID
+   - Each must have unique KVN
    - Can add/remove without affecting other sets
 
 ### Example: complete key management flow
 
 ```csharp
 // Start with default keys
 var defaultScp03Params = Scp03KeyParameters.DefaultKey;
+var firstKvn = 0x1;
+var keyRef1 = KeyReference.Create(ScpKeyIds.Scp03, firstKvn);
 using (var session = new SecurityDomainSession(yubiKeyDevice, defaultScp03Params))
 {
     // Add first custom key set (removes default)
-    var keyRef1 = KeyReference.Create(ScpKeyIds.Scp03, 0x01);
     session.PutKey(keyRef1, newKeys);
 }
 
 // Now authenticate with new keys
-var newScp03Params = new Scp03KeyParameters(ScpKeyIds.Scp03, 0x01, newKeys);
+var newScp03Params = new Scp03KeyParameters(keyRef1, newKeys);
 using (var session = new SecurityDomainSession(yubiKeyDevice, newScp03Params))
 {
     // Add second key set
-    var keyRef2 = KeyReference.Create(ScpKeyIds.Scp03, 0x02);
+    var secondKvn = 0x2;
+    var keyRef2 = KeyReference.Create(ScpKeyIds.Scp03, secondKvn);
     session.PutKey(keyRef2, customKeys2);
 
     // Check current key information
@@ -354,11 +357,10 @@ using (var session = new SecurityDomainSession(yubiKeyDevice, newScp03Params))
 
 ### Key management responsibilities
 
-Your application must:
+You should:
 - Track which keys are loaded on each YubiKey
-- Know if a YubiKey has custom keys from manufacturing
-- Manage key distribution and storage
 - Track KVNs in use
+- Know if a YubiKey has custom keys from manufacturing
 - Handle key rotation
 
 The YubiKey provides no metadata about installed keys beyond what's available through `GetKeyInformation()`.
@@ -375,7 +377,6 @@ SCP11 uses asymmetric cryptography based on elliptic curves (NIST P-256) for aut
 
 Detailed information about SCP11 can be found in [GlobalPlatform Card Technology, Secure Channel Protocol '11' Card Specification v2.3 – Amendment F, Chapter 2](https://globalplatform.org/specs-library/secure-channel-protocol-11-amendment-f/)
 
-
 It comes in three variants, each offering different security properties:
 
 ### SCP11 variants
@@ -540,8 +541,7 @@ using var session = new SecurityDomainSession(yubiKeyDevice, scp11Params);
 4. **Certificate Allowlists:**
    - Restrict which certificates can authenticate
    - Update lists as certificates change
-   - Clear allowlists when no longer needed
-   - Can be used as a part of a certificate revocation stategy
+   - Can be used as a part of a certificate revocation strategy
 
 ### Checking SCP support