备案控制台
文档
产品文档
输入文档关键字查找
首页 对象存储 开发参考 开发指南 发起请求 使用REST API发起请求 在Header中包含签名 签名版本4（推荐）

在Header中包含V4签名（推荐）

更新时间：
一键部署
产品详情
相关技术圈
我的收藏

在OSS中，使用HTTP请求的Authorization Header来携带签名信息是进行身份验证的最常见方法。除了使用POST签名和URL签名之外，所有的OSS操作都需要通过Authorization Header来进行身份验证。本文介绍如何使用V4签名算法来在Header中包含签名。

SDK签名实现

OSS SDK已实现自动完成V4签名。推荐采用OSS SDK的方式发起请求，可以免去手动签名的过程。如果您想了解具体语言的V4签名实现，请参考OSS SDK的代码。OSS SDK签名实现的文件请参见下表。

SDK

签名实现

Java

OSSV4Signer.java

PHP

SignerV4.php

Node.js

client.js

Browser.js

Python

auth.py

Go

v4.go

C++

SignerV4.cc

C

oss_auth.c

Authorization计算方法

Authorization字段以空格的形式分隔签名版本和签名信息。

Authorization字段

说明

签名版本

仅支持填写OSS4-HMAC-SHA256。

签名信息

以键值对（key=value）的形式呈现。键值对之间用逗号分隔，键与值之间用等号连接。其中，签名信息支持的key包括两个必选字段（Credential和Signature）以及一个可选字段（AdditionalHeaders）。

  • Credential：描述具体使用哪个派生密钥，中间以正斜线（/）分隔。

  • Signature：描述计算得到的签名值。

  • AdditionalHeaders：允许用户指定计算签名过程中可选的Header，如有多项需以分号（;）分隔，忽略大小写，且按字典序排列。

  • 格式

    Authorization: "OSS4-HMAC-SHA256 Credential=" + AccessKeyId + "/" + SignDate + "/" + SignRegion + "/oss/aliyun_v4_request, " + [ "AdditionalHeaders=" + AdditionalHeadersVal + ", " ] + "Signature=" + SignatureVal

  • 示例

    Authorization: OSS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20231203/cn-hangzhou/oss/aliyun_v4_request, AdditionalHeaders=host;userdefine, Signature=34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7
说明

通过STS服务获取的临时访问凭证发送请求时，您还需要将获得的security-token值以x-oss-security-token:security-token的形式加入到请求头中。关于如何获取Security-Token的具体操作，请参见AssumeRole - 获取扮演角色的临时身份凭证。

签名计算流程

image

步骤1：构造CanonicalRequest

按照OSS签名定义的规范，对请求进行格式化。

格式

HTTP Verb + "\n" +
Canonical URI + "\n" +
Canonical Query String + "\n" +
Canonical Headers + "\n" +
Additional Headers + "\n" +
Hashed PayLoad

各参数说明如下：

参数

类型

是否必选

示例

说明

HTTP Verb

枚举值

是

PUT

HTTP请求的Method，包含PUT、GET、POST、HEAD、DELETE、OPTIONS等。

Canonical URI

字符串

是

/examplebucket/exampleobject

URI进行UriEncode后的字符串，其中正斜线（/）不需要编码。

  • 如果URI中不包含QueryString，则从正斜线（/）开始到URI末尾。

  • 如果URI中包含QueryString，则从正斜线（/）开始到问号（？）结束。

根据请求URI包含的资源有差异，Canonical URI的填写方法说明如下：

  • 如果请求的URI中既包含Bucket也包含Object，则Canonical URI填写示例为

    /examplebucket/exampleobject。

  • 如果请求的URI中只包含Bucket不包含Object，则Canonical URI填写示例为/examplebucket/。

  • 如果请求的URI中不包含Bucket只包含Object，则Canonical URI填写示例为/。

Canonical Query String

字符串

是

UriEncode("marker") + "=" + UriEncode("someMarker") + "&" + UriEncode("max-keys") + "=" + UriEncode("20") + "&" + UriEncode("prefix") + "=" + UriEncode("somePrefix")

针对QueryString执行UriEncode后的字符串，单独对key和value进行编码。

  • 按QueryString的key进行排序，先编码，再排序。如果有多个相同的key，按照原来添加的顺序放置即可。

  • 只有key没有value的情况下，只添加 key即可。

  • 如果没有QueryString，则只需要放置空字符串“”，末尾仍然需要有换行符。

Canonical Headers

字符串

是

host:cname.com
x-oss-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-oss-date:20231203T121212Z

对请求Header的列表格式化后的字符串，各个Header之间需要添加 "\n"。

  • 单个Header中的key和value通过冒号:分隔，Header与Header之间通过换行符分隔。

  • Header的key必须小写，value必须经过Trim（去除头尾的空格）。

  • 按Header中key的字典序进行排列。

  • 请求时间通过x-oss-date来描述，要求格式必须是FormatISO8601（示例值为20231203T121212Z）。

Canonical Headers包含以下两类：

  • 必须存在且参与签名的Header包括：

    • x-oss-content-sha256（其值为UNSIGNED-PARYLOAD）

    • AdditionalHeader指定必须存在且参与签名的Header

  • 如果存在则加入签名的Header包括：

    • Content-Type

    • Content-MD5

    • x-oss-*

