Merge pull request #123 from niscy-eudiw/main

Add SecureAreas documentation and update related references in EudiWalletKit

Sources/EudiWalletKit/EudiWalletKit.docc/EudiWalletKit.md

@@ -35,6 +35,7 @@ The library depends on the following EUDI libraries:
 - <doc:GetStarted>
 - <doc:ManageDocuments>
 - <doc:IssueDocuments>
+- <doc:SecureAreas>
 - <doc:PresentationService>
 
 @Links(visualStyle: detailedGrid) {

Sources/EudiWalletKit/EudiWalletKit.docc/IssueDocuments.md

@@ -15,8 +15,8 @@ When the document docType to be issued use the ``EudiWallet/issueDocument(docTyp
 __Important Notes__:
 
 - Currently, only mso_mdoc format is supported
-- Currently, only ES256 algorithm is supported for signing OpenId4CVI proof of possession of the
-	publicKey.
+- For the 'SecureEnclave' secure area, only ES256 algorithm is supported for signing OpenId4CVI proof of possession of the
+public/private key pair.
 
 The following example shows how to issue an EUDI Personal ID document using OpenID4VCI:
 
@@ -34,7 +34,7 @@ catch {
 ```
 ### Resolving Credential offer
 
-The library provides the ``EudiWallet/resolveOfferUrlDocTypes(uriOffer:format:)``   method that resolves the credential offer URI.
+The library provides the ``EudiWallet/resolveOfferUrlDocTypes(uriOffer:format:)`` method that resolves the credential offer URI.
 The method returns the resolved ``OfferedIssuanceModel`` object that contains the offer's data (offered document types, issuer name and transaction code specification for pre-authorized flow). The offer's data can be displayed to the
 user.
 
@@ -76,7 +76,7 @@ When the transaction code is provided, the issuance process can be resumed by ca
 ### Dynamic issuance
 Wallet kit supports the Dynamic [PID based issuance](https://github.com/eu-digital-identity-wallet/eudi-wallet-product-roadmap/issues/82)
 
-After calling ``EudiWallet/issueDocument(docType:format:keyOptions: KeyOptions:promptMessage:)`` or ``EudiWallet/issueDocumentsByOfferUrl(offerUri:docTypes:txCodeValue:format:promptMessage:claimSet:)`` the wallet application need to check if the doc is pending and has a `authorizePresentationUrl` property. If the property is present, the application should perform the OpenID4VP presentation using the presentation URL. On success, the ``EudiWallet/resumePendingIssuance(pendingDoc:webUrl:)`` method should be called with the authorization URL provided by the server.
+After calling ``EudiWallet/issueDocument(docType:format:keyOptions:promptMessage:)`` or ``EudiWallet/issueDocumentsByOfferUrl(offerUri:docTypes:docTypeKeyOptions:txCodeValue:format:promptMessage:claimSet:)`` the wallet application need to check if the doc is pending and has a `authorizePresentationUrl` property. If the property is present, the application should perform the OpenID4VP presentation using the presentation URL. On success, the ``EudiWallet/resumePendingIssuance(pendingDoc:webUrl:)`` method should be called with the authorization URL provided by the server.
 ```swift
 if let urlString = newDocs.last?.authorizePresentationUrl { 
 	// perform openid4vp presentation using the urlString 

Sources/EudiWalletKit/EudiWalletKit.docc/SecureAreas.md

@@ -0,0 +1,38 @@
+# Custom key management
+
+Eudi Wallet Kit supports custom key management through the implementation of [SecureArea](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/securearea) and [SecureKeyStorage](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/securekeystorage) protocols. This document details the process of integrating custom key management with the library.
+
+### Secure areas
+
+The wallet developer can customize cryptographic key operations by passing SecureArea instances to the wallet. In the absence of custom instances, the wallet kit automatically generates [SecureEnclaveSecureArea](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-security/documentation/mdocsecurity18013/secureenclavesecurearea) (default) and [SecureEnclaveSecureArea](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-security/documentation/mdocsecurity18013/softwaresecurearea) secure areas. 
+
+The secure area instance must be initialized with a secure key storage area implementing the [SecureKeyStorage](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/securekeystorage) protocol. An iOS keychain-based storage is provided via the [KeyChainSecureKeyStorage](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-wallet-storage/documentation/walletstorage/keychainsecurekeystorage) actor. 
+
+Assuming that the application developer has implemented the SecureArea protocol and registered an instance with the wallet kit, it will be available for custom secure area for cryptographic operations. The following example demonstrates how to register a custom secure area with the wallet kit:
+
+```swift
+let keyChainStorage = KeyChainSecureKeyStorage(serviceName: self.serviceName, accessGroup: nil)
+let mySecureArea = MySecureArea(storage: keyChainStorage)
+let wallet = try! EudiWallet(serviceName: "wallet_dev_ui",
+		trustedReaderCertificates: [Data(name: "eudi_pid_issuer_ut", ext: "der")!],
+		secureAreas: [mySecureArea])
+```
+
+### Secure key creation on issuing
+
+For each document type, the wallet developer has the flexibility to define specific key creation parameters, including the [secure area name](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/securearea/name-1uugf), [curve type](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/coseeccurve), [key access control](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/keyaccesscontrol) and [key unlock policy](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/keyaccessprotection).
+
+Specifically:
+
+- The ``EudiWallet/issueDocument(docType:format:keyOptions:promptMessage:)`` has been extended to support an
+additional [keyOptions](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/keyoptions) optional parameter to specify the secure area name and other key options for the key creation. 
+- The ``EudiWallet/issueDocumentsByOfferUrl(offerUri:docTypes:docTypeKeyOptions:txCodeValue:format:promptMessage:claimSet:)`` has been extended to support a `docTypeKeyOptions` to specify the secure area name and other key options for each doc type.
+
+```swift
+// For keychain saved keys, the iOS will automatically present a biometric or user PIN screen to authorize key usage for PID documents
+let docTypeKeyOptions: [EuPidModel.euPidDocType : KeyOptions(secureAreaName: "Software", accessControl: [.requireUserPresence])]
+let issuedDocs = try await wallet.issueDocumentsByOfferUrl(offerUri: uriOffered, docTypes: docIssueOffered.docModels, docTypeKeyOptions: docTypeKeyOptions)
+```
+### Secure key usage on presentation
+
+During presentation with BLE proximity or OpenID4VP, the private key is used to create a device signature. The secure area is automatically used to sign the device response. An unlock key hook is provided via the [unlockKey](https://eu-digital-identity-wallet.github.io/eudi-lib-ios-iso18013-data-model/documentation/mdocdatamodel18013/securearea/unlockkey(id:)-19q3g) method which is internally called to get the optional `unlockData`. 

changelog.md

@@ -19,11 +19,6 @@
 - ElementViewModel: `public var isMandatory: Bool` is removed
 - ElementViewModel: `public var isOptional: Bool` is added (opposite of `isMandatory`)
 
-## v0.7.6
-- Refactored security to use SecureArea for cryptographic operations. The wallet developer can specify SecureArea instances which are registered by their name, otherwise the wallet-kit creates 'SecureEnclave' (default) and 'Software' secure areas.  The wallet developer can specify Key create options per doc-type such as curve type, secure area name, key unlock policy, key access control and key unlock data.
-
-## v0.7.5
-
 ## v0.7.4
 - Update Package.resolved and Package.swift with new versions for openid4vci, openid4vp