@icure/api 6.3.1 → 7.0.0-beta.0

package/icc-x-api/crypto/KeyRecovery.ts

@@ -0,0 +1,261 @@
+import { DataOwnerWithType, IccDataOwnerXApi } from '../icc-data-owner-x-api'
+import { KeyPair } from './RSA'
+import { CryptoPrimitives } from './CryptoPrimitives'
+import { BaseExchangeKeysManager } from './BaseExchangeKeysManager'
+import { hex2ua, ua2hex } from '../utils'
+import { fingerprintToPublicKeysMapOf } from './utils'
+
+/**
+ * @internal this class is intended only for internal use and may be changed without notice.
+ *
+ */
+export class KeyRecovery {
+  private readonly primitives: CryptoPrimitives
+  private readonly baseExchangeKeysManager: BaseExchangeKeysManager
+  private readonly dataOwnerApi: IccDataOwnerXApi
+
+  constructor(primitives: CryptoPrimitives, baseExchangeKeysManager: BaseExchangeKeysManager, dataOwnerApi: IccDataOwnerXApi) {
+    this.primitives = primitives
+    this.baseExchangeKeysManager = baseExchangeKeysManager
+    this.dataOwnerApi = dataOwnerApi
+  }
+
+  /**
+   * Attempt to recover private keys of a data owner using all available key recovery methods and all available private keys. The method will
+   * automatically try to use newly recovered key pairs to recover additional key pairs.
+   * @param dataOwner a data owner.
+   * @param knownKeys keys available for the data owner.
+   * @return new key pairs (exclude already known pairs) which could be recovered using the known keys.
+   */
+  async recoverKeys(
+    dataOwner: DataOwnerWithType,
+    knownKeys: { [pubKeyFp: string]: KeyPair<CryptoKey> }
+  ): Promise<{ [pubKeyFp: string]: KeyPair<CryptoKey> }> {
+    const selfPublicKeys = Array.from(this.dataOwnerApi.getHexPublicKeysOf(dataOwner.dataOwner))
+    const knownKeysFpSet = new Set(Object.keys(knownKeys))
+    const missingKeysFpSet = new Set(selfPublicKeys.map((x) => x.slice(-32)).filter((x) => !knownKeysFpSet.has(x)))
+
+    const recoveryFunctions = [this.recoverFromTransferKeys.bind(this), this.recoverFromShamirSplitKeys.bind(this)]
+    let allPrivateKeys: { [pubKeyFingerprint: string]: KeyPair<CryptoKey> } = { ...knownKeys }
+    let foundNewPrivateKeys = true
+
+    while (missingKeysFpSet.size > 0 && foundNewPrivateKeys) {
+      // TODO for each recovered verify correct association with public key
+      foundNewPrivateKeys = false
+      for (const recover of recoveryFunctions) {
+        const recovered = await recover(dataOwner, allPrivateKeys, missingKeysFpSet)
+        const validatedRecovered: { [fp: string]: KeyPair<CryptoKey> } = {}
+        for (const [fp, keyPair] of Object.entries(recovered)) {
+          const valid = await this.primitives.RSA.checkKeyPairValidity(keyPair)
+          if (valid) {
+            validatedRecovered[fp] = keyPair
+          }
+        }
+        if (Object.keys(validatedRecovered).length > 0) {
+          foundNewPrivateKeys = true
+          Object.keys(validatedRecovered).forEach((fp) => missingKeysFpSet.delete(fp))
+          allPrivateKeys = { ...allPrivateKeys, ...validatedRecovered }
+        }
+      }
+    }
+
+    return Object.fromEntries(Object.entries(allPrivateKeys).filter(([keyFp]) => !knownKeysFpSet.has(keyFp)))
+  }
+
+  /*TODO?
+   * Ask access back suggestion: if by getting access back to an exchange key with another data owner I may recover additional keys we could suggest
+   * to ask for access back to that data owner.
+   */
+
+  private async recoverFromShamirSplitKeys(
+    dataOwner: DataOwnerWithType,
+    allKeys: { [pubKeyFingerprint: string]: KeyPair<CryptoKey> },
+    missingKeysFp: Set<string>
+  ): Promise<{ [pubKeyFingerprint: string]: KeyPair<CryptoKey> }> {
+    if (
+      dataOwner.dataOwner.publicKey &&
+      dataOwner.dataOwner.privateKeyShamirPartitions &&
+      Object.keys(dataOwner.dataOwner.privateKeyShamirPartitions).length > 0
+    ) {
+      const selfId = dataOwner.dataOwner.id!
+      const shamirSplits: { [keyPairFp: string]: { [delegateId: string]: string } } = {
+        [dataOwner.dataOwner.publicKey!.slice(-32)]: dataOwner.dataOwner.privateKeyShamirPartitions!,
+      }
+      const delegatesOfSplits = Array.from(
+        new Set(
+          Object.entries(shamirSplits).flatMap(([splitKeyFp, splitKeyData]) => (missingKeysFp.has(splitKeyFp) ? Object.keys(splitKeyData) : []))
+        )
+      )
+      const exchangeKeys: { [delegateId: string]: CryptoKey[] } = {}
+      for (const delegate of delegatesOfSplits) {
+        const currExchangeKeys = await this.baseExchangeKeysManager.getEncryptedExchangeKeysFor(selfId, delegate)
+        exchangeKeys[delegate] = (await this.baseExchangeKeysManager.tryDecryptExchangeKeys(currExchangeKeys, allKeys)).successfulDecryptions
+      }
+      return await this.recoverWithSplits(dataOwner, shamirSplits, exchangeKeys)
+    } else return {}
+  }
+
+  private async recoverWithSplits(
+    dataOwner: DataOwnerWithType,
+    splits: { [keyPairFp: string]: { [delegateId: string]: string } },
+    exchangeKeys: { [delegateId: string]: CryptoKey[] }
+  ): Promise<{ [pubKeyFingerprint: string]: KeyPair<CryptoKey> }> {
+    const res: { [pubKeyFingerprint: string]: KeyPair<CryptoKey> } = {}
+    const keysByFp = fingerprintToPublicKeysMapOf(dataOwner.dataOwner)
+    for (const [fp, split] of Object.entries(splits)) {
+      const recovered = await this.tryRecoverSplitPrivate(split, exchangeKeys)
+      if (recovered) {
+        const pub = keysByFp[fp]
+        if (!pub) {
+          console.warn(`Missing public key for fingerprint ${fp} of recovered shamir key.`)
+        } else {
+          try {
+            res[fp] = {
+              privateKey: recovered,
+              publicKey: await this.primitives.RSA.importKey('spki', hex2ua(pub), ['encrypt']),
+            }
+          } catch (e) {
+            console.warn(`Failed to import public key ${pub}`, e)
+          }
+        }
+      }
+    }
+    return res
+  }
+
+  private async tryRecoverSplitPrivate(
+    split: { [delegateId: string]: string },
+    exchangeKeys: { [delegateId: string]: CryptoKey[] }
+  ): Promise<CryptoKey | undefined> {
+    const splitsCount = Object.keys(split).length
+    if (splitsCount === 1) {
+      // Not sure about the key nor if the key is accessible
+      const [delegate, encryptedKey] = Object.entries(split)[0]
+      for (const exchangeKey of exchangeKeys[delegate] ?? []) {
+        try {
+          const decrypted = await this.primitives.AES.decrypt(exchangeKey, hex2ua(encryptedKey))
+          const importedKey = await this.primitives.RSA.importKey('pkcs8', decrypted, ['decrypt'])
+          if (importedKey) return importedKey
+        } catch (e) {}
+      }
+      return undefined
+    } else {
+      const decryptedSplits: string[] = []
+      for (const delegateAndEncryptedSplit of Object.entries(split)) {
+        const decrypted = await this.tryDecryptSplitPiece(delegateAndEncryptedSplit, exchangeKeys, splitsCount)
+        if (decrypted) decryptedSplits.push(ua2hex(decrypted).slice(1)) // Drop padding
+      }
+      try {
+        const combinedKey = hex2ua(this.primitives.shamir.combine(decryptedSplits))
+        return await this.primitives.RSA.importKey('pkcs8', combinedKey, ['decrypt'])
+      } catch (e) {
+        // Could be not enough splits decrypted
+        return undefined
+      }
+    }
+  }
+
+  private async tryDecryptSplitPiece(
+    delegateAndEncryptedSplit: [string, string],
+    exchangeKeys: { [delegateId: string]: CryptoKey[] },
+    splitsCount: number
+  ): Promise<ArrayBuffer | undefined> {
+    const [delegate, encryptedPiece] = delegateAndEncryptedSplit
+    for (const exchangeKey of exchangeKeys[delegate] ?? []) {
+      try {
+        const decrypted = await this.primitives.AES.decrypt(exchangeKey, hex2ua(encryptedPiece))
+        if (this.validateDecryptedSplit(decrypted, splitsCount)) return decrypted
+      } catch (e) {}
+    }
+    return undefined
+  }
+
+  private validateDecryptedSplit(decryptedSplit: ArrayBuffer, splitsCount: number): boolean {
+    // Normally shamir split starts with 8 followed by the index of the split in hexadecimal.
+    // However, we pad with an extra 'f' at the beginning
+    const decryptedHex = ua2hex(decryptedSplit)
+    if (decryptedHex[0] !== 'f' || decryptedHex[1] !== '8') return false
+    try {
+      const splitIndex = parseInt(decryptedHex.slice(2, 4), 16)
+      return splitIndex > 0 && splitIndex <= splitsCount
+    } catch (e) {
+      return false
+    }
+  }
+
+  private async recoverFromTransferKeys(
+    dataOwner: DataOwnerWithType,
+    allKeys: { [pubKeyFingerprint: string]: KeyPair<CryptoKey> },
+    missingKeysFp: Set<string>
+  ): Promise<{ [pubKeyFingerprint: string]: KeyPair<CryptoKey> }> {
+    const publicKeyFingerprintToPublicKey = fingerprintToPublicKeysMapOf(dataOwner.dataOwner)
+    const missingKeysTransferData: { [recoverableKeyPubFp: string]: { publicKey: string; encryptedPrivateKey: Set<string> } } = {}
+    Object.values(dataOwner.dataOwner.transferKeys ?? {}).forEach((transferKeysByEncryptor) => {
+      Object.entries(transferKeysByEncryptor).forEach(([transferToPublicKey, transferPrivateKeyEncrypted]) => {
+        const transferToPublicKeyFp = transferToPublicKey.slice(-32) // We are not sure if transfer public key will be a fp or not
+        if (missingKeysFp.has(transferToPublicKeyFp)) {
+          const existingEntryValue = missingKeysTransferData[transferToPublicKeyFp]
+          if (existingEntryValue) {
+            existingEntryValue.encryptedPrivateKey.add(transferPrivateKeyEncrypted)
+          } else {
+            const fullPublicKey = publicKeyFingerprintToPublicKey[transferToPublicKeyFp]
+            if (fullPublicKey) {
+              missingKeysTransferData[transferToPublicKeyFp] = {
+                publicKey: fullPublicKey,
+                encryptedPrivateKey: new Set([transferPrivateKeyEncrypted]),
+              }
+            } else {
+              console.warn('Invalid data owner: there is a transfer key for an unknown public key')
+            }
+          }
+        }
+      })
+    })
+
+    const { successfulDecryptions: availableExchangeKeys } = await this.baseExchangeKeysManager.tryDecryptExchangeKeys(
+      await this.baseExchangeKeysManager.getEncryptedExchangeKeysFor(dataOwner.dataOwner.id!, dataOwner.dataOwner.id!),
+      allKeys
+    )
+
+    return Object.entries(missingKeysTransferData).reduce(async (acc, [recoverableKeyPubFp, transferData]) => {
+      const awaitedAcc = await acc
+      const decryptedTransferData = await this.tryDecryptTransferData(transferData, availableExchangeKeys)
+      if (decryptedTransferData != undefined) {
+        return { ...awaitedAcc, [recoverableKeyPubFp]: decryptedTransferData }
+      } else return awaitedAcc
+    }, Promise.resolve({} as { [pubKeyFingerprint: string]: KeyPair<CryptoKey> }))
+  }
+
+  private async tryDecryptTransferData(
+    transferData: { publicKey: string; encryptedPrivateKey: Set<string> },
+    availableExchangeKeys: CryptoKey[]
+  ): Promise<KeyPair<CryptoKey> | undefined> {
+    for (const encryptedTransferKey of transferData.encryptedPrivateKey) {
+      const decryptedTransferKey = await this.tryDecryptTransferKey(encryptedTransferKey, availableExchangeKeys)
+      if (decryptedTransferKey != undefined)
+        return {
+          privateKey: decryptedTransferKey,
+          publicKey: await this.primitives.RSA.importKey('spki', hex2ua(transferData.publicKey), ['encrypt']),
+        }
+    }
+    return undefined
+  }
+
+  // attempt to decrypt a transfer key in pkcs8 using any of the provided exchange keys
+  private async tryDecryptTransferKey(
+    encryptedTransferKey: string, // in hex format
+    exchangeKeys: CryptoKey[]
+  ): Promise<CryptoKey | undefined> {
+    const encryptedKeyBytes = hex2ua(encryptedTransferKey)
+    for (const exchangeKey of exchangeKeys) {
+      try {
+        const decryptedKeyData = await this.primitives.AES.decrypt(exchangeKey, encryptedKeyBytes)
+        const importedPrivateKey = await this.primitives.RSA.importPrivateKey('pkcs8', decryptedKeyData)
+        if (importedPrivateKey != undefined) return importedPrivateKey
+      } catch (e) {
+        /* failure is a valid possibility: we don't know the correct key to use */
+      }
+    }
+    return undefined
+  }
+}

