# oss-network-security

Part of **OSS**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for [Configure bucket-level security policies](../../intent/oss-configure-security/SKILL.md). If you're unsure which path to take, check the routing skill first.

# Object Storage Service Network Security

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Anti-DDoS | Synchronous | Initialize, create, query, update, and change the status of Anti-DDoS instances for buckets. |
| Configure CORS | Synchronous | Set up, retrieve, and delete CORS rules for buckets, and handle preflight requests. |
| Get Bucket HTTPS Config | Synchronous | Retrieve HTTPS configuration settings for a bucket. |
| Manage Requester QoS | Synchronous | Configure and manage quality of service settings based on requesters. |

## API Calling Patterns

### Authentication
The primary authentication method is **OSS Signature Version 4 (OSS4-HMAC-SHA256)**.

- Use the `Authorization` header with format:  
  `Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyID>/<Date>/<Region>/oss/aliyun_v4_request,Signature=<Signature>`
- Store credentials in environment variables:  
  `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET`
- Alternative methods (like basic signature) exist but OSS4-HMAC-SHA256 is recommended for enhanced security.

### Service Endpoint (Endpoint)
APIs use region-specific endpoints with the pattern:  
`https://{bucket-name}.oss-{region}.aliyuncs.com` or `https://oss-{region}.aliyuncs.com`

Common regions include:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

### Synchronous API Pattern
All operations in this domain follow a synchronous request-response model:

1. Construct an HTTP request with the appropriate method (`GET`, `PUT`, `POST`, `DELETE`)
2. Include required headers (e.g., `Authorization`, `Date`, custom headers like `x-oss-defender-instance`)
3. For configuration updates, include XML body when required (e.g., CORS rules, QoS settings)
4. Send the request to the region-specific endpoint
5. Parse the immediate JSON or XML response (or check HTTP status for success)

No polling or streaming is required — responses are returned directly.

## Parameter Reference

### Manage Anti-DDoS

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| x-oss-defender-instance | string | true | - | - | The ID of the Anti-DDoS instance. |
| x-oss-defender-type | string | true | - | Must be 'AntiDDosPremimum' | The type of the Anti-DDoS instance. |
| x-oss-defender-status | string | true | - | One of: Init, Defending, HaltDefending | The new status of the Anti-DDoS instance. |
| marker | string | false | - | - | The name of the Anti-DDoS instance after which the list starts. |
| max-keys | string | true | 100 | Valid values: 1 to 100 | The maximum number of Anti-DDoS instances that can be returned. |
| Domain | string | false | - | Up to 5 domains per bucket | The custom domain names that you want to protect. |

### Configure CORS

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| AllowedOrigin | string | true | - | Only one asterisk (*) allowed as wildcard | The origin from which cross-origin requests are allowed. |
| AllowedMethod | enumeration | true | - | One of: GET, PUT, DELETE, POST, HEAD | The cross-origin request method that is allowed. |
| AllowedHeader | string | false | - | Only one asterisk (*) allowed; no < > & ' " | Headers allowed in preflight requests. |
| ExposeHeader | string | false | - | No * < > & ' " | Response headers accessible to client-side scripts. |
| MaxAgeSeconds | integer | false | 100 | Max 1000000 seconds | Time browser caches preflight response (seconds). |
| ResponseVary | boolean | false | false | true or false | Whether to return the Vary: Origin header. |
| Origin | string | true | null | Only one Origin header allowed | The origin of the preflight request. |
| Access-Control-Request-Method | string | true | null | Only one allowed | Method used in actual cross-origin request. |
| Access-Control-Request-Headers | string | false | null | Comma-separated headers | Custom headers in actual cross-origin request. |

### Manage Requester QoS

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| resourcePool | string | true | - | - | The name of the resource pool to query. |
| max-keys | integer | false | - | - | Maximum number of requesters to return. |
| continuation-token | string | false | - | - | The requester from which results continue. |

## Code Examples

### Query Anti-DDoS Instances - Bash - All Regions

```bash
GET /?antiDDos HTTP/1.1
Date: Thu, 17 Apr 2025 05:34:24 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
```

### Initialize Anti-DDoS Protection - Bash - China

