Callback

在URL中携带参数时，callback为必选参数，callback-var为可选参数。如果请求中出现了callback或callback-var，则在计算签名时，需要将callback或者callback-var参数作为CanonicalizedResource的子资源。更多信息，请参见构建CanonicalizedResource的方法。

PUT /your_object?OSSAccessKeyId=LTAI5t7h6SgiLSga****&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****&Expires=1682484377&callback-var=eyJ4Om15X3ZhciI6ICJ2YX****==&callback=bGxiYWNrVXJsIjogImh0dHA6Ly94eHgueHh4LjIyLjE0My90ZXN0IiwKICAgICJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLAogICAgImNhbGxiYWNrQm9keSI6ICJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mbXlfdmFyPSR7eDpteV92YXJ9IiwKICAgICJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCIsCiAgICAiY2FsbGJhY2tTTkkiOiBmYWxzZQp9 HTTP/1.1
Host: callback-test.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 26 Apr 2023 03:46:17 GMT
Content-Length: 5
Content-Type: text/plain

在Header中携带参数时，需要将x-oss-callback或者x-oss-callback-var作为Header带入请求发送。在计算签名CanonicalizedOSSHeaders时，将x-oss-callback-var和x-oss-callback计算在内。

完整示例如下：

PUT /your_object HTTP/1.1
Host: callback-test.oss-test.aliyun-inc.com
Accept-Encoding: identity
Content-Length: 5
x-oss-callback-var: eyJ4Om15X3ZhciI6ICJ2YX****==
User-Agent: aliyun-sdk-python/0.4.0 (Linux/2.6.32-220.23.2.ali1089.el5.x86_64/x86_64;2.5.4)
x-oss-callback: ewogICAg****bGxiYWNrVXJsIjogImh0dHA6Ly94eHgueHh4LjIyLjE0My90ZXN0IiwKICAgICJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLAogICAgImNhbGxiYWNrQm9keSI6ICJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mbXlfdmFyPSR7eDpteV92YXJ9IiwKICAgICJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCIsCiAgICAiY2FsbGJhY2tTTkkiOiBmYWxzZQp9
Host: callback-test.oss-test.aliyun-inc.com
Expect: 100-Continue
Date: Wed, 26 Apr 2023 03:46:17 GMT
Content-Type: text/plain
Authorization: OSS qn6q**************:77Dv****************
Test

使用PostObject接口上传Object时，仅支持通过POST请求的Body中使用表单域来携带参数的方式指定回调参数。

• 如果需要在POST上传Object时附带回调参数，callback参数要使用独立的表单域来附加，示例如下：

  --9431149156168
  Content-Disposition: form-data; name="callback"
  eyJjYWxsYmFja1VybCI6IjEwLj****4xN

• 如果是自定义参数，不能直接将callback-var参数直接附加到表单域中。每个自定义的参数都需要使用独立的表单域来添加。例如，自定义参数JSON字段示例如下：

  {
  "x:var1":"value1",
  "x:var2":"value2"
  }

  则POST请求的表单域为：

  --9431149156168
  Content-Disposition: form-data; name="callback"
  eyJjYWxsYmFja1VybCI6IjEwLj****4xN
  --9431149156168
  Content-Disposition: form-data; name="x:var1"
  value1
  --9431149156168
  Content-Disposition: form-data; name="x:var2"
  value2

  同时，您还可以在policy中添加callback条件。如果不添加callback条件，则不对该参数做上传验证，如下所示。

  { "expiration": "2021-12-01T12:00:00.000Z",
    "conditions": [
      {"bucket": "johnsmith" },
      {"callback": "eyJjYWxsYmFja1V****4My"},
      ["starts-with", "$key", "user/eric/"],
    ]
  }

• 生成签名的方式

  采用RSA非对称方式生成签名。

  authorization = base64_encode(rsa_sign(private_key, url_decode(path) + query_string + '\n' + body, md5))

  说明

  其中，private_key为私钥，path为回调请求的资源路径，query_string为查询字符串，body为回调的消息体。

• 生成签名的步骤

  1. 获取待签名字符串：资源路径经过URL解码后，会附加原始的查询字符串、一个回车符以及回调消息体。

  2. RSA签名：使用密钥对待签名字符串进行签名，签名的哈希函数为md5。

  3. 将签名后的结果做Base64编码，获取最终的签名，然后将签名放在回调请求的authorization头中。

• 生成签名的示例

  POST /index.php?id=1&index=2 HTTP/1.0
  Host: 172.16.XX.XX
  Connection: close
  Content-Length: 18
  authorization: kKQeGTRccDKyHB3H9vF+xYMSrmhMZj****/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****
  Content-Type: application/x-www-form-urlencoded
  User-Agent: http-client/0.0.1
  x-oss-pub-key-url: aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnsr****
  bucket=examplebucket

  path为/index.php，query_string为?id=1&index=2，body为bucket=examplebucket，最终签名结果为kKQeGTRccDKyHB3H9vF+xYMSrmhMZjzzl2/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****。

• 验证签名的方式

  通过应用服务器验证签名示例如下：

  Result = rsa_verify(public_key, md5(url_decode(path) + query_string + ‘\n’ + body), base64_decode(authorization))

  其中，public_key为公钥，authorization为回调头中的签名。

• 验证签名的过程

  1. 回调请求的x-oss-pub-key-url头保存的是公钥URL地址的base64编码，需要对x-oss-pub-key-url执行base64解码后获取公钥。

     public_key = urlopen(base64_decode(x-oss-pub-key-url头的值))

     例如，获取到公钥的URL地址为aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnBlbQ==，经过base64解码后得到http://gosspublic.alicdn.com/callback_pub_key_v1.pem。

     说明

     OSS颁发的public_key中x-oss-pub-key-url头的值必须以http://gosspublic.alicdn.com/或者https://gosspublic.alicdn.com/开头。由于公钥地址的内容不变，因此推荐根据公钥地址缓存公钥内容，以避免因为网络或者公钥地址所在服务问题造成的业务异常。

  2. 获取base64解码后的签名。

     signature = base64_decode(authorization头的值)

  3. 获取待签名字符串，方法与签名一致。

     sign_str = url_decode(path) + query_string + ‘\n’ + body

  4. 验证签名。

     result = rsa_verify(public_key, md5(sign_str), signature)

• 验证签名示例

  以Python为例，演示应用服务器中验证签名的方法，此示例需要安装M2Crypto库。

  import httplib
  import base64
  import md5
  import urllib2
  from BaseHTTPServer import BaseHTTPRequestHandler, HTTPServer
  from M2Crypto import RSA
  from M2Crypto import BIO
  def get_local_ip():
      try:
          csock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
          csock.connect(('8.8.8.8', 80))
          (addr, port) = csock.getsockname()
          csock.close()
          return addr
      except socket.error:
          return ""
  class MyHTTPRequestHandler(BaseHTTPRequestHandler):
      '''
      def log_message(self, format, *args):
          return
      '''
      def do_POST(self):
          #get public key
          pub_key_url = ''
          try:
              pub_key_url_base64 = self.headers['x-oss-pub-key-url']
              pub_key_url = pub_key_url_base64.decode('base64')
              if not pub_key_url.startswith("http://gosspublic.alicdn.com/") and not pub_key_url.startswith("https://gosspublic.alicdn.com/"):
                  self.send_response(400)
                  self.end_headers()
                  return
              url_reader = urllib2.urlopen(pub_key_url)
              #you can cache it,recommend caching public key content based on the public key address
              pub_key = url_reader.read() 
          except:
              print 'pub_key_url : ' + pub_key_url
              print 'Get pub key failed!'
              self.send_response(400)
              self.end_headers()
              return
          #get authorization
          authorization_base64 = self.headers['authorization']
          authorization = authorization_base64.decode('base64')
          #get callback body
          content_length = self.headers['content-length']
          callback_body = self.rfile.read(int(content_length))
          #compose authorization string
          auth_str = ''
          pos = self.path.find('?')
          if -1 == pos:
              auth_str = urllib2.unquote(self.path) + '\n' + callback_body
          else:
              auth_str = urllib2.unquote(self.path[0:pos]) + self.path[pos:] + '\n' + callback_body
          print auth_str
          #verify authorization
          auth_md5 = md5.new(auth_str).digest()
          bio = BIO.MemoryBuffer(pub_key)
          rsa_pub = RSA.load_pub_key_bio(bio)
          try:
              result = rsa_pub.verify(auth_md5, authorization, 'md5')
          except:
              result = False
          if not result:
              print 'Authorization verify failed!'
              print 'Public key : %s' % (pub_key)
              print 'Auth string : %s' % (auth_str)
              self.send_response(400)
              self.end_headers()
              return
          #do something according to callback_body
          #response to OSS
          resp_body = '{"Status":"OK"}'
          self.send_response(200)
          self.send_header('Content-Type', 'application/json')
          self.send_header('Content-Length', str(len(resp_body)))
          self.end_headers()
          self.wfile.write(resp_body)
  class MyHTTPServer(HTTPServer):
      def __init__(self, host, port):
          HTTPServer.__init__(self, (host, port), MyHTTPRequestHandler)
  if '__main__' == __name__:
      server_ip = get_local_ip()
  server_port = 23451
  server = MyHTTPServer(server_ip, server_port)
  server.serve_forever()

  其他语言的服务端代码请参见下表。

  SDK语言	描述
  Java	下载地址：Java 运行方法：解压包运行java -jar oss-callback-server-demo.jar 9000（9000指运行的端口，可以自行指定）。
  Python	下载地址：Python 运行方法：解压包直接运行python callback_app_server.py，运行该程序需要安装RSA的依赖。
  Go	下载地址：Go 运行方法：解压后参看README.md。
  PHP	下载地址：PHP 运行方法：部署到Apache环境下，因为PHP本身语言的特点，取一些数据头部会依赖于环境。所以可以参考例子根据所在环境修改。
  .NET	下载地址：.NET 运行方法：解压后参看README.md。
  Node.js	下载地址：Node.js 运行方法：解压包直接运行node example.js。
  Ruby	下载地址：Ruby 运行方法：ruby aliyun_oss_callback_server.rb