@avieldr/react-native-rsa 1.0.0

package/android/src/main/java/com/rsa/core/RSASigner.kt

@@ -0,0 +1,70 @@
+package com.rsa.core
+
+import java.security.Signature
+import java.util.Base64
+
+/**
+ * RSA signing and verification operations for Android.
+ *
+ * Uses `java.security.Signature` with algorithm configurations from [Algorithms].
+ * All data crosses the bridge as base64 strings to avoid binary encoding issues.
+ *
+ * Supported padding modes:
+ *   - "pss"   — PSS (Probabilistic Signature Scheme) with configurable hash.
+ *               Salt length equals the hash output length. Available on API 24+.
+ *   - "pkcs1" — PKCS#1 v1.5 deterministic signatures
+ */
+object RSASigner {
+
+    /**
+     * Sign data with an RSA private key.
+     *
+     * @param dataBase64    The data to sign, encoded as base64
+     * @param privateKeyPEM The private key in PEM format (PKCS#1 or PKCS#8)
+     * @param padding       "pss" or "pkcs1"
+     * @param hash          "sha256", "sha1", "sha384", or "sha512"
+     * @return The signature encoded as base64
+     */
+    fun sign(dataBase64: String, privateKeyPEM: String, padding: String, hash: String): String {
+        val privateKey = KeyUtils.loadPrivateKey(privateKeyPEM)
+        val data = Base64.getDecoder().decode(dataBase64)
+        val algorithm = Algorithms.getSignatureAlgorithm(padding, hash)
+
+        val sig = Signature.getInstance(algorithm.name)
+        // PSS requires explicit parameter spec; PKCS#1 v1.5 has no params
+        if (algorithm.params != null) {
+            sig.setParameter(algorithm.params)
+        }
+        sig.initSign(privateKey)
+        sig.update(data)
+
+        val signature = sig.sign()
+        return Base64.getEncoder().encodeToString(signature)
+    }
+
+    /**
+     * Verify a signature against data using an RSA public key.
+     *
+     * @param dataBase64      The original data that was signed, encoded as base64
+     * @param signatureBase64 The signature to verify, encoded as base64
+     * @param publicKeyPEM    The public key in SPKI PEM format ("BEGIN PUBLIC KEY")
+     * @param padding         "pss" or "pkcs1" — must match the padding used during signing
+     * @param hash            "sha256", "sha1", "sha384", or "sha512" — must match signing hash
+     * @return true if the signature is valid, false otherwise
+     */
+    fun verify(dataBase64: String, signatureBase64: String, publicKeyPEM: String, padding: String, hash: String): Boolean {
+        val publicKey = KeyUtils.loadPublicKey(publicKeyPEM)
+        val data = Base64.getDecoder().decode(dataBase64)
+        val signatureBytes = Base64.getDecoder().decode(signatureBase64)
+        val algorithm = Algorithms.getSignatureAlgorithm(padding, hash)
+
+        val sig = Signature.getInstance(algorithm.name)
+        if (algorithm.params != null) {
+            sig.setParameter(algorithm.params)
+        }
+        sig.initVerify(publicKey)
+        sig.update(data)
+
+        return sig.verify(signatureBytes)
+    }
+}

package/ios/ASN1Utils.swift