```bash
PUT /?antiDDos HTTP/1.1
Date: Thu, 17 Apr 2025 05:34:24 GMT
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-defender-instance: cbcac8d2-4f75-4d6d-9f2e-c3447f73****
x-oss-defender-type: AntiDDosPremimum
```

### Configure CORS Rules - Bash - All Regions

```bash
PUT /?cors HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 186
Date: Fri, 04 May 2012 03:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
    <CORSRule>
      <AllowedOrigin>*</AllowedOrigin>
      <AllowedMethod>PUT</AllowedMethod>
      <AllowedMethod>GET</AllowedMethod>
      <AllowedHeader>Authorization</AllowedHeader>
    </CORSRule>
    <CORSRule>
      <AllowedOrigin>http://example.com</AllowedOrigin>
      <AllowedOrigin>http://example.net</AllowedOrigin>
      <AllowedMethod>GET</AllowedMethod>
      <AllowedHeader> Authorization</AllowedHeader>
      <ExposeHeader>x-oss-test</ExposeHeader>
      <ExposeHeader>x-oss-test1</ExposeHeader>
      <MaxAgeSeconds>100</MaxAgeSeconds>
    </CORSRule>
    <ResponseVary>false</ResponseVary>
</CORSConfiguration >
```

### Get Resource Pool QoS Configuration - Go - All Regions

```go
package main

import (
	"fmt"
	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	client, err := oss.New("oss-cn-hangzhou.aliyuncs.com", "your-access-key-id", "your-access-key-secret")
	if err != nil {
		panic(err)
	}

	bucket, err := client.Bucket("my-test-pool")
	if err != nil {
		panic(err)
	}

	config, err := bucket.GetResourcePoolRequesterPriorityQosConfiguration()
	if err != nil {
		panic(err)
	}

	fmt.Printf("Priority Count: %d\n", config.PriorityCount)
	fmt.Printf("Default Priority Level: %d\n", config.DefaultPriorityLevel)
	fmt.Printf("Total Upload Bandwidth: %d Gbps\n", config.DefaultGuaranteedQosConfiguration.TotalUploadBandwidth)
}
```

### Handle CORS Preflight Request - Bash - All Regions

```bash
OPTIONS /testobject HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com  
Date: Fri, 24 Feb 2012 05:45:34 GMT  
Origin:http://www.example.com
Access-Control-Request-Method:PUT
Access-Control-Request-Headers:x-oss-test1,x-oss-test2
```

### Get Bucket HTTPS Configuration - Curl - All Regions

```curl
GET /?httpsConfig HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Date: Thu, 17 Apr 2025 08:40:17 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
```

### Update Anti-DDoS Status - Bash - China

```bash
POST /?antiDDos HTTP/1.1
Date: Thu, 17 Apr 2025 05:34:24 GMT
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-defender-instance: cbcac8d2-4f75-4d6d-9f2e-c3447f73****
x-oss-defender-status: Init
<AntiDDOSConfiguration>
  <Cnames>
    <Domain>abc1.example.cn</Domain>
    <Domain>abc2.example.cn</Domain>
  </Cnames>
</AntiDDOSConfiguration>
```

## Response Format (Response Format)

```json
{
  "AntiDDOSListConfiguration": {
    "AntiDDOSConfiguration": [
      {
        "InstanceId": "cbcac8d2-4f75-4d6d-9f2e-c3447f73****",
        "Owner": "114893010724****",
        "Ctime": 12345667,
        "Mtime": 12345667,
        "ActiveTime": 12345680,
        "Status": "Init"
      }
    ]
  }
}
```

**Key Fields**:
- `AntiDDOSListConfiguration.AntiDDOSConfiguration.InstanceId` — Unique identifier of the Anti-DDoS instance
- `AntiDDOSListConfiguration.AntiDDOSConfiguration.Owner` — Alibaba Cloud account ID of the owner
- `AntiDDOSListConfiguration.AntiDDOSConfiguration.Ctime` — Creation timestamp (Unix time)
- `AntiDDOSListConfiguration.AntiDDOSConfiguration.Mtime` — Last modification timestamp
- `AntiDDOSListConfiguration.AntiDDOSConfiguration.ActiveTime` — Activation timestamp
- `AntiDDOSListConfiguration.AntiDDOSConfiguration.Status` — Current status (e.g., Init, Defending)

