Issues in documentation

[hvge]

Hello,
I'm sending you a several suggestions about the documentation, just to be clear and to prevent some possible misinterpretations:

• PBKDF2 should be more specified
  • Please add which pseudorandom function is used in the scheme (e.g. HMAC-SHA256, SHA1, etc...)
  • Please specify what's your notation for that function. Now the implementer don't know what's the salt, password, etc...
• Mysterious GET_BYTES function
  • ...is completely unclear. I didn't get it. Is it a conversion from already pure ASCII to "just to be sure UTF-8" or some conversion from BASE32 to binary data? Or some kind of type abstraction, like "now we're casting a string into a blob of binary data"?
  • GET_BYTES(ACTIVATION_ID_SHORT + "-" + ACTIVATION_OTP, "UTF-8") ... i guess that in this case it is converting B32 into bytes. So then, the function will have to deal with separator, which is not a valid character for B32 encoding. That's creepy. I understand that in some activation step we'll show that to the user and thus the visual separator is very appreciated, but this fact should not affect a way, how the information is transmitted over the network or via the QR code..
• Usage of AES
  • The block mode and padding scheme is not specified.
  • Instead of simple "AES" & "AES^inverse", you should use AES_encrypt / AES_decrypt, just to be more clear
  • The same as PBKDF2, it's unclear what's your notation (e.g. what's password, data, iv...)
• Usage of ECDSA
  • Similar to AES. It's better to use ECDSA_sign / ECDSA_verify naming instead of ECDSA / ECDSA^inverse
  • There's SHA256withECDSA signature used, but that's mentioned in the code examples only. Should be also in the pseudo-algorithm part of the documentation
• BASE64
  • BASE64Encode doesn't have "encoding" parameter, like UTF8. I think it's not necessary to highlight, that result is a string :)

Well, hope that's all. I think it will be enough to add some introduction notes, which will describe what's going on when, for example, PBKDF2 is used in the documentation. Something like "PBKDF2(salt, password, iterations) uses HMAC_SHA256 as pseudorandom function.", "AES_Encrypt(data, iv, key) means AES in OFB mode with PKCS7 padding", etc...

[petrdvorak]

Thank you for detailed comments, Juraj!

I should probably:

• Start the document with some basic function definition.
• Use Java-like syntax for pseudo-code to make some things more clear
  • I guess that ("hello" + "world").getBytes("UTF-8") is more readable than GET_BYTES("hello" + "world", "UTF-8")
  • This also causes the issue with "Base64 encoding" syntax - does not make sense unless you know that I mean Base64.encode("hello".getBytes("UTF-8")) by this cryptic syntax.
• The whole use base64 is a bit chaotic there - in code, it is apparent that base64 plays role only in networking (there is no base64 reference in the powerauth-java library). I should drop base64 from the cryptography description and re-introduce it with RESTful APIs.

For now, please have a look at used cryptography in "powerauth-java" project to see what is going on while I fix the documentation.

[petrdvorak]

I have committed an improved version:

• added definitions in the beginning
• pseudo-code is more Java-like
• I cleared Base64 from the crypto description

Please could you have another pass-through and send updated feedback, before we can close the issue?

[petrdvorak]

There is one more hint: we should probably split the "monolith document" into multiple documents to improve information discoverability.

[petrdvorak]

Document is broken down into multiple smaller chapters, hopefully this will do.

[hvge]

Thank you. That's what I'm calling an improvement 👍 I'm closing this issue.