search

facebookarchive / conceal

Conceal provides easy Android APIs for performing fast encryption and authentication of data.
http://facebook.github.io/conceal/
Other
2.96k stars 431 forks source link

docs clarification #173

Closed vonovak closed 7 years ago

vonovak commented 7 years ago

In the documentation, you provide short examples on how to encrypt and decrypt some data. My question is: in Entity.create("entity_id")); what exactly is the entity_id?

I assume that string must a be a secret key? In other words, am I right in thinking that if you steal somebody's encrypted content and guess this string, you will b able to decrypt the message? If that is the case, I believe the "entity_id" string should be renamed something that conveys the importance of keeping this string secret.

Thanks

helios175 commented 7 years ago

The secret value is the key, provided by the KeyChain implementation. That's what's used for encryption and for hashing content.

Entity id is a ok-to-be-public value that represents the identity of that file. It's used to check integrity.

Let's say we encrypt two files F1 and F2. An attacker doesn't have access to the key. What could the attacker do? 1) change encrypted content to produce another intended plain content: they lack the key (from key chain) to use it 2) change encrypted content to produce some random intended plain content: they could do that, but there's an extra step on encryption for integrity check (to know it wasn't touched). That step generates a tail tag (or integrity tag) from (key, the IV [a random value used only once when encrypting], and the entity). It's guaranteed by algorithm properties (AES/GCM) that an attacker cannot produce a modified encrypted content and find the corresponding integrity tag for the changed content. 3) swap two valid files: let's say an attacker renames our two files: F1 -> F2, and F2 -> F1. All the integrity checks would pass. If we want to avoid this we need to link somehow the entity id to that. For example, entity id can be the file name. In that case if we try to decrypt F1 we will say it's entity = F1, therefore, if the file has been swapped it will fail integrity check and we will detect this case.

Summarizing: the entity is used to identify the content in a unique way among your different files/contents. It's ok for it to be public as the secret used to encrypt is the key. And the general health of the encryption is guarded by the secret key and the only-used-once IV value, generated for each call to a new encryption. [See AES/GCM documentation for more insight on how that works]

CarlTien commented 7 years ago

i find that the entity is useless , i use different value in input and output , but it still work well , there is no error.

Thanks