S3 Gateway & Native REST API Specification

The Aarkam.IO Gateway provides a high-throughput, drop-in replacement for Amazon Web Services (AWS) S3. It exposes standard REST endpoints compatible with the AWS CLI, AWS SDKs (C#, Python, Go, Java), and enterprise backup platforms.

Gateway Architecture & DMZ Perimeter

To protect internal storage nodes from direct exposure to untrusted networks, the Gateway is deployed in a DMZ perimeter:

[Public / Enterprise Network]
             │
             │ HTTPS (Port 57776) / TLS 1.3
             ▼
┌────────────────────────────────────────────────────────┐
│ Aarkam.Gateway (DMZ Perimeter)                         │
│ • Reverse Proxy & SSL Termination                      │
│ • Token Bucket Rate Limiter (DDoS Mitigation)          │
│ • AWS SigV4 (AWS4-HMAC-SHA256) Signature Validation    │
│ • Granular RBAC & Tenant Namespace Isolation           │
└──────────────────────────┬─────────────────────────────┘
                           │
                           │ gRPC over mTLS (Internal Only)
                           ▼
┌────────────────────────────────────────────────────────┐
│ Internal Storage Cluster (Ports 57777 / 57778)         │
│ • Coordinator & Storage Nodes                          │
└────────────────────────────────────────────────────────┘

Supported S3 Operations

Aarkam implements core S3 protocol specifications:

Bucket Operations

• CreateBucket / DeleteBucket / HeadBucket / ListBuckets
• GetBucketLocation / GetBucketVersioning / PutBucketVersioning
• PutBucketPolicy / GetBucketPolicy
• PutBucketLifecycleConfiguration

Object Operations

• PutObject / GetObject / HeadObject / DeleteObject / DeleteObjects
• CopyObject
• ListObjectsV2 with delimiter and prefix pagination
• CreateMultipartUpload / UploadPart / CompleteMultipartUpload / AbortMultipartUpload
• PutObjectLockConfiguration (WORM compliance & immutable financial records retention)

Code Example: Connecting via AWS SDK (.NET)

using Amazon.S3;
using Amazon.S3.Model;

var config = new AmazonS3Config
{
    ServiceURL = "https://s3.aarkam.internal:57776",
    ForcePathStyle = true, // Required for private cloud endpoints
    SignatureVersion = "4",
    SignatureMethod = SigningAlgorithm.HmacSHA256
};

using var client = new AmazonS3Client("AKIASOVEREIGNKEY2026", "SECRET_KEY_HERE", config);

// Upload sovereign object
var putRequest = new PutObjectRequest
{
    BucketName = "energy-seismic-vault",
    Key = "surveys/2026/block-4-telemetry.raw",
    FilePath = @"/data/seismic/block-4-telemetry.raw"
};

var response = await client.PutObjectAsync(putRequest);
Console.WriteLine($"Upload committed with ETag: {response.ETag}");