...

• Response
  • postURL: POST url to upload the file to. e.g. "https://ssvmpublicip/upload/uuid". The URL has the uuid to query the status using listtemplate/volumes API subsequently
  • payload: payload to be sent in the POST request
  • signature: signature is SHA1 key generated using PSK based on 'jsonData' payload, expires and postURL in the response.
  • uuid: uuid of the template/volume. This can be used to query the status of it
  • expires: the time at which the signature expires

POST URL to post the data on to SSVM. This post url is returned from the getUploadParams api call Ex: https://ssvmpublicip/upload/uuid 

• Request: (this is a POST request)
  • payload: JSON string of parameters returned from getUploadParams API call
  • file: the location of the template/volume to be posted as multipart/form-data
  • signature: signature returned from getUploadParams API call
  • expires: expires returned from getUploadParams API call
• Response:
  • '200 OK' on successful upload
  • '401 authorization error' incase the signature key validation or any other validation failed
  • '500 internal server error' incase the file upload fails with clear error message
  • '409 conflict' incase there is already another upload with same params in-progress/success/error

...

Management server API

Request

http://managementip:8080/client/api?command=getUploadParams&type=template&response=json&sessionkey=OXgYX%2BINFOOcxQgI2yzEzuA3xCg%3D&name=lxc1&displayText=lxc1&zoneid=-1&format=TAR&isextractable=false&passwordEnabled=false&isdynamicallyscalable=false&osTypeId=1b510c30-3352-11e4-aaca-a5c7f57670d0&hypervisor=LXC&requireshvm=false&_=1410847402478 apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Response

{ "

postURL

...

:

...

https://ssvmpublicip/upload/

...

DD0A9FC6-C17E-4180-963C-870B9D03A80A,

payload:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,

signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,

expires: 2014-10-17T12:00:00+0530,

uuid:DD0A9FC6-C17E-4180-963C-870B9D03A80A

}

File upload

Request

curl -X POST "https://ssvmpublicip/upload/uuid" -F "template=@templatelocation.tar" -F "signature=de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" -F "payload=TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=" -v

Response

F "expires=2014-10-17T12:00:00+0530" -v

Response

200 200 OK

Design

Pre-shared key management

...

1. On start of management server, if the key doesn't exist, it auto-generates one using SHA1 and stores it in db
2. Key is saved in encrypted form (if db encryption is enabled) in the configuration table as hidden configuration with name upload.post.secret.key
   
3. During SSVM start-up, the key is passed on to it by management server 
4. SSVM stores this key in a file at /etc/cloudstack/agent/ms-psk
5. If the key sharing fails SSVM agent would shut itself down
6. Updating the PSK would involve the following:
   1. Delete the upload.secret.key config from configuration table in db
   2. Restart the MS, so that it gets regenerated again
   3. Destroy all the existing SSVMs
   4. When the new SSVMs starts up the key is copied to it
   5. There will be a window when the key is not in sync between management server and SSVMs

signature generation and verification

The signature returned from the management server in the response of getUploadParams will be validated on the SSVM Agent.

1. The signature is generated using SHA1 and the PSK on the payload, expires and postURL
2. on the SSVM Agent, it computes hash on payload, expires and postURL using SHA1 and PSK and rejects the request if they do not match.
   
3. the postURL, expires and payload returned from getUploadParams shouldn't be tampered by the user. Else, signature validation would fail.

encryption and decryption of payload

...