Additional Headers

字符串

是

content-length;host

除了Content-Type、Content-MD5、x-oss-*以外，其他需要加入签名的Header。所有的Header必须是小写，且按照字典序排列。

Hashed PayLoad

字符串

是

UNSIGNED-PAYLOAD

仅支持UNSIGNED-PAYLOAD。

示例

"GET" | "PUT" | ... + "\n" +
UriEncode(<Resource>) + "\n" +
UriEncode(<QueryParam1>) + "=" + UriEncode(<Value>) + "&" + UriEncode(<QueryParam2>) + "\n" +
Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n" + Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n" + "\n"
Lowercase(<AdditionalHeaderName1>) + ";" + Lowercase(<AdditionalHeaderName2>) + "\n" +
UNSIGNED-PAYLOAD

步骤2：构造待签名字符串（StringToSign）

将格式化后的请求进行统一的计算处理，得到待签名的字符串。

  • 格式

    "OSS4-HMAC-SHA256" + "\n" +
TimeStamp + "\n" +
Scope + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

    参数说明如下：

    参数

    类型

    是否必选

    示例

    说明

    OSS4-HMAC-SHA256

    枚举值

    是

    OSS4-HMAC-SHA25

    指明使用的签名哈希算法，取值必须是OSS4-HMAC-SHA256。

    TimeStamp

    字符串

    是

    20231203T121212Z

    指明当前的UTC时间，格式必须是 ISO8601。

    Scope

    字符串

    是

    20231203/cn-hangzhou/oss/aliyun_v4_request

    指明获取Region派生密钥的参数集，格式如下：

    <SigningDate>/<SigningRegion>/oss/aliyun_v4_request

    • SigningDate：填写请求的日期。

    • SigningRegion：填写请求所在的Region。

    • oss：请求的服务名称，固定为oss。

    • aliyun_v4_request：请求的版本说明，固定为aliyun_v4_request。

    CanonicalRequest

    字符串

    是

    PUT

    /examplebucket/exampleobject

    content-md5:eB5eJF1ptWaXm4bijSPyxw

    content-type:text/html

    host:examplebucket.oss-cn-hangzhou.aliyuncs.com

    x-oss-content-sha256:UNSIGNED-PAYLOAD

    x-oss-date:20231203T121212Z

    x-oss-meta-author:alice

    x-oss-meta-magic:abracadabra

    host

    UNSIGNED-PAYLOAD

    上一步骤构造出来的字符串。

  • 示例

    "OSS4-HMAC-SHA256" + "\n" +
FormatISO8601 + "\n" +
20231203/cn-hangzhou/oss/aliyun_v4_request + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

步骤3：计算Signature

使用签名密钥对待签名字符串进行计算。

  1. 计算SigningKey。

    HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("aliyun_v4" + SK, Date), Region), "oss"), "aliyun_v4_request");

  2. 计算Signature。

    HEX(HMAC-SHA256(SigningKey, StringToSign))

签名计算示例

以PutObject为例，演示如何在Header包含V4签名。

  • 计算示例参数说明

    参数

    值

    AccessKeyId

    accesskeyid

    AccessKeySecret

    accesskeysecret

    Timestamp

    20231203T121212Z

    Bucket

    examplebucket

    Object

    exampleobject

    Region

    cn-hangzhou

  • PutObject

    PUT /exampleobject HTTP/1.1
Content-MD5: eB5eJF1ptWaXm4bijSPyxw
Content-Type: text/html
Date: Sun, 03 Dec 2023 12:12:12 GMT
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureToBeCalculated
x-oss-date: 20231203T121212Z 
x-oss-meta-author: alice
x-oss-meta-magic: abracadabra
x-oss-content-sha256: UNSIGNED-PAYLOAD

在Header包含V4签名的步骤如下：

  1. 构造CanonicalRequest。

    PUT
/examplebucket/exampleobject

content-md5:eB5eJF1ptWaXm4bijSPyxw
content-type:text/html
host:examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-content-sha256:UNSIGNED-PAYLOAD
x-oss-date:20231203T121212Z
x-oss-meta-author:alice
x-oss-meta-magic:abracadabra

host
UNSIGNED-PAYLOAD

  2. 构造待签名字符串（StringToSign）。

    OSS4-HMAC-SHA256
20231203T121212Z
20231203/cn-hangzhou/oss/aliyun_v4_request
129b14df88496f434606e999e35dee010ea1cecfd3ddc378e5ed4989609c1db3

  3. 计算签名。

    1. 计算SigningKey。

      说明

      为方便可读，如下为SigningKey经Base64编码后的字符串。

      WVjaYR8lCj9YC5PUS2RSZQANYbuh9DhMFxjU1NtZKfc=

    2. 计算Signature。

      4b663e424d2db9967401ff6ce1c86f8c83cabd77d9908475239d9110642c63fa

  4. 将签名添加到Authorization中。

    OSS4-HMAC-SHA256 Credential=accesskeyid/20231203/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=4b663e424d2db9967401ff6ce1c86f8c83cabd77d9908475239d9110642c63fa
文档推荐
  • 本页导读 （1）
文档反馈