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

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. throw an error stating that it is already in use
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

Assumptions

• 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 loadbalancer 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 resource 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)

load_balancer_cert_map(id, load_balancer_id, certitficate_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:

• certificate : Required : The public certificate, should also include the trust chain if required
• privatekey : 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
• account: Optional : The account to associate with the cert
• domainid: Optional : The domain to associate with the cert
• projectid: Optional : The project to associate with the cert

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
• domainid : The domain id associated with the cert
• domain : The domain name associated with the cert
  -- either --
• account : The account associated with the cert
  -- or --
• projectid : The project id associated with the cert
• project : The project name associated with the cert

http://10.x.x.x:8080/client/api?command=uploadSslCert&certificate=-----BEGIN+CERTIFICATE-----<certificate>-----END+CERTIFICATE-----&privatekey=-----BEGIN+RSA+PRIVATE+KEY----<privatekey>-----END+RSA+PRIVATE+KEY-----

Note : The certificate,key and chain should be UTF-encoded in the URL.

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

http://10.x.x.x:8080/client/api?command=deleteSslCert&id=7

listSSLCerts

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 : The account associated with the certificate
• lbruleid : The lb rule associated with the certificate
• projectid : The project associated with the certificate

http://10.x.x.x:8080/client/api?command=listSslCerts&accountid=2

New Apis  to add SSL cets to LBs

For associating the certificates to loadbalancing rules, we need to have the following APIs

assignCertToLoadBalancer

Request parametes:

• certid: Required : The id of the certificate to assign to this rule.
• lb_id:Required : The lb rule to assign the cert to

http://10.x.x.x:8080/client/api?command=assignCertToLoadBalancer&certid=138ad12e-a486-44e3-bb02-7a55d0813174&lbruleid=47

removeCertFromLoadBalancer

Request parameter to be added:

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

http://10.x.x.x:8080/client/api?command=removeCertFromLoadBalancer&lbruleid=47

UI flow

The certificates can be accessed as a tab on the Accounts page.

Add Certificate

List Certificates

Certificate details

Note: I cannot get the certificate to display as a block.

The actual certificate looks like this

-----BEGIN CERTIFICATE-----
MIIDBjCCAe4CCQCEkqahWR0hjjANBgkqhkiG9w0BAQUFADBFMQswCQYDVQQGEwJB
VTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50ZXJuZXQgV2lkZ2l0
cyBQdHkgTHRkMB4XDTEzMTAyMTEzNTIyMFoXDTE0MTAyMTEzNTIyMFowRTELMAkG
A1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoMGEludGVybmV0
IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
AN6wEhbwZgBfgh5+fE1OYm9B7jA+IMbraIY80IyV2ERbNXJoi2/XrDtAr5NAxWkL
qpaccOA4XupMUWzUCpDxa9M7L/QfCP6PFEJnJZ2dCPvosZQKuFcj+h9LHsK5nVW6
1Zkh9HhtbdIS6l1JsV/119ZJGxzoGUEJPdEnsNt1cE1cW8sKvMo5GC2toZQV4d96
17IpMuyRYhdEyRNq+sDQetAUDHYthBK7QVDy/9Sw+/lbgf2OsWacIrysDCF3hXc0
qyNoBgp/s39NZDXx49GKwNmx9IuRV+P/WEqXfDxSDmHP4APtzDTtMTFnIW8+gH4z
0GkeLRi7EQY48LyyGcB88lkCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEAlgx04bvU
/EE5z7lJsYmUM2oi8FjqZcZkD4F1ku7zvdAXaDNhOHjrR5LxGL+iI/N9S8lKVeSV
xZv+EXAT0NqkTidNFjvP7coctDrrM+JHSNTRlr2GnnYjCnjEph4+ZXNppx8vnhXe
7jDnHoXL/C5GIPOm0+LQaH1AlGTPF0lnBrtQaz1UG34vCr8SSUtRbTDDxH/liXfc
hfvVnf4OV5Duj0oUXsmB3YzITYZnZ/xvZ4Dw6rOU/U5Vetng+msOOt8momeTCnWB
/d1clA7rulJTCNZXb0YyaUNaC6eQX7S9JHnluB67b9yp4yg8f00qz4xR165eTQmq
mLiuE/U5fTODvA==
-----END CERTIFICATE-----

Assign Certificate to Rule

Assigned View

IP Clearance

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