@@ -0,0 +1,225 @@
+import Foundation
+
+/**
+ * ASN.1 DER encoding/decoding utilities for RSA key format conversions.
+ *
+ * Handles the low-level binary encoding needed to convert between
+ * PKCS#1 and PKCS#8 key formats, and to wrap raw public keys in SPKI.
+ *
+ * ASN.1 (Abstract Syntax Notation One) uses TLV (Tag-Length-Value) encoding:
+ *   - Tag:    identifies the data type (e.g. 0x02 = INTEGER, 0x30 = SEQUENCE)
+ *   - Length: number of bytes in the value
+ *   - Value:  the actual data bytes
+ */
+enum ASN1Utils {
+
+    // RSA algorithm OID: 1.2.840.113549.1.1.1
+    // This identifies the key as RSA in AlgorithmIdentifier structures
+    static let rsaOID: [UInt8] = [
+        0x06, 0x09, 0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x01, 0x01, 0x01
+    ]
+
+    // ASN.1 NULL value — used as the parameter in AlgorithmIdentifier (RSA has no params)
+    static let asn1Null: [UInt8] = [0x05, 0x00]
+
+    // MARK: - Length Encoding / Decoding
+
+    /**
+     * Encode a length value in ASN.1 DER format.
+     *
+     * DER length encoding:
+     *   - 0–127:     single byte (short form)
+     *   - 128–255:   0x81 followed by one byte
+     *   - 256–65535:  0x82 followed by two bytes (big-endian)
+     *   - 65536+:     0x83 followed by three bytes
+     */
+    static func encodeASN1Length(_ length: Int) -> Data {
+        if length < 128 {
+            return Data([UInt8(length)])
+        } else if length < 256 {
+            return Data([0x81, UInt8(length)])
+        } else if length < 65536 {
+            return Data([0x82, UInt8(length >> 8), UInt8(length & 0xFF)])
+        } else {
+            return Data([0x83, UInt8(length >> 16), UInt8((length >> 8) & 0xFF), UInt8(length & 0xFF)])
+        }
+    }
+
+    /**
+     * Decode an ASN.1 DER length field starting at `offset` in `bytes`.
+     *
+     * - Returns: Tuple of (decoded length or nil on error, number of bytes consumed)
+     */
+    static func decodeASN1Length(_ bytes: [UInt8], _ offset: Int) -> (Int?, Int) {
+        guard offset < bytes.count else { return (nil, 0) }
+        let first = bytes[offset]
+        if first < 128 {
+            return (Int(first), 1)
+        }
+        let numBytes = Int(first & 0x7F)
+        guard numBytes > 0, offset + numBytes < bytes.count else { return (nil, 0) }
+        var length = 0
+        for i in 0..<numBytes {
+            length = (length << 8) | Int(bytes[offset + 1 + i])
+        }
+        return (length, 1 + numBytes)
+    }
+
+    // MARK: - Structure Builders
+
+    /// Wrap arbitrary data in an ASN.1 SEQUENCE (tag 0x30 + length + data).
+    static func wrapInSequence(_ data: Data) -> Data {
+        var result = Data([0x30])
+        result.append(encodeASN1Length(data.count))
+        result.append(data)
+        return result
+    }
+
+    /**
+     * Wrap a raw PKCS#1 public key in an SPKI (SubjectPublicKeyInfo) structure.
+     *
+     * iOS `SecKeyCopyExternalRepresentation` returns raw PKCS#1 for RSA public keys,
+     * but the standard PEM "PUBLIC KEY" format expects SPKI wrapping.
+     *
+     * SPKI layout:
+     *   SEQUENCE {
+     *     algorithm  AlgorithmIdentifier { OID, NULL },
+     *     publicKey  BIT STRING (0x00 unused-bits prefix + raw key bytes)
+     *   }
+     */
+    static func wrapPublicKeyInSPKI(rawKeyData: Data) -> Data {
+        // AlgorithmIdentifier SEQUENCE { rsaOID, NULL }
+        var algId = Data()
+        algId.append(contentsOf: rsaOID)
+        algId.append(contentsOf: asn1Null)
+        let algIdSeq = wrapInSequence(algId)
+
+        // BIT STRING: tag + length + 0x00 (zero unused bits) + raw key data
+        var bitStringContent = Data([0x00])
+        bitStringContent.append(rawKeyData)
+
+        var bitString = Data([0x03]) // BIT STRING tag
+        bitString.append(encodeASN1Length(bitStringContent.count))
+        bitString.append(bitStringContent)
+
+        // Combine into outer SEQUENCE
+        var spkiContent = Data()
+        spkiContent.append(algIdSeq)
+        spkiContent.append(bitString)
+
+        return wrapInSequence(spkiContent)
+    }
+
+    /**
+     * Wrap PKCS#1 private key data inside a PKCS#8 PrivateKeyInfo structure.
+     *
+     * PKCS#8 PrivateKeyInfo layout:
+     *   SEQUENCE {
+     *     version    INTEGER (0),
+     *     algorithm  AlgorithmIdentifier { OID, NULL },
+     *     privateKey OCTET STRING containing PKCS#1 bytes
+     *   }
+     */
+    static func wrapPkcs1InPkcs8(pkcs1Data: Data) -> Data {
+        var content = Data()
+
+        // version INTEGER 0
+        content.append(contentsOf: [0x02, 0x01, 0x00] as [UInt8])
+
+        // AlgorithmIdentifier SEQUENCE { rsaOID, NULL }
+        var algId = Data()
+        algId.append(contentsOf: rsaOID)
+        algId.append(contentsOf: asn1Null)
+        content.append(wrapInSequence(algId))
+
+        // OCTET STRING wrapping the raw PKCS#1 bytes
+        content.append(Data([0x04]))
+        content.append(encodeASN1Length(pkcs1Data.count))
+        content.append(pkcs1Data)
+
+        return wrapInSequence(content)
+    }
+
+    /**
+     * Extract the inner PKCS#1 private key data from a PKCS#8 wrapper.
+     *
+     * Walks the PKCS#8 structure:
+     *   SEQUENCE → skip version INTEGER → skip AlgorithmIdentifier → read OCTET STRING
+     *
+     * Returns the original data unchanged if parsing fails.
+     */
+    static func extractPkcs1FromPkcs8(pkcs8Data: Data) -> Data {
+        let bytes = [UInt8](pkcs8Data)
+        var offset = 0
+
+        // Outer SEQUENCE tag + length
+        guard offset < bytes.count, bytes[offset] == 0x30 else { return pkcs8Data }
+        offset += 1
+        let (_, seqLenBytes) = decodeASN1Length(bytes, offset)
+        offset += seqLenBytes
+
+        // version INTEGER — skip over it
+        guard offset < bytes.count, bytes[offset] == 0x02 else { return pkcs8Data }
+        offset += 1
+        let (verLen, verLenBytes) = decodeASN1Length(bytes, offset)
+        offset += verLenBytes + (verLen ?? 0)
+
+        // AlgorithmIdentifier SEQUENCE — skip over it
+        guard offset < bytes.count, bytes[offset] == 0x30 else { return pkcs8Data }
+        offset += 1
+        let (algLen, algLenBytes) = decodeASN1Length(bytes, offset)
+        offset += algLenBytes + (algLen ?? 0)
+
+        // OCTET STRING containing the PKCS#1 private key
+        guard offset < bytes.count, bytes[offset] == 0x04 else { return pkcs8Data }
+        offset += 1
+        let (octetLen, octetLenBytes) = decodeASN1Length(bytes, offset)
+        offset += octetLenBytes
+
+        guard let len = octetLen, offset + len <= bytes.count else { return pkcs8Data }
+        return Data(bytes[offset..<(offset + len)])
+    }
+
+    /**
+     * Strip the SPKI (SubjectPublicKeyInfo) wrapper to get the raw PKCS#1 public key.
+     *
+     * iOS `SecKeyCreateWithData` expects raw PKCS#1 public key data, not SPKI.
+     * Standard PEM "PUBLIC KEY" files contain SPKI, so we need to unwrap.
+     *
+     * SPKI layout:
+     *   SEQUENCE {
+     *     AlgorithmIdentifier SEQUENCE { ... },
+     *     BIT STRING (0x00 prefix + raw key bytes)
+     *   }
+     */
+    static func stripSPKIHeader(spkiData: Data) -> Data {
+        let bytes = [UInt8](spkiData)
+        var offset = 0
+
+        // Outer SEQUENCE
+        guard offset < bytes.count, bytes[offset] == 0x30 else { return spkiData }
+        offset += 1
+        let (_, seqLenBytes) = decodeASN1Length(bytes, offset)
+        offset += seqLenBytes
+
+        // AlgorithmIdentifier SEQUENCE — skip over it
+        guard offset < bytes.count, bytes[offset] == 0x30 else { return spkiData }
+        offset += 1
+        let (algLen, algLenBytes) = decodeASN1Length(bytes, offset)
+        offset += algLenBytes + (algLen ?? 0)
+
+        // BIT STRING
+        guard offset < bytes.count, bytes[offset] == 0x03 else { return spkiData }
+        offset += 1
+        let (bitLen, bitLenBytes) = decodeASN1Length(bytes, offset)
+        offset += bitLenBytes
+
+        // Skip the "unused bits" byte (always 0x00 for RSA keys)
+        guard offset < bytes.count, bytes[offset] == 0x00 else { return spkiData }
+        offset += 1
+
+        // The remaining bytes are the raw PKCS#1 public key
+        guard let len = bitLen, offset + len - 1 <= bytes.count else { return spkiData }
+        return Data(bytes[offset..<(offset + len - 1)])
+    }
+}

