1.Video Overview #

Last updated on August 25, 2020

2.Overview #

KiloSSL will provide you with an image* of a server which is a web server and SSL certificate management system. Further on we will call it ACM (Automatic Certificate Management server).
You will be able to install the ACM quite easily inside your infrastructure and to point all your domains to the ACM, meaning the DNS record for your domains should point to the installed ACM server.
Afterwards all requests to your domains will reach the ACM which will proxy requests to the destination you specified as well as signing the response with the relevant certificate.
All the certificates will be automatically renewed until you will remove the domain.
You will be able to add domains via a simple interface or via API.
* As for now the image is only available as Amazon Machine Image (AMI)

Last updated on August 28, 2020

2.2.Install KiloSSL ACM #

As for now the KiloSSL image is available only as an AMI (Amazon Machine Image) however we are working hard to make it available on other popular platforms.

  1. Go to the Amazon Marketplace (from AWS Console go to EC2 service, press Launch instance button, choose “AWS Marketplace”, type “kilo” in the search)
  2. Order a machine using KiloSSL AMI
  3. Choose machine’s resources configuration. One of the last steps will be security group configuration. We advise to create a new security group with default values which are already set.
  4. After having the EC2 machine installed continue to the security settings section
Last updated on August 28, 2020

3.Perform Initial Configuration #

Last updated on August 28, 2020

3.1.ACM and your services machines security setting #

  1. After the EC2 instance is deployed and running it must obtain a static IP. If you will not perform this step your ACM machine will be getting a new IP every time it being reset. You will use this IP to point your domains/subdomains to this EC2 instance in the future.
  2. You should setup security group (Inbound and outbound rules set). You can see that after EC2 instance was created, it also created a Security Group with some default rules. In these default rules it allows ANY outgoing traffic to ANY IPv4 addresses (any IPv4 address is set by 0.0.0.0/0). Also default inbound rules allow incoming traffic from ANY IPv4 addresses to machine’s ports: 80, 22, 3000-3001,443.
    1. For Inbound rules, make port 3000 available ONLY for machines that will be generating the domains via API
    2. For Inbound rules, make port 3001 available only for machines that require an access to the web interface. Web interface might be required in the following cases:
      1. Initial set up
      2. ACM monitoring
      3. Manual domains creation

Example:
Let’s say you want the domains to be created automatically via API from several servers within your network, but you want to grant access to the admin panel only to your admins. And your current web server is hosted outside Amazon. So, the setup we recommend is following:

  1. Open ACM’s port 3000 for your network IP
  2. Open ACM’s port 3001 only for admins machines or some network only admins have access to.
  3. Open port 443 on your service server only for ACM machine.
  4. Then when you’ll be able to add the end point domains in the following manner: add endpointdomain1.com and point it to https://myservices.com/endpoint1 or https://endpoint1.myservices.com or http://:<your service’s IP>:<some port>
Last updated on August 25, 2020

3.2.ACM Initial Configuration #

When all the ports are opened as described previously you can browse the ACM’s admin panel at http://<ACM’s IP or domain>:3001 which you can enter with the default credentials:
login: admin password: admin

Update ACM service to the latest version: go to About page and if any updates available – run Update.

Afterwards you will be able to set the following settings:

  1. Admin credentials – here you will be able to edit admin panel login and password. Please notice that you will not be able to make any changes until updating the default password. While updating the default login is not mandatory, we strongly recommend changing it.
  2. LetsEncrypt settings – LetsEncrypt will notify you about different events like coming expiration of one of your certificates (in normal situation you shouldn’t be getting such notifications since KiloSSL will renew the certificate by itself but if you did receive such a notification you should contact [our support] (link to contact us form on KiloSSL website)) This field is mandatory to allow KiloSSL to produce SSL certificates automatically.
  3. Default destination – allows to set URL of the page to show in case when some domain already points to ACM machine, but this domain wasn’t added to the list of domains yet. 
  4. API key management – here you will be able to generate an API key to be used to authenticate while using KiloSSL API
  5. Default Nginx redirection settings – when adding a new domain to the ACM’s web server along with the target location where to redirect the request after validating the certificate KiloSSL will also add few settings to take effect during the redirection. You will be able to edit all the configurations in the default template (will take effect only on new domains being created) or specifically for each domain in My Domains page. Pay attention that the changes are saved directly to the Nginx config file and may affect the web server functioning so before making any change ensure you’re familiar with Nginx Configuration principals.
  6. CloudWatch settings – Along with the logs KiloSSL produces on the machine itself you have an option to duplicate the logs to your CloudWatch to view them there or even to attach monitoring system afterwards. Letsencrypt will be sending you error notifications to the provided email, even though we strongly recommend to enable this option since otherwise you won’t have any option to get notified about problems happened before generating or renewing the Certificate other than entering the machine itself and viewing the logs. Just create AWS user with permissions to write to Cloudwatch and attach credentials of this user here. Diving deeper, this created user should have at least these 5 permissions:
    1. CreateLogGroup
    2. PutLogEvents
    3. DescribeLogStreams
    4. PutRetentionPolicy
    5. CreateLogStream

