{"id":27026868,"url":"https://github.com/serengil/cipherface","last_synced_at":"2025-08-09T02:11:42.937Z","repository":{"id":278954237,"uuid":"936850343","full_name":"serengil/cipherface","owner":"serengil","description":"A Homomorphic Encryption-Driven Python Framework for Secure Cloud-Based Facial Recognition","archived":false,"fork":false,"pushed_at":"2025-07-09T12:42:55.000Z","size":3299,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-06T05:52:26.429Z","etag":null,"topics":["cryptography","face-recognition","facial-recognition","fhe","homomorphic-encryption","lattice-based-cryptography","phe","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serengil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"serengil","patreon":"serengil","buy_me_a_coffee":"serengil"}},"created_at":"2025-02-21T19:52:36.000Z","updated_at":"2025-07-13T21:34:20.000Z","dependencies_parsed_at":"2025-02-22T19:31:32.654Z","dependency_job_id":"5c0d39df-3c1f-43c3-9f8b-8ccbd4db0fa0","html_url":"https://github.com/serengil/cipherface","commit_stats":null,"previous_names":["serengil/cipherface"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/serengil/cipherface","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serengil%2Fcipherface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serengil%2Fcipherface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serengil%2Fcipherface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serengil%2Fcipherface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serengil","download_url":"https://codeload.github.com/serengil/cipherface/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serengil%2Fcipherface/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269518731,"owners_count":24430644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","face-recognition","facial-recognition","fhe","homomorphic-encryption","lattice-based-cryptography","phe","python"],"created_at":"2025-04-04T23:16:13.806Z","updated_at":"2025-08-09T02:11:42.926Z","avatar_url":"https://github.com/serengil.png","language":"Python","funding_links":["https://github.com/sponsors/serengil","https://patreon.com/serengil","https://buymeacoffee.com/serengil","https://www.patreon.com/serengil?repo=cipherface","https://www.patreon.com/serengil?repo=deepface"],"categories":[],"sub_categories":[],"readme":"# CipherFace\n\n\u003cdiv align=\"center\"\u003e\n\n[![Downloads](https://static.pepy.tech/personalized-badge/cipherface?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=downloads)](https://pepy.tech/project/cipherface)\n[![Stars](https://img.shields.io/github/stars/serengil/cipherface?color=yellow\u0026style=flat\u0026label=%E2%AD%90%20stars)](https://github.com/serengil/cipherface/stargazers)\n[![License](http://img.shields.io/:license-MIT-green.svg?style=flat)](https://github.com/serengil/cipherface/blob/master/LICENSE)\n[![Tests](https://github.com/serengil/cipherface/actions/workflows/tests.yml/badge.svg)](https://github.com/serengil/cipherface/actions/workflows/tests.yml)\n[![arXiv](https://img.shields.io/badge/arXiv-2503.05850-b31b1b.svg?logo=arXiv)](https://arxiv.org/abs/2503.05850)\n[![arXiv](https://img.shields.io/badge/arXiv-2502.18514-b31b1b.svg?logo=arXiv)](https://arxiv.org/abs/2502.18514)\n\n[![Blog](https://img.shields.io/:blog-sefiks.com-blue.svg?style=flat\u0026logo=wordpress)](https://sefiks.com)\n[![YouTube](https://img.shields.io/:youtube-@sefiks-red.svg?style=flat\u0026logo=youtube)](https://www.youtube.com/@sefiks?sub_confirmation=1)\n[![Twitter](https://img.shields.io/:follow-@serengil-blue.svg?style=flat\u0026logo=x)](https://twitter.com/intent/user?screen_name=serengil)\n\n[![Patreon](https://img.shields.io/:become-patron-f96854.svg?style=flat\u0026logo=patreon)](https://www.patreon.com/serengil?repo=cipherface)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/serengil?logo=GitHub\u0026color=lightgray)](https://github.com/sponsors/serengil)\n[![Buy Me a Coffee](https://img.shields.io/badge/-buy_me_a%C2%A0coffee-gray?logo=buy-me-a-coffee)](https://buymeacoffee.com/serengil)\n\n\u003c/div\u003e\n\nCipherFace is a hybrid homomorphic encryption-driven python framework for secure cloud-based facial recognition supporting both partially homomorphic encryption and fully homomorphic encryption. It combines [DeepFace](https://github.com/serengil/deepface), [LightPHE](https://github.com/serengil/lightphe) and [TenSEAL](https://github.com/OpenMined/TenSEAL) libraries.\n\n## Installation [![PyPI](https://img.shields.io/pypi/v/cipherface.svg)](https://pypi.org/project/cipherface/)\n\nThe easiest way to install CipherFace is to download it from [`PyPI`](https://pypi.org/project/cipherface/). It's going to install the library itself and its prerequisites as well.\n\n```shell\n$ pip install cipherface\n```\n\nAlternatively, you can also install deepface from its source code. Source code may have new features not published in pip release yet.\n\n```shell\n$ git clone https://github.com/serengil/cipherface.git\n$ cd cipherface\n$ pip install -e .\n```\n\nOnce you installed the library, then you will be able to import it and use its functionalities.\n\n```python\nfrom cipherface import CipherFace, CipherFace Lite\n```\n\n# Partially Homomorphic Encryption\n\nYou need to initialize CipherFaceLite to use PHE. Currently, [Paillier](https://sefiks.com/2023/04/03/a-step-by-step-partially-homomorphic-encryption-example-with-paillier-in-python/), [Damgard-Jurik](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-damgard-jurik-in-python/), [Okamoto-Uchiyama](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-okamoto-uchiyama-in-python/) cryptosystems are supported in CipherFaceLite.\n\n## On Prem Encryption\n\nWhen you initialize a CipherFaceLite object, it sets up an PHE cryptosystem. Currently, it supports the [`VGG-Face`](https://sefiks.com/2018/08/06/deep-face-recognition-with-keras/), [`Facenet`](https://sefiks.com/2018/09/03/face-recognition-with-facenet-in-keras/), and [`Facenet512`](https://sefiks.com/2018/09/03/face-recognition-with-facenet-in-keras/) facial recognition models; cosine similarity.\n\n```python\n# build a cryptosystem\nonprem = CipherFaceLite(\n    model_name=\"Facenet\",\n    algorithm_name = \"Paillier\",\n)\n\n# export keys of built cryptosystem\nonprem.export_private_key(\"private.txt\")\nonprem.export_public_key(\"public.txt\")\n\n# create vector embedding for 1st image and encrypt in one shot\nsource_embedding_encrypted = onprem.securely_embed(img_path=\"dataset/img1.jpg\")\n```\n\nThe 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.\n\n## Encrypted Similarity Calculation On Cloud\n\nThe cloud can also generate vector embeddings. Additionally, it can compute the encrypted distance between a recently generated plain embedding and an encrypted embedding created on the on-prem side.\n\n```python\n# cloud loads cryptosystem with public key\nonprem = CipherFaceLite(\n    model_name=\"Facenet\",\n    algorithm_name = \"Paillier\",\n    cryptosystem=\"public.txt\",\n)\n\n# create vector embedding for target image and encrypt in one shot\ntarget_embedding = cloud.represent(img_path=\"dataset/target.jpg\")[0]\n\n# compare encrypted embedding and plain embedding\nencrypted_similarity = cloud.encrypted_compare(\n    source_embedding_encrypted,\n    target_embedding\n)\n```\n\n## On Prem Verification\n\nOnce the cloud calculates the encrypted similarity, 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.\n\n```python\n# on prem loads cryptosystem with private key\nonprem = CipherFaceLite(\n    model_name=\"Facenet\",\n    algorithm_name = \"Paillier\",\n    cryptosystem=\"private.txt\",\n)\n\n# on prem restores distance\ndecrypted_similarity = onprem.restore(encrypted_similarity)\n\n# verification\nis_verified = onprem.verify(decrypted_similarity)\n\nif is_verified is True:\n    print(\"they are same person\")\nelse:\n    print(\"they are different persons\")\n```\n\nIn this setup, the cloud system performs the similarity calculation, utilizing most of the computational power. The on-prem system, holding the private key, is only responsible for decrypting the similarity to determine whether the images belong to the same person or different individuals.\n\n# Fully Homomorphic Encryption\n\nYou need to initialize CipherFace object to use FHE.\n\n## On Prem Encryption\n\nWhen you initialize a CipherFace object, it sets up an FHE cryptosystem. Currently, CipherFace supports the [`VGG-Face`](https://sefiks.com/2018/08/06/deep-face-recognition-with-keras/), [`Facenet`](https://sefiks.com/2018/09/03/face-recognition-with-facenet-in-keras/), and [`Facenet512`](https://sefiks.com/2018/09/03/face-recognition-with-facenet-in-keras/) facial recognition models, as well as Euclidean and cosine distance metrics.\n\n```python\n# build a cryptosystem\nonprem = CipherFace(\n    model_name=\"Facenet\",\n    distance_metric=\"euclidean\",\n)\n\n# export keys of built cryptosystem\nonprem.export_private_key(\"private.txt\")\nonprem.export_public_key(\"public.txt\")\n\n# create vector embedding for 1st image and encrypt in one shot\nsource_embedding_encrypted = onprem.securely_embed(img_path=\"dataset/img1.jpg\")\n```\n\nThe 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.\n\n## Encrypted Distance Calculation On Cloud\n\nThe 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.\n\n```python\n# cloud loads cryptosystem with public key\nonprem = CipherFace(\n    model_name=\"Facenet\",\n    distance_metric=\"euclidean\",\n    cryptosystem=\"public.txt\",\n)\n\n# create vector embedding for target image and encrypt in one shot\ntarget_embedding_encrypted = cloud.securely_embed(img_path=\"dataset/target.jpg\")[0]\n\nencrypted_distance = cloud.encrypted_compare(\n    target_embedding_encrypted,\n    source_embedding_encrypted\n)\n```\n\n## On Prem Verification\n\nOnce 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.\n\n```python\n# on prem loads cryptosystem with private key\nonprem = CipherFace(\n    model_name=\"Facenet\",\n    distance_metric=\"euclidean\",\n    cryptosystem=\"private.txt\",\n)\n\n# on prem restores distance\ndecrypted_distance = onprem.restore(encrypted_distance)\n\n# verification\nis_verified = onprem.verify(decrypted_distance)\n\nif is_verified is True:\n    print(\"they are same person\")\nelse:\n    print(\"they are different persons\")\n```\n\nIn 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.\n\n## Contribution\n\nPull 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.\n\nBefore creating a PR, you should run the unit tests and linting locally by running `make test \u0026\u0026 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](https://github.com/serengil/cipherface/actions) before approval.\n\n## Support\n\nThere are many ways to support a project - starring⭐️ the GitHub repo is just one 🙏\n\nIf you do like this work, then you can support it financially on [Patreon](https://www.patreon.com/serengil?repo=deepface), [GitHub Sponsors](https://github.com/sponsors/serengil) or [Buy Me a Coffee](https://buymeacoffee.com/serengil).\n\n\u003ca href=\"https://www.patreon.com/serengil?repo=deepface\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/serengil/deepface/master/icon/patreon.png\" width=\"30%\"\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://github.com/sponsors/serengil\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/serengil/deepface/refs/heads/master/icon/github_sponsor_button.png\" width=\"37%\"\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://buymeacoffee.com/serengil\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/serengil/deepface/master/icon/bmc-button.png\" width=\"25%\"\u003e\n\u003c/a\u003e\n\n## Citation\n\nPlease cite CipherFace in your publications if it helps your research. Here is its BibTex entries:\n\n```BibTeX\n@article{serengil2025cipherfacelite,\n  title={Encrypted Vector Similarity Computations Using Partially Homomorphic Encryption: Applications and Performance Analysis},\n  author={Serengil, Sefik and Ozpinar, Alper},\n  journal={arXiv preprint arXiv:2503.05850},\n  note={doi: 10.48550/arXiv.2503.05850. [Online]. Available: \\url{https://arxiv.org/abs/2503.05850}},\n  year={2025}\n}\n```\n\n```BibTeX\n@article{serengil2025cipherface,\n  title={CipherFace: A Fully Homomorphic Encryption-Driven Framework for Secure Cloud-Based Facial Recognition},\n  author={Serengil, Sefik and Ozpinar, Alper},\n  journal={arXiv preprint arXiv:2502.18514},\n  note={doi: 10.48550/arXiv.2502.18514. [Online]. Available: \\url{https://arxiv.org/abs/2502.18514}},\n  year={2025}\n}\n```\n\n## Licence\n\nCipherFace is licensed under the MIT License - see [`LICENSE`](https://github.com/serengil/cipherface/blob/master/LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserengil%2Fcipherface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserengil%2Fcipherface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserengil%2Fcipherface/lists"}