package/ios/Algorithms.swift

@@ -0,0 +1,89 @@
+import Foundation
+import Security
+
+/**
+ * Maps (padding, hash) option strings to `SecKeyAlgorithm` values.
+ *
+ * This provides a single lookup point so that RSACipher and RSASigner don't
+ * need to duplicate algorithm selection logic.
+ *
+ * Supported combinations:
+ *   Encryption (encrypt/decrypt):
+ *     - "pkcs1"  → rsaEncryptionPKCS1
+ *     - "oaep"   → rsaEncryptionOAEPSHA{N}
+ *
+ *   Signature (sign/verify):
+ *     - "pkcs1"  → rsaSignatureMessagePKCS1v15SHA{N}
+ *     - "pss"    → rsaSignatureMessagePSSSHA{N}
+ *
+ * The "Message" variants (rsaSignatureMessage…) hash the input data internally,
+ * so callers pass the raw message — not a pre-computed digest.
+ */
+enum Algorithms {
+
+    /**
+     * Look up the SecKeyAlgorithm for an encrypt/decrypt operation.
+     *
+     * - Parameters:
+     *   - padding: "pkcs1" or "oaep"
+     *   - hash:    "sha1", "sha256", "sha384", or "sha512" (only used with OAEP)
+     * - Throws: If the padding or hash is unsupported
+     */
+    static func encryptionAlgorithm(padding: String, hash: String) throws -> SecKeyAlgorithm {
+        switch padding {
+        case "pkcs1":
+            return .rsaEncryptionPKCS1
+        case "oaep":
+            switch hash {
+            case "sha1":   return .rsaEncryptionOAEPSHA1
+            case "sha256": return .rsaEncryptionOAEPSHA256
+            case "sha384": return .rsaEncryptionOAEPSHA384
+            case "sha512": return .rsaEncryptionOAEPSHA512
+            default:
+                throw NSError(domain: "Algorithms", code: 1,
+                              userInfo: [NSLocalizedDescriptionKey: "Unsupported hash for OAEP: \(hash)"])
+            }
+        default:
+            throw NSError(domain: "Algorithms", code: 2,
+                          userInfo: [NSLocalizedDescriptionKey: "Unsupported encryption padding: \(padding)"])
+        }
+    }
+
+    /**
+     * Look up the SecKeyAlgorithm for a sign/verify operation.
+     *
+     * - Parameters:
+     *   - padding: "pkcs1" or "pss"
+     *   - hash:    "sha1", "sha256", "sha384", or "sha512"
+     * - Throws: If the padding or hash is unsupported
+     */
+    static func signatureAlgorithm(padding: String, hash: String) throws -> SecKeyAlgorithm {
+        switch padding {
+        case "pkcs1":
+            // PKCS#1 v1.5 deterministic signatures
+            switch hash {
+            case "sha1":   return .rsaSignatureMessagePKCS1v15SHA1
+            case "sha256": return .rsaSignatureMessagePKCS1v15SHA256
+            case "sha384": return .rsaSignatureMessagePKCS1v15SHA384
+            case "sha512": return .rsaSignatureMessagePKCS1v15SHA512
+            default:
+                throw NSError(domain: "Algorithms", code: 3,
+                              userInfo: [NSLocalizedDescriptionKey: "Unsupported hash for PKCS#1 signature: \(hash)"])
+            }
+        case "pss":
+            // PSS probabilistic signatures
+            switch hash {
+            case "sha1":   return .rsaSignatureMessagePSSSHA1
+            case "sha256": return .rsaSignatureMessagePSSSHA256
+            case "sha384": return .rsaSignatureMessagePSSSHA384
+            case "sha512": return .rsaSignatureMessagePSSSHA512
+            default:
+                throw NSError(domain: "Algorithms", code: 4,
+                              userInfo: [NSLocalizedDescriptionKey: "Unsupported hash for PSS signature: \(hash)"])
+            }
+        default:
+            throw NSError(domain: "Algorithms", code: 5,
+                          userInfo: [NSLocalizedDescriptionKey: "Unsupported signature padding: \(padding)"])
+        }
+    }
+}

