Bug Reference

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

A user should be able to create/update/delete SSL certs for his account.
Certificates can be searched by using either the certificate ID or the account ID.
Attach/Remove a certificate from a loadbalancers which support SSL offload feature.
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 SSL Certificates.
AWS API for assigning certificate to LB , Updating certificate for a LB and Unset certificate from LB, but does not work
StackOverflow thread for the unset SSL certificate issue in AWS.

Document History

Version	Author	Date	Changes
V1.0	Syed Ahmed	07-Oct-2013	Initial Draft
V1.1	Syed Ahmed	08-Oct-2013	Changing name & updating uploadSSLCert to include certificate chain

Functional requirements & non-requirements

Introduce a new entity SSLCerts linked to a user account
Users should be able to Add/Delete/List certificates linked to their account
Admin should be able to list all the certificates for all accounts
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
Users should be able to attach/remove their certificates to their loadbalancers.
Deleting a SSL certificate should also remove it from all the loadbalancers it is attached to. throw an error stating that it is already in use
If a user account gets deleted, the associated Certificates should also be deleted.
If a loadbalancer gets deleted, the associated binding should also be deleted.
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. ( Cert chain will be passed as an optional argument )
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.
The certificate is not checked for validity at cloudstack level. The device errors if the certificate is invalid ( Certificate validation happens at cloudstack )

Design

General Flow for assign/remove SSL certificate to a load balancer

when calling AssignToLoadBalancerRule if there is a certificate id in the request execute() method of the command calls
assignSslCertToLoadBalancer(lb_id, certId) in LoadBalancingRulesManagerImpl
assignSslCertToLoadBalancer checks if the loadbalancer is capable of SSL. If not error is returned.
verify if other certificate is bound to the loadbalancer and if it is, return error
It then verifies if the certificate is valid ( not revoked ) and creates an entry in the load_balancer_cert_map table
the loadbalncer state is set to Add
call the applyLoadBalancerConfig which calls applyLoadBalancerRules with the lbId
getLoadBalancerRuleToApply function should also add getSslCertificates(lbId) which gets called from applyLoadBalancerConfig
Now the rule has SSL certificate info as well.
When the rules get applied by calling applyLBRules of the NetscalerElement, the SSL info is passed inside the rule.
Netscaler should check for SslOffload Capability if the rule has certificate info.
NetscalerElement creates a LoadBalancerTO which transfers the params to the resouce layer.
The LoadBalancerTO should contain SslCertTO for holding certificate information.

New classes and fields

The SSL offload will be defined as a new Capability as SslOffload in Network.java static class Capability
NetscalerElement when checking for canHandleLbRules will check for SSL rule and respond accordingly
LoadBalancingRule will have a new static class LbSslCert and will have a list List<LbSslCert> for holding the certificate(s)

{{LoadBalancerTO}} will have a new parameter for passing certificate information and an array {{SslCertsTO\[\]}} for holding the certificates.

The loadbalancign rule will have a new subclass for SSL certs

// rule for SSL certificates
public class LoadBalancingRule {
 ....

  public static class LbSslCert()
  {
    String cert;
    String key;
    String password;
    boolean _revoke;

    public LbSslCert(cert,key,password) {}

  }

  public void setSslCerts(List<SslCert> certs){}
  public void getSslCerts(List<SslCert> certs){}
...
}

The transfer object should also be able to pass SSL certs

// TO for SSL certificates
public class LoadBalancerTO {
 ....
  public SslCertsTO[] sslCerts;

  public static class SslCertTO()
  {
    String cert;
    String key;
    String password;
    boolean _revoke;

    public LbSslCert(cert,key,password) {}

  }

...
}

New tables

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

Field name	Type	Allow nulls	Key	Default value
id	bigint(20) unsigned	No	Primary	Null
uuid	varchar(40)	Yes	Unique	Null
account_id	bigint(20)	No	Mul	Null
cert	varchar(255)	No	None	Null
chain	varchar(255)	Yes	None	Null
key	varchar(255)	No	None	Null
password	varchar(255)	Yes	None	Null
created	datatime	Yes	None	Null
revoke	tinyint(1)	No	None	0

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

Field name	Type	Allow nulls	Key	Default value
id	bigint(20) unsigned	No	Primary	Null
load_balancer_id	bigint(20)	No	Mul	Null
cert_id	bigint(20)	No	Mul	Null
revoke	tinyint(1)	No	None	0

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
chain: Optional : The certificate chain
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
chain : The certificate chain

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
chain : The certificate chain

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
chain : The certificate chain

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
chain : The certificate chain
account : Account associated with the certificate
lbruleid : The lb rule associated with the certificate