wip: adding in serializable object literal

src/components/galois-keys.js

@@ -176,7 +176,7 @@ export const GaloisKeys = library => ({
      * @name GaloisKeys#copy
      * @param {GaloisKeys} key GaloisKeys to copy
      * @example
-     * const keyA = keyGenerator.genGaloisKeys()
+     * const keyA = keyGenerator.genGaloisKeysLocal()
      * const keyB = Morfix.GaloisKeys()
      * keyB.copy(keyA)
      * // keyB holds a copy of keyA
@@ -196,7 +196,7 @@ export const GaloisKeys = library => ({
      * @name GaloisKeys#clone
      * @returns {GaloisKeys}
      * @example
-     * const keyA = keyGenerator.genGaloisKeys()
+     * const keyA = keyGenerator.genGaloisKeysLocal()
      * const keyB = keyA.clone()
      * // keyB holds a copy of keyA
      */
@@ -222,7 +222,7 @@ export const GaloisKeys = library => ({
      * @name GaloisKeys#move
      * @param {GaloisKeys} key GaloisKeys to move
      * @example
-     * const keyA = keyGenerator.genGaloisKeys()
+     * const keyA = keyGenerator.genGaloisKeysLocal()
      * const keyB = Morfix.GaloisKeys()
      * keyB.move(keyA)
      * // keyB holds a the instance of keyA.

src/components/index.js

@@ -23,6 +23,7 @@ export { RelinKeys } from './relin-keys'
 export { SchemeType } from './scheme-type'
 export { SecretKey } from './secret-key'
 export { SecurityLevel } from './security-level'
+export { Serializable } from './serializable'
 export { Modulus } from './modulus'
 export { Vector } from './vector'
 export { Util } from './util'

src/components/key-generator.js

@@ -4,7 +4,7 @@ export const KeyGenerator = library => ({
   SecretKey,
   RelinKeys,
   GaloisKeys,
-  ComprModeType
+  Serializable
 }) => (context, secretKey = null, publicKey = null) => {
   const Constructor = library.KeyGenerator
   let _instance = constructInstance(context, secretKey, publicKey)
@@ -107,13 +107,15 @@ export const KeyGenerator = library => ({
     },
 
     /**
-     * Generate and return a set of RelinKeys
+     * Generates and returns relinearization keys. This function returns
+     * relinearization keys in a fully expanded form and is meant to be used
+     * primarily for demo, testing, and debugging purposes.
      *
      * @function
-     * @name KeyGenerator#genRelinKeys
+     * @name KeyGenerator#genRelinKeysLocal
      * @returns {RelinKeys} New RelinKeys from the KeyGenerator's internal secret key
      */
-    genRelinKeys() {
+    genRelinKeysLocal() {
       try {
         const key = RelinKeys()
         const instance = _instance.genRelinKeysLocal()
@@ -125,21 +127,43 @@ export const KeyGenerator = library => ({
     },
 
     /**
-     * Generates and returns GaloisKeys. If provided with an array of steps,
-     * this function creates specific GaloisKeys that can be used to apply
-     * specific Galois automorphisms on encrypted data. The user needs to give
-     * as input a vector of desired Galois rotation step counts, where negative
-     * step counts correspond to rotations to the right and positive step counts
-     * correspond to rotations to the left. A step count of zero can be used to
-     * indicate a column rotation in the BFV scheme complex conjugation in the
-     * CKKS scheme.
+     * Generates and returns relinearization keys as a serializable object.
+     *
+     * Half of the key data is pseudo-randomly generated from a seed to reduce
+     * the object size. The resulting serializable object cannot be used
+     * directly and is meant to be serialized for the size reduction to have an
+     * impact.
      *
      * @function
-     * @name KeyGenerator#genGaloisKeys
+     * @name KeyGenerator#relinKeys
+     * @returns {RelinKeys} New RelinKeys from the KeyGenerator's internal secret key
+     */
+    relinKeys() {
+      try {
+        const serialized = Serializable()
+        const instance = _instance.genRelinKeys()
+        serialized.unsafeInject(instance)
+        return serialized
+      } catch (e) {
+        throw Exception.safe(e)
+      }
+    },
+
+    /**
+     * Generates and returns Galois keys. This function returns Galois keys in
+     * a fully expanded form and is meant to be used primarily for demo, testing,
+     * and debugging purposes. The user can optionally give an input a vector of desired
+     * Galois rotation step counts, where negative step counts correspond to
+     * rotations to the right and positive step counts correspond to rotations to
+     * the left. A step count of zero can be used to indicate a column rotation
+     * in the BFV scheme complex conjugation in the CKKS scheme.
+     *
+     * @function
+     * @name KeyGenerator#genGaloisKeysLocal
      * @param {Int32Array} [steps=null] Specific Galois Elements to generate
      * @returns {GaloisKeys} New GaloisKeys from the KeyGenerator's internal secret key
      */
-    genGaloisKeys(steps = null) {
+    genGaloisKeysLocal(steps = null) {
       try {
         if (steps) {
           const key = GaloisKeys()
@@ -157,29 +181,35 @@ export const KeyGenerator = library => ({
     },
 
     /**
-     * Generates and saves Galois keys to a base64 string. If provided with steps,
-     * This function creates specific Galois keys that can be used to apply
-     * specific Galois automorphisms on encrypted data. The user needs to give
-     * as input a vector of Galois elements corresponding to the keys that are
-     * to be created.
-
-     * Half of the polynomials in Galois keys are randomly generated and are
-     * replaced with the seed used to compress output size. The output is in
-     * binary format and not human-readable. The output stream must have the
-     * "binary" flag set.
+     * Generates and returns Galois keys as a serializable object. This function
+     * creates specific Galois keys that can be used to apply specific Galois
+     * automorphisms on encrypted data. The user can optionally give an input a vector
+     * of desired Galois rotation step counts, where negative step counts
+     * correspond to rotations to the right and positive step counts correspond
+     * to rotations to the left. A step count of zero can be used to indicate
+     * a column rotation in the BFV scheme complex conjugation in the CKKS scheme.
+     * Half of the key data is pseudo-randomly generated from a seed to reduce
+     * the object size. The resulting serializable object cannot be used
+     * directly and is meant to be serialized for the size reduction to have an
+     * impact.
      *
      * @function
-     * @name KeyGenerator#galoisKeysSave
+     * @name KeyGenerator#galoisKeys
      * @param {Int32Array} [steps=null] Specific Galois Elements to generate
-     * @param {ComprModeType} [compression={@link ComprModeType.deflate}] The compression mode to use
      * @returns {String} Base64 encoded string
      */
-    galoisKeysSave(steps = null, compression = ComprModeType.deflate) {
+    galoisKeys(steps = null) {
       try {
         if (steps) {
-          return _instance.galoisKeysSave(steps, compression)
+          const serialized = Serializable()
+          const instance = _instance.genGaloisKeys(steps)
+          serialized.unsafeInject(instance)
+          return serialized
         }
-        return _instance.galoisKeysSaveAll(compression)
+        const serialized = Serializable()
+        const instance = _instance.genGaloisKeys(Int32Array.from(0))
+        serialized.unsafeInject(instance)
+        return serialized
       } catch (e) {
         throw Exception.safe(e)
       }

src/components/relin-keys.js

@@ -177,7 +177,7 @@ export const RelinKeys = library => ({
      * @name RelinKeys#copy
      * @param {RelinKeys} key RelinKeys to copy
      * @example
-     * const keyA = keyGenerator.genRelinKeys()
+     * const keyA = keyGenerator.genRelinKeysLocal()
      * const keyB = Morfix.RelinKeys()
      * keyB.copy(keyA)
      * // keyB holds a copy of keyA
@@ -197,7 +197,7 @@ export const RelinKeys = library => ({
      * @name RelinKeys#clone
      * @returns {RelinKeys}
      * @example
-     * const keyA = keyGenerator.genRelinKeys()
+     * const keyA = keyGenerator.genRelinKeysLocal()
      * const keyB = keyA.clone()
      * // keyB holds a copy of keyA
      */
@@ -223,7 +223,7 @@ export const RelinKeys = library => ({
      * @name RelinKeys#move
      * @param {RelinKeys} key RelinKeys to move
      * @example
-     * const keyA = keyGenerator.genRelinKeys()
+     * const keyA = keyGenerator.genRelinKeysLocal()
      * const keyB = Morfix.RelinKeys()
      * keyB.move(keyA)
      * // keyB holds a the instance of keyA.

src/components/serializable.js

@@ -0,0 +1,92 @@
+export const Serializable = () => ({
+  Exception,
+  Vector,
+  ComprModeType
+}) => () => {
+  let _instance = null
+
+  /**
+   * @implements Serializable
+   */
+
+  /**
+   * @interface Serializable
+   */
+  return {
+    /**
+     * Get the underlying WASM instance
+     *
+     * @private
+     * @readonly
+     * @name Serializable#instance
+     * @type {instance}
+     */
+    get instance() {
+      return _instance
+    },
+
+    /**
+     * Inject this object with a raw WASM instance. No type checking is performed.
+     *
+     * @private
+     * @function
+     * @name Serializable#unsafeInject
+     * @param {instance} instance WASM instance
+     */
+    unsafeInject(instance) {
+      if (_instance) {
+        _instance.delete()
+        _instance = null
+      }
+      _instance = instance
+    },
+
+    /**
+     * Delete the underlying WASM instance.
+     *
+     * Should be called before dereferencing this object to prevent the
+     * WASM heap from growing indefinitely.
+     * @function
+     * @name Serializable#delete
+     */
+    delete() {
+      if (_instance) {
+        _instance.delete()
+        _instance = null
+      }
+    },
+
+    /**
+     * Save to a base64 string
+     *
+     * @function
+     * @name Serializable#save
+     * @param {ComprModeType} [compression={@link ComprModeType.deflate}] The compression mode to use
+     * @returns {String} Base64 encoded string
+     */
+    save(compression = ComprModeType.deflate) {
+      try {
+        return _instance.saveToString(compression)
+      } catch (e) {
+        throw Exception.safe(e)
+      }
+    },
+
+    /**
+     * Save as a binary Uint8Array
+     *
+     * @function
+     * @name Serializable#saveArray
+     * @param {ComprModeType} [compression={@link ComprModeType.deflate}] The compression mode to use
+     * @returns {Uint8Array} A byte array containing the Serializable object in binary form
+     */
+    saveArray(compression = ComprModeType.deflate) {
+      const tempVect = Vector(new Uint8Array(0))
+      const instance = _instance.saveToArray(compression)
+      tempVect.unsafeInject(instance)
+      const tempArr = tempVect.toArray()
+      tempVect.delete()
+      return tempArr
+    }
+  }
+}

src/seal/seal.js

@@ -22,6 +22,9 @@ export const SEAL = library => {
     Modulus,
     Vector
   })(components.PlainModulus)
+  const Serializable = applyDependencies({ Exception, Vector, ComprModeType })(
+    components.Serializable
+  )
   const SchemeType = applyDependencies()(components.SchemeType)
   const Util = applyDependencies()(components.Util)
   const ParmsIdType = applyDependencies({ Exception })(components.ParmsIdType)
@@ -79,7 +82,8 @@ export const SEAL = library => {
   const Encryptor = applyDependencies({
     Exception,
     MemoryPoolHandle,
-    CipherText
+    CipherText,
+    Serializable
   })(components.Encryptor)
   const Evaluator = applyDependencies({
     Exception,
@@ -118,6 +122,7 @@ export const SEAL = library => {
     SecretKey,
     RelinKeys,
     GaloisKeys,
+    Serializable,
     ComprModeType
   })(components.KeyGenerator)
 
@@ -1025,6 +1030,66 @@ export const SEAL = library => {
      */
     SecurityLevel,
 
+    /**
+     * @description
+     * Class to represent a serializable object. Some functions return serializable
+     * objects rather than normal objects. For example, Encryptor can be used in
+     * symmetric-key mode to create symmetric-key ciphertexts, where half of the
+     * ciphertext data is pseudo-random and can be generated from a seed, reducing
+     * the size of the newly created ciphertext object by nearly 50%. However, the
+     * compression only has an effect when the object is serialized with compression
+     * mode compr_mode_type::deflate due to an implementation detail. This makes
+     * sense when, e.g., the ciphertexts need to be communicated from a client to
+     * a server for encrypted computation.
+     *
+     * Serializable objects are created only by the following functions:
+     *     - Encryptor::encrypt_symmetric
+     *     - Encryptor::encrypt_zero_symmetric
+     *     - KeyGenerator::relin_keys
+     *     - KeyGenerator::galois_keys
+     *
+     * Serializable objects also expose the save_size function that behaves just
+     * as the save_size functions of other objects in Microsoft SEAL: it returns
+     * an upper bound on the size of a buffer needed to hold the serialized data.
+     *
+     * The following illustrates the use of serializable objects:
+     *
+     *        +--------------------------+
+     *        | Serializable<GaloisKeys> |  Size 2 MB (example)
+     *        +------------+-------------+
+     *                     |
+     *                     |                Serializable<GaloisKeys>::save
+     *                     |                with compr_mode_type::deflate
+     *                     |
+     *             +-------v-------+
+     *             | Stream/Buffer |        Size ~1 MB (example)
+     *             +-------+-------+
+     *                     |
+     *                     |
+     *                  +--v--+
+     *                  Network             Minimized communication
+     *                  +--+--+
+     *                     |
+     *                     |                GaloisKeys::load
+     *                     |
+     *               +-----v------+
+     *               | GaloisKeys |         Size 2 MB (example)
+     *               +------------+
+     *
+     * @private
+     * @function
+     * @name SEAL#Serializable
+     * @returns {Serializable} A serializable object
+     * @example
+     * import { Seal } from 'node-seal'
+     * const Morfix = await Seal()
+     * ...
+     * const serializableGaloisKeys = Morfix.KeyGenerator.genGaloisKeys()
+     * const base64 = serializableGaloisKeys.save(Morfix.ComprModeType.deflate)
+     * const binaryArray = serializableGaloisKeys.saveArray(Morfix.ComprModeType.deflate)
+     */
+    Serializable,
+
     /**
      * @description
      * Create an instance of a Modulus