package/ios/KeyUtils.swift

@@ -0,0 +1,125 @@
+import Foundation
+import Security
+
+/**
+ * PEM parsing and key loading utilities for iOS.
+ *
+ * Handles conversion between PEM-encoded key strings and SecKey objects.
+ * Supports both PKCS#1 ("BEGIN RSA PRIVATE KEY") and PKCS#8 ("BEGIN PRIVATE KEY")
+ * private key formats, and SPKI ("BEGIN PUBLIC KEY") public key format.
+ */
+enum KeyUtils {
+
+    /**
+     * Extract the base64-encoded content from a PEM string,
+     * stripping the header/footer lines.
+     */
+    static func extractBase64(from pem: String) -> String {
+        return pem.components(separatedBy: "\n")
+            .filter { !$0.hasPrefix("-----") }
+            .joined()
+    }
+
+    /**
+     * Format raw DER data as a PEM string with the given header.
+     *
+     * - Parameters:
+     *   - data:   The raw DER-encoded key data
+     *   - header: The PEM header label (e.g. "RSA PRIVATE KEY", "PRIVATE KEY", "PUBLIC KEY")
+     * - Returns: A properly formatted PEM string with 64-char line wrapping
+     */
+    static func toPEM(data: Data, header: String) -> String {
+        let base64 = data.base64EncodedString()
+        let lines = base64.chunked(into: 64).joined(separator: "\n")
+        return "-----BEGIN \(header)-----\n\(lines)\n-----END \(header)-----"
+    }
+
+    /**
+     * Load an RSA private key from a PEM string as a SecKey.
+     *
+     * Accepts both PKCS#1 and PKCS#8 formats:
+     *   - PKCS#1 ("BEGIN RSA PRIVATE KEY"): used directly, since SecKeyCreateWithData
+     *     expects raw PKCS#1 for RSA private keys
+     *   - PKCS#8 ("BEGIN PRIVATE KEY"): extracts the inner PKCS#1 data first
+     *
+     * - Throws: If base64 decoding fails or the key cannot be imported
+     */
+    static func loadPrivateKey(pem: String) throws -> SecKey {
+        let base64 = extractBase64(from: pem)
+        guard let derData = Data(base64Encoded: base64) else {
+            throw NSError(domain: "KeyUtils", code: 1,
+                          userInfo: [NSLocalizedDescriptionKey: "Invalid base64 encoding in private key PEM"])
+        }
+
+        // SecKeyCreateWithData expects raw PKCS#1 for RSA keys
+        let pkcs1Data: Data
+        if pem.contains("BEGIN RSA PRIVATE KEY") {
+            pkcs1Data = derData
+        } else if pem.contains("BEGIN PRIVATE KEY") {
+            // PKCS#8 wraps PKCS#1 — extract the inner key
+            pkcs1Data = ASN1Utils.extractPkcs1FromPkcs8(pkcs8Data: derData)
+        } else {
+            throw NSError(domain: "KeyUtils", code: 2,
+                          userInfo: [NSLocalizedDescriptionKey: "Unrecognized private key PEM format"])
+        }
+
+        let attributes: [String: Any] = [
+            kSecAttrKeyType as String: kSecAttrKeyTypeRSA,
+            kSecAttrKeyClass as String: kSecAttrKeyClassPrivate,
+        ]
+
+        var error: Unmanaged<CFError>?
+        guard let key = SecKeyCreateWithData(pkcs1Data as CFData, attributes as CFDictionary, &error) else {
+            let errorMessage = error?.takeRetainedValue().localizedDescription ?? "Unknown error"
+            throw NSError(domain: "KeyUtils", code: 3,
+                          userInfo: [NSLocalizedDescriptionKey: "Failed to import private key: \(errorMessage)"])
+        }
+        return key
+    }
+
+    /**
+     * Load an RSA public key from a PEM string as a SecKey.
+     *
+     * Expects SPKI ("BEGIN PUBLIC KEY") format. Since SecKeyCreateWithData
+     * expects raw PKCS#1 public key data (not SPKI), the SPKI header is
+     * stripped automatically.
+     *
+     * - Throws: If base64 decoding fails or the key cannot be imported
+     */
+    static func loadPublicKey(pem: String) throws -> SecKey {
+        let base64 = extractBase64(from: pem)
+        guard let derData = Data(base64Encoded: base64) else {
+            throw NSError(domain: "KeyUtils", code: 4,
+                          userInfo: [NSLocalizedDescriptionKey: "Invalid base64 encoding in public key PEM"])
+        }
+
+        // SecKeyCreateWithData expects raw PKCS#1 public key, not SPKI
+        let rawKeyData = ASN1Utils.stripSPKIHeader(spkiData: derData)
+
+        let attributes: [String: Any] = [
+            kSecAttrKeyType as String: kSecAttrKeyTypeRSA,
+            kSecAttrKeyClass as String: kSecAttrKeyClassPublic,
+        ]
+
+        var error: Unmanaged<CFError>?
+        guard let key = SecKeyCreateWithData(rawKeyData as CFData, attributes as CFDictionary, &error) else {
+            let errorMessage = error?.takeRetainedValue().localizedDescription ?? "Unknown error"
+            throw NSError(domain: "KeyUtils", code: 5,
+                          userInfo: [NSLocalizedDescriptionKey: "Failed to import public key: \(errorMessage)"])
+        }
+        return key
+    }
+}
+
+// MARK: - String Extension for PEM Line Wrapping
+
+extension String {
+    /// Split a string into chunks of the given size (used for 64-char PEM line wrapping).
+    func chunked(into size: Int) -> [String] {
+        return stride(from: 0, to: count, by: size).map {
+            let start = index(startIndex, offsetBy: $0)
+            let end = index(start, offsetBy: min(size, count - $0))
+            return String(self[start..<end])
+        }
+    }
+}

