用 Rust 从零实现对象存储客户端:S3 签名到底签了什么
直接用 S3 SDK 当然最省事。但签名错误时 SDK 只给你一句
SignatureDoesNotMatch,你完全不知道该改哪个字段。
自己实现一遍签名算法,你对"鉴权"这件事的理解会完全不同。而且 S3 协议是事实标准——MinIO、Ceph、阿里云 OSS、腾讯云 COS 全都兼容它。写一遍就通吃。
先说清楚要解决的问题
一个开放网络上的 HTTP 请求,服务端要确认三件事:
- 身份:这个请求是哪个账号发的
- 完整性:请求内容在传输过程中没被篡改
- 时效性:这不是一个被录下来重放的旧请求
三条都不能靠"在 header 里明文写个密钥"——那样密钥会泄漏。
S3 的解法是 HMAC 签名:
签名 = HMAC-SHA256(密钥派生链, 规范化后的请求内容)服务端用同样的方式重算一遍签名,一致就通过。密钥从未出现在网络上,但服务端能验证你有它。
AWS Signature V4 的四步派生
密钥不是一个,而是一条派生链:
kDate = HMAC("AWS4" + secret_key, date) // date 形如 20260920
kRegion = HMAC(kDate, region) // 如 us-east-1
kService = HMAC(kRegion, service) // 如 s3
kSigning = HMAC(kService, "aws4_request") // 固定字符串fn derive_signing_key(secret_key: &str, date: &str, region: &str, service: &str) -> Vec<u8> {
let k_date = hmac_sha256(format!("AWS4{secret_key}").as_bytes(), date.as_bytes());
let k_region = hmac_sha256(&k_date, region.as_bytes());
let k_service = hmac_sha256(&k_region, service.as_bytes());
hmac_sha256(&k_service, b"aws4_request")
}
fn hmac_sha256(key: &[u8], data: &[u8]) -> Vec<u8> {
// 标准 HMAC 实现
const BLOCK: usize = 64;
let mut key_block = vec![0u8; BLOCK];
if key.len() > BLOCK {
let h = sha256(key);
key_block[..h.len()].copy_from_slice(&h);
} else {
key_block[..key.len()].copy_from_slice(key);
}
let mut ipad = vec![0x36u8; BLOCK];
let mut opad = vec![0x5cu8; BLOCK];
for i in 0..BLOCK {
ipad[i] ^= key_block[i];
opad[i] ^= key_block[i];
}
let mut inner = ipad;
inner.extend_from_slice(data);
let inner_hash = sha256(&inner);
let mut outer = opad;
outer.extend_from_slice(&inner_hash);
sha256(&outer)
}为什么要派生四层,而不是直接用 secret_key?
这是**密钥隔离(key separation)**的实践。同一条派生链生成的不同 kSigning 只能用于特定的"日期 + 区域 + 服务"组合。即使某次签名被攻击者逆推出 kDate,他也伪造不出其他日期或者其他区域的签名。
而且 kDate 里带了日期——这就顺带实现了"时效性":一个签名只在当天有效(S3 允许 ±15 分钟时钟偏差)。
签名链的每一层都在收窄适用范围。 这是密码学里"不要把一个密钥用于多个用途"原则的具体应用。
第一步:规范化请求(Canonical Request)
签名不是直接对 body 算,而是对一个规范化的字符串算。这个字符串有五部分:
CanonicalRequest =
HTTPMethod + '\n'
+ CanonicalURI + '\n'
+ CanonicalQueryString + '\n'
+ CanonicalHeaders + '\n'
+ SignedHeaders + '\n'
+ HashedPayloadpub fn canonical_request(
method: &str,
uri: &str,
query: &[(String, String)],
headers: &[(String, String)],
payload_hash: &str,
) -> String {
// 1. URI 要编码(但保留 /)
let canonical_uri = uri_encode(uri, false);
// 2. query 要按 key 排序,且都要编码
let mut sorted_query = query.to_vec();
sorted_query.sort_by(|a, b| a.0.cmp(&b.0));
let canonical_query = sorted_query
.iter()
.map(|(k, v)| format!("{}={}", uri_encode(k, true), uri_encode(v, true)))
.collect::<Vec<_>>()
.join("&");
// 3. header 要小写、按名排序、值要去掉多余空白
let mut sorted_headers: Vec<(String, String)> = headers
.iter()
.map(|(k, v)| (k.to_lowercase(), v.trim().to_string()))
.collect();
sorted_headers.sort_by(|a, b| a.0.cmp(&b.0));
let canonical_headers = sorted_headers
.iter()
.map(|(k, v)| format!("{k}:{v}\n"))
.collect::<String>();
let signed_headers = sorted_headers
.iter()
.map(|(k, _)| k.as_str())
.collect::<Vec<_>>()
.join(";");
format!(
"{method}\n{canonical_uri}\n{canonical_query}\n{canonical_headers}\n{signed_headers}\n{payload_hash}"
)
}这四步"排序 + 小写 + 编码"是签名失败的头号来源。 服务端会严格按这个规则重算,任何一处不同都会导致 SignatureDoesNotMatch。
URI 编码的规则要严格
AWS 的编码规则和标准的 percent-encode 有一点关键差异:
fn uri_encode(input: &str, encode_slash: bool) -> String {
let mut out = String::new();
for byte in input.bytes() {
match byte {
// 未保留字符:不编码
b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
out.push(byte as char);
}
// 斜杠:路径里不编码,query 里编码
b'/' if !encode_slash => out.push('/'),
_ => out.push_str(&format!("%{byte:02X}")),
}
}
out
}三个必须注意的点:
~不编码。 很多语言的urlencode会把~编成%7E,AWS 不接受。- 空格编成
%20,不是+。 这是 form-encoding 和 URI-encoding 的经典混淆点。 - 十六进制要用大写。
%2F可以,%2f不行。
任何一个踩错,签名都会失败——而且服务端只回一个笼统的错误,不告诉你哪里错了。
签名的调试成本几乎全在"规范化"上。 所以实现时要做的第一件事是:把
canonical_request完整打印出来。服务端的错误信息虽然笼统,但通常会在返回体里附上"它期望的规范化字符串"——两个一比就知道差在哪。
第二步:待签字符串(String to Sign)
拿到规范化请求后,先哈希它,再拼成待签字符串:
pub fn string_to_sign(
timestamp: &str, // 形如 20260920T123456Z
scope: &str, // 20260920/us-east-1/s3/aws4_request
canonical_request: &str,
) -> String {
let hash = hex(sha256(canonical_request.as_bytes()));
format!("AWS4-HMAC-SHA256\n{timestamp}\n{scope}\n{hash}")
}格式非常固定:
AWS4-HMAC-SHA256
20260920T123456Z
20260920/us-east-1/s3/aws4_request
<sha256 hex of canonical request>scope 里的四段(日期/区域/服务/aws4_request)必须和签名链的派生完全一致。 这里不一致是最隐蔽的一类 bug——因为签名链和 scope 是两处独立写的字符串。
第三步:计算签名
pub fn compute_signature(signing_key: &[u8], string_to_sign: &str) -> String {
hex(hmac_sha256(signing_key, string_to_sign.as_bytes()))
}到这里签名就完成了。 最后的 Authorization 头是这样:
Authorization: AWS4-HMAC-SHA256
Credential=AKIDEXAMPLE/20260920/us-east-1/s3/aws4_request,
SignedHeaders=host;x-amz-content-sha256;x-amz-date,
Signature=abcdef0123456789...拼起来:
pub fn authorization_header(
access_key: &str,
scope: &str,
signed_headers: &str,
signature: &str,
) -> String {
format!(
"AWS4-HMAC-SHA256 Credential={access_key}/{scope}, \
SignedHeaders={signed_headers}, Signature={signature}"
)
}第四步:组装完整请求
把上面几步串起来,就是一次完整的"签名请求":
pub struct S3Client {
access_key: String,
secret_key: String,
region: String,
endpoint: String,
http: reqwest::Client,
}
impl S3Client {
pub fn put_object(&self, bucket: &str, key: &str, body: Vec<u8>) -> Result<(), S3Error> {
// 1. 计算 payload 的哈希
let payload_hash = hex(sha256(&body));
// 2. 时间戳和 scope
let now = now_utc();
let timestamp = format_amz_datetime(&now); // 20260920T123456Z
let date = format_amz_date(&now); // 20260920
let scope = format!("{date}/{}/s3/aws4_request", self.region);
let uri = format!("/{bucket}/{key}");
let headers = vec![
("host".to_string(), self.host(bucket)),
("x-amz-content-sha256".to_string(), payload_hash.clone()),
("x-amz-date".to_string(), timestamp.clone()),
("content-length".to_string(), body.len().to_string()),
];
// 3. 规范化 + 签名
let canonical = canonical_request("PUT", &uri, &[], &headers, &payload_hash);
let sts = string_to_sign(×tamp, &scope, &canonical);
let signing_key = derive_signing_key(&self.secret_key, &date, &self.region, "s3");
let signature = compute_signature(&signing_key, &sts);
let signed_headers = headers
.iter()
.map(|(k, _)| k.as_str())
.collect::<Vec<_>>()
.join(";");
// 4. 发请求
let url = format!("{}{uri}", self.endpoint);
let resp = self
.http
.put(&url)
.header("Authorization", authorization_header(&self.access_key, &scope, &signed_headers, &signature))
.header("x-amz-content-sha256", &payload_hash)
.header("x-amz-date", ×tamp)
.body(body)
.send()?;
if !resp.status().is_success() {
return Err(S3Error::from_response(resp));
}
Ok(())
}
}x-amz-content-sha256 这个头很关键:它同时进入了签名和请求,所以任何对 body 的篡改都会导致签名失败。它是"完整性"保证的载体。
不想要这个开销的话,可以用 UNSIGNED-PAYLOAD——但那意味着放弃完整性校验,一般只在上传大文件且已经用了 HTTPS 时使用。
分片上传:大文件必须走的路
S3 有单次上传大小限制(5GB)。大文件必须走 multipart upload:
1. CreateMultipartUpload -> 拿到 upload_id
2. UploadPart (part 1) -> 得到 ETag
3. UploadPart (part 2) -> 得到 ETag
...
4. CompleteMultipartUpload -> 提交所有 ETagpub struct MultipartUpload {
pub upload_id: String,
pub parts: Vec<CompletedPart>,
}
#[derive(Debug, Clone)]
pub struct CompletedPart {
pub part_number: u32,
pub etag: String,
}
impl S3Client {
pub fn create_multipart(&self, bucket: &str, key: &str) -> Result<String, S3Error> {
let resp = self.signed_request("POST", &format!("/{bucket}/{key}?uploads"), vec![])?;
// 从 XML 响应里抽 <UploadId>
parse_upload_id(&resp)
}
pub fn upload_part(
&self,
bucket: &str,
key: &str,
upload_id: &str,
part_number: u32,
data: Vec<u8>,
) -> Result<String, S3Error> {
let query = format!("partNumber={part_number}&uploadId={upload_id}");
let resp = self.signed_request(
"PUT",
&format!("/{bucket}/{key}?{query}"),
data,
)?;
// ETag 在响应头里
Ok(resp.header("etag").unwrap_or_default().to_string())
}
pub fn complete_multipart(
&self,
bucket: &str,
key: &str,
upload_id: &str,
parts: &[CompletedPart],
) -> Result<(), S3Error> {
let mut xml = String::from("<CompleteMultipartUpload>");
for p in parts {
xml.push_str(&format!(
"<Part><PartNumber>{}</PartNumber><ETag>{}</ETag></Part>",
p.part_number, p.etag
));
}
xml.push_str("</CompleteMultipartUpload>");
self.signed_request(
"POST",
&format!("/{bucket}/{key}?uploadId={upload_id}"),
xml.into_bytes(),
)?;
Ok(())
}
}分片大小怎么定
| 分片大小 | 100 GB 文件的分片数 | 说明 |
|---|---|---|
| 5 MB | 20480 | S3 上限 10000 片,超了 |
| 8 MB | 12800 | 仍然超限 |
| 16 MB | 6400 | 安全 |
| 64 MB | 1600 | 推荐 |
| 128 MB | 800 | 失败重传代价大 |
两个约束:
- 每片最小 5MB(最后一片除外)——否则
CompleteMultipartUpload会失败 - 最多 10000 片——所以 100GB 文件至少要用 10MB 的片
推荐做法是按文件大小动态计算:
fn part_size(total_size: u64) -> u64 {
const MIN_PART: u64 = 5 * 1024 * 1024;
const MAX_PARTS: u64 = 10_000;
const DEFAULT: u64 = 64 * 1024 * 1024;
// 至少保证不超过 MAX_PARTS 片
let needed = total_size.div_ceil(MAX_PARTS);
needed.max(MIN_PART).max(DEFAULT)
}断点续传:分片上传的真正价值
分片上传最大的好处不是"并发",而是失败只需要重传一片。
要做断点续传,需要能"列出已上传的分片":
impl S3Client {
pub fn list_parts(&self, bucket: &str, key: &str, upload_id: &str) -> Result<Vec<CompletedPart>, S3Error> {
let resp = self.signed_request(
"GET",
&format!("/{bucket}/{key}?uploadId={upload_id}"),
vec![],
)?;
parse_parts(&resp)
}
}于是"上传一个大文件"变成了一个可恢复的流程:
pub fn upload_resumable(
client: &S3Client,
bucket: &str,
key: &str,
path: &std::path::Path,
) -> Result<(), S3Error> {
let total = std::fs::metadata(path)?.len();
let psize = part_size(total);
// 1. 尝试复用已有的 upload_id(存在本地临时文件里)
let state_path = format!("/tmp/upload-{}.state", sanitize(key));
let (upload_id, mut done) = if let Ok(s) = read_state(&state_path) {
(s.upload_id, s.parts)
} else {
let id = client.create_multipart(bucket, key)?;
(id.clone(), Vec::new())
};
// 2. 续传:跳过已完成的分片
let mut offset = (done.len() as u64) * psize;
while offset < total {
let this = psize.min(total - offset);
let data = read_at(path, offset, this)?;
let part_number = (offset / psize) as u32 + 1;
let etag = client.upload_part(bucket, key, &upload_id, part_number, data)?;
done.push(CompletedPart { part_number, etag });
// 每上传一片就记录状态——这是断点续传的关键
write_state(&state_path, &upload_id, &done)?;
offset += this;
}
// 3. 完成
client.complete_multipart(bucket, key, &upload_id, &done)?;
std::fs::remove_file(&state_path).ok();
Ok(())
}"每上传一片就落一次状态"是关键。 如果状态只在全部完成后才写,那崩溃之后还是要从头开始——断点续传就白做了。
还有一个必须处理的问题:ETag 的解析。
ETag: "d41d8cd98f00b204e9800998ecf8427e"引号必须去掉。 而且要注意:multipart 上传的 ETag 形如 "abc-3"(带 -分片数 后缀),和普通上传的 ETag 格式不同。提交时必须用原样(去掉引号)的值。
并发上传与背压
分片可以并发上传,但并发数要有上限:
pub async fn upload_concurrent(
client: &S3Client,
bucket: &str,
key: &str,
path: &std::path::Path,
concurrency: usize,
) -> Result<(), S3Error> {
let total = std::fs::metadata(path)?.len();
let psize = part_size(total);
let part_count = total.div_ceil(psize);
let upload_id = client.create_multipart(bucket, key)?;
let semaphore = std::sync::Arc::new(tokio::sync::Semaphore::new(concurrency));
let mut handles = Vec::new();
for i in 0..part_count {
let permit = semaphore.clone().acquire_owned().await.unwrap();
let offset = i * psize;
let size = psize.min(total - offset);
// ... 每个分片一个任务,完成后释放 permit ...
let client = client.clone();
let id = upload_id.clone();
handles.push(tokio::spawn(async move {
let _permit = permit;
let data = read_at(path, offset, size)?;
client.upload_part(bucket, key, &id, (i + 1) as u32, data)
}));
}
// 收集所有 ETag
let mut parts = Vec::new();
for (i, h) in handles.into_iter().enumerate() {
let etag = h.await??;
parts.push(CompletedPart { part_number: (i + 1) as u32, etag });
}
parts.sort_by_key(|p| p.part_number); // 顺序必须正确
client.complete_multipart(bucket, key, &upload_id, &parts)?;
Ok(())
}parts.sort_by_key 这一行不能省。 并发完成顺序是乱的,但 S3 要求 CompleteMultipartUpload 里的分片按序号(实际上现代 S3 已经容忍乱序,但很多兼容实现仍然严格要求)。
并发数建议 4-8。 太高会打满带宽或者触发服务端的限流;太低就浪费了并发的意义。
三个容易忽略的实践点
1. 时钟必须准。 签名里带了时间戳,服务端允许的偏差通常只有 15 分钟。一台时钟漂移的机器会导致所有请求失败,而且错误信息还是"签名不匹配"——非常难排查。
// 启动时检查时钟偏差,偏差过大就告警
async fn check_clock_skew(client: &S3Client) -> Result<(), S3Error> {
let local = now_utc();
let server = client.get_server_time()?; // 从响应 Date 头取
let skew = (local - server).num_seconds().abs();
if skew > 300 {
eprintln!("时钟偏差 {skew} 秒,会导致签名失败");
}
Ok(())
}2. 错误响应也是 XML。 S3 的错误不是 JSON,需要解析:
<Error>
<Code>SignatureDoesNotMatch</Code>
<Message>The request signature we calculated does not match...</Message>
<StringToSign>...</StringToSign>
</Error><StringToSign> 这个字段在调试时无价——它直接告诉你服务端算出来的待签字符串是什么。和自己算的一比,立刻能定位到是 canonical request 的哪一部分不对。
3. 路径风格的兼容性。 有两个端点格式:
虚拟主机风格: https://bucket.s3.amazonaws.com/key
路径风格: https://s3.amazonaws.com/bucket/key虚拟主机风格的 host 里带 bucket,所以 CanonicalHeaders 里的 host 值不同,签名也就不同。MinIO、Ceph 这类自建服务通常只支持路径风格——切换时要确认签名用的 host 和实际请求的 host 一致。
结论
S3 签名看起来步骤多,但它每一层都有明确目的:
四层密钥派生 + 日期/区域/服务限定作用范围;规范化请求把"任意 HTTP 请求"变成"唯一确定的字符串";
x-amz-content-sha256保证 body 完整性;时间戳提供时效性。
实现时的三个要点:
- URI 编码严格按 AWS 规则(
~不编码、空格用%20、十六进制大写) - 分片大小按文件大小动态算,同时满足"每片 ≥ 5MB"和"总片数 ≤ 10000"
- 断点续传的关键是"每片落一次状态",否则恢复等于重来
写完这个客户端,你能对接的不只是 AWS——MinIO、阿里云 OSS、腾讯云 COS、七牛、Backblaze B2 全都支持这套协议。 一份实现,通吃主流对象存储。