Skip to end of metadata
Go to start of metadata

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

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

V1.2Will Stevens22-Sep-2014Added support for Projects as well as allowing an admin to assign certs to one of their users accounts

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

LoadBalancingRule.java
// 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

LoadBalancerTO.java
// 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

certificate

text

No

None

Null

chain

text

Yes

None

Null

key

text

No

None

Null

password

varchar(255)

Yes

None

Null

domain_id

 bigint(20) unsigned

No

Mul

Null


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

Field name

Type

Allow nulls

Key

Default value

id

bigint(20) unsigned

No

Primary

Null

uuidvarchar(40)YesNoneNull

load_balancer_id

bigint(20)

No

Mul

Null

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

  • 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

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

  • No labels