For App Developers

Installation and dependencies

See Platform Install Manual for installation instructions.

Using a Scheme

To use any of our existing schemes in your application, each scheme includes a main routine that runs through every alorithm (with sample inputs) defined for that scheme. Thus, the main function provides a test that the scheme works in addition to demonstrate how to use it. For example, below is an example of how to instantiate the Cramer-Shoup scheme from above within your application:

from charm.schemes.pkenc.pkenc_cs98 import CS98
from charm.toolbox.eccurve import prime192v1
from charm.toolbox.ecgroup import ECGroup

groupObj = ECGroup(prime192v1)
pkenc = CS98(groupObj)

(pk, sk) = pkenc.keygen()

M = b'Hello World!'
ciphertext = pkenc.encrypt(pk, M)

message = pkenc.decrypt(pk, sk, ciphertext)

For a full list of schemes that are available to you, see the Implemented Schemes section.

Using serialization API

To support serialization of key material and ciphertexts, we provide two high-level API calls to serialize charm objects embedded in arbitrary python structures (e.g., lists, tuples, or dictionaries, etc) which are objectToBytes() and bytesToObject() from the charm.core.engine.util package. These functions provide the necessary functionality for converting keys and ciphertexts to base 64 encoded strings. Both calls require the object to be serialized/deserialized and a class that defines the serialize and deserialize methods such as the group object. We also show below how to customize our serialization routines:

Here is an example of how to use the API with any of the supported group objects (integergroup, pairinggroup or ecgroup):

from charm.core.engine.util import objectToBytes,bytesToObject

pk_bytes = objectToBytes(pk, group)

orig_pk = bytesToObject(pk_bytes, group)

If you would like to define your own custom serialization routine in conjunction with our API, the following example works for schemes based on the integergroup which in some cases do not utilize a group object:

from charm.core.math.integer import integer,serialize,deserialize

class mySerializeAPI:
        def __init__(self)
                ...

        def serialize(self, charm_object):
            assert type(charm_object) == integer, "required type is integer, not: ", type(charm_object)
            return serialize(charm_object)

        def deserialize(self, object):
            assert type(object) == bytes, "required type is bytes, not: ", type(object)
            return deserialize(object)

from charm.core.engine.util import objectToBytes,bytesToObject

serObject = mySerializeAPI()

pk_bytes = objectToBytes(pk, serObject)

orig_pk = bytesToObject(pk_bytes, serObject)

Using Charm in C/C++ Apps

To make Charm easy to use conveniently with C/C++ applications, we have provided a C interface to encapsulate the details. While this feature is still in development, here is a code snippet that shows how to utilize a Charm scheme in C:

/* Charm C interface header */
#include "charm_embed_api.h"

Charm_t *module, *group, *class;

/* initialize charm environment */
InitializeCharm();

/* initialize a group object */
group = InitPairingGroup("SS1024");

/* initialize a scheme */
class = InitClass("abenc_bsw07", "CPabe_BSW07", group);

/* call setup algorithm */
Charm_t *master_keys = CallMethod(class, "setup", "");

Charm_t *pkDict = GetIndex(master_keys, 0);
Charm_t *mskDict = GetIndex(master_keys, 1);

/* call keygen algorithm */
Charm_t *skDict = CallMethod(class, "keygen", "%O%O%A", pkDict, mskDict, "[ONE, TWO, THREE]");

/* generate message */
Charm_t *msg = CallMethod(group, "random", "%I", GT);
/* call encrypt algorithm */
Charm_t *ctDict = CallMethod(class, "encrypt", "%O%O%s", pkDict, msg, "((THREE or ONE) and (THREE or TWO))");
/* call decrypt mesaage */
Charm_t *msg2 = CallMethod(class, "decrypt", "%O%O%O", pkDict, skDict, ctDict);
/* process the Charm objects */
/* .....see source for a simple approach.... */
/* free the objects */
Free(module);
Free(group);
Free(class);
Free(master_keys);
Free(pkDict);
Free(mskDict);
Free(skDict);
Free(msg);
Free(msg2);
/* tear down the environment */
CleanupCharm();
....

The rest of the example can be found in test.c in the embed dir of Charm source.

Feel free to send us suggestions, bug reports, issues and scheme implementation experiences within Charm at support@charm-crypto.com.