package/icc-x-api/crypto/LegacyCryptoStrategies.ts

@@ -0,0 +1,27 @@
+import { CryptoStrategies } from './CryptoStrategies'
+import { DataOwner } from '../icc-data-owner-x-api'
+import { CryptoPrimitives } from './CryptoPrimitives'
+import { KeyPair } from './RSA'
+
+/**
+ * Implementation of crypto strategies which should closely resemble a basic legacy behaviour of the crypto api:
+ * - Automatically creates a new key if there is no verified key available
+ * - Fully trusts the public keys coming from the server for the creation of aes exchange keys to delegates
+ * - Never trust the own public keys coming from the server: this way the sdk will not automatically create data for key recovery.
+ */
+export class LegacyCryptoStrategies implements CryptoStrategies {
+  generateNewKeyForDataOwner(self: DataOwner, cryptoPrimitives: CryptoPrimitives): Promise<KeyPair<CryptoKey> | boolean> {
+    return Promise.resolve(true)
+  }
+
+  recoverAndVerifySelfHierarchyKeys(
+    keysData: { dataOwner: DataOwner; unknownKeys: string[]; unavailableKeys: string[] }[],
+    cryptoPrimitives: CryptoPrimitives
+  ): Promise<{ [p: string]: { recoveredKeys: { [p: string]: KeyPair<CryptoKey> }; keyAuthenticity: { [p: string]: boolean } } }> {
+    return Promise.resolve(Object.fromEntries(keysData.map(({ dataOwner }) => [dataOwner.id, { recoveredKeys: {}, keyAuthenticity: {} }])))
+  }
+
+  verifyDelegatePublicKeys(delegate: DataOwner, publicKeys: string[], cryptoPrimitives: CryptoPrimitives): Promise<string[]> {
+    return Promise.resolve(publicKeys)
+  }
+}

