From 6d4583f5de0dea88e1e57704e2d630b34d745636 Mon Sep 17 00:00:00 2001 From: Evgenii Stratonikov Date: Tue, 16 Apr 2024 14:01:25 +0300 Subject: [PATCH] [#1097] docs: Describe authentication mechanisms Signed-off-by: Evgenii Stratonikov --- docs/authentication.md | 57 ++++++++++++++++++++ docs/images/authentication/authoverview.puml | 28 ++++++++++ docs/images/authentication/authoverview.svg | 1 + 3 files changed, 86 insertions(+) create mode 100644 docs/authentication.md create mode 100644 docs/images/authentication/authoverview.puml create mode 100644 docs/images/authentication/authoverview.svg diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 000000000..4efb03f93 --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,57 @@ +# Authentication and signatures + +## General overview + +![Auth general overview](images/authentication/authoverview.svg) + +## Signatures + +Every message in the FrostFS network is signed. +Each signature consists of: +1. Scheme +2. Public key +3. Signature + +If signature check fails, operation is aborted and the error is returned to the user. + +### Schemes +Currently, 3 schemes are defined in the [frostfs-api](https://git.frostfs.info/TrueCloudLab/frostfs-api/src/commit/4bae9dd78abcf1a358a65a45fe7303e37fd98099/refs/types.proto#L105): + +#### ECDSA + +Defined in section 6 of [FIPS 186](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf). +Implemented in the Go stdlib. +This is the primary algorithm used to sign and verify requests. +The hash algorithm used is SHA-512. + +#### RFC6979 + +[RFC 6979](https://www.rfc-editor.org/rfc/rfc6979) defines deterministic algorithm for ECDSA signatures. +It it used primarily used by neo-go and allows us to perform signature checks inside the contract, such as for container. +The hash algorithm used is SHA-256 + +### Public key + +ECDSA public key corresponding to the private key being used to sign a message. +It is the primary user identity and is used to determine the request originator. + +## Session token + +Session token can override the rules of determining request owner. +It is defined in the [frostfs-api](https://git.frostfs.info/TrueCloudLab/frostfs-api/src/branch/master/session/types.proto#L89). +If user A signs a session token for user B, then user B can sign request with its own key, while the node will still process the request as if it was originated from user A. +This is used, for example, when putting objects in system: +1. User creates a session with node, recevieving session token. +2. User signs session token for a freshly generated key, stored on a storage node. +3. User sends raw stream of bytes, while the node signs created objects with the session key. This way other nodes can validate the object owned by user, even though it is signed by a different key. + +Session token may have some restrictions: +1. Lifetime, effectively an epoch after which it becomes invalid. +2. Set of operations it applies to. +3. The entity it is given to. This is provided in `session_key` field containing the public key. + +## Bearer token + +## FrostFS ID + +## APE \ No newline at end of file diff --git a/docs/images/authentication/authoverview.puml b/docs/images/authentication/authoverview.puml new file mode 100644 index 000000000..1242fdfc6 --- /dev/null +++ b/docs/images/authentication/authoverview.puml @@ -0,0 +1,28 @@ +@startuml authoverview +!include +!include +AddElementTag("smart-contract", $bgColor=#0abab5) + +Person(user, "User", "User with private key") + +Container_Boundary(stor, "FrostFS Storage") { + Component(verify, "Sign Service", $descr="Check request signature") + Component(apesvc, "APE Service") + Component(objsvc, "Object service") +} + +Container_Boundary(neogo, "Blockchain") { + Interface "NeoGo" + Component(ffsid, "FrostFS ID", $tags="smart-contract", $descr="Stores namespaces and users") + Component(policy, "Policy", $tags="smart-contract", $descr="Stores APE rules") +} + +Rel_R(user, verify, "Requests", "gRPC") +Rel_R(verify, apesvc, "Access control") +Rel_R(apesvc, objsvc, "Operation") +Rel_D(apesvc, NeoGo, "Get data to validate request") +Rel("NeoGo", ffsid, "Fetch users") +Rel("NeoGo", policy, "Fetch policies") + +SHOW_LEGEND(true) +@enduml \ No newline at end of file diff --git a/docs/images/authentication/authoverview.svg b/docs/images/authentication/authoverview.svg new file mode 100644 index 000000000..a34a68da0 --- /dev/null +++ b/docs/images/authentication/authoverview.svg @@ -0,0 +1 @@ +FrostFS Storage[Container]Blockchain[Container]Sign Service Check request signatureAPE ServiceObject serviceNeoGoFrostFS ID Stores namespaces andusersPolicy Stores APE rulesUser User with private keyRequests[gRPC]Access controlOperationGet data to validaterequestFetch usersFetch policiesLegend ▯ person ▯ component ▯ container boundary(dashed) ▯ smart-contract(last text color)  \ No newline at end of file