Page History

...

• Request
  • type: type of upload request. Possible values are volume or template : required
  • name: the name of the volume/template : required
    
  • format: the format of the volume/template to be uploaded. Possible values for volume include QCOW2, OVA and VHD. Possible values for template include QCOW2, RAW and VHD : required
    
  • zoneid: the UUID of the zone the volume/template is associated to : required
  • checksum: the MD5 checksum of volume/template to be uploaded. If specified this is used to validate the content of the uploaded volume/template for integrity.
  • account: an optional account name. Must be used with 'domainid' parameter below.
  • domainid: an optional domain to which the account belongs. If the account parameter is used, 'domainid' must also be used.
  • projectid: the UUID of the project if the volume/template needs to be associated with one
  • 'type' specified as volume
    • imagestoreuuid: the UUID of the storage pool where the uploaded volume gets stored. This can be obtained using listImageStores API call (https://cloudstack.apache.org/docs/api/apidocs-4.4/root_admin/listImageStores.html)
  • 'type' specified as template
    • displaytext: the display text of the template. This is used for setting a suitable name for display purposes. : required
    • hypervisor: the target hypervisor for the template : required
    • ostypeid: the UUID of the OS type that best represents the OS of this template : required
    • bits: specifies if template supports 32 or 64 bit. Default is 64 bit.
    • details: additional template details in key/value pairs
    • isdynamicallyscalable: true if template contains XS/VMWare tools in order to support dynamic scaling of VM cpu/memory
    • isextractable: true if the template or its derivatives are extractable. Default is false
    • isfeatured: true if the template is a featured template, false otherwise
    • ispublic: true if the template is available to all users. Default is true.
    • isrouting: true if the template type is routing i.e. , if template is used to deploy router
    • passwordenabled: true if the template supports the password reset feature. Default is false.
    • requireshvm: true if this template requires hardware assisted virtualization support
    • sshkeyenabled: true if the template supports the sshkey upload feature. Default is false.
    • templatetag: the tag for this template. Used to deploy VMs on hosts with this tag.

• Response
  • uuid: Unique UUID to identify the template/volume. This is used to query the status of volume/template after successful completion of upload
  • postURL: POST url to upload the file to; for e.g. "https://ssvmpublicip/upload/uuid".
  • payload: encrypted data to be sent in the POST request. This is used to transfer some internal data required for upload
  • expires: the timestamp after which the signature expires
  • signature: signature is SHA1 key generated using PSK based on 'postURL', 'payload' and 'expires' in the response. This is used to validate that the actual POST request to upload data is a genuine one 

...

GetUploadParams call for volume

http://managementip:8080/client/api?command=getUploadParams&response=json&sessionkey=TW1GLzPclNGgKtoYN5Xznbw8Nds%3D&name=windows&zoneId=c2bcad2f-1eb1-45ba-bebe-1c21873831b7&format=VHD&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

...

{ 
postURL:https://ssvmpublicip/upload/C7D351D2-F167-4CC8-A9FF-3BECB0A625C4,
payload:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,
signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,
expires: 2014-10-17T12:00:00+0530,
uuid:C7D351D2-F167-4CC8-A9FF-3BECB0A625C4
}

...

GetUploadParams call for template

http://managementip:8080/client/api?command=getUploadParams&type=template&response=json&name=centos 64 64bit&displayText=centos 64 64bit&zoneid=-1&format=VHD&isextractable=false&passwordEnabled=false&isdynamicallyscalable=false&osTypeId=1b510c30-3352-11e4-aaca-a5c7f57670d0&hypervisor=XenServer&requireshvm=false&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

...

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. management Management server and SSVM Agent machines should be in time sync for the verification to work. work 
3. on On the SSVM Agentagent, it first checks if the expires has crossed. 
4. it It computes hash on payload, expires and postURL using SHA1 and PSK and rejects the request if they do not match.
   
5. the 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

The PSK will also be used to encrypt and decrypt the payload data sent from the management server in the api response and received on the SSVM agent in the api request.

1. jasypt library with PBEWITHSHA1ANDDESEDE algorithm and the initial PSK will be used to encrypt and decrypt the payload data.
2. Management server, encrypts the payload data using the method in 1 . and returns the ecrypted string in the response
3. SSVM Agent, after receiving the payload, decrypts using the method in 1 and then does signature validation.

...