package/icc-x-api/crypto/RSA.ts

@@ -0,0 +1,180 @@
+import { ua2utf8, utf8_2ua } from '../utils'
+
+/**
+ * Represents an RSA KeyPair in a generic format.
+ */
+export type KeyPair<T> = { publicKey: T; privateKey: T }
+
+export class RSAUtils {
+  /********* RSA Config **********/
+  //TODO bigger modulus
+  //TODO PSS for signing
+  rsaParams: any = { name: 'RSA-OAEP' }
+  // RSA params for 'import' and 'generate' function.
+  rsaHashedParams: any = {
+    name: 'RSA-OAEP',
+    modulusLength: 2048,
+    publicExponent: new Uint8Array([0x01, 0x00, 0x01]), // Equivalent to 65537 (Fermat F4), read http://en.wikipedia.org/wiki/65537_(number)
+    hash: { name: 'sha-1' },
+  }
+
+  private crypto: Crypto
+
+  constructor(crypto: Crypto = typeof window !== 'undefined' ? window.crypto : typeof self !== 'undefined' ? self.crypto : ({} as Crypto)) {
+    this.crypto = crypto
+  }
+
+  /**
+   * It returns CryptoKey promise, which doesn't hold the bytes of the key.
+   * If bytes are needed, you must export the generated key.
+   *
+   * @returns {Promise} will be {publicKey: CryptoKey, privateKey: CryptoKey}
+   */
+  generateKeyPair(): Promise<KeyPair<CryptoKey>> {
+    const extractable = true
+    const keyUsages: KeyUsage[] = ['decrypt', 'encrypt']
+
+    return new Promise<KeyPair<CryptoKey>>((resolve, reject) => {
+      this.crypto.subtle.generateKey(this.rsaHashedParams, extractable, keyUsages).then(resolve, reject)
+    })
+  }
+
+  /**
+   *
+   * 'JWK': Json Web key (ref. http://tools.ietf.org/html/draft-ietf-jose-json-web-key-11)
+   * 'spki': for private key
+   * 'pkcs8': for private Key
+   *
+   * @param keyPair is {publicKey: CryptoKey, privateKey: CryptoKey}
+   * @param privKeyFormat will be 'pkcs8' or 'jwk'
+   * @param pubKeyFormat will be 'spki' or 'jwk'
+   * @returns {Promise} will the AES Key
+   */
+  exportKeys(keyPair: KeyPair<CryptoKey>, privKeyFormat: 'jwk', pubKeyFormat: 'jwk'): Promise<KeyPair<JsonWebKey>>
+  exportKeys(keyPair: KeyPair<CryptoKey>, privKeyFormat: 'pkcs8', pubKeyFormat: 'spki'): Promise<KeyPair<ArrayBuffer>>
+  exportKeys(keyPair: KeyPair<CryptoKey>, privKeyFormat: string, pubKeyFormat: string): Promise<KeyPair<JsonWebKey | ArrayBuffer>> {
+    const pubPromise = this.crypto.subtle.exportKey(pubKeyFormat as any, keyPair.publicKey)
+    const privPromise = this.crypto.subtle.exportKey(privKeyFormat as any, keyPair.privateKey)
+
+    return Promise.all([pubPromise, privPromise]).then(function (results) {
+      return {
+        publicKey: results[0],
+        privateKey: results[1],
+      }
+    })
+  }
+
+  /**
+   *  Format:
+   *
+   * 'JWK': Json Web key (ref. http://tools.ietf.org/html/draft-ietf-jose-json-web-key-11)
+   * 'spki': for private key
+   * 'pkcs8': for private Key
+   *
+   * @param cryptoKey public or private
+   * @param format either 'jwk' or 'spki' or 'pkcs8'
+   * @returns {Promise|*} will be RSA key (public or private)
+   */
+  exportKey(cryptoKey: CryptoKey, format: 'jwk'): Promise<JsonWebKey>
+  exportKey(cryptoKey: CryptoKey, format: 'spki'): Promise<ArrayBuffer>
+  exportKey(cryptoKey: CryptoKey, format: 'pkcs8'): Promise<ArrayBuffer>
+  exportKey(cryptoKey: CryptoKey, format: string): Promise<JsonWebKey | ArrayBuffer> {
+    return new Promise((resolve: (value: JsonWebKey | ArrayBuffer) => any, reject) => {
+      this.crypto.subtle.exportKey(format as any, cryptoKey).then(resolve, reject)
+    })
+  }
+
+  /**
+   *
+   * @param publicKey (CryptoKey)
+   * @param plainData (Uint8Array)
+   */
+  encrypt(publicKey: CryptoKey, plainData: Uint8Array): Promise<ArrayBuffer> {
+    return new Promise((resolve: (value: ArrayBuffer) => any, reject) => {
+      this.crypto.subtle.encrypt(this.rsaParams, publicKey, plainData.buffer ? plainData.buffer : plainData).then(resolve, reject) //Node prefers arrayBuffer
+    })
+  }
+
+  /**
+   *
+   * @param privateKey (CryptoKey)
+   * @param encryptedData (Uint8Array)
+   */
+  decrypt(privateKey: CryptoKey, encryptedData: Uint8Array): Promise<ArrayBuffer> {
+    return new Promise((resolve: (value: ArrayBuffer) => any, reject) => {
+      this.crypto.subtle.decrypt(this.rsaParams, privateKey, encryptedData).then(resolve, reject)
+    })
+  }
+
+  /**
+   *
+   * @param format 'jwk', 'spki', or 'pkcs8'
+   * @param keydata should be the key data based on the format.
+   * @param keyUsages Array of usages. For example, ['encrypt'] for public key.
+   * @returns {*}
+   */
+  importKey(format: string, keydata: JsonWebKey | ArrayBuffer, keyUsages: KeyUsage[]): Promise<CryptoKey> {
+    const extractable = true
+    return new Promise((resolve: (value: CryptoKey) => any, reject) => {
+      this.crypto.subtle.importKey(format as any, keydata as any, this.rsaHashedParams, extractable, keyUsages).then(resolve, reject)
+    })
+  }
+
+  /**
+   *
+   * @param format 'jwk' or 'pkcs8'
+   * @param keydata should be the key data based on the format.
+   * @returns {*}
+   */
+  importPrivateKey(format: string, keydata: JsonWebKey | ArrayBuffer): Promise<CryptoKey> {
+    const extractable = true
+    return new Promise((resolve: (value: CryptoKey) => any, reject) => {
+      this.crypto.subtle.importKey(format as any, keydata as any, this.rsaHashedParams, extractable, ['decrypt']).then(resolve, reject)
+    })
+  }
+
+  /**
+   *
+   * @param privateKeyFormat 'jwk' or 'pkcs8'
+   * @param privateKeydata    should be the key data based on the format.
+   * @param publicKeyFormat 'jwk' or 'spki'
+   * @param publicKeyData should be the key data based on the format.
+   * @returns {Promise|*}
+   */
+  importKeyPair(
+    privateKeyFormat: string,
+    privateKeydata: JsonWebKey | ArrayBuffer,
+    publicKeyFormat: string,
+    publicKeyData: JsonWebKey | ArrayBuffer
+  ): Promise<KeyPair<CryptoKey>> {
+    const extractable = true
+    const privPromise = this.crypto.subtle.importKey(privateKeyFormat as any, privateKeydata as any, this.rsaHashedParams, extractable, ['decrypt'])
+    const pubPromise = this.crypto.subtle.importKey(publicKeyFormat as any, publicKeyData as any, this.rsaHashedParams, extractable, ['encrypt'])
+
+    return Promise.all([pubPromise, privPromise]).then(function (results) {
+      return {
+        publicKey: results[0],
+        privateKey: results[1],
+      }
+    })
+  }
+
+  /**
+   * Tries to encrypt then decrypt data using a keypair. If both operations succeed without throwing an error and the decrypted data matches the
+   * original data returns true, else false.
+   * @param keyPair a key pair.
+   * @return if the key pair could be successfully used to encrypt then decrypt data.
+   */
+  async checkKeyPairValidity(keyPair: KeyPair<CryptoKey>): Promise<boolean> {
+    try {
+      const text = 'shibboleth'
+      const encryptedText = await this.encrypt(keyPair.publicKey, utf8_2ua(text))
+      const decryptedText = ua2utf8(await this.decrypt(keyPair.privateKey, new Uint8Array(encryptedText)))
+      return decryptedText === text
+    } catch (e) {
+      return false
+    }
+  }
+}
+
+export const RSA = new RSAUtils()