Mandatory settings

You must set several settings on this page in order to be able to create and manage domains via UI or API. These settings are:

  1. Admin credentials (we block functionality if you didn’t change default password for security reasons)
  2. LetsEncrypt Settings – as they are needed for account creation in LetsEncrypt
  3. Default Destination – we force clients to set this setting as we want our Kilo SSL users to be aware about this option and in mostly all cases this should have some value
Last updated on August 28, 2020

4.Default Nginx Redirection Settings #

  • proxy_set_header X-Real-Host $host; – this will add X-Real-Host header which will contain the original host of the request since all the request will be redirected to your services via ACM server the host header will contain ACM’s info, so to know the original host of the request you’ll have to use the data from this header.
  • proxy_set_header X-Real-IP $remote_addr; – this will add X-Real-IP header which will contain the original IP of the request
  • proxy_set_header Referer $http_referer; – this will proxy initial referer header
  • proxy_buffering off; – this will disable buffering of responses from the proxied server (as buffering is enabled by default)
  • proxy_ssl_server_name on; – this will Enable passing of the server name through TLS Server Name Indication extension when establishing a connection with the proxied HTTPS server. (as this is disabled by default)
  • proxy_ssl_protocols TLSv1.1 TLSv1.2; – this will Enable the specified protocols for requests to a proxied HTTPS server. (proxy_ssl_protocols option uses “TLSv1 TLSv1.1 TLSv1.2” as default value)
  • proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; – NGINX provides a $proxy_add_x_forwarded_for variable to automatically append $remote_addr to any incoming X-Forwarded-For headers.
  • One extra setting will be added for every domain which is created with enabled HTTPS. This setting will force all incoming to http:// requests to be redirected to https://. This setting line will be: if ($scheme = http){ return 301 https://$host$request_uri; }
  • All other settings will be Nginx defaults
Last updated on August 28, 2020

5.Start Using #

When all the initial setup is done you can finally start using the KiloSSL. There are few major actions you’ll be able to perform with KiloSSL ACM:

  1. Add domain
  2. Edit Destination
  3. Remove domain
  4. Getting domains list
Last updated on August 28, 2020

5.1.Limitations #

  1. Each domain will have its own certificate (currently it is not possible to have multiple domains in certificate’s Subject Alternative Names field)
  2. If API will get several simultaneous requests to create/revoke certificate – it will process such requests one by one in a queue. As it takes several seconds to create each certificate in Letsencrypt, you will be able to create approximately about 10 certificates per minute.
  3. You can use only 1 API key. If you will create new API key – old API key will stop working immediately. API key is shown only once right after creation. If you will forget API key value – the only option is to create a new one.
  4. There is an option to update software directly from the site. But using update you can only install the latest existing version of the program. Currently you can’t install back one of the previous versions. On demand, you can contact support in order to get instruction about how to install one of the previous versions.
  5. There is no option to use staging Letsencrypt environment for test purposes. Check Letsencrypt limitations in order not to meet any rate limits. Here are the limitations which are more likely to be reached
    1. Only 50 certificates for specific domain can be created per week
    2. Revoking certificates for the domain does not reset rate limits for that domain
Last updated on August 25, 2020

5.2.Adding a Domain #

