frostfs-node/docs/authentication.md

# 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.

## Tokens

Generally, the request owner, i.e. an account all access control checks are applied to
is taken from the request signature.
However, session and bearer tokens can alter authentication process by making "effective" request owner differ from the actual one.
The general scheme is given by the following picture:

![Token processing](images/authentication/impersonate.svg)

It is important to note, that the token is only valid when the request signature corresponds to the actor token is issued to.

### 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

Bearer token is generally used for access control but can also affect authentication if `allow_impersonate` flag is set. With this flag it behaves similarly to session token.

## FrostFS ID

## APE