返回文章列表

用 Rust 从零实现对象存储客户端:S3 签名到底签了什么

718 字·6 分钟阅读
Rust从零造轮子云服务

直接用 S3 SDK 当然最省事。但签名错误时 SDK 只给你一句 SignatureDoesNotMatch,你完全不知道该改哪个字段。

自己实现一遍签名算法,你对"鉴权"这件事的理解会完全不同。而且 S3 协议是事实标准——MinIO、Ceph、阿里云 OSS、腾讯云 COS 全都兼容它。写一遍就通吃。


先说清楚要解决的问题

一个开放网络上的 HTTP 请求,服务端要确认三件事:

  1. 身份:这个请求是哪个账号发的
  2. 完整性:请求内容在传输过程中没被篡改
  3. 时效性:这不是一个被录下来重放的旧请求

三条都不能靠"在 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'
    + HashedPayload
pub 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
}

三个必须注意的点:

  1. ~ 不编码。 很多语言的 urlencode 会把 ~ 编成 %7E,AWS 不接受。
  2. 空格编成 %20,不是 +。 这是 form-encoding 和 URI-encoding 的经典混淆点。
  3. 十六进制要用大写。 %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(&timestamp, &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", &timestamp)
            .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 -> 提交所有 ETag
pub 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 完整性;时间戳提供时效性。

实现时的三个要点:

  1. URI 编码严格按 AWS 规则(~ 不编码、空格用 %20、十六进制大写)
  2. 分片大小按文件大小动态算,同时满足"每片 ≥ 5MB"和"总片数 ≤ 10000"
  3. 断点续传的关键是"每片落一次状态",否则恢复等于重来

写完这个客户端,你能对接的不只是 AWS——MinIO、阿里云 OSS、腾讯云 COS、七牛、Backblaze B2 全都支持这套协议。 一份实现,通吃主流对象存储。