frostfs-api/proto-docs/acl.md
Stanislav Bogatyrev a6ecab41b8 Update auto-generated docs
Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
2020-10-16 14:40:24 +03:00

8.8 KiB

Protocol Documentation

Table of Contents

Top

acl/types.proto

Message BearerToken

BearerToken allows to attach signed Extended ACL rules to the request in RequestMetaHeader. If container's Basic ACL rules allow, the attached rule set will be checked instead of one attached to the container itself. Just like JWT, it has a limited lifetime and scope, hence can be used in the similar use cases, like providing authorisation to externally authenticated party.

Field Type Label Description
body BearerToken.Body Bearer Token body
signature neo.fs.v2.refs.Signature Signature of BearerToken body

Message BearerToken.Body

Bearer Token body structure contains Extended ACL table issued by container owner with additional information preventing token's abuse.

Field Type Label Description
eacl_table EACLTable Table of Extended ACL rules to use instead of the ones attached to the container
owner_id neo.fs.v2.refs.OwnerID OwnerID to whom the token was issued. MUST match with the request originator's OwnerID
lifetime BearerToken.Body.TokenLifetime Token expiration and valid time period parameters

Message BearerToken.Body.TokenLifetime

Lifetime parameters of the token. Filed names taken from rfc7519.

Field Type Label Description
exp uint64 Expiration Epoch
nbf uint64 Not valid before Epoch
iat uint64 Issued at Epoch

Message EACLRecord

Describes a single eACL rule.

Field Type Label Description
operation Operation NeoFS request Verb to match
action Action Rule execution result. Either allows or denies access if filters match.
filters EACLRecord.Filter repeated List of filters to match and see if rule is applicable
targets EACLRecord.Target repeated List of target subjects to apply ACL rule to

Message EACLRecord.Filter

Filter to check particular properties of the request or object.

Field Type Label Description
header_type HeaderType Define if Object or Request header will be used
match_type MatchType Match operation type
header_name string Name of the Header to use
header_val string Expected Header Value or pattern to match

Message EACLRecord.Target

Target to apply ACL rule. Can be a subject's role class or a list of public keys to match.

Field Type Label Description
role Role Target subject's role class
key_list bytes repeated List of public keys to identify target subject

Message EACLTable

Extended ACL rules table. Defined a list of ACL rules additionally to Basic ACL. Extended ACL rules can be attached to the container and can be updated or may be defined in BearerToken structure. Please see the corresponding NeoFS Technical Specification's section for detailed description.

Field Type Label Description
version neo.fs.v2.refs.Version eACL format version. Effectively the version of API library used to create eACL Table.
container_id neo.fs.v2.refs.ContainerID Identifier of the container that should use given access control rules
records EACLRecord repeated List of Extended ACL rules

Action

Rule execution result action. Either allows or denies access if the rule's filters match.

Name Number Description
ACTION_UNSPECIFIED 0 Unspecified action, default value
ALLOW 1 Allow action
DENY 2 Deny action

HeaderType

Enumeration of possible sources of Headers to apply filters.

Name Number Description
HEADER_UNSPECIFIED 0 Unspecified header, default value.
REQUEST 1 Filter request headers
OBJECT 2 Filter object headers

MatchType

MatchType is an enumeration of match types.

Name Number Description
MATCH_TYPE_UNSPECIFIED 0 Unspecified match type, default value.
STRING_EQUAL 1 Return true if strings are equal
STRING_NOT_EQUAL 2 Return true if strings are different

Operation

Request's operation type to match if the rule is applicable to a particular request.

Name Number Description
OPERATION_UNSPECIFIED 0 Unspecified operation, default value
GET 1 Get
HEAD 2 Head
PUT 3 Put
DELETE 4 Delete
SEARCH 5 Search
GETRANGE 6 GetRange
GETRANGEHASH 7 GetRangeHash

Role

Target role of the access control rule in access control list.

Name Number Description
ROLE_UNSPECIFIED 0 Unspecified role, default value
USER 1 User target rule is applied if sender is the owner of the container
SYSTEM 2 System target rule is applied if sender is the storage node within the container or inner ring node
OTHERS 3 Others target rule is applied if sender is not user nor system target

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str