package/icc-x-api/crypto/ShamirKeysManager.ts

@@ -0,0 +1,170 @@
+import { DataOwner, DataOwnerWithType, IccDataOwnerXApi } from '../icc-data-owner-x-api'
+import { KeyManager } from './KeyManager'
+import { ExchangeKeysManager } from './ExchangeKeysManager'
+import { CryptoPrimitives } from './CryptoPrimitives'
+import { KeyPair } from './RSA'
+import { hex2ua, ua2hex } from '../utils'
+
+/**
+ * Allows to create or update shamir split keys.
+ */
+export class ShamirKeysManager {
+  private readonly primitives: CryptoPrimitives
+  private readonly dataOwnerApi: IccDataOwnerXApi
+  private readonly keyManager: KeyManager
+  private readonly exchangeKeysManager: ExchangeKeysManager
+
+  constructor(primitives: CryptoPrimitives, dataOwnerApi: IccDataOwnerXApi, keyManager: KeyManager, exchangeKeysManager: ExchangeKeysManager) {
+    this.primitives = primitives
+    this.dataOwnerApi = dataOwnerApi
+    this.keyManager = keyManager
+    this.exchangeKeysManager = exchangeKeysManager
+  }
+
+  /**
+   * Get information on existing private keys splits for the provided data owner. For each private key of the provided data owner which has been
+   * split using the Shamir sharing algorithm gives the list of the notaries (other data owners) which hold a copy of the key part.
+   * @param dataOwner a data owner
+   * @return the existing splits for the current data owner as a publicKeyFingerprint -> notariesIds object
+   */
+  getExistingSplitsInfo(dataOwner: DataOwner): { [keyPairFingerprint: string]: string[] } {
+    const legacyPartitionDelegates = Object.keys(dataOwner.privateKeyShamirPartitions ?? {})
+    if (legacyPartitionDelegates.length > 0) {
+      const fp = dataOwner.publicKey?.slice(-32)
+      if (!fp) {
+        console.error('Invalid data owner: the owner has legacy key partitions but no legacy key.')
+      } else return { [fp]: legacyPartitionDelegates }
+    }
+    return {}
+  }
+
+  /**
+   * Creates, updates or deletes shamir splits for keys of the current data owner. Any request to update the splits for a specific key will completely
+   * replace any existing data on that split (all previous notaries will be ignored).
+   * Note: currently you can only split the legacy key pair.
+   * @param keySplitsToUpdate the fingerprints of key pairs which will have updated/new splits and the details on how to create the updated splits.
+   * @param keySplitsToDelete the fingerprints or hex-encoded spki public keys which will not be shared anymore.
+   * @throws if the parameters refer to non-existing or unavailable keys, have split creation details, or if they request to delete a non-existing
+   * split.
+   */
+  async updateSelfSplits(
+    keySplitsToUpdate: { [publicKeyHexOrFp: string]: { notariesIds: string[]; minShares: number } },
+    keySplitsToDelete: string[]
+  ): Promise<DataOwnerWithType> {
+    const self = await this.dataOwnerApi.getCurrentDataOwner()
+    const toUpdateSet = new Set(Object.keys(keySplitsToUpdate).map((x) => x.slice(-32)))
+    const toDeleteSet = new Set(keySplitsToDelete.slice(-32))
+    const intersection = Array.from(toDeleteSet).filter((x) => toUpdateSet.has(x))
+    const existingSplits = new Set(Object.keys(this.getExistingSplitsInfo(self.dataOwner)))
+    const allKeys = this.keyManager.getDecryptionKeys()
+    if (toDeleteSet.size !== keySplitsToDelete.length || toUpdateSet.size !== Object.keys(keySplitsToUpdate).length || intersection.length > 0)
+      throw new Error(`Duplicate keys in input:\nkeySplitsToUpdate: ${keySplitsToUpdate}\nkeySplitsToDelete: ${keySplitsToDelete}`)
+    Object.entries(keySplitsToUpdate).forEach(([key, params]) => this.validateShamirParams(key, params))
+    if (!Array.from(existingSplits).every((x) => existingSplits.has(x))) {
+      throw new Error(`Requested to delete non-existing split.\nexistingSplits: ${Array.from(existingSplits)}\ntoDelete:${Array.from(toDeleteSet)}`)
+    }
+    if (Array.from(toUpdateSet).some((x) => !allKeys[x])) {
+      throw new Error(`Private key is not available for some of the requested key split updates. ${keySplitsToUpdate}`)
+    }
+    const delegatesKeys: { [delegateId: string]: CryptoKey } = {}
+    let updatedSelf = self
+    for (const delegateId of new Set(Object.values(keySplitsToUpdate).flatMap((x) => x.notariesIds))) {
+      const res = await this.exchangeKeysManager.getOrCreateEncryptionExchangeKeysTo(delegateId)
+      delegatesKeys[delegateId] = res.keys[0]
+      if (res.updatedDelegator) {
+        updatedSelf = res.updatedDelegator
+      }
+    }
+    for (const [key, params] of Object.entries(keySplitsToUpdate)) {
+      updatedSelf = await this.updateKeySplit(updatedSelf, key.slice(-32), params.notariesIds, params.minShares, delegatesKeys, allKeys)
+    }
+    for (const keyFp of toDeleteSet) {
+      updatedSelf = this.deleteKeySplit(updatedSelf, keyFp)
+    }
+    return await this.dataOwnerApi.updateDataOwner(updatedSelf)
+  }
+
+  /*TODO
+   * Get suggested recovery keys: analyse transfer keys and shamir to get keys which should be shared with shamir for optimal recovery.
+   */
+
+  private validateShamirParams(key: string, params: { notariesIds: string[]; minShares: number }) {
+    if (params.notariesIds.length > 0) {
+      if (params.minShares > params.notariesIds.length) {
+        throw new Error(`Invalid parameters for key ${key}: min shares can't be greater than the number of delegates. ${params}`)
+      }
+    } else throw new Error(`Invalid parameters for key ${key}: must have at least one delegate. ${params}`)
+  }
+
+  private deleteKeySplit(dataOwner: DataOwnerWithType, keyFp: string): DataOwnerWithType {
+    if (keyFp !== dataOwner.dataOwner.publicKey?.slice(-32)) {
+      throw new Error('Currently it is possible to use shamir splits only for the legacy public key')
+    }
+    return {
+      type: dataOwner.type,
+      dataOwner: {
+        ...dataOwner.dataOwner,
+        privateKeyShamirPartitions: {},
+      },
+    }
+  }
+
+  private async updateKeySplit(
+    dataOwner: DataOwnerWithType,
+    keyFp: string,
+    delegateIds: string[],
+    minShares: number,
+    delegatesKeys: { [p: string]: CryptoKey },
+    allKeys: { [p: string]: KeyPair<CryptoKey> }
+  ): Promise<DataOwnerWithType> {
+    if (keyFp !== dataOwner.dataOwner.publicKey?.slice(-32)) {
+      throw new Error('Currently it is possible to use shamir splits only for the legacy public key')
+    }
+    return {
+      type: dataOwner.type,
+      dataOwner: {
+        ...dataOwner.dataOwner,
+        privateKeyShamirPartitions: await this.createPartitionsFor(allKeys[keyFp], delegateIds, minShares, delegatesKeys),
+      },
+    }
+  }
+
+  private async createPartitionsFor(
+    keyPair: KeyPair<CryptoKey>,
+    delegateIds: string[],
+    minShares: number,
+    delegatesKeys: { [p: string]: CryptoKey }
+  ): Promise<{ [delegateId: string]: string }> {
+    const exportedKey = await this.primitives.RSA.exportKey(keyPair.privateKey, 'pkcs8')
+    if (delegateIds.length == 1) {
+      return await this.encryptShares([exportedKey], delegateIds, delegatesKeys)
+    } else {
+      const exportedKeysHex = ua2hex(exportedKey)
+      const stringShares = this.primitives.shamir.share(exportedKeysHex, delegateIds.length, minShares)
+      const paddedStringShares = stringShares.map((x) => `f${x}`) // Shares are uneven length, apart from that they are perfect hexes
+      for (const share of paddedStringShares) {
+        if (!/^(?:[0-9a-f][0-9a-f])+$/g.test(share)) throw new Error('Unexpected result of shamir split: padded shares should be a valid hex value')
+        if (share !== ua2hex(hex2ua(share))) throw new Error('Unexpected result with encoding-decoding share')
+      }
+      return await this.encryptShares(
+        paddedStringShares.map((x) => hex2ua(x)),
+        delegateIds,
+        delegatesKeys
+      )
+    }
+  }
+
+  private async encryptShares(
+    shares: ArrayBuffer[],
+    delegateIds: string[],
+    delegatesKeys: { [p: string]: CryptoKey }
+  ): Promise<{ [delegateId: string]: string }> {
+    return delegateIds.reduce(
+      async (acc, delegateId, index) => ({
+        ...(await acc),
+        [delegateId]: ua2hex(await this.primitives.AES.encrypt(delegatesKeys[delegateId], shares[index])),
+      }),
+      Promise.resolve({} as { [delegateId: string]: string })
+    )
+  }
+}

package/icc-x-api/crypto/ShareMetadataBehaviour.ts

@@ -0,0 +1,19 @@
+/**
+ * Specifies a behaviour for the sharing of encryption keys or owning entity ids in the extended apis 'share' methods.
+ */
+export enum ShareMetadataBehaviour {
+  /**
+   * The method must share the metadata with the delegate. If this is not possible, because for example the current user has no access to this kind of
+   * metadata, the method will throw an error.
+   */
+  REQUIRED = 'REQUIRED',
+  /**
+   * The method must share the metadata with the delegate if available. If this is not possible, because for example the current user has no access to
+   * this kind of metadata, the method will simply not share this metadata.
+   */
+  IF_AVAILABLE = 'IF_AVAILABLE',
+  /**
+   * The method must not share the metadata with the delegate, even if the current data owner can access it.
+   */
+  NEVER = 'NEVER',
+}