When you add new domain – there are 3 available options for managing SSL:

  1. create domain with HTTPS support. Before adding the domain to the ACM you must redirect its DNS settings to the ACM via A or CNAME records and while the domain is not redirected you’ll be receiving a Domain not attached (Code=1300) error from KiloSSL. Together with the domain an SSL certificate will be created for the domain and the domain will start being available via https (http requests will be redirected to https). The certificate will be renewed automatically 29 days before its expiration until you delete the domain from the server.
  2. create domain without HTTPS support (your domain will work only with HTTP, certificate won’t be created)
  3. create domain and import your own existing certificate (this option available currently only from UI). In order to use your own certificate, you should attach 2 files:
    1. The server certificate, which is a public entity. It is sent to every client that connects to the server
    2. The private key, which is a secure entity
    Under the hood  these 2 files will be integrated into nginx configuration like 

    ssl_certificate www.example.com.cert;
    ssl_certificate_key www.example.com.cert;

    Certificate for this domain will  be renewed automatically when it will be less than 29 days before expiration of imported certificate.

 You’ve 2 ways to add a domain:

Last updated on August 28, 2020

5.2.1.Adding a domain using Interface #

  1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
  2. Go to My Domains page in the ACM admin panel
  3. Press the Add Domain button
  4. You’ll be asked to provide following information:
    1. Domain you want to add without http or https prefixes (please notice that you won’t be able to change it after the creation)
    2. If HTTPS should be enabled (turned ON by default). When this option is active, you are able to see another setting allowing import of an existing certificate
    3. URL of your service you want the ACM to redirect the request arriving for this domain. It can be http/https, URL containing domain or IP address. Note: If your service is behind https, ACM will ignore any SSL errors (for example if your service uses obsolete or self-signed certificate)
    4. Also, you’ve an option to change the Nginx redirection settings
Last updated on August 28, 2020

5.2.2.Adding a domain using an API #

Check Add Domain API method specification

Last updated on August 25, 2020

5.3.Editing a Domain #

After domain is created on the ACM you have a possibility to change it’s targeting URL or/and it’s Nginx redirection settings, both via interface and via API.

 

If this domain was set previously to work over HTTP only (without a certificate), you will be able to

  1. enable HTTPS for this domain automatically. This will create new certificate on the server by issuing new certificate from LetsEncrypt
  2. enable HTTPS by importing your own existing SSL certificate
Last updated on August 28, 2020

5.3.1.Editing a Domain using Interface #

  1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
  2. Go to My Domains page in the ACM admin panel
  3. Press the Edit icon near the Domain you want to change
  4. You be able to update following information:
    1. URL of your service you want the ACM to redirect the request arriving for this domain.
    2. Also, you’ve an option to change the Nginx redirection settings
Last updated on August 28, 2020

5.3.2.Editing a Domain using API #

Check Update Domain API method specification

Last updated on August 25, 2020

5.4.Deleting a Domain #

Deleting a domain will also cause removal of its SSL certificate and as well as its periodical renewal. You can delete a domain using interface or an API.

Last updated on August 25, 2020

5.4.1.Deleting a Domain using Interface #

  1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
  2. Go to My Domains page in the ACM admin panel
  3. Press the Delete icon near the Domain you want to change
Last updated on August 28, 2020

5.4.2.Deleting a Domain using API #

Check Delete Domain API method specification

Last updated on August 25, 2020

5.5.Getting Domains List #

You will be able to view a list of all your domains and get the following information for them:

  1. Domain name
  2. Current certificate creation date
  3. Current certificate expiration date
Last updated on August 25, 2020

5.5.1.View domains list using interface #

  1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
  2. Go to My Domains page in the ACM admin panel
Last updated on August 28, 2020

5.5.2.View domains list using API #

Check Get Domains API method specification

Last updated on August 25, 2020

6.API Error Codes #

Http Code Error Code Message
403 403 Forbidden
404 404 Action not found
500 500 Unspecified error occurred
400 1000 Certbot already running
400 1100 Parameter must have a value
400 1101 Parameter value is invalid
400 1102 Action not available for default password
400 1103 Letsencrypt email is not set
400 1200 Domain not found
400 1201 Domain already exists
400 1300 Domain not attached
400 1301 Can’t create certificate as nginx machine already has this certificate
400 1302 Couldn’t find certificate file after certbot created certificate
400 1303 Couldn’t find certificate file
400 1304 Invalid Nginx configuration
Last updated on August 28, 2020