{"id":13603977,"url":"https://github.com/facebookarchive/conceal","last_synced_at":"2025-04-11T22:32:19.850Z","repository":{"id":13534553,"uuid":"16226063","full_name":"facebookarchive/conceal","owner":"facebookarchive","description":"Conceal provides easy Android APIs for performing fast encryption and authentication of data.","archived":true,"fork":false,"pushed_at":"2019-01-22T20:01:11.000Z","size":43992,"stargazers_count":2956,"open_issues_count":29,"forks_count":428,"subscribers_count":174,"default_branch":"master","last_synced_at":"2025-04-04T10:37:11.018Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://facebook.github.io/conceal/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facebookarchive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-25T06:22:49.000Z","updated_at":"2025-04-01T15:23:14.000Z","dependencies_parsed_at":"2022-09-04T05:13:00.830Z","dependency_job_id":null,"html_url":"https://github.com/facebookarchive/conceal","commit_stats":null,"previous_names":["facebook/conceal"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fconceal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fconceal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fconceal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookarchive%2Fconceal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebookarchive","download_url":"https://codeload.github.com/facebookarchive/conceal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640459,"owners_count":20971557,"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","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":[],"created_at":"2024-08-01T19:00:37.533Z","updated_at":"2025-04-11T22:32:14.838Z","avatar_url":"https://github.com/facebookarchive.png","language":"C++","funding_links":[],"categories":["C++","安全"],"sub_categories":[],"readme":"## What is Conceal? [![Build Status](https://travis-ci.org/facebook/conceal.svg?branch=master)](https://travis-ci.org/facebook/conceal)\n\nConceal provides a set of Java APIs to perform cryptography on Android. \nIt was designed to be able to encrypt large files on disk in a fast and \nmemory efficient manner. \n\nThe major target for this project is typical Android devices which run old \nAndroid versions, have low memory and slower processors.\n\nUnlike other libraries, which provide a Smorgasbord of encryption algorithms \nand options, Conceal prefers to abstract this choice and use sane defaults. \nThus Conceal is not a general purpose crypto library, however it aims to provide \nuseful functionality.\n\n***Upgrading version?*** Check the [Upgrade notes](#upgrade-notes) for key compatibility!\n\n#### IMPORTANT: Initializing the library loader\n\nSince v2.0.+ (2017-06-27) you will need to initialize the native library loader.\nThis step is needed because the library loader uses the context.\nThe highly suggested way to do it is in the application class onCreate method like this:\n\n```java\nimport com.facebook.soloader.SoLoader;\npublic class MyApplication extends Application {\n    @Override\n    public void onCreate() {\n        super.onCreate();\n        SoLoader.init(this, false);\n    }\n}\n```\n\n## Quick start\n\n#### Setup options\n\n1. **Use Maven Central**: Available on maven central under **com.facebook.conceal:conceal:2.0.1@aar** as an AAR package.\nIf you use Android Studio and select the library using the UI, **make sure** to change `build.gradle` **to include the `@aar` suffix**. Otherwise the library won't be included.\n\n2. **Build using gradle**\n\n```bash\n./gradlew build\n```\n\nIt uses gradlew so it takes care of downloading Gradle and all the dependencies it needs.\nOutput will be in `/build/outputs/aar/` directory.\n\n3. **Use prebuilt binaries**: http://facebook.github.io/conceal/documentation/. (linked documentation needs update)\n\n###### An aside on KitKat\n\u003e Conceal predates Jellybean 4.3. On KitKat, Android changed the provider for \n\u003e cryptographic algorithms to OpenSSL. The default Cipher stream however still \n\u003e does not perform well. When replaced with our Cipher stream \n\u003e (see BetterCipherInputStream), the default implementation is competitive against \n\u003e Conceal. On older phones, Conceal is faster than the system provided libraries.\n\n#### Re-build OpenSSL library\n\nYou can run make from the openssl directory. It will download the code and copile the libraries for each architecture.\n\n```bash\n# go to /third-party/openssl\nmake\n```\n\n#### Before running any test!\n\nTest uses BUCK build tool. BUCK uses the source code for OpenSSL. If you didn't already rebuilt OpenSSL form scrach (previous item) then\nrun this:\n\n```bash\n# go to /third-party/openssl\nmake clone\n```\n\nThat will download the OpenSSL code to a subdirectory.\n\n#### Running unit tests\n```bash\n# C++ tests\nbuck test :cpp\n```\n\n#### Running integration tests\n```bash\n# Emulator/device tests\n./instrumentTest/crypto/run\n```\n\nSince Conceal uses native libraries, the only way to run a test on the entire\nencryption process is using integration tests.\n\n#### Running Benchmarks\n```bash\n./benchmarks/run \\\n  benchmarks/src/com/facebook/crypto/benchmarks/CipherReadBenchmark.java \\\n  -- -Dsize=102400\n```\n\nThis script runs vogar with caliper benchmarks.\nYou can also specify all the options caliper provides.\n\n## Usage\n\n#### Entity and keys\n\n**Entity:** this is a not-secret identifier of your data. It's used for integrity check purposes (to know that the content has not been tampered) and also to verify it was not swapped with another valid encrypted content/file.\n\n**Key:** the key is provided by the KeyChain implementation passed to the Crypto object. So each time a new encryption is requested, the key is requested to the KeyChain. The key is generated randomly the first time on demand. You might change the implementation by we strongly suggest to generate a random value. If the encryption key needs for some reason to be based on a text password, you can try using the PasswordBasedKeyGenerator object.\n\n#### Encryption\n```java\n// Creates a new Crypto object with default implementations of a key chain\nKeyChain keyChain = new SharedPrefsBackedKeyChain(context, CryptoConfig.KEY_256);\nCrypto crypto = AndroidConceal.get().createDefaultCrypto(keyChain);\n\n// Check for whether the crypto functionality is available\n// This might fail if Android does not load libaries correctly.\nif (!crypto.isAvailable()) {\n  return;\n}\n\nOutputStream fileStream = new BufferedOutputStream(\n  new FileOutputStream(file));\n\n// Creates an output stream which encrypts the data as\n// it is written to it and writes it out to the file.\nOutputStream outputStream = crypto.getCipherOutputStream(\n  fileStream,\n  Entity.create(\"entity_id\"));\n\n// Write plaintext to it.\noutputStream.write(plainText);\noutputStream.close();\n```\n\n#### Decryption\n```java\n// Get the file to which ciphertext has been written.\nFileInputStream fileStream = new FileInputStream(file);\n\n// Creates an input stream which decrypts the data as\n// it is read from it.\nInputStream inputStream = crypto.getCipherInputStream(\n  fileStream,\n  Entity.create(\"entity_id\"));\n\n// Read into a byte array.\nint read;\nbyte[] buffer = new byte[1024];\n\n// You must read the entire stream to completion.\n// The verification is done at the end of the stream.\n// Thus not reading till the end of the stream will cause\n// a security bug. For safety, you should not\n// use any of the data until it's been fully read or throw\n// away the data if an exception occurs.\nwhile ((read = inputStream.read(buffer)) != -1) {\n  out.write(buffer, 0, read);\n}\n\ninputStream.close();\n```\n\nIf you don't have a lot of data to encrypt, you could\nuse the convenience functions:\n\n```java\nbyte[] cipherText = crypto.encrypt(plainText, Entity.create(\"mytext\"));\n\nbyte[] plainText = crypto.decrypt(cipherText, Entity.create(\"mytext\"));\n```\n\n#### Integrity\n```java\nOutputStream outputStream = crypto.getMacOutputStream(fileStream, entity);\noutputStream.write(plainTextBytes);\noutputStream.close();\n\nInputStream inputStream = crypto.getMacInputStream(fileStream, entity);\n\n// Will throw an exception if mac verification fails.\n// You must read the entire stream to completion.\n// The verification is done at the end of the stream.\n// Thus not reading till the end of the stream will cause\n// a security bug. For safety, you should not\n// use any of the data until it's been fully read or throw\n// away the data if an exception occurs.\nwhile((read = inputStream.read(buffer)) != -1) {\n  out.write(buffer, 0, read);\n}\ninputStream.close();\n```\n\n### Upgrade notes\n\nStarting with v1.1 recommended encryption will use a 256-bit key (instead of 128-bit). This means stronger security.\nYou should use this default.\n\nIf you need to read from an existing file, you still will need 128-bit encryption. You can use the old way of creating `Crypto` objects as it preserves its 128-bit behavior. Although ideally you should re-encrypt that content with a 256-bit key.\n\nAlso there's an improved way of creating Entity object which is platform independent. It's strongly recommended for new encrypted items although you need to stick to the old way for already encrypted content.\n\n#### Existing code still with 128-bit keys and old Entity (deprecated)\n\n```java\n// this constructor creates a key chain that produces 128-bit keys\nKeyChain keyChain = new SharedPrefsBackedKeyChain(context);\n// this constructor creates a crypto that uses  128-bit keys\nCrypto crypto = new Crypto(keyChain, library);\nEntity entity = new Entity(someStringId);\n```\n\n#### New code using 256-keys and Entity.create\n\nWe recommend the use of the factory class `AndroidConceal`.\n\n```java\n// explicitely create 256-bit key chain\nKeyChain keyChain = new SharedPrefsBackedKeyChain(context, CryptoConfig.KEY_256);\n// create the default crypto (expects 256-bit key)\nAndroidConceal.get().createDefaultCrypto(keyChain);\n// factory class also has explicit methods: createCrypto128Bits and ceateCrypto256Bits if desired.\nEntity entity = Entity.create(someStringId);\n```\n\n## Troubleshooting\n\n#### I'm getting NoSuchFieldError on runtime\n\nIf you hit an error on runtime and it says something similar to:\n\n````\njava.lang.NoSuchFieldError: no field with name='mCtxPtr' signature='J' in class Lcom/facebook/crypto/cipher/NativeGCMCipher;\n````\n\nThis happens because native code needs to refer to Java fields/methods. For doing so it uses typical JNI functions which receive the name and signature. At the same time tools like proguard trim off or rename class members in order to get smaller executables. Normally this process is run on release versions. When native code request the member, it's not present anymore.\n\nTo avoid this kind of problems exceptions can be defined. You will need to configure proguard with the rules defined in ``proguard_annotations.pro``. You can use the file as is, or you can include its content in your own proguard configuration file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookarchive%2Fconceal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebookarchive%2Fconceal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookarchive%2Fconceal/lists"}