package/ios/RSACipher.swift

@@ -0,0 +1,77 @@
+import Foundation
+import Security
+
+/**
+ * RSA encryption and decryption operations for iOS.
+ *
+ * Uses the Security framework's `SecKeyCreateEncryptedData` / `SecKeyCreateDecryptedData`.
+ * All data crosses the bridge as base64 strings to avoid binary encoding issues.
+ *
+ * Supported padding modes:
+ *   - "oaep"  — OAEP (Optimal Asymmetric Encryption Padding) with configurable hash
+ *   - "pkcs1" — PKCS#1 v1.5 padding (legacy, not recommended for new applications)
+ *
+ * Exposed to Objective-C via `@objc` for the React Native bridge.
+ */
+@objc public class RSACipher: NSObject {
+
+    /**
+     * Encrypt data with an RSA public key.
+     *
+     * - Parameters:
+     *   - dataBase64:   The plaintext data encoded as base64
+     *   - publicKeyPEM: The public key in SPKI PEM format ("BEGIN PUBLIC KEY")
+     *   - padding:      "oaep" or "pkcs1"
+     *   - hash:         "sha256", "sha1", "sha384", or "sha512" (used with OAEP)
+     * - Throws: If the input is invalid, key loading fails, or encryption fails
+     * - Returns: The ciphertext encoded as base64
+     */
+    @objc public static func encrypt(dataBase64: String, publicKeyPEM: String, padding: String, hash: String) throws -> String {
+        guard let data = Data(base64Encoded: dataBase64) else {
+            throw NSError(domain: "RSACipher", code: 1,
+                          userInfo: [NSLocalizedDescriptionKey: "Invalid base64 input data"])
+        }
+
+        let publicKey = try KeyUtils.loadPublicKey(pem: publicKeyPEM)
+        let algorithm = try Algorithms.encryptionAlgorithm(padding: padding, hash: hash)
+
+        var error: Unmanaged<CFError>?
+        guard let encryptedData = SecKeyCreateEncryptedData(publicKey, algorithm, data as CFData, &error) as Data? else {
+            let errorMessage = error?.takeRetainedValue().localizedDescription ?? "Unknown error"
+            throw NSError(domain: "RSACipher", code: 2,
+                          userInfo: [NSLocalizedDescriptionKey: "Encryption failed: \(errorMessage)"])
+        }
+
+        return encryptedData.base64EncodedString()
+    }
+
+    /**
+     * Decrypt data with an RSA private key.
+     *
+     * - Parameters:
+     *   - dataBase64:    The ciphertext encoded as base64
+     *   - privateKeyPEM: The private key in PEM format (PKCS#1 or PKCS#8)
+     *   - padding:       "oaep" or "pkcs1" — must match the padding used during encryption
+     *   - hash:          "sha256", "sha1", "sha384", or "sha512" — must match encryption hash
+     * - Throws: If the input is invalid, key loading fails, or decryption fails
+     * - Returns: The decrypted plaintext encoded as base64
+     */
+    @objc public static func decrypt(dataBase64: String, privateKeyPEM: String, padding: String, hash: String) throws -> String {
+        guard let data = Data(base64Encoded: dataBase64) else {
+            throw NSError(domain: "RSACipher", code: 3,
+                          userInfo: [NSLocalizedDescriptionKey: "Invalid base64 input data"])
+        }
+
+        let privateKey = try KeyUtils.loadPrivateKey(pem: privateKeyPEM)
+        let algorithm = try Algorithms.encryptionAlgorithm(padding: padding, hash: hash)
+
+        var error: Unmanaged<CFError>?
+        guard let decryptedData = SecKeyCreateDecryptedData(privateKey, algorithm, data as CFData, &error) as Data? else {
+            let errorMessage = error?.takeRetainedValue().localizedDescription ?? "Unknown error"
+            throw NSError(domain: "RSACipher", code: 4,
+                          userInfo: [NSLocalizedDescriptionKey: "Decryption failed: \(errorMessage)"])
+        }
+
+        return decryptedData.base64EncodedString()
+    }
+}