From 03c958a97c7520f4406728c7f10597c1d9bd0aaf Mon Sep 17 00:00:00 2001 From: Roman Strobl Date: Thu, 3 Oct 2024 15:08:11 +0800 Subject: [PATCH] Fix #654: Add temporary keys into the list of keys --- docs/List-of-Used-Keys.md | 31 +++++++++++++++++++++++++++++++ docs/List-of-used-keys.md | 30 ------------------------------ docs/_Sidebar.md | 2 +- 3 files changed, 32 insertions(+), 31 deletions(-) create mode 100644 docs/List-of-Used-Keys.md delete mode 100644 docs/List-of-used-keys.md diff --git a/docs/List-of-Used-Keys.md b/docs/List-of-Used-Keys.md new file mode 100644 index 00000000..abcda3ff --- /dev/null +++ b/docs/List-of-Used-Keys.md @@ -0,0 +1,31 @@ +# List of Used Keys + +The following keys are used in the PowerAuth cryptography scheme. + +## Application Scoped Keys + +| name | created as | purpose | +|-----------------------------|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `KEY_SERVER_MASTER_PRIVATE` | ECDH - private key | Embedded on server, used to assure authenticity of data during the transfer from server to client during application scoped use-cases (i.e., device activation). | +| `KEY_SERVER_MASTER_PUBLIC` | ECDH - public key | Embedded in client app, used to verify authenticity of data while transferring from server to client during application scoped use-cases (i.e., device activation). | +| `APP_KEY` | Application version key | Shared random ID between the server and client app, used to identify specific application version. The value travels in plain form over HTTPS channel. | +| `APP_SECRET` | Application version secret | Shared random secret key between the server and client app, used to authenticate specific application version. Used in digest and MAC values. | +| `KEY_ENC_TEMPORARY` | Temporary encryption key pair | Temporary encryption key pair used in end-to-end encryption in application scope. The key pair enhances security by ensuring forward secrecy for encrypted data. | + +## Activation Scoped Keys + +| name | created as | purpose | +|----------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `KEY_DEVICE_PRIVATE` | ECDH - private key | Generated on client to allow construction of `KEY_MASTER_SECRET`. | +| `KEY_DEVICE_PUBLIC` | ECDH - public key | Generated on client to allow construction of `KEY_MASTER_SECRET`. | +| `KEY_SERVER_PRIVATE` | ECDH - private key | Generated on server to allow construction of `KEY_MASTER_SECRET`. | +| `KEY_SERVER_PUBLIC` | ECDH - public key | Generated on server to allow construction of `KEY_MASTER_SECRET`. | +| `KEY_MASTER_SECRET` | ECDH - pre-shared | A key deduced using ECDH derivation, `KEY_MASTER_SECRET = ECDH.phase(KEY_DEVICE_PRIVATE, KEY_SERVER_PUBLIC) = ECDH.phase(KEY_SERVER_PRIVATE, KEY_DEVICE_PUBLIC)` and then reduced with `ByteUtils.convert32Bto16B()`. | +| `KEY_SIGNATURE_POSSESSION` | KDF derived key from `KEY_MASTER_SECRET` | A signing key associated with the possession, factor deduced using KDF derivation with `INDEX = 1`, `KEY_SIGNATURE_POSSESSION = KDF.derive(KEY_MASTER_SECRET, 1)`, used for subsequent request signing. | +| `KEY_SIGNATURE_KNOWLEDGE` | KDF derived key from `KEY_MASTER_SECRET` | A key associated with the knowledge factor, deduced using KDF derivation with `INDEX = 2`, `KEY_SIGNATURE_KNOWLEDGE = KDF.derive(KEY_MASTER_SECRET, 2)`, used for subsequent request signing. | +| `KEY_SIGNATURE_BIOMETRY` | KDF derived key from `KEY_MASTER_SECRET` | A key associated with the biometry factor, deduced using KDF derivation with `INDEX = 3`, `KEY_SIGNATURE_BIOMETRY = KDF.derive(KEY_MASTER_SECRET, 3)`, used for subsequent request signing. | +| `KEY_TRANSPORT` | KDF derived key from `KEY_MASTER_SECRET` | A key deduced using KDF derivation with `INDEX = 1000`, `KEY_TRANSPORT = KDF.derive(KEY_MASTER_SECRET, 1000)`, used for encrypted data transport. This key is used as master transport key for end-to-end encryption key derivation. | +| `KEY_ENCRYPTION_VAULT` | KDF derived key from `KEY_MASTER_SECRET` | A key deduced using KDF derivation with `INDEX = 2000`, `KEY_ENCRYPTION_VAULT = KDF.derive(KEY_MASTER_SECRET, 2000)`, used for encrypting a vault that stores the secret data, such as `KEY_DEVICE_PRIVATE`. | +| `KEY_TRANSPORT_IV` | KDF derived key from `KEY_TRANSPORT` | A key deduced using KDF derivation with `INDEX = 3000`, `KEY_ENCRYPTION_IV = KDF.derive(KEY_TRANSPORT, 3000)`, used for derivation of initial vector, that encrypts activation status blob. | +| `KEY_TRANSPORT_CTR` | KDF derived key from `KEY_TRANSPORT` | A key deduced using KDF derivation with `INDEX = 4000`, `KEY_TRANSPORT_CTR = KDF.derive(KEY_TRANSPORT, 4000)`, used for computing hash from current value of hash-based counter. | +| `KEY_ENC_TEMPORARY` | Temporary encryption key pair | Temporary encryption key pair used in end-to-end encryption in activation scope. This key pair enhances security by ensuring forward secrecy for encrypted data. | diff --git a/docs/List-of-used-keys.md b/docs/List-of-used-keys.md deleted file mode 100644 index 11b322b2..00000000 --- a/docs/List-of-used-keys.md +++ /dev/null @@ -1,30 +0,0 @@ -# List of Used Keys - -The following keys are used in the PowerAuth cryptography scheme. - -## Application Scoped Keys - -| name | created as | purpose | -|-----------------------------|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `KEY_SERVER_MASTER_PRIVATE` | ECDH - private key | Embedded on server, used to assure authenticity of data during the transfer from server to client during application scoped use-cases (i.e., device activation). | -| `KEY_SERVER_MASTER_PUBLIC` | ECDH - public key | Embedded in client app, used to verify authenticity of data while transferring from server to client during application scoped use-cases (i.e., device activation). | -| `APP_KEY` | Application version key | Shared random ID between the server and client app, used to identify specific application version. The value travels in plain form over HTTPS channel. | -| `APP_SECRET` | Application version secret | Shared random secret key between the server and client app, used to authenticate specific application version. Used in digest and MAC values. | - - -## Activation Scoped Keys - -| name | created as | purpose | -|-----------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `KEY_DEVICE_PRIVATE` | ECDH - private key | Generated on client to allow construction of `KEY_MASTER_SECRET`. | -| `KEY_DEVICE_PUBLIC` | ECDH - public key | Generated on client to allow construction of `KEY_MASTER_SECRET`. | -| `KEY_SERVER_PRIVATE` | ECDH - private key | Generated on server to allow construction of `KEY_MASTER_SECRET`. | -| `KEY_SERVER_PUBLIC` | ECDH - public key | Generated on server to allow construction of `KEY_MASTER_SECRET`. | -| `KEY_MASTER_SECRET` | ECDH - pre-shared | A key deduced using ECDH derivation, `KEY_MASTER_SECRET = ECDH.phase(KEY_DEVICE_PRIVATE, KEY_SERVER_PUBLIC) = ECDH.phase(KEY_SERVER_PRIVATE, KEY_DEVICE_PUBLIC)` and then reduced with `ByteUtils.convert32Bto16B()`. | -| `KEY_SIGNATURE_POSSESSION` | KDF derived key from `KEY_MASTER_SECRET` | A signing key associated with the possession, factor deduced using KDF derivation with `INDEX = 1`, `KEY_SIGNATURE_POSSESSION = KDF.derive(KEY_MASTER_SECRET, 1)`, used for subsequent request signing. | -| `KEY_SIGNATURE_KNOWLEDGE` | KDF derived key from `KEY_MASTER_SECRET` | A key associated with the knowledge factor, deduced using KDF derivation with `INDEX = 2`, `KEY_SIGNATURE_KNOWLEDGE = KDF.derive(KEY_MASTER_SECRET, 2)`, used for subsequent request signing. | -| `KEY_SIGNATURE_BIOMETRY` | KDF derived key from `KEY_MASTER_SECRET` | A key associated with the biometry factor, deduced using KDF derivation with `INDEX = 3`, `KEY_SIGNATURE_BIOMETRY = KDF.derive(KEY_MASTER_SECRET, 3)`, used for subsequent request signing. | -| `KEY_TRANSPORT` | KDF derived key from `KEY_MASTER_SECRET` | A key deduced using KDF derivation with `INDEX = 1000`, `KEY_TRANSPORT = KDF.derive(KEY_MASTER_SECRET, 1000)`, used for encrypted data transport. This key is used as master transport key for end-to-end encryption key derivation. | -| `KEY_ENCRYPTION_VAULT` | KDF derived key from `KEY_MASTER_SECRET` | A key deduced using KDF derivation with `INDEX = 2000`, `KEY_ENCRYPTION_VAULT = KDF.derive(KEY_MASTER_SECRET, 2000)`, used for encrypting a vault that stores the secret data, such as `KEY_DEVICE_PRIVATE`. | -| `KEY_TRANSPORT_IV` | KDF derived key from `KEY_TRANSPORT` | A key deduced using KDF derivation with `INDEX = 3000`, `KEY_ENCRYPTION_IV = KDF.derive(KEY_TRANSPORT, 3000)`, used for derivation of initial vector, that encrypts activation status blob. | -| `KEY_TRANSPORT_CTR` | KDF derived key from `KEY_TRANSPORT` | A key deduced using KDF derivation with `INDEX = 4000`, `KEY_TRANSPORT_CTR = KDF.derive(KEY_TRANSPORT, 4000)`, used for computing hash from current value of hash-based counter. | \ No newline at end of file diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index a653a6ac..9d2cde9c 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -28,7 +28,7 @@ - [Additional Activation OTP](./Additional-Activation-OTP.md) - [Implementation Details](./Implementation-notes.md) - [List of Used Algorithms](./List-of-Used-Algorithms.md) -- [List of Used Keys](./List-of-used-keys.md) +- [List of Used Keys](./List-of-Used-Keys.md) **Tutorials**