paragonie/ciphersweet

Documentation enhancement request (re: Blind Index Planning)

udf2457 opened this issue · 9 comments

udf2457 commented

Hi,

Re: The Blind Index Planning page of the docs (https://ciphersweet.paragonie.com/php/blind-index-planning)

It would be helpful for the non-cryptographers amongst us to perhaps provide a plain-english definition of what you mean by the terms output size and input domain.

I have tried asking Mr Google what an index input domain is but he was not being particularly helpful. Therefore whilst I think I know what you mean by the term, I would rather be "safe than sorry" and see a plain-english definition magically appear in the docs. ;-)

Thanks and keep up the fabulous work !

paragonie-scott commented

Absolutely.

The term input domain is related to the concepts of the "domain" and "range" of a function in algebra. Another term that's used in a similar context is "keyspace".

This will be explained in our next documentation update. 👍

  • 👍1
udf2457 commented

https://ciphersweet.paragonie.com/php/blind-index-planning -- how does this look now?

A significant step in in the right direction. If I were being picky, I might question the following:

  1. Whether the expression "existing index ("name_goes_here") has an output size of" perhaps needs to be tweaked ? Since in essence you're talking about the (average) length of the plaintext before it gets encrypted, right ?

  2. The hot-off-the-press definition for Output size, you say "you want your blind index output to be". But surely it's not necessarily a case of what "I" want ? Since the purpose of FieldIndexPlanner is to give me the recommended range ? Taking your example code, going by your definition, I'm saying "I want the output to be 16" but then the output from FieldIndexPlanner is saying "No, between 4 and 11". (Maybe I'm overthinking this point though !)

paragonie-scott commented

Since in essence you're talking about the (average) length of the plaintext before it gets encrypted, right ?

No, the output sizes of other indexes built from the same input diminish the safe boundary of your new index on the same input.

udf2457 commented

Alright, let me have a another noob go at "getting" this whole output size thing....

Are you saying output size for FieldIndexPlanner is like blake2b and its "pick your own digest length" approach ?

paragonie-scott commented

I've updated the documentation once again: https://ciphersweet.paragonie.com/php/blind-index-planning

  • 👍1
paragonie-scott commented

Are you saying output size for FieldIndexPlanner is like blake2b and its "pick your own digest length" approach ?

Yes, your output size is something you get to choose. The planner tells you the minimum and maximum safe values (inclusive).

When you're adding an existing index, you have to provide the output size of each existing index. That will inform the planner of how much leakage is already present in the existing indexes, and therefore how much to limit the recommendations for an additional index on the same field.

udf2457 commented

I've updated the documentation once again: https://ciphersweet.paragonie.com/php/blind-index-planning

That's awesome ! Now it all clicks ! Turns out I was overthinking what needed too be done at the first stage, and also the whole thing about concatenations on the same data was sort of there in my mind but I couldn't see how the pieces of the indexing planner jigsaw fitted together to keep things safe, which I do now.

Thanks for your patience !

paragonie-scott commented

Happy to help! Thanks for your valuable feedback on improving our documentation. :)