This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

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