1st version of API

core/pubnub_crypto.h

@@ -18,13 +18,49 @@
 
 */
 
-/** Cryptor algorithm type.
+/**
+   Encrypted data structure.
+ */
+struct pubnub_encrypted_data {
+    /** Encrypted data. */
+    struct pubnub_char_mem_block data;
+
+    /** Metadata. 
+        
+        Cryptor may provide here any information which will be usefull when data 
+        should be decrypted.
+
+        For example `metadata` may contain:
+        - initialization vector
+        - cipher key Identifier
+        - encrypted *data* length
+     */
+    struct pubnub_char_mem_block metadata;
+};
+
+
+/** Cryptor header version 1.
+    
+    This is the struct containing the information about the 
+    cryptor header version 1. It contains the identifier of the 
+    algorithm and the encrypted data length.
+ */
+struct pubnub_cryptor_header_v1 {
+    /** Cryptor algorithm identifier. */
+    uint8_t identifier[4];
+
+    /** Encrypted data length. */
+    uint32_t data_length;
+};
+
+
+/** Crypto algorithm type.
     
     This is the struct containing the information about the 
     cryptor algorithm type. It contains the identifier of the 
     algorithm and the function pointers to the algorithm implementation.
  */
-typedef struct pubnub_cryptor_t {
+typedef struct pubnub_crypto_algorithm_t {
     /** Identifier of the algorithm.
         
         Identifier will be encoded into crypto data header and passed along 
@@ -40,12 +76,12 @@ typedef struct pubnub_cryptor_t {
         @param cryptor Pointer to the cryptor structure.
         @param msg Memory block (pointer and size) of the data to encrypt.
         @param base64_str String (allocated by the user) to write encrypted and
-        base64 encoded string.
+                base64 encoded string.
         @param n The size of the string.
 
         @return 0: OK, -1: error
       */
-    int (*encrypt)(struct pubnub_cryptor_t const *cryptor, pubnub_bymebl_t msg, char *base64_str, size_t n);
+    int (*encrypt)(struct pubnub_crypto_algorithm_t const *cryptor, struct pubnub_encrypted_data msg, char *base64_str, size_t n);
 
     // TODO: return type - int or enum?
     /** Function pointer to the decrypt function.
@@ -56,42 +92,96 @@ typedef struct pubnub_cryptor_t {
 
         @return 0: OK, -1: error
      */
-    int (*decrypt)(struct pubnub_cryptor_t const *cryptor, char const *base64_str, size_t n, pubnub_bymebl_t *data);
-} pubnub_cryptor;
+    int (*decrypt)(struct pubnub_crypto_algorithm_t const *cryptor, char const *base64_str, size_t n, struct pubnub_encrypted_data *data);
 
-/**
-   Encrypted data structure.
- */
-struct pubnub_encrypted_data {
-    /** Encrypted data. */
-    struct pubnub_char_mem_block data;
+    /** Pointer to the user data needed for the algorithm. */
+    void *user_data;
 
-    /** Metadata. 
-        
-        Cryptor may provide here any information which will be usefull when data 
-        should be decrypted.
+} pubnub_crypto_algorithm_t;
 
-        For example `metadata` may contain:
-        - initialization vector
-        - cipher key Identifier
-        - encrypted *data* length
-     */
-    struct pubnub_char_mem_block metadata;
-};
 
-/** Cryptor header version 1.
+/** Crypto algorithm wrapper
     
     This is the struct containing the information about the 
-    cryptor header version 1. It contains the identifier of the 
-    algorithm and the encrypted data length.
+    abstract cryptor algorithm. It wraps the algorithm implementation
+    and provides the interface to the Pubnub client library.
  */
-struct pubnub_cryptor_header_v1 {
-    /** Cryptor algorithm identifier. */
-    uint8_t identifier[4];
+typedef struct pubnub_cryptor_t {
+    /** Cryptor algorithm for data encription / decryption. */
+    struct pubnub_crypto_algorithm_t algorithm;
+
+} pubnub_cryptor;
+
+
+/** Retrieves the cryptor algorithm identifier.
+    
+    @param cryptor Pointer to the cryptor structure.
+
+    @return Pointer to the cryptor algorithm identifier.
+ */
+uint8_t const *pubnub_cryptor_identifier(pubnub_cryptor const *cryptor);
+
+
+// TODO: return type - int or enum?
+/** Encrypt provided data.
+
+    @param cryptor Pointer to the cryptor structure.
+    @param msg The memory block (pointer and size) of the data to encrypt.
+    @param base64_block The char block (pointer and size) to write encrypted and
+            base64 encoded string.
+
+    @return 0: OK, -1: error
+ */
+int pubnub_cryptor_encrypt(pubnub_cryptor const *cryptor, pubnub_bymebl_t const *msg, pubnub_chamebl_t base64_block);
+
+
+// TODO: return type - int or enum?
+/** Decrypt provided data.
+
+    @param cryptor Pointer to the cryptor structure.
+    @param base64_block The char block (pointer and size) to Base64 decode and decrypt.
+    @param data User allocated memory block to write the decrypted contents to.
+
+    @return 0: OK, -1: error
+ */
+int pubnub_cryptor_decrypt(pubnub_cryptor const *cryptor, pubnub_chamebl_t const *base64_block, pubnub_bymebl_t *data);
+
+
+/** Cryptor module for data processing. */
+typedef struct pubnub_crypto_module_t {
+    /** Array of the cryptor algorithms. */
+    struct pubnub_crypto_algorithm_t *algorithms;
+
+    /** Number of the cryptor algorithms. */
+    size_t algorithms_n;
+
+} pubnub_crypto_module;
+
+
+// TODO: return type - int or enum?
+/** Encrypt provided data.
+
+    @param module crypto module Pointer to the cryptor module structure.
+    @param msg The memory block (pointer and size) of the data to encrypt.
+    @param base64_block The char block (pointer and size) to write encrypted and
+            base64 encoded string.
+
+    @return 0: OK, -1: error
+ */
+int pubnub_crypto_module_encrypt(pubnub_crypto_module const *module, pubnub_bymebl_t const *msg, pubnub_chamebl_t base64_block);
+
+
+// TODO: return type - int or enum?
+/** Decrypt provided data.
+
+    @param module crypto module Pointer to the cryptor module structure.
+    @param base64_block The char block (pointer and size) to Base64 decode and decrypt.
+    @param data User allocated memory block to write the decrypted contents to.
+
+    @return 0: OK, -1: error
+ */
+int pubnub_crypto_module_decrypt(pubnub_crypto_module const *module, pubnub_chamebl_t const *base64_block, pubnub_bymebl_t *data);
 
-    /** Encrypted data length. */
-    uint32_t data_length;
-};
 
 /** Sets @p secret_key to be used with the Pubnub context @p p.