Bug Reference

CLOUDSTACK-4821

Introduction

SSL Offloading feature allows loadbalancers to handle encryption/decryption of HTTP(s) traffic giving plaintext HTTP to the backend servers freeing them from the resource intensive task of handling encryption/decryption. Major loadblancers like the Netscaler and F5 have this functionality. This document is a functional sepc for adding certificate mangaement and implementing SSL offload capability for cloudstack provisioned loadbalancers.

Goals

1. A user should be able to create/update/delete SSL certs for his account.
2. Certificates can be searched by using either the certificate ID or the account ID.
3. Attach/Remove a certificate from a loadbalancers which support SSL offload feature.
4. Add support for Netscaler to use this feature.

References

• http://support.citrix.com/proddocs/topic/netscaler/ns-ssl-wrapper-con-92.html
• AWS API for Upload, Delete, List, Update

Document History

Functional requirements & non-requirements

1. Introduce a new entity SSLCerts linked to a user account
2. Users should be able to Add/Delete/List certificates linked to their account
3. Admin should be able to list all the certificates for all accounts
4. When creating a loadbalancer if the public port is 443 and the private port is 80, then
   • If the loadbalancer device supports SSL offloading,
     • The loadbalncer created should be of type SSL.
     • Should allow attach/remove of a SSL certificate to it.
   • If the loadbalancer device does not support ssl offload,
     • The loadbalancer type will be TCP.
     • Trying to attach a certificate to it should generate an error
5. Users should be able to attach/remove their certificates to their loadbalancers.
6. Deleting a SSL certificate should also remove it from all the loadbalancers it is attached to.
7. If a user account gets deleted, the associated Certificates should also be deleted.
8. If a loadbalancer gets deleted, the associated binding should also be deleted.
9. The private key and password for the key should be stored encrypted

Architecture and Design description

Assumtions

• The SSL certificates should include the chain trust with them. They are added to the device as-is.
• For the netscaler loadbalancer, we assume that the port 22 is open and there is space in /nsconfig as we scp the certificate to the device.
• A loadbalancer rule can have only one certificate attached to it. A certificate however can be attached to multiple loadbalancers ( As long they are SSL type ). Support for multiple certificates for a single loadbalancer is not scoped.

Design

AssignToLoadBalancerRuleCmd Flow

• execute() method of the command calls {{assignToLoadBalancer(lb_id, vmIds, certId) }}

• The SSL offload will be defined as a Capability in LbSchemes as SSL
• NetscalerElement when checking for canHandleLbRules will check for SSL rule and respond accordingly
• LoadBalancerTO will have a new parameter for passing certificate information.
  LbSslCert.java

  // Transfer object for SSL certificates
  public class LbSslCert()
  {
      String cert;
      String key;
      String password;
  }
  

New tables

ssl_certs(id, uuid, account_id, cert, key, password)

load_balancer_cert_map(id, load_balancer_id, cert_id, revoke, state)

New Webservice APIs for Certificate Management

This section lists the new webservice APIs for Certificate management. They are derived from their AWS Equivalant ( UploadServerCertificate, ListServerCertificates, GetServerCertificate, DeleteServerCertificate )

uploadSSLCert

Uploads a new SSL certificate-key pair

Request parameters:

• cert : Required : The public certificate, should also include the trust chain if required
• key : Required : The private key for the certificate, if the key is encrypted, password should be provided
• password: Optional : The password for the private key

Response parameters:

• id : The ID of the certificate
• account : The account of the SSL certificate
• cert : public certificate
• key : private key

deleteSSLCert

Deletes an existing SSL cert from cloudstack.

Request parameters:

• id : Required : The id of the certificate

Response parameters:

• displaytext : any text associated with the success or failure
• success : true if operation is executed successfully

updateSSLCert

updates an existing certificate-key pair

Request parameters:

• id : Required: The id of the certificate
• cert : Optional : The public certificate, should also include the trust chain if required
• key : Optional : The private key for the certificate, if the key is encrypted, password should be provided
• password: Optional : The password for the private key

Response parameters:

• id : The id of the certificate
• cert : The public certificate, should also include the trust chain if required
• key : The private key for the certificate, if the key is encrypted, password should be provided

listSSLCerts

lists the certificates for an Id or an account

Request parameters:

• id : Optional : The id of the certificate
• accountid : Optional : The account id for which the certs are to be listed
• lbruleid : Optional : The load balancer rule to list the certificate for

Response parameters:

The response is a list of following

• id : The id of the certificate
• cert : The public certificate, should also include the trust chain if required
• key : The private key for the certificate, if the key is encrypted, password should be provided
• account : Account associated with the certificate
• lbruleid : The lb rule associated with the certificate

New parameters to loadbalancing APIs

For associating the certificates to loadbalancing rules, we need to add the certificate id parameter to following loadbalancer apis.

assignToLoadBalancerRule

Request parameter to be added:

• certificateid: Optional : The id of the certificate to assign to this rule.

removeFromLoadBalancerRule

Request parameter to be added:

• certificateid: Optional : The id of the certificate to remove from this rule.

UI flow

Right now, this feature will only be available via the API. UI support is not yet scoped.

IP Clearance

No external dependecies are being added for this feature. All code will be developed within Cloudstack’s scope.