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

docs/images/authentication/authoverview.puml

@@ -0,0 +1,28 @@
+@startuml authoverview
+!include <c4/C4_Container.puml>
+!include <c4/C4_Component.puml>
+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