```xml
<CORSConfiguration>
    <CORSRule>
      <AllowedOrigin>*</AllowedOrigin>
      <AllowedMethod>GET</AllowedMethod>
      <AllowedHeader>*</AllowedHeader>
      <ExposeHeader>x-oss-test</ExposeHeader>
      <MaxAgeSeconds>100</MaxAgeSeconds>
    </CORSRule>
    <ResponseVary>false</ResponseVary>
</CORSConfiguration>
```

**Key Fields**:
- `CORSConfiguration.CORSRule.AllowedOrigin` — Origins permitted for cross-origin requests
- `CORSConfiguration.CORSRule.AllowedMethod` — Allowed HTTP methods
- `CORSConfiguration.CORSRule.AllowedHeader` — Headers allowed in requests
- `CORSConfiguration.CORSRule.ExposeHeader` — Headers exposed to client scripts
- `CORSConfiguration.CORSRule.MaxAgeSeconds` — Preflight cache duration
- `CORSConfiguration.ResponseVary` — Whether Vary: Origin header is returned

```xml
<HttpsConfiguration>
  <TLS>
    <Enable>true</Enable>
    <TLSVersion>TLSv1.2</TLSVersion>
    <TLSVersion>TLSv1.3</TLSVersion>
  </TLS>
  <CipherSuite>
    <Enable>true</Enable>
    <StrongCipherSuite>true</StrongCipherSuite>
    <CustomCipherSuite>ECDHE-ECDSA-AES128-SHA256</CustomCipherSuite>
    <TLS13CustomCipherSuite>ECDHE-ECDSA-AES256-CCM8</TLS13CustomCipherSuite>
  </CipherSuite>
</HttpsConfiguration>
```

**Key Fields**:
- `HttpsConfiguration.TLS.Enable` — Whether TLS is enabled
- `HttpsConfiguration.TLS.TLSVersion` — Supported TLS versions
- `HttpsConfiguration.CipherSuite.Enable` — Whether custom cipher suites are enabled
- `HttpsConfiguration.CipherSuite.StrongCipherSuite` — Whether strong cipher suites are enforced
- `HttpsConfiguration.CipherSuite.CustomCipherSuite` — Custom cipher suites for TLS 1.2 and below
- `HttpsConfiguration.CipherSuite.TLS13CustomCipherSuite` — Custom cipher suites for TLS 1.3

```xml
<PriorityQosConfiguration>
  <PriorityCount>5</PriorityCount>
  <DefaultPriorityLevel>1</DefaultPriorityLevel>
  <DefaultGuaranteedQosConfiguration>
    <TotalUploadBandwidth>10</TotalUploadBandwidth>
    <IntranetUploadBandwidth>5</IntranetUploadBandwidth>
    <ExtranetUploadBandwidth>5</ExtranetUploadBandwidth>
    <TotalDownloadBandwidth>20</TotalDownloadBandwidth>
    <IntranetDownloadBandwidth>10</IntranetDownloadBandwidth>
    <ExtranetDownloadBandwidth>10</ExtranetDownloadBandwidth>
  </DefaultGuaranteedQosConfiguration>
  <QosPriorityLevelConfiguration>
    <PriorityLevel>1</PriorityLevel>
    <GuaranteedQosConfiguration>
      <TotalUploadBandwidth>20</TotalUploadBandwidth>
      <TotalDownloadBandwidth>20</TotalDownloadBandwidth>
    </GuaranteedQosConfiguration>
    <Subjects>
      <Requester>1111111111111111</Requester>
    </Subjects>
  </QosPriorityLevelConfiguration>
</PriorityQosConfiguration>
```

**Key Fields**:
- `PriorityCount` — Number of priority levels configured
- `DefaultPriorityLevel` — Default priority level for unassigned requesters
- `DefaultGuaranteedQosConfiguration` — Bandwidth limits for default priority
- `QosPriorityLevelConfiguration.PriorityLevel` — Specific priority level
- `QosPriorityLevelConfiguration.GuaranteedQosConfiguration` — Bandwidth guarantees for this priority
- `QosPriorityLevelConfiguration.Subjects.Requester` — Alibaba Cloud account IDs assigned to this priority

## Error Handling (Error Handling)

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| 403 | Access denied. The user does not have the required permission (e.g., oss:GetUserAntiDDosInfo, oss:InitBucketAntiDDosInfo). | Ensure your RAM user or STS session has the necessary permissions granted via policy. |
| 400 | Bad request. The request syntax is invalid or missing required parameters. | Verify all required headers, URL parameters, and XML body structure match the API specification. |
| 404 | Not found. The specified bucket, Anti-DDoS instance, or resource pool does not exist. | Confirm the bucket name, instance ID, or resource pool name is correct and exists in the target region. |
| NoSuchBucket | The error message returned because the specified bucket does not exist. | Check bucket name spelling and ensure it exists in the specified region. |
| NoSuchCORSConfiguration | The error message returned because the specified CORS rule does not exist. | Call PutBucketCors first to configure CORS before attempting to retrieve or delete. |
| AccessForbidden | OSS does not allow the cross-origin request or CORS is disabled for the bucket. | Enable CORS for the bucket using PutBucketCors with appropriate rules. |
| InvalidDigest | The Content-MD5 value calculated by OSS differs from the one in the request header. | Recalculate the MD5 hash of your request body and ensure it matches. |

## Environment Requirements (Requirements)

- **Go SDK**: `github.com/aliyun/aliyun-oss-go-sdk/oss` (version >= 1.0.0 for QoS operations)
- **Environment Variables**:  
  `export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id`  
  `export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret`

## FAQ

Q: How do I enable Anti-DDoS protection for my OSS bucket?
A: First, create an Anti-DDoS instance using InitUserAntiDDosInfo. Then, initialize protection for your bucket with InitBucketAntiDDosInfo, specifying the instance ID and custom domains to protect.

Q: Why is my CORS preflight request failing with AccessForbidden?
A: Your bucket likely has no CORS rules configured. Use PutBucketCors to define at least one CORS rule that matches your request's Origin, method, and headers.

Q: Can I use wildcards in CORS AllowedOrigin?
A: Yes, but only a single asterisk (`*`) is allowed to permit all origins. You cannot use partial wildcards like `*.example.com`.

Q: What TLS versions are supported for OSS buckets?
A: OSS supports TLS 1.2 and TLS 1.3. You can configure which versions are enabled via the HTTPS configuration API.

Q: How are QoS priorities assigned to requesters?
A: Requesters (Alibaba Cloud account IDs) are explicitly assigned to priority levels via configuration APIs. Unassigned requesters use the default priority level.

## Pricing & Billing

### Billing Model
Most operations are billed per request. Some read operations (e.g., GetUserAntiDDosInfo, ListResourcePoolRequesterQoSInfos) are free.

### Price Reference

| Tier / Operation | Input Price | Output Price |
|------------------|-------------|--------------|
| AntiDDosPremimum initialization | 0.001 / | - |
| Anti-DDoS instance creation | 0.01 / | - |
| DeleteBucketCors | 0.0001 / | - |
| GetBucketCors | 0.0001 / | 0.0001 / |
| PutBucketCors | 0.0001 / | 0.0001 / |
| OPTIONS preflight | 0.0001 / | 0.0001 / |
| GetResourcePoolRequesterPriorityQosConfiguration | 0.0001 / | 0.0001 / |

### Free Tier
- GetUserAntiDDosInfo: Free
- ListBucketAntiDDosInfo: Free
- UpdateBucketAntiDDosInfo: Free
- UpdateUserAntiDDosInfo: Free
- GetBucketHttpsConfig: Free
- ListResourcePoolRequesterQoSInfos: Free
- GetBucketCors: 1000 free requests per month
- GetResourcePoolRequesterPriorityQosConfiguration: 1000 free calls per month

### Usage Limits
- Anti-DDoS: Up to 5 custom domain names per bucket; 100 requests per second per account
- CORS: Up to 20 rules per bucket; 100 QPS per bucket; request body max 16 KB
- QoS: 10 requests per second per account for GetResourcePoolRequesterPriorityQosConfiguration

### Billing Notes
- Failed requests (e.g., 4xx errors) may still incur charges for non-free operations.
- Free tier quotas reset monthly and apply across all OSS operations unless specified otherwise.
- Bandwidth usage for data transfer is billed separately from these API calls.