Merge develop-main to main

README.md

@@ -1,79 +1,106 @@
-- [Ülevaade](#ülevaade)
-- [Demorakenduse jooksutamise juhend](#demorakenduse-jooksutamise-juhend)
-- [Integreerimise juhend](#integreerimise-juhend)
-  - [Rakenduse nõuded](#rakenduse-nõuded)
-    - [Lubada NFC Võimekus](#lubada-nfc-võimekus)
-    - [Uuendada Info.plist](#uuendada-infoplist)
-    - [Teegi ehitamine](#teegi-ehitamine)
-    - [Teegi lisamine rakendusse](#teegi-lisamine-rakendusse)
-- [Teegi liidesed id-kaardiga suhtluseks](#teegi-liidesed-id-kaardiga-suhtluseks)
-
-# Ülevaade 
-
-NFC-ID teek pakub võimalust kasutada ID-kaardi autentimis- ja signeerimisfunktsionaalsust üle NFC liidese. Teegist on kaks versiooni - Android ja iOS platvormile.
-
-NFC-ID teek ei ole mõeldud avalikuks kasutamiseks. Tegemist on tehnilise taseme teegiga, mis delegeerib kasutajaga suhtlemise rakendusele. Pikema aja jooksul ei ole ohutu võimaldada lõppkasutajal sisestada oma ID-kaardi PIN-koode igasse mobiilirakendusse. ID-kaardiga suhtluseks, usaldusväärse kasutajaliidese ning muude vajalike funktsioonide jaoks on vajalik luua tulevikus spetsiaalne mobiilirakendus. Selline lahendus võimaldab edaspidi mobiilirakendust kiiremini uuendada ning rünnete korral kaitsemeetmeid kohandada ja täiendada. 
-NFC-ID teek on arendatud m-valimiste projektis lähtudes vajadusest kasutada ID-kaarti m valijarakenduses. 
-
-# Demorakenduse jooksutamise juhend
-- Avada mvtng-nfc-demo.xcworkspace. Antud töökeskkond sisaldab endas nii demorakendust kui nfclib teeki.
-- Oodata, kuni Swift Package Manager'i sõltuvused laetakse alla
-- Product -> Run
-
-Simulaator pole toetatud, sest simulaatoril puudub NFC tugi.
-
-# Integreerimise juhend
-
-## Rakenduse nõuded
-### Lubada NFC Võimekus
-Xcode projektis tuleb seadistada NFC võimekuse loa küsimine
-
-- Projekti navigaatoris valida oma projekt.
-- Valida oma rakenduse sihtmärk ja seejärel minna vahelehele "Signing & Capabilities".
-- Klikkida nupul "+ Capability".
-- Otsida "Near Field Communication Tag Reading" ja lisada see oma projekti.
-
-### Uuendada Info.plist
-Info.plist failis peab deklareerima NFC kasutuse, et selgitada, miks rakendus vajab juurdepääsu sellele tehnoloogiale.
-
-- Avada oma Info.plist fail.
-- Lisada uus võti Privacy - NFC Scan Usage Description (NFCReaderUsageDescription).
-- Määrata selle väärtuseks string, mis kirjeldab, miks rakendus vajab juurdepääsu NFC-le. See kirjeldus kuvatakse kasutajale esmakordselt, kui rakendus üritab NFC-d kasutada.
-
-### Teegi ehitamine
-Eesmärk on ehitada .xcframework failikogumik, mida saab lisata sõltuvusena teistesse projektidesse.
-
-- Jooksuta skripti nimega build_xcframework.sh, mis asub projekti kaustas
-  - Selle tagajärjel ilmub projekti kaustas build kausta nflib.xcframework
-
-### Teegi lisamine rakendusse
-- Ava projekt, kuhu soovid integreerida nfclib teegi
-- Vali projekt ja TARGETS menüü all õige programm
-- Selle tagajärjel peaks olema nähtav General osa sihtprogrammi kohta
-- Otsida Frameworks and Libraries
-- Vajutada + -> Add Other... -> Add Files -> Valida nfclib.xcframework
-
-Nüüd on nfc teek rakendusse integreeritud.
-
-# Teegi liidesed id-kaardiga suhtluseks
-Kõik avalikud operatsioonid on kirjeldatud `CardOperations` protokollis.
-
-Järgnevalt on nimetatud operatsioonid, mida teek võimaldab.
-
-Tagastab, kas NFC on seadmel toetatud.
-`public func isNFCSupported() -> Bool`
-
-Loeb asünkroonselt kaardilt avalikku teavet kaardi omaniku kohta
-`public func readPublicInfo(CAN: String) async throws -> CardInfo`
-
-Loeb asünkroonselt kaardilt autentimise sertifikaadi.
-`public func readAuthenticationCertificate(CAN: String) async throws -> SecCertificate`
-
-Loeb asünkroonselt kaardilt allkirjastamise sertifikaadi.
-`public func readSigningCertificate(CAN: String) async throws -> SecCertificate`
-
-Hangib andmeid WebEID autentimiseks, kasutades antud volikirju ja väljakutset.
-`public func loadWebEIDAuthenticationData(CAN: String, pin1: String, challenge: String, origin: String) async throws -> WebEidData`
-
-Viib läbi allkirjastamise operatsiooni, kasutades eelnevalt arvutatud räsi (toetatud on ainult SHA-384) ja PIN-koodi
-`public func sign(CAN: String, hash: Data, pin2: String) async throws -> Data`
+- [Overview](#overview)  
+- [Demo Application Run Guide](#demo-application-run-guide)  
+- [Integration Guide](#integration-guide)  
+  - [Application Requirements](#application-requirements)  
+    - [Enable NFC Capability](#enable-nfc-capability)  
+    - [Update Info.plist](#update-infoplist)  
+    - [Build the Library](#build-the-library)  
+    - [Add the Library to the Application](#add-the-library-to-the-application)  
+- [Library Interfaces for ID Card Communication](#library-interfaces-for-id-card-communication)  
+
+# Overview
+
+The NFC-ID library provides functionality to use ID card authentication and digital signing over the NFC interface. Two platform-specific versions of the library are available – one for Android and one for iOS.  
+
+The NFC-ID library is not intended for public use. It is a low-level technical library that delegates user interaction to the application itself. In the long term, it is not safe to allow end users to enter their ID card PIN codes directly into every mobile app. For secure ID card interaction, a trusted user interface, and additional required features, a dedicated mobile application must be developed in the future. Such a solution would also allow faster updates to the application and enable quick adjustments of countermeasures in case of attacks.  
+
+The NFC-ID library was originally developed within the m-valimiste project, based on the need to use the ID card inside the m-Voting client application.  
+
+# Demo Application Run Guide
+- Open **mvtng-nfc-demo.xcworkspace**. This workspace includes both the demo app and the `nfclib` library.  
+- Wait until **Swift Package Manager** dependencies are fully downloaded.  
+- Select **Product → Run**.  
+
+⚠️ The simulator is not supported, since it does not provide NFC functionality.  
+
+# Integration Guide
+
+## Application Requirements
+### Enable NFC Capability
+You must configure your Xcode project to request NFC capability access:
+
+- In the project navigator, select your project.  
+- Select your app target, then go to the **Signing & Capabilities** tab.  
+- Click **+ Capability**.  
+- Search for **Near Field Communication Tag Reading** and add it to your project.  
+
+### Update Info.plist
+You must declare NFC usage in your **Info.plist** file to explain why the application requires access to this technology.
+
+- Open your **Info.plist** file.  
+- Add a new key: **Privacy – NFC Scan Usage Description** (`NFCReaderUsageDescription`).  
+- Set its value to a string explaining why the app requires NFC access. This text will be displayed to the user the first time the app attempts to use NFC.  
+
+### Build the Library
+The goal is to build an `.xcframework` bundle that can be added as a dependency to other projects.
+
+- Run the script `build_xcframework.sh`, located at `nfc-lib/nfc-lib/build_xcframework.sh`.  
+  - After execution, the project’s **build** folder will contain the file **nfclib.xcframework**.  
+
+### Add the Library to the Application
+- Open the project where you want to integrate the `nfclib` library.  
+- Select the project, then under **TARGETS**, choose the correct target.  
+- In the **General** tab of the target, find the **Frameworks and Libraries** section.  
+- Click **+ → Add Other… → Add Files… → Select nfclib.xcframework**.  
+
+The NFC library is now integrated into your application.  
+
+# Library Interfaces for ID Card Communication
+The library provides the following operation classes for ID card communication:
+- `OperationReadPublicData` - Reads cardholder information
+- `OperationReadCertificate` - Extracts authentication/signing certificates
+- `OperationSignHash` - Performs a signing operation using the provided hash and PIN
+- `OperationUnblockPin` - Unblock PIN1 or PIN2 using PUK
+- `OperationAuthenticateWithWebEID` - Web-eID authentication flow
+
+For a complete integration example, see the demo app's `CardOperations` protocol (`mvoting-nfc/nfc-demo/CardOperations.swift`) and its implementation in `Operator.swift`, which provides a convenient wrapper around these operations: 
+
+Returns whether NFC is supported on the device:  
+```swift
+public func isNFCSupported() -> Bool
+```
+
+Asynchronously reads public information about the cardholder from the card:
+```swift
+public func readPublicInfo(CAN: String) async throws -> CardInfo
+```
+
+Asynchronously reads the authentication certificate from the card:
+```swift
+public func readAuthenticationCertificate(CAN: String) async throws -> SecCertificate
+```
+
+Asynchronously reads the signing certificate from the card:
+```swift
+public func readSigningCertificate(CAN: String) async throws -> SecCertificate
+```
+
+Retrieves data required for WebEID authentication, using the provided credentials and challenge:
+```swift
+public func loadWebEIDAuthenticationData(CAN: String, pin1: String, challenge: String, origin: String) async throws -> WebEidData
+```
+
+Performs a signing operation using a precomputed hash (only SHA-384 supported) and the PIN2 code:
+```swift
+public func sign(CAN: String, hash: Data, pin2: String) async throws -> Data
+```
+
+Unblocks PIN1 using the PUK code and sets a new PIN:
+```swift
+public func unblockPin1(CAN: String, puk: String, newCode: String) async throws
+```
+
+Unblocks PIN2 using the PUK code and sets a new PIN:
+```swift
+public func unblockPin2(CAN: String, puk: String, newCode: String) async throws
+```

mvoting-nfc/nfc-demo.xcodeproj/project.pbxproj

@@ -14,6 +14,8 @@
 		139195AE2AFA29CC00EDA022 /* ContentView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 139195AD2AFA29CC00EDA022 /* ContentView.swift */; };
 		139195B02AFA29CD00EDA022 /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 139195AF2AFA29CD00EDA022 /* Assets.xcassets */; };
 		139195B32AFA29CD00EDA022 /* Preview Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 139195B22AFA29CD00EDA022 /* Preview Assets.xcassets */; };
+		1A0AA6F32E8EB4D2000B11FA /* CardOperations.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A0AA6F22E8EB4D2000B11FA /* CardOperations.swift */; };
+		1A0AA6F42E8EB4D2000B11FA /* Operator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A0AA6F12E8EB4D2000B11FA /* Operator.swift */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXCopyFilesBuildPhase section */
@@ -40,6 +42,8 @@
 		139195AF2AFA29CD00EDA022 /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
 		139195B22AFA29CD00EDA022 /* Preview Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = "Preview Assets.xcassets"; sourceTree = "<group>"; };
 		1392583F2B04B06A00AD38EA /* nfc-demo.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = "nfc-demo.entitlements"; sourceTree = "<group>"; };
+		1A0AA6F12E8EB4D2000B11FA /* Operator.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Operator.swift; sourceTree = "<group>"; };
+		1A0AA6F22E8EB4D2000B11FA /* CardOperations.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CardOperations.swift; sourceTree = "<group>"; };
 		5A2C028B2B060E9D00C6D249 /* SkSigningLib.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; path = SkSigningLib.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		5A9969882B03B9A4002A1060 /* nfc_lib.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; path = nfc_lib.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
@@ -83,6 +87,8 @@
 				13176D742B3193F70093D806 /* CardInfoView.swift */,
 				139195AF2AFA29CD00EDA022 /* Assets.xcassets */,
 				139195B12AFA29CD00EDA022 /* Preview Content */,
+				1A0AA6F12E8EB4D2000B11FA /* Operator.swift */,
+				1A0AA6F22E8EB4D2000B11FA /* CardOperations.swift */,
 			);
 			path = "nfc-demo";
 			sourceTree = "<group>";
@@ -182,6 +188,8 @@
 			files = (
 				139195AE2AFA29CC00EDA022 /* ContentView.swift in Sources */,
 				139195AC2AFA29CC00EDA022 /* nfc_demoApp.swift in Sources */,
+				1A0AA6F32E8EB4D2000B11FA /* CardOperations.swift in Sources */,
+				1A0AA6F42E8EB4D2000B11FA /* Operator.swift in Sources */,
 				13176D752B3193F70093D806 /* CardInfoView.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;

mvoting-nfc/nfc-demo/CardInfoView.swift

@@ -1,9 +1,21 @@
-//
-//  CardInfoView.swift
-//  nfc-demo
-//
-//  Created by Timo Kallaste on 19.12.2023.
-//
+/*
+ * Copyright 2017 - 2025 Riigi Infosüsteemi Amet
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ */
 
 import SwiftUI
 import nfclib

nfc-lib/nfc-lib/nfclib/CardOperations.swift → mvoting-nfc/nfc-demo/CardOperations.swift

@@ -1,15 +1,28 @@
-//
-//  CardOperations.swift
-//  nfclib
-//
-//  Created by Timo Kallaste on 31.01.2024.
-//
+/*
+ * Copyright 2017 - 2025 Riigi Infosüsteemi Amet
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ */
 
 /// `CardOperations` protocol
 ///
 /// This protocol defines a set of operations for interacting with a card,
 /// including NFC support checking, reading card information, and performing
 /// authentication and signing operations.
+import nfclib
 
 public protocol CardOperations {
 
@@ -59,4 +72,22 @@ public protocol CardOperations {
     /// - Returns: A `Data` object containing the signature.
     /// - Throws: An error if the signing operation fails.
     func sign(CAN: String, hash: Data, pin2: String) async throws -> Data
+
+    /// Unblocks a PIN1 using the PUK code.
+    ///
+    /// - Parameters:
+    ///   - CAN: A `String` representing the Card Access Number.
+    ///   - puk: The current PUK code for verification.
+    ///   - newCode: The new PIN code.
+    /// - Throws: An error if the operation fails.
+    func unblockPin1(CAN: String, puk: String, newCode: String) async throws
+
+    /// Unblocks a PIN2 using the PUK code.
+    ///
+    /// - Parameters:
+    ///   - CAN: A `String` representing the Card Access Number.
+    ///   - puk: The current PUK code for verification.
+    ///   - newCode: The new PIN code.
+    /// - Throws: An error if the operation fails.
+    func unblockPin2(CAN: String, puk: String, newCode: String) async throws
 }