下载凭证

下载凭证是七牛云存储用于验证下载私有资源请求合法性的机制。
用户通过下载凭证授权客户端，使其具备访问指定私有资源的能力。

下载公开空间资源不需要下载凭证。

• 算法
• 附注
• 示例
• 内部参考资源
• 外部参考资源
  

算法

1. 构造下载URL：

   DownloadUrl = 'http://developer.qiniu.com/resource/flower.jpg'
   

2. 为下载URL加上过期时间（e参数，Unix时间戳）：

   DownloadUrl = 'http://developer.qiniu.com/resource/flower.jpg?e=1451491200'
   

3. 对上一步得到的URL字符串计算HMAC-SHA1签名（假设SecretKey是MY_SECRET_KEY），并对结果做URL安全的Base64编码：

   Sign = hmac_sha1(DownloadUrl, 'MY_SECRET_KEY')
   EncodedSign = urlsafe_base64_encode(Sign)
   

4. 将AccessKey（假设是MY_ACCESS_KEY）与上一步计算得到的结果以“:”连接起来：

   Token = 'MY_ACCESS_KEY:yN9WtB0lQheegAwva64yBuH3ZgU='
   

5. 将下载凭证添加到含过期时间参数的下载URL之后，作为最后一个参数（token参数）：

   RealDownloadUrl = 'http://developer.qiniu.com/resource/flower.jpg?e=1451491200&token=MY_ACCESS_KEY:yN9WtB0lQheegAwva64yBuH3ZgU='
   

RealDownloadUrl即为下载对应私有资源的可用URL，并在指定时间后失效。
失效后，可按需重新生成下载凭证。

附注

• 为确保客户端、业务服务器和七牛服务器对于授权截止时间的理解保持一致，需要同步校准各自的时钟。频繁返回401状态码时请先检查时钟同步性与生成e参数值的代码逻辑。
  
• 对于包含中文或其它非英文字符的Key，需要做到以下两点：
  
  • Key 本身要做 UTF-8 编码；
  • 为 URL 签名之前，对 Path 部分（不含前导/符号，通常就是 Key 本身，即上例中的 flower.jpg）做一次 URL编码。

示例

下载凭证不需要单独生成，七牛支持的语言SDK都提供了生成完整 private_url 的方法（包含下载凭证），python示例代码如下：

import requests

from qiniu import Auth

access_key = '...'
secret_key = '...'

q = Auth(access_key, secret_key)

bucket_domain = '...' #可以在空间设置的域名设置中找到
key = 'test_private_key'
base_url = 'http://%s/%s' % (bucket_domain, key)
private_url = q.private_download_url(base_url, expires=3600)
print(private_url)
r = requests.get(private_url)
assert r.status_code == 200

内部参考资源

• URL安全的Base64编码

外部参考资源

• Unix时间戳
• HMAC-SHA1签名