README.md

CipherFace

CipherFace is a homomorphic encryption-driven python framework for secure cloud-based facial recognition. It combines DeepFace and TenSEAL libraries.

Installation

The easiest way to install CipherFace is to download it from PyPI. It's going to install the library itself and its prerequisites as well.

$ pip install cipherface

Alternatively, you can also install deepface from its source code. Source code may have new features not published in pip release yet.

$ git clone https://github.com/serengil/cipherface.git
$ cd cipherface
$ pip install -e .

Once you installed the library, then you will be able to import it and use its functionalities.

from cipherface import CipherFace

On Prem Encryption

When you initialize a CipherFace object, it sets up an FHE cryptosystem. Currently, CipherFace supports the VGG-Face, Facenet, and Facenet512 facial recognition models, as well as Euclidean and cosine distance metrics.

# build a cryptosystem
onprem = CipherFace(
    model_name="Facenet",
    distance_metric="euclidean",
)

# export keys of built cryptosystem
onprem.export_private_key("private.txt")
onprem.export_public_key("public.txt")

# create vector embedding for 1st image and encrypt in one shot
source_embedding_encrypted = onprem.securely_embed(img_path="dataset/img1.jpg")

The on-prem system should generate embeddings for its facial database and encrypt them in advance. This process only needs to be done once to extract the encrypted embeddings. Once encrypted, these embeddings can be securely stored in the cloud.

Encrypted Distance Calculation On Cloud

The cloud can also generate vector embeddings and encrypt them since encryption only requires a public key. Additionally, it can compute the encrypted distance between a recently generated encrypted embedding and an encrypted embedding created on the on-prem side.

# cloud loads cryptosystem with public key
onprem = CipherFace(
    model_name="Facenet",
    distance_metric="euclidean",
    cryptosystem="public.txt",
)

# create vector embedding for target image and encrypt in one shot
target_embedding_encrypted = cloud.securely_embed(img_path="dataset/target.jpg")[0]

encrypted_distance = cloud.calculate_encrypted_distance(
    target_embedding_encrypted,
    source_embedding_encrypted
)

On Prem Verification

Once the cloud calculates the encrypted distance, only the on-prem system can decrypt it since it holds the private key of the cryptosystem. This allows the on-prem system to determine whether the source and target images belong to the same person or different individuals.

# on prem loads cryptosystem with private key
onprem = CipherFace(
    model_name="Facenet",
    distance_metric="euclidean",
    cryptosystem="private.txt",
)

# on prem restores distance
decrypted_distance = onprem.restore(encrypted_distance)

# verification
is_verified = onprem.verify(decrypted_distance)

if is_verified is True:
    print("they are same person")
else:
    print("they are different persons")

In this setup, the cloud system performs the distance calculation, utilizing most of the computational power. The on-prem system, holding the private key, is only responsible for decrypting the distances to determine whether the images belong to the same person or different individuals.

Contribution

Pull requests are more than welcome! If you are planning to contribute a large patch, please create an issue first to get any upfront questions or design decisions out of the way first.

Before creating a PR, you should run the unit tests and linting locally by running make test && make lint command. Once a PR sent, GitHub test workflow will be run automatically and unit test and linting jobs will be available in GitHub actions before approval.

Support

There are many ways to support a project - starring⭐️ the GitHub repo is just one 🙏

If you do like this work, then you can support it financially on Patreon, GitHub Sponsors or Buy Me a Coffee.

Citation

Please cite CipherFace in your publications if it helps your research. Here is its BibTex entry:

@misc{cipherface,
  author       = {Serengil, Sefik Ilkin},
  title        = {CipherFace: A Homomorphic Encryption-Driven Framework for Secure Cloud-Based Facial Recognition},
  year         = {2024},
  url          = {https://github.com/serengil/cipherface},
  note         = {GitHub repository}
}

Licence

CipherFace is licensed under the MIT License - see LICENSE for more details.