简介

本文档主要针对RESTful API调用者。

1 API认证简介

用户可以通过两种方式与百度云进行交互,包括认证方式和匿名方式。对于认证方式,需要通过使用Access Key Id / Secret Access Key加密的方法来验证某个请求的发送者身份。Access Key Id(AK)用于标示用户,Secret Access Key(SK)是用户用于加密认证字符串和百度云用来验证认证字符串的密钥,其中SK必须保密,只有用户和百度云知道。

当百度云接收到用户的请求后,系统将使用相同的SK和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。

说明:

本文档主要针对RESTful API调用者,SDK使用者无需关注。在SDK中已经封装了完整的签名算法,使用者无需自己实现。

2 名词解释

本章节涉及的核心名词解释如下:

  • 认证字符串:非匿名请求中必须携带的认证信息。包含生成待签名串CanonicalRequest所必须的信息以及签名摘要signature。
  • authStringPrefix:认证字符串的前缀部分。
  • canonicalRequest:待签名串。携带经过规范化处理后的请求信息。
  • signingKey:签名Key。百度云不直接使用SK对待签名串生成摘要。相反的,百度云首先使用SK和认证字符串前缀生成signingKey,然后用signingKey对待签名串生成摘要。
  • signature:签名摘要。百度云使用signingKey对canonicalRequest使用HMAC算法计算签名。

3 API认证优势

API认证将为用户带来以下优势:

  • 对于请求者的身份进行验证。认证字符串使用指定用户的AK/SK对HTTP请求进行签名,可以起到验证用户身份的作用。关于AK/SK的获取,请参看获取AK/SK
  • 对被传输内容进行保护,防止非法篡改。用户基于HTTP请求的指定内容生成认证字符串,如果在传输过程中遭到非法篡改,将导致系统生成的认证字符串与用户生成的认证字符串不匹配,最终导致认证失败。
  • 防止重放攻击。认证字符串都具有指定的生效时间,一个请求必须要在指定时间内到达百度云,否则系统将拒绝该请求。
  • 为了保护用户的SK信息,百度云不直接使用SK信息,而是使用SK生成SigningKey,同时在SigningKey中包含有效时间范围。这样可以减少用户因SigningKey丢失带来的安全隐患。

4 API认证方式

百度云通过认证算法对HTTP请求的指定内容进行计算并输出认证字符串用于认证。开发者需要首先将HTTP请求的指定内容连接成字符串,结合百度云分配的SK,通过HMAC算法计算密文摘要,这个过程也就是对HTTP请求进行签名过程。百度云API使用基于认证字符串的HTTP请求签名机制来验证用户身份。对于每个HTTP请求,都需要携带一个认证字符串然后通过以下两种方式将这个认证字符串包含在请求中:

  • 在HTTP Header中包含认证字符串

    通常使用的方法是在HTTP请求的Authorization头域中包含认证字符串,除了匿名请求之外,所有与百度云的交互都应该包含该字段。更多关于在HTTP Header中包含认证字符串的方法,请参考在Header中包含认证字符串

  • 在URL中包含认证字符串

    用户也可以认证字符串放在HTTP请求Query String的authorization参数中。常用于生成URL给第三方使用的场景,例如要临时把某个数据开放给他人下载。关于如何在URL中包含认证字符串,请参考在URL中包含认证字符串

5 认证字符串生成简介

百度云认证字符串的生成机制如下图所示:

关于认证字符串的详细生成方案,请参看生成认证字符串

百度云API使用基于认证字符串的HTTP请求签名机制来验证用户身份,对于非匿名方式的HTTP请求,都应携带一个认证字符串。当百度云收到用户的HTTP请求后,系统将按照下图所示流程进行处理。

  1. 判断用户的HTTP请求是否为匿名请求,即用户的请求中是否包含Authorization认证字符串。如果不包含认证字符串,则需要根据不同业务情况,参考其他相关流程进行处理;如果包含认证字符串,则执行下一步操作。

  2. 判断用户的请求是否超时,即服务器收到请求的时间需要符合以下要求:

    {timestamp} - 5分钟 < 服务器接收到请求时间 < {timestamp} + {expirationPeriodInSeconds} + 5分钟

    timestamp代表签名生效UTC时间,expirationPeriodInSeconds代表签名有效期限。

    为了防止用户时钟与服务器时钟不同步而导致的认证失败,此处引入5分钟的宽松系数。如果服务器收到请求的时间不符合以上时间要求,则认为请求超时,拒绝该请求;如果符合上述要求,则执行下一步操作。

  3. 基于HTTP请求信息,使用相同的算法,生成Signature字符串。

  4. 使用服务器生成的Signature字符串与用户提供的字符串进行比对,如果内容不一致,则认为认证失败,拒绝该请求;如果内容一致,则表示认证成功,系统将按照用户的请求内容进行操作。