The OneFS S3 protocol implementation enables clients to access data residing on a PowerScale cluster as objects and buckets, in addition to and concurrent with standard files and directories. Every interaction with OneFS S3 is either authenticated or anonymous, with the former verifying the identity of the requester attempting to access data.
If authentication is successful, the OneFS authorization framework then controls the explicit permissions (read, write, execute, etc) which the requester has for the desired data. OneFS employs a unified permission model which integrates POSIX permissions for NFS users, NTFS ACLs for Windows SMB users, and S3 object ACLs and bucket policies, etc. This ensures consistent access control across all protocols. So when a user accesses a file or object, OneFS evaluates all applicable permissions and applies the most restrictive effective permission. In this article we’ll focus on the S3 protocol, and examine how OneFS uses fine-grained access controls to authenticate and authorize each S3 request.
There are two classes of upload method when authenticating requests via the AWS Signature Version 4 Authorization header:
- Transfer payload via a single chunk.
- Transfer payload via multiple chunks ( chunked upload).
Chunked upload enables applications, such as the AWS S3 Java SDK, to seamlessly and efficiently integrate with the OneFS S3 service. By dividing and uploading the data into fixed or variable-size chunks, applications can avoid reading the entire payload to calculate the signature. Instead, for the first chunk, a seed signature is calculated using only the request headers. The second chunk contains the signature for the first chunk, and each subsequent chunk holds the signature for its preceding chunk. At the end of the upload, a final, zero-byte chunk is transmitted containing the last payload chunk’s signature.
The OneFS S3 protocol authenticates requests via the AWS Signature authentication signing mechanism, using either version 2 or version 4 of the protocol. Authenticated requests must include a signature value that authenticates the request sender, and each of these requires the user to have an access ID and a secret key, which can be obtained via the OneFS WebUI or CLI prior to performing signed S3 requests. For example, the access ID and secret key for the admin user can be generated from the WebUI as follows:
An ‘Access ID’ indicates who the user is, and OneFS generates one access ID per user. For example, OneFS may generate access ID ‘1_peter_accid’ for user ‘peter’. For example:
# isi s3 mykeys view Access ID: 1_peter_accid Secret Key: **************************** Timestamp: 2025-06-18T21:33:04 Old Secret Key: **************************** Old Key Timestamp: 2025-06-16T08:20:58 Old Key Expiry: 2025-06-18T21:43:04
The number prefixing the Access ID represents the user’s access zone ID. Each access ID has a current secret key without an expiry time set, and often an old secret key with an expiry time set.
This secret key is used to generate a signature value, along with several request-header values. After receiving the signed request, OneFS uses the access ID to retrieve a copy of the secret key internally, recomputing the signature value of the request, and comparing it against the received signature. If they match, the requester is authenticated and any header value used in the signature is verified as tamper-free.
OneFS provides support for both bucket ACLs and object ACLs, in order to govern S3 user access to those resources. Every bucket and object has an associated ACL which defines the OneFS users or groups to be granted access, including the type and level.
When receiving a S3 request for a bucket operation, OneFS parses the user access ID from the request header and evaluates the request according to the target bucket ACL.
OneFS supports the following set of bucket ACL permission entities:
Bucket ACL | Description |
READ | Permits users to list the objects in the bucket. |
WRITE | Permits users to create, overwrite, and delete objects in the bucket. |
READ_ACP | Permits users to read the bucket ACL. |
WRITE_ACP | Permits users to write the ACL for the applicable bucket. |
FULL_CONTROL | Grants users READ, WRITE, READ_ACP, and WRITE_ACP permissions on the bucket. |
Note that when creating a OneFS S3 bucket, the underlying directory must already be present or the command will fail with the following error message:
# isi s3 buckets create –owner=root bucket1 /ifs/tmp/bucket1
Error in field(s): path
Path ‘/ifs/tmp/bucket1’ does not exist.
The following CLI command can be used to grant write permission on a bucket, in this case for the user ‘Peter’.
# isi s3 buckets modify <bucket> --add-ace="name=Peter,type=user,perm=write" --zone=<name>
Similarly, to revoke write permission:
# isi s3 buckets modify <bucket> --remove-ace="name=Peter,type=user,perm=write" --zone=<name>
OneFS automatically treats an unauthenticated S3 request as anonymous requests from the ‘nobody’ user (UID 65534). If an object is uploaded to a bucket via an unauthenticated request, the ‘nobody’ user owns the object and has FULL_CONTROL of it. To prevent an anonymous request from modifying OneFS buckets and objects, exercise caution when using ACLs that give the ‘nobody’ user write access to a bucket.
To access OneFS S3 objects, the S3 request must be authorized at both the bucket and object levels. When receiving an S3 request for an object operation, OneFS parses the username from the request header. If the request is to PUT or DELETE an object, OneFS evaluates the request according to the target bucket ACL. If authorized, OneFS evaluates the request against the OneFS file system ACL. Otherwise, OneFS evaluates the request against OneFS ACL directly. The Object ACL is derived from the OneFS file system ACL and is for representation only.
OneFS S3 supports the following object ACL permissions:
Object ACL | Description |
READ | Permits users to read the object data and its metadata. |
WRITE | Not applicable, but can still be set on an object. When updating an object, S3 overwrites the entire object instead of just modifying existing data. Overwriting an object requires the WRITE permission at the bucket level. |
READ_ACP | Permits users to read the object ACL. |
WRITE_ACP | Permits users to write the ACL for the applicable object. |
FULL_CONTROL | Allows grantee the READ, WRITE, READ_ACP, and WRITE_ACP permissions on the object. Also includes additional execute and std_write_owner OneFS permissions to provide consistent multiprotocol access. |
As stated above, when updating an object, OneFS (and S3 in general) overwrites the entire object rather than simply modifying existing data, as with file protocols. Overwriting an object requires write permission at both the bucket level and on the directory containing the object (for example, the object ‘/a/b/c.xml’ will require write permission on the ‘/a/b/’ sub-directory). When this permission is set on an object, OneFS assigns its corresponding ACL rights so that the object data can be modified via other protocols, if required.
OneFS always manages permissions enforcement based on the OneFS ACL, with the associated object ACL provided for representation only. Note that the S3 object ACL only defines ‘ALLOW ACL’, whereas the OneFS ACL also includes a ‘DENY ACL’ . To reconcile the S3 object ACL and OneFS ACL, OneFS provides the following object ACL policy, in conjunction with the mapping relationship described below:
ACL Policy | Description |
Replace | When S3 modifies a OneFS ACL, OneFS removes the existing ACL (including both ALLOW and DENY settings) and replaces it with the new S3 ACL. This is the default setting. |
Deny | OneFS ACL modification by S3 is not permitted. The S3 client receives a permission-denied error when attempting to modify ACL. |
Note that, when viewing the object ACL via an S3 client, in certain circumstances only a subset of the actual ACL will be shown.
The following OneFS CLI syntax can be used to modify the object ACL policy on a bucket:
# isi s3 buckets modify <bucket> --object-acl-policy=<replace/deny> --zone=<name>
The object ACL permissions are mapped to the following OneFS ACL permissions respectively:
Object ACL permission | OneFS ACL permission |
READ | file_read, file_read_attr, file_read_ext_attr, std_synchronize |
WRITE | file_write, append, file_write_attr, file_write_ext_attr, std_synchronize |
READ_ACP | std_read_dac |
WRITE_ACP | std_write_dac |
FULL_CONTROL | file_gen_all (includes execute, std_write_owner, and all the above permissions) |
The S3 protocol uses a set of predefined ACLs, also known as ‘canned ACLs’, each having predetermined grantees and permissions. OneFS supports the following canned ACLs, and their associated predefined entitlements:
Canned ACL | Applies to | Permissions |
private | Bucket and object | Owner gets FULL_CONTROL. No other user has rights (default). |
public-read | Bucket and object | Owner gets FULL. The AllUsers group gets READ access. |
public-read-write | Bucket and object | Owner granted FULL_CONTROL. AllUsers group granted READ and WRITE access. Use with caution. |
authenticated-read | Bucket and object | Owner granted FULL_CONTROL. AuthenticatedUsers group granted READ access. |
bucket-owner-read | Object | Object owner granted FULL_CONTROL. Bucket owner granted READ access. |
Bucket-owner-full-control | Object | Both object and bucket owners granted FULL_CONTROL over the object. |
The AWS S3 protocol includes the following predefined groups, which OneFS equates to its own predefined groups as follows:
Predefined S3 Group | Predefined OneFS Group | Detail |
Authenticated Users group | Authenticated Users | Only authenticated request is permitted in this group. |
All Users group | Everyone | Both authenticated and unauthenticated requests are permitted in this group. |
Log Delivery group | Unsupported | OneFS does not support this group. |