Object Storage Service:Callback

Add the parameters to the URL

If you add the parameters to the URL, the callback parameter is required and the callback-var parameter is optional. If a request contains the callback or callback-var parameter, you must use the callback or callback-var parameter as a subresource of CanonicalizedResource when you calculate the signature. For more information, see Include signatures in the Authorization header.

PUT /test.txt?OSSAccessKeyId=LTAI5t7h6SgiLSga****&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****&Expires=1682484377&callback-var=eyJ4Om15X3ZhciI6ImZvci1jYWxsYmFjay10ZXN0****&callback=eyJjYWxsYmFja1VybCI6IjEyMS40My4xMTMuODoyMzQ1Ni9pbmRleC5odG1sIiwgICJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mZXRhZz0ke2V0YWd9JnNpemU9JHtzaXplfSZtaW1lVHlwZT0ke21pbWVUeXBlfSZpbWFnZUluZm8uaGVpZ2h0PSR7aW1hZ2VJbmZvLmhlaWdodH0maW1hZ2VJbmZvLndpZHRoPSR7aW1hZ2VJbmZvLndpZHRofSZpbWFnZUluZm8uZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mbXlfdmFyPSR7eDpteV92YXJ9**** 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

Add the parameters to the request as a header

Add the x-oss-callback or x-oss-callback-var header to the request. The x-oss-callback-var and x-oss-callback headers are included in CanonicalizedOSSHeaders to calculate the signature. Example:

PUT /test.txt HTTP/1.1
Host: callback-test.oss-test.aliyun-inc.com
Accept-Encoding: identity
Content-Length: 5
x-oss-callback-var: eyJ4Om15X3ZhciI6ImZvci1jYWxsYmFjay10ZXN0****
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: eyJjYWxsYmFja1****4x
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 mlepou3zr4u****:5a74vhd4UXpmyuudV14Kaen5****
Test

Add the parameters to the form fields in the body of a POST request

You can use only this method to configure callback parameters when you upload objects by calling the PostObject operation.

• If you want to add the callback parameter when you use the POST method to upload an object, add the callback parameter by using a different form field. Example:

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

• Each custom parameter uses a different form field. You cannot add the callback-var parameter to existing form fields. You must add each custom parameter by using a separate form field. Example of JSON fields that you can configure for custom parameters:

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

  Example of form fields in the POST request:

  --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

  You can add callback conditions to the policy. If you do not add callback conditions to the policy, the callback parameters are not verified for the upload. Example:

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

Step 1: Generate a signature

• Method for generating a signature

  OSS uses the RSA encryption algorithm to sign a callback request.

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

  Note

  In the preceding code, private_key specifies a private key, path specifies the resource path that is included in the callback request, query_string specifies the query string, and body specifies the message body in the callback request.

• Procedure for generating a signature

  1. Obtain the callback string that you want to sign. The string consists of the resource path that is obtained by decoding the URL, the original query string, a carriage return, and the callback message body.

  2. Sign the callback string by using the RSA encryption algorithm. Use the private key to encrypt the signature string. The hash function that is used for the signature is MD5.

  3. Use Base64 to encode the signed result to obtain the final signature. Then, add the signature to the Authorization header in the callback request.

• Example

  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

  In the preceding code, path is set to /index.php, query_string is set to ?id=1&index=2, and the body is set to bucket=examplebucket. The final signature is kKQeGTRccDKyHB3H9vF+xYMSrmhMZjzzl2/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****.

Step 2: Verify the signature

• Method for verifying the signature

  The following sample code provides an example on how to verify the signature by using the application server:

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

  public_key specifies the public key, and authorization specifies the signature that you want to include in the callback request header.

• Procedure for verifying the signature

  1. The x-oss-pub-key-url header in the callback request stores the Base64-encoded URL of the public key. Decode the Base64-encoded URL to obtain the public key.

     public_key = urlopen(base64_decode(x-oss-pub-key-url header value))

     For example, obtain the URL of the public key by decoding aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnBlbQ== in Base64. The decoded URL is http://gosspublic.alicdn.com/callback_pub_key_v1.pem.

     Note

     The value of the x-oss-pub-key-url header in the public_key field issued by OSS must start with http://gosspublic.alicdn.com/ or https://gosspublic.alicdn.com/.

  2. Obtain the signature that is decoded in Base64.

     signature = base64_decode(authorization header value)

  3. Obtain the string to sign by performing the same procedure that you use to obtain the string after the callback request is signed.

     sign_str = url_decode(path) + query_string + '\n' + body

  4. Verify the signature.

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

• Example

  The following code provides an example on how an application server verifies a signature. Before you run the code in OSS SDK for Python, install the M2Crypto library.

  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
              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()

  The following table describes the code that you can use to verify a signature on the server in other programming languages.

  SDK programming language	Description
  Java	Download link: OSS SDK for Java Running method: Decompress the package and run java -jar oss-callback-server-demo.jar 9000. The port number is 9000. You can change the port number.
  Python	Download link: OSS SDK for Python Running method: Decompress the package and run python callback_app_server.py. Before you run the code, install RSA dependencies.
  Go	Download link: OSS SDK for Go Running method: Decompress the package and follow the instructions in README.md.
  PHP	Download link: OSS SDK for PHP Running method: Deploy the code to an Apache environment to ensure that specific headers in the code can use the environment as a dependency. You can modify the sample code based on the environment.
  .NET	Download link: OSS SDK for .NET Running method: Decompress the package and follow the instructions in README.md.
  Node.js	Download link: OSS SDK for Node.js Running method: Decompress the package and run node example.js.
  Ruby	Download link: OSS SDK for Ruby Running method: Run ruby aliyun_oss_callback_server.rb.