Thursday, October 28, 2021

Enrolling chromeOS Devices against EJBCA

 Introduction

chromeOS is an operating system based on Chromium (with Google Chrome as its primary UI) which is the default operating system on devices such as ChromeBooks, ChromeBoxes, ChromeBases and similar devices. In order to allow these devices to access the network, ensure internal network security and other PKI use cases, chromeOS can be easily set up to automatically enroll for certificates from EJBCA over the SCEP protocol. 

This scenario requires three parties: 

The Google Cloud Certificate Connector is a service installed on a third device which acts as an enrollment and administration portal for the enrolling chromeOS devices. 

EJBCA Configuration

As a part of this tutorial, it's assumed that you've already installed EJBCA and configured a CA you would like to enroll against. 

Certificate Profile

The pertinent fields in the Certificate Profile to set are as follows:
  • Authority Key Id: Use
  • Subject Key Id: Use
  • Key Usages: Digital Signature
  • Extended Key Usages: Client Authentication

End Entity Profile

The following values are expected to be available in the end entity profile:

Subject DN Fields

  • Common Name (CN)
  • Organizational Unit (OU)
  • Organization (O)
  • Country (C)




Subject Alt Names 

  • RFC 822 Name
  • DNS Name
  • IP Adress
  • MS User Principal Name


SCEP Alias

Lastly, the SCEP alias has been set up as follows:



Google Cloud Certificate Connector

Installation

The Google Cloud Certificate Connector is downloaded when first setting up your Google Cloud account, as documented here. The Connector needs to be installed on a Microsoft Windows Server.

To do so, perform the following steps:
  1. Create an Active Directory service account user which will run the Google Cloud certificate connector. This account must have a static password.
  2. Connect to the Google Admin Console with an administrator account
  3. Under Devices → Networks, select Secure SCEP connector
  4. The download connector page will give you access to:
    1. The Connector Executable
    2. The connector configuration JSON file (config.json)
    3. The service account credentials JSON file (key.json)


  5. Copy all the files downloaded to the server hosting the Google Cloud certificate connector
  6. Run the installer as an Administrator






  7. Provide the AD service account user

    Note: The connector cannot be installed with a non domain account

  8. Install the connector


Configuration

  1. Put the connector configuration JSON file (config.json) and the service account credentials JSON file (key.json) in the Google Cloud certificate connector folder (Default location is: C:\Program Files\Google Cloud Certificate Connector).
  2. For the SSL handshake between the Google Cloud Certificate Connector and EJBCA to properly work, EJBCA's Management CA certificate needs to be added to the CA store of the Google Cloud certificate connector:
    1. Locate the CA store of the Google Cloud certificate connector (default location is: C:\Program Files\Google Cloud Certificate Connector\rt\lib\security\cacerts)
    2. Either install a Java SDK on the Google Cloud certificate connector server or copy the cacerts file to a computer where a Java SDK is installed
    3. Add the Management CA certificate using keytool:

      keytool.exe -import -keystore ./cacerts -trustcacerts -file <ManagementCA.pem> -storepass changeit



    4. Copy the cacerts file back to the Google Cloud certificate connector server (default location: C:\Program Files\Google Cloud Certificate Connector\rt\lib\security) if keytool wasn’t run on the server itself.
  3. Start the Google Cloud Certificate Connector service.
  4. Check that everything is properly started in the event viewer:
    1. The Google Cloud Certificate Connector should be able to parse its configuration:


    2. Initialize the service


    3. Every 30 second the service will check against the Google backend if there are any requests to process


Adding your own CA to Google Cloud

  1. Connect to the Google admin console with an administrator account
  2. Under Devices → Networks → Certificates, select Add certificate. This should be done the root of the Google domain or for Chromebooks root OU


  3. Provide a name for the CA, or otherwise the common name of the issuer will be used), then upload the CA certificate in PEM format and choose to deploy on Chromebooks


SCEP Profile Configuration

  1. Connect to the Google admin console with an administrator account.
  2. Under Devices → Networks → Secure SCEP connector, select Add secure SCEP profile. This can be done at the root domain level, at Chromebooks root OU in case of device certificates or Users root OU in case of user certificates.


  3. Set a profile name, subject and the key size. The following example is focused on issuing device certificates, but can easily be adapted for user certificates:

    CSR subject fields are defined in the SCEP profile. Placeholder variables can be used in order to customize the CSR to the need. Available placeholder variables are defined in this article.

  4. If needed, Subject Alternative Names (SANs) can also be added:


  5. Configure:
    1. The SCEP server URL, which should look something like https://<hostname>:<port>/ejbca/publicweb/apply/scep/<alias>/pkiclient.exe
    2. the certificate characteristics
    3. the static challenge (pass-phrase) used to authenticate the request coming from the Google Cloud certificate connector on the SCEP server and the corresponding certificate authority.


  6. Configure how this template should be applied on ChromeBooks, per user or per device:


Testing

  1. Connect to a user session on the ChromeBook.
  2. Ensure that the device/user gets the policies to create the certificate request in chrome://policy (RequiredClientCertificateForDevice for a device certificate and RequiredClientCertificateForUser for a user certificate)
  3. Under chrome://certificate-manager, follow the certificate creation process.
  4. On the Google Cloud certificate connector event viewer, look for the following events:
    1. Processed Requests


    2. Google Cloud Certificate Connector submitting the SCEP request to EJBCA and receiving a certificate


    3. ACK message between the Connector and the Google backend, pushing certificate to the Chromebook


  5. Check that the certificate has been properly added to the Chromebook under chrome://certificate-manager
  6. In the case of a device certificate, this process is also triggered just after a device enrollment


Tuesday, January 26, 2021

Performance! How to use EJBCA as a Massive PKI!

Are  your CRLs are scaling out of proportion, clients are complaining about timeouts and your VA is on its knees? Are your certificates counted not by thousands but by the millions? Never to fear, EJBCA is designed to handle some of the world's biggest PKI, so read on to find out how!

What can you do about your Architecture?

A large part of scaling up is adapting the architecture of your PKI to meet the requirements. Before we move on, here are two basic design choices that are the key to every large scale PKI.

Clustering and Load Balancing

The first step to being able to handle more issuances and traffic is by clustering: splitting the load between several instances of EJBCA working in concert. This has the added bonus of adding a layer of reliability to your PKI, a cluster can always survive one or more of its nodes failing. EJBCA has been designed to allow for hot-upgrading, meaning that your PKI is still active and running while the nodes in your cluster are running different versions of EJBCA, with zero downtime as a result. 


Likewise, clustering can be performed on VAs or RAs to easen to load on your PKI, depending on where your PKI is having performance issues:

  • If you're experiencing long response times or timeouts in your VA infrastructure, then either the VA's HSM or the database are overloaded by queries - this can simply be solved by adding more VAs, but also by clustering the VA instances. 
  • If you're issuing/revoking certificates in large volumes, clustering the CAs will allow more nodes to do the work of revoking and publishing. Each revocation sent out to the VA's is just a single write per cluster.
Essential if your have multiple VAs/VA clusters is to place them behind a Load Balancer in order to balance the load on each VA. 

Database Sharding

For databases of extreme volumes, it may be desirable to shard the database over several database instances in order to save space.  By setting the following value to true in database.properties:

database.useSeparateCertificateTable = true

the certificate body will be stored in the table Base64CertificateData instead of CertificateData


Base64CertificateData can then be sharded and placed on a different database volume. 

CRL Partitioning

If your population of unexpired certificates is large and you rely on CRLs, you might start finding that CRL generation times are beginning to spin out of control, and that CRL sizes becomes unmanageable. EJBCA supports CRL partitioning in accordance with RFC 5280, allowing certificates to be assigned to a specific CRL shard. 

CRL partitioning means that instead of a single CRL, the CRL is split into several shards. As the shards grow themselves in size, EJBCA allows you to suspend shards, automatically creating new ones. 

Service Pinning

In a clustered EJBCA instance, service execution happens at semi-random, the service being run by the first node to activate within the granted service interval. If some services - for example generating CRLs - are taking an inordinate amount of time, you may be experiencing latency in the cluster node executing the service, leading to intermittent delays being experienced while the service is running. The easiest solution is to pin the service to a single node and remove that node from the load balancer's roster, meaning that all service executions will happen on that node only, while enrollment, issuance and revocation operations are processed on the remaining node. 





Ephemeral Certificates

EJBCA can be configured to function as an Ephemeral Certificate CA. In this mode EJBCA simply functions as a high speed certificate factory, issuing certificates but not storing any trace of them in the local database.

While the mode still allows for revocation of certificates, it does not allow for certificates to be searched for in the database or for any constraints based on existing certificates to be enforced.

Precompiled OCSP Responses

Each OCSP reply requires an individual signature by the crypto token on the VA. While generated responses are cached by the EJBCA VA,  validity times of OCSP replies are commonly short (< one day) and caches are not shared between nodes in a cluster, thus responses still need to be generated anew frequently. The traditional solution to this has been OCSP Stapling, caching the first reply encountered in the http proxy. While this may solve the problem to some extent, it moves the burden of administration of caching the replies over to you.

Instead, EJBCA offers Precompiled OCSP Responses. Colloquially known as Canned OCSP, this functionality allows a VA to generate the full set of expected OCSP responses on a regular schedule within a set timeframe, when there are expected lulls in traffic. For any PKI, this will dramatically decrease the latency of the VA infrastructure.


Tuesday, December 22, 2020

A laymans guide to EJBCA compliance tools

Compliance Overview

Standards and other specifications that you may be required to show compliance with are usually large with many options. Many times these options are also described vaguely requiring some level of interpretation. Interpretations usually get to a point of common understanding between different stakeholders after some period of time. Adding insult to the injury is that interpretations and specifications also change over time. In addition, many standards are large and contain many parts that are irrelevant for most use cases, so implementing a standard to the letter is not cost efficient neither for the implementor nor for the user. 

All this considered, compliance is not a trivial concept.

Related specifically to PKI, a very small pick of some specifications that you may be asked to be compliant with includes RFC5280, RFC4210, RFC4211, RFC7030, RFC8555, RFC6010, RFC6960, RFC3739, CA/B Forum BR 1.7.3, EV SSL Certificate Guidelines 1.7.4, EV Code Signing Guidelines v. 1.4, 3GPP 33.310, EN 319 401, EN 319 411, EN 319 412, ETSI TS 119 495, ICAO 9303, PCI-DSS, NIST SP 800-73, FIPS 201-2, FPKIPA, ETSI TS 103 097, IEEE 1609.2, just to name a few.

It is safe to say that any type of compliance requires a fair amount of knowledge about a lot of details.

Implementation or Operation

A question that comes up is who manages compliance. Is it the implementor of a product or the organization operating the product delivering a service? In reality it is usually somewhere in between. Products should implement capabilities of configuring them, by the operator, to be compliant. Due to the number of standards, each requires different configurations and a configuration compliant with one specification may be non-compliant with another specification, here it is up to the operator to keep track of configuration.

Compliance over Time

Compliance with various standards is most of the time possible to demonstrate at a specific point in time, still considering that you don't fully implement many standards. But compliance is hard to keep up in the long run as specifications evolve constantly, interpretations change in various forums (some closed and some open). Just considering the sheer number of specifications to be compliant with, and the number of forums where these are handled in practice makes it impossible for the people actually implementing the standards to keep track of everything that is going on.

Compliance is continuous work, it is not a one-time effort.

Falling out of Compliance

How does it happen that an organization, being compliant once, becomes non-compliant? There are a number of reasons this can happen, including but not limited to:

  • Compliance specification updates

  • Specification re-interpretation in the governing forum

  • Discovery of previously non-discovered compliance details

  • Accidental re-configuration of the system

  • Deliberate re-configuration of the system to achieve one compliance, breaking another

  • Software bugs

As understood by now, maintaining compliance requires continuous work and tools to monitor the system and compliance, as well as to track changes and ensure it's done in a controlled and repeatable way.

Do I need Compliance?

This question has to be answered by yourself of course. There are basic things you absolutely want to be compliant with, such as RFC5280, if you want to be interoperable with various client software. There are other things that may become more of a burden, say a WebTrust or eIDAS audit if you do not have any external driving force for these. The reasons for compliance with the range of standards (a few listed above can be ranging depending on your use case:

  • As wide interoperability as possible
  • Industry-specific standards
  • Regulations
  • External or internal security requirements
  • Generic trust posture (also internal or external)

You typically don't want compliance requirements that force you to do things that drive cost without making sense for your specific use case.

One Time vs Continuous Monitoring

One time, and regularly occurring, compliance monitoring plays an important role. When implementing a new system, or a new requirement, it is normal to manually verify compliance. During regular audits this is also verified. During these verifications personnel with the needed skills analyze systems and output, creating appropriate configuration, controls and processes.

During operation of the system you can deploy tools, that continuously validate the compliance achieved in the above step, ensuring that things don't start to break unexpectedly.

Any serious compliance work should involve both the regularly occurring (one time) compliance audits and continuous monitoring.

EJBCA Compliance Assisting Tools

EJBCA comes with a large set of tools that can help you manage compliance over a long time, as well as monitor for unexpected changes, keep track of changes and perform changes in a repeatable way. Using these tools, tailored for your specific needs, can help lower the risk of falling out of compliance.

These tools are numerous and it can be hard to keep track of all of them. This blog post outlines the most important ones, as of the writing date. New tools are continuously developed, and new documentation added, so be sure to check the product documentation and release notes when new versions of EJBCA are released.

Also note that different tools are more or less easily available on different platforms. For example using an Appliance or Cloud installation with limited access to the command line limit available options to run local scripts and similar.

Validation and Compliance features

This is a list of different features in EJBCA that are useful for compliance work. It is not possible to say which you should use for specific deployments and which not, as each environment is unique. 

The list starts with basic configuration, and ends up with more specific tools.

Naturally this list is a snapshot in time when this blog is posted, and also does not describe all possible features in EJBCA, but a subset.

Certificate Profiles

In certificate profiles you configure the basic technical contents of certificates. It specifies the certificate contents, in detail. What type of keys they can contain, what certificate extensions (such as key usage) should be present, and what can be overridden by the caller (RA or user). This is the static content of a type of certificate.

See Certificate Profiles Overview in the EJBCA documentation.

Important compliance fields are:

End entity profiles

The end entity profile defines the dynamic, or user-specific fields, of a certificate along with some meta data.

See End Entity Profiles Overview in the EJBCA documentation.

The most important fields are the Subject DN fields. Subject DN fields define, unless DN Override is allowed in the certificate profile, which subject DN fields must be present and which may be present. Other DN attributes that are not enabled in the end entity profile is not allowed.

You can also enable validation of requested DN fields, by configuring the Validation field which is present for every configured DN field. This enables regexp validation of fields, for example size and other format restrictions.

Validators

Validators are functions that can be used to validate various aspects of a request. It is possible to use both built-in validators and external scripts.

The built-in validators are:

  • RSA and EC Key Validators. Validates that public keys fulfill CA/B Forum Guidelines, including FIPS 186-4 and NIST (SP 800-89 and NIST SP 56A: Revision 2) requirements, and is not a ROCA (CVE-2017-15361) weak key.

  • Public Key Blocklist Validators: Validates that the public key not on one of the blocklists, uploaded by an administrator. Most commonly used to check that the key is not one of the old Debian weak keys.

  • Domain Blocklist Validator. Validates domain names to issue certificates for (as subject alternative DNSName's) against a administrator defined blocklist, i.e. domains forbidden to issue for.

  • CAA Validator. Validates domain names to issue certificates for (as subject alternative DNSName's) according to RFC 8659.

  • Google Safe Browsing Validator. Validates domain names to issue certificates for (as subject alternative DNSName's) against Google Safe Browsing database, i.e. that it is not a known phishing or malware spreading site.

In addition to the built-in validators you can also call external scripts with the External Command Certificate Validator. For example using a tool such as Zlint to check the certificate against CA/B Forum requirements, or the eIDAS Inspector to check against eIDAS requirements.

Validation can be performed in various stages of issuance, before or after the actual certificate has been created and signed. Check the documentation for the details.

Audit logging

Of course you can not talk about compliance without mentioning audit logging. Audit logs can be produced on file, shipped to syslog, and stored in the database. Audit logging is there to give a trace of every security related event in the PKI system. This is not the same as everything that happens, and an audit log is separate from a complete event log. For example, events that cause a change (such as issuing a certificate or editing a profile) are audit logged, while events that do not change anything (such as reading revocation status to send an OCSP response) are not logged because nothing was changed. At the same time, non-changing events such as granting access, or receiving a certificate request are also logged. It's not black and white, but it is documented.

For the compliance and monitoring topic you will always be able to see in the audit log if a profile was changed. You will be able to see who, when and what changed. You can of course have triggers in your monitoring system on these events so no profile changes can happen undetected.

Validation/Conformance tool

In addition to other validation tools, there is also a separate Validation/Conformance tool shipped with EJBCA. The special feature about this tool is that it is a standalone tool that compares issued certificates (and OCSP responses) to a template that you create. Once you have a certificate the looks exactly the way you want it, you can compare the issued certificate with that to get an alarm if they suddenly stop matching. This is useful to detect configuration changes that cause some unexpected change to the output.

It can also validate only a sampling, say every 100th, issued certificate or OCSP response, making it suitable for high performance deployments where you can't afford the validation latency in every certificate.

ConfigDump

 A tool designed to make repeatable installation and configuration simple is ConfigDump. ConfigDump enables you to export configuration, of almost everything, as human-readable, and machine parsable YAML. You can use the exported YAML files for multiple purposes, including but not limited to:

  • Creating and testing profiles and other configuration on a test system before moving it to production, where it can be imported.

  • Version control of configuration, tracking configuration in a VCS such as Git.

  • Configuration monitoring, exporting configuration nightly and comparing it to a defined version in the VCS.

These are just some possible usages of ConfigDump, making it a great tool for compliance configuration and monitoring.

Configuration checker

For Administrators using the CA UI of EJBCA the experimental Configuration Checker, gives an immediate overview and warnings about some common misconfigurations that we have noticed out there.

Publishers

Publishers, while being used for the Validation/Conformance tool, can also be used for any custom validation that you may imagine, including sending certificates to your personal archive, an S3 bucket, or similar ideas.

Thursday, October 1, 2020

Supporting EdDSA - The Details

About EdDSA

EdDSA is a fairly new signature algorithm, at least if we compare to the classic algorithms we use, where RSA was introduced in 1977 and ECDSA entering wide use in the early 2000's. In contrast EdDSA was published in 2011. EdDSA is meant to be simple, elegant, and well defined, so it is hard to make security catastrophic mistakes upon use, something that is rather easy to do with the classic algorithms. EdDSA, with regards to digital signatures, consist of two distinct variants, Ed25519 and Ed448, with different key lengths. The usage of EdDSA, as relevant for us, has been standardized in RFC8032, RFC8410 and RFC8419.

EdDSA in EJBCA

Albeit not very widely used, we have been asked on occasions for support of EdDSA in EJBCA, commonly in IoT related use cases. Due to these requests we added software support for Ed25519 and Ed448 in EJBCA 7.4.0 in June 2020. As EJBCA is used in high security PKIs, Hardware Security Modules are typically used, and we have recently tested support for EdDSA in HSMs. 

This post describes the details of what is involved in supporting this new signature algorithm, in software and in hardware. The final result can be seen in the EJBCA documentation.

A note of caution: implementing cryptography is not for everyone, and we could not have done it without the help of our friends from Bouncy Castle, who helped us with the hard core details, and even gave us an introductory training session on the specific topic of EdDSA. Bouncy Castle support contracts are available though Crypto Workshop.

Software Support

The first step when supporting a new algorithm for PKI usage, in Java, is to get all the ASN.1 and Java crypto stuff in place. Without that, there is no going forward. This includes at least, but not exclusively the following parts:

  • ASN.1 Object identifiers
  • Public and Private key classes
  • Reading and writing (encoding and decoding) said public and private keys
  • SubjectPublicKeyInfo ASN.1 structures for properly encoding public keys in certificates and CSRs
  • Signatures themselves, on at least certificates, CRLs, CSRs, OCSP responses and CMS messages
  • Conversion between names (for example Ed25519) and OIDs (1.3.101.112)

A specific trick worth mentioning, that we stumbled upon, is that there are two versions of encoding/decoding format of EdDSA. A version 1 and a version 2, where different software implementation, for example OpenSSL, produces the v1 format, while others produce the (newer) v2 format. Needless to say, we needed to handle both.

For EJBCA, we are lucky to use the Bouncy Castle crypto APIs, which are commonly among the first to implement anything new. As Bouncy Castle had support for all the relevant RFCs EJBCA could start adding the application layer support right away. There were a few additions needed on the way, mostly related to various corner cases or handling encoding/decoding of keys and PKCS#12 files from different sources, that needed minor additional features in Bouncy Castle. As always, they were fast to add the needed tricks in the crypto API.

Usability

Apart from the core crypto pieces, EJBCA also implement a bunch of usability features making it easy(!) for users to use PKI with various algorithms. With EdDSA being so simple, both the keys and signature algorithm is referred to Ed25519 and Ed448, it still needed some extra code to fit into the overall structure. For the classic algorithms there are countless combinations, for example an RSA 2048 bit key can be used with all RSA signature algorithms:

  • SHA256WithRSA
  • SHA384WithRSA
  • SHA512WithRSA
  • SHA256WithRSAandMGF1
  • ...

Just to name a few. And the same goes for ECDSA, but with even more combinations are there are numerous different EC curves to choose from. All in all there are hundreds of combinations that can be used in EJBCA, and we try to make it easier by or example limiting the available signature algorithms based on the selected key type. So albeit EdDSA having limited number of combinations, some if's and but's in the code is still needed for it to fit in the overall usability framework.


Another trick we play is that a suitable key encryption algorithm is selected, for Key Recovery, based on the signature algorithm used, typically this means selecting an RSA based algorithm, and we have a method for this, where EdDSA had to be added as well.

Adding HSM Support

We, and most of the world, use HSMs through the standard PKCS#11 API. In the until recently latest version of PKCS#11, version 2.40, there was no standardized support for EdDSA. As there was still a requirement from some users for EdDSA, the inevitable result was that some HSM vendors supported EdDSA using what is called Vendor Defined Mechanisms. This is of course a nightmare for product implementors, as specific support has be be built for HSMs from different vendors. PKCS#11 version 3 however, which was released only this year, introduced standardized support for EdDSA.

Now HSM vendors have moved to use the standardized way of supporting EdDSA, which means it's a good time for us to look at supporting HSMs for this algorithm.

Having recently introduced the P11-NG Crypto Token in EJBCA Enterprise, we have low level control of PKCS#11, as used by EJBCA, which was needed in order to support this new feature, P11v3 feature in a P11v2.40 library. In addition, SoftHSMv2 has support for EdDSA, making it easy to develop without access to a real hardware security module.

The last trickery showed up when generating keys and reading them from the HSM. According to the PKCS#11v3 specification the EdDSA public key is generated using the mechanism CKM_EC_EDWARDS_KEY_PAIR_GEN with the same parameters as a normal ECDSA key, which means that a CKA_EC_PARAMS is used in the public key template, with the OID of the curve as parameter, in this case the OID of Ed25519. The public key is then stored as a CKA_EC_POINT. The CKA_EC_POINT is normally used to store EC curve points, but in the case of Ed the point it's not quite the same. This required an if statement and some special handling in the case of EdDSA keys.

In the case of ECDSA:

final java.security.spec.EllipticCurve ellipticCurve = EC5Util.convertCurve(bcspec.getCurve(), bcspec.getSeed());
final java.security.spec.ECPoint ecPoint = ECPointUtil.decodePoint(ellipticCurve,
        ASN1OctetString.getInstance(ckaQ.getValue()).getOctets());
final org.bouncycastle.math.ec.ECPoint ecp = EC5Util.convertPoint(bcspec.getCurve(), ecPoint);
final ECPublicKeySpec pubKeySpec = new ECPublicKeySpec(ecp, bcspec);
final KeyFactory keyfact = KeyFactory.getInstance("ECDSA", BouncyCastleProvider.PROVIDER_NAME);
return keyfact.generatePublic(pubKeySpec);

 and in the case of EdDSA:

X509EncodedKeySpec edSpec = createEdDSAPublicKeySpec(ckaQ.getValue());
final KeyFactory keyfact = KeyFactory.getInstance(oid.getId(), BouncyCastleProvider.PROVIDER_NAME);
return keyfact.generatePublic(edSpec);

As usual, a big thanks to the team at Bouncy Castle for help.

Summary

With all the above details in place, we now have the functionality we need in EJBCA:

  • Generating Ed25519 and Ed448 key pairs (in software and in HSMs)
  • Retrieve public keys
  • Test a key pair
  • Sign and verify
    • Certificate
    • CRL
    • OCSP response
    • CSRs (PKCS#10 and CRMF)
    • CMS message
  • Read and write
    • PEM files
    • PKCS#12 files
  • Presenting EdDSA in Web UIs in a user friendly way 


Cheers,
Tomas Gustavsson
CTO 

EJBCA Enterprise PKI and EJBCA Appliance developed by PrimeKey.

PrimeKey® and EJBCA® are trademarks of PrimeKey Solutions AB, in the EU, the United States, Japan and certain other countries.

Friday, June 5, 2020

Using CertBot to issue certificates with ACME to an Apache Web Server

The popular ACME (RFC8555) agent CertBot can be used to automatically create and renew TLS certificates for an Apache web server. The same setup can easily be used for other web servers that CertBot has support for, for example NGINX. With a TLS certificate, the web server can be reached using the HTTPS protocol, and all traffic to and from the web server is encrypted.

This post describes how to issue private TLS certificates, from your own CA, for usage in your organization.

This picture shows a simplified image approximately what happens in the background when issuing a certificate with ACME.

Prerequisites

Issuing web host certificates using ACME makes use of DNS for authorizing issuance of certificates for a specific domain. Therefore it is important that both the web host and the CA have proper FQDNs and that these are in the DNS. The CA needs to be able to reach the web server, looking up its FQDN in DNS.

The following prerequisites are required to complete the issuance:
  • EJBCA
    • EJBCA Enterprise (with ACME support) deployed on an Ubuntu server, configured with:
      • A CA that will issue web server certificates
      • A certificate profile in EJBCA for the web server certificates
      • An end entity profile in EJBCA for the web server certificates that is configured to use the web server certificate profile
  • Apache web server
    • A server/VM installed with Ubuntu 19.04 (as used in this guide, other operating systems should work the same/similarly)
  • DNS host records
    • A host record for the CA server, used by the web server to contact the CA (in this guide ejbca.example.com)
    • A host record for the web server, used by the CA to contact the web server for ACME http-01 authorization (in this guide tgacme.com and www.tgacme.com

Issue Web Server TLS Certificate over ACME with CertBot

To complete issuance of a web server certificate, follow the steps outlined in the sections below.

Step 1 - Trusted CA Certificate Configuration

In order to contact the CA server over https, the CA certificate that signs your servers (EJBCA and Apache) TLS certificates needs to be installed as trusted in your systems, both the EJBCA host and the Web host. If not, CertBot will not be able to talk to the CA.

In this guide, the Management CA (a Root CA) is used and the Management CA certificate has been downloaded as /tmp/ManagementCA.cacert.pem.

Run the following on both servers:
sudo mkdir /usr/share/ca-certificates/extra/
sudo cp /tmp/ManagementCA.cacert.pem /usr/share/ca-certificates/extra/ManagementCA.cacert.crt
echo 'extra/ManagementCA.cacert.crt' | sudo tee -a /etc/ca-certificates.conf
sudo update-ca-certificates
Next, test that you can access the CA server from both the CA itself and the web server. Example URL: https://ejbca.example.com:8442/

Step 2 - Configure EJBCA on the CA Host

Perform the following steps to configure EJBCA on the CA host:

  1. To configure the Management CA to allow the same subject DN on multiple end entities:
    • In the EJBCA Admin UI, click Certificate Authorities>Management CA>Edit and set the following:
      • Enforce unique public keys = unchecked.
      • Enforce unique DN = unchecked.
  2. To create a Server Certificate Profile, SslServerProfile :
    • To clone the SERVER certificate profile, click Certificate Profiles>SERVER>Clone and set the following:
      • Extended Key Usage = Server Authentication.
      • Available CA: Any CA.
  3. To create a Server End Entity Profile, SslServerProfile:
    • In the EJBCA Admin UI, click End Entity Profiles>Add profile and set the following:
      • End Entity E-mail: Use, Modifiable.
      • Subject DN Attributes: Only CN, Required and Modifiable.
      • Subject Alternative Name: two DNSName.
      • Default/Available Certificate Profile: SslServerProfile.
      • Default/Available CA: Management CA.
  4. Enable the ACME protocol under System Configuration>Protocol Configuration.
  5. Add an ACME alias in EJBCA:
    • In the EJBCA Admin UI, click ACME Configuration>Add and set the following:
      • End Entity Profile: SslServerProfile.
      • Site URL: https://www.primekey.com/
      • Terms of Service URL: https://primekey.com/products/software/
      • DNS Resolver: 8.8.8.8.
  6. Set the ACME alias as Default ACME configuration in the ACME Configuration Overview (EJBCA Admin UI>ACME Configuration).
The following displays an example ACME alias configuration:

Step 3 - Install CertBot on the Apache Web Server Host

On the Web host, install CertBot using the following command. Note that you may need to run sudo apt update on a fresh installation.
sudo apt install python3-certbot-apache
The above command installs the Apache2 web server automatically.

Step 4 - Issue Web Server Certificate

First, to test that https is not available (looks good in a demo), test the following with a web browser:
  • http://tgacme.com - Should show the Apache default web page
  • https://tgacme.com - Should show an error that the browser cannot connect
Next, run certbot to install the certificate from the EJBCA server:
sudo certbot --server https://ejbca.example.com:8442/ejbca/acme/directory -d tgacme.com --apache --agree-tos --email admin@example.com --no-eff-email --noninteractive
Then test with the web browser again:
  • https://tgacme.com - Should now connect and show the Apache default web page.
Additionally, you can go to the certificate view page of your web browser and inspect the web server certificate (that the issuer is the private Management CA).

Step 5 - Configure CertBot for Automatic Monitoring of Expiry

You can now configure CertBot for automatic monitoring of expiry. For information on configuring CertBot, refer to the CertBot documentation.

Additional Notes

Roles and responsibilities

There are at least three distinct roles used in this guide, although they can be more.

  1. CA administrator, performing the configuration of EJBCA. This role can further be divided for CA role separation, for example:
    • CA policy administrator, configuring certificate- and end entity profiles ensuring that properly formatted certificates are issued
    • CA protocol administrator, configuring ACME aliases
  2. Web server administrator, performing configuration of the Apache server and CertBot on the web host.
  3. DNS administrator, adding records to the DNS enabling ACME authorization
In addition it is recommended to monitor all web hosts for expiring certificates. There is a plethora of tools for this, and it's probably included as part of your organization server monitoring solution.

Cleanup/Reset Web Server to Run Again

A simple script can be run on the web host to re-install Apache and CertBot, making it straightforward to run the test as many times as you want, the same fresh installation every time.

The steps are outlined below to describe the process although the script can be run during the initial setup as well.
/home/user/certbot-reinstall.sh
The script does the following:
#!/bin/bash
sudo apt-get -yq remove --purge python3-certbot-apache
sudo apt-get -yq remove --purge apache2
sudo rm -rf /etc/letsencrypt
sudo rm -rf /etc/apache2
sudo apt-get -yq --ignore-missing install python3-certbot-apache
  • Test with browser:
    • http://tgacme.com - Shows the Apache default web page
    • https://tgacme.com - Shows an error that the browser cannot connect.
  • sudo certbot --server https://ejbca.example.com:8442/ejbca/acme/directory -d tgacme.com --apache --agree-tos --email admin@example.com --no-eff-email --noninteractive
  • Test with browser:
    • https://tgacme.com - Connects and shows the Apache default web page.
  • Show the web server certificate in the browser (and verify that it comes from the private Management CA)

CertBot on a Fresh Ubuntu 18.04 or Lower Host

Without updating the Ubuntu repos, the client that will be installed is 0.23. This is older and not supported by EJBCA version > 7.3.0.

To install a newer CertBot version, use the following commands:
sudo apt-get -y update
sudo apt-get -y install software-properties-common
sudo add-apt-repository -y universe
sudo add-apt-repository -y ppa:certbot/certbot
sudo apt-get -y update
sudo apt-get -y install certbot python3-certbot-apache 

Cheers,
Tomas Gustavsson
CTO 

 EJBCA Enterprise PKI and PKI Appliance developed by PrimeKey.

EJBCA is a registered trademark of PrimeKey Solutions AB in the EU, the United States, Japan and certain other countries.

Friday, May 29, 2020

A practical analysis of the SSH Certificate format

I've been messing around a wee bit with SSH certificates, and while the specification is fairly easy to read, reading the actual format was not quite as much so and there was quite a bit of trial and error involved. For the sake of posterity, I thought I'd give a rundown of a sample SSH certificate and how to parse it.

Why use SSH Certificates?
The default use for SSH is with a username/password combo. Why relying purely on username/password is a poor idea is self evident, as passwords are commonly reused/stolen, so the next step up is using SSH keys so that an attacker needs to have also acquired the SSH private key, as well as the password used to protect the key pair. SSH keys can easily be produced using OpenSSH:
$ ssh-keygen -b 384 -t ecdsa -f id_ec384 
The common procedure is then to send your public key off to your favorite IT-admin, who adds it to a list of known keys. If you're an organization of 8000 employees all working from home, your IT-admin is going to be sad and depressed indeed. 

Without going into details in the complete setup (that's a separate blog post, and can be found plenty elsewhere), what your IT-admin can do instead is set up a CA. From there they'll set up some form of RA, and what you instead can do is send in your public key, have it signed and receive a certificate back. This certificate is now your SSH passcode - the difference being that the IT-admin never had to in any way interface directly with your public key. As long as the signature is valid and the certificate hasn't expired, you're good to go.

The Specification
The specification for an RSA certificate is as follows:
78:     string    "ssh-rsa-cert-v01@openssh.com"
79:     string    nonce
80:     mpint     e
81:     mpint     n
82:     uint64    serial
83:     uint32    type
84:     string    key id
85:     string    valid principals
86:     uint64    valid after
87:     uint64    valid before
88:     string    critical options
89:     string    extensions
90:     string    reserved
91:     string    signature key
92:     string    signature
SSH certificates have no similarities to x509, as x509 was by the designers deemed to be overly complex for the purpose. The SSH certificate format also provides some nice perks that x509 does not. So, let's get into it. 

Breaking it down
A sample SSH certificate looks like this.
ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1yc2EtY2VydC12MDFAb3BlbnNzaC5jb20AAAAg5XCeFvniKnNbRZaclB83kTyF8zITCde4uRrv4mqesn4AAAADAQABAAABAQDiFqTBdKOWPeBeP1PiKSVy8ilfNChu5/6Z3iXu3Rdtg5ozu98IoAl4MtlklDdUDzvFkB+VPD/9gqHPKK8fTOhqgUPGoiCeZP3Ktr6NR53xd1QPQDeBvOMiYkPqQXziCQiVyL1WFzN616szrxsJ1Ni7WCHXcMTKOMruLv4es8FfB03wGDbBKVzMwo0JuZCicGg2pg/o8n9BPlzW6CvjUkmvUO3ycGKibPPFkiDgyuYynIbkMcmdShhY3XSOGB4UPeA3U4OiH6Z+09K9LqogWIcjxJeK0tObORd9QnQ4k1ba+/bbEfnFIQwLyzqXXPsPQ0Ud9upxVHD1lezRNE1DAIr9AAAAAAAAAAAAAAABAAAABWVqYmNhAAAAFAAAAAZlamJjYTAAAAAGZWpiY2ExAAAAAF7Q0HgAAAAAYLCytwAAAAAAAACCAAAAFXBlcm1pdC1YMTEtZm9yd2FyZGluZwAAAAAAAAAXcGVybWl0LWFnZW50LWZvcndhcmRpbmcAAAAAAAAAFnBlcm1pdC1wb3J0LWZvcndhcmRpbmcAAAAAAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAEXAAAAB3NzaC1yc2EAAAADAQABAAABAQC8ajEtOvKxSPYSRL+A1y7Ye0baYHaR65KkzaT3U5XugHKHusvVPsDlRfSl598TsMjPQhbJt0O1SefMvXCbqdj776PWok5I1ScnLKJWRKzreeslEJZdcKTOUoT9Y5sg/LxC3xXwhIz+yLm8SbvQ7yQvPMmmlg5ldwccC8/0cua/25Vrjm0JhRjgxny65s2bNkClXXLmtevhvlQ7rXMQhpGmg5th156Ny/BUac7CQPEnDkRkhfsH8zKuh0NX19Y/93bwLsI7z+zP7CJJ11C0CpZl5yi2/8vqZUkufjRu/TH78EnLdCE/bkKcn0yyahG5BTh9dInrSclgCSiEPOYojvzjAAABFAAAAAxyc2Etc2hhMi0yNTYAAAEAj4/d9pKGGReo7B1ZbVBtHD9ftBfa5fjyPnuM8qbEMtYWgbx/MlCqVf2CL6VfJe2lvsg4ZZWvHyq0XBucFQqVHMekHJ71CymAs5/boGF4efLo56Ck6FF7tqM4dYmcO0aWRRQt3DyC24bLUZ4ZcdkyAgEm4EbTj9nPyvzbR57VsP/p+6WlszrGAHPwBlZ6my0g3cwPJSxwdV0USfMUIWooMIXLS7ocVZ7a8y+HF6qC2FGYIXYSgJuBaG5jlfXOojfKwA4tzwdy3ZziHxW50WDRkPrw6ZnXeRantJfMOhJ7ol9NSt1WcdkiAHqzDbEUpOz9UF0aSwxtIQYI7ONgl29a7w== Mike's Certificate
We can see right away a nice perk, the certificate begins by telling us what's going to be inside, so off the ball we can figure out how we're going to decode it. The astute of you will notice that the main body of the certificate (between the prefix declaring the type and the comment at the end) looks a lot like Base64, which it very correctly is. If you've seen a certificate or two you'll also notice that every certificate of the same type starts with the same text, and that's because the first characters are (as stated in the specification above) the certificate type, in this case ssh-rsa-cert-v01@openssh.com. So, throw the certificate body into your favorite Base64 decoder and let's move on. 

The byte array follows a simple structure: first a four byte integer declaring the length of the structure, then the contents itself:
What you actually find inside the contents is up to the specification above, hence the importance of knowing beforehand what you're parsing. There can also be additional byte arrays of this format hidden within the payload, as we'll see in a moment. Parsing our way through the byte array, we're going to encounter the following objects, in this exact order:
Item    Description
 nonce   A 16 or 32 bit random byte array generated on the CA, simply to make collision attacks less likely.    
 e  The RSA exponent of the public key for this certificate. Note that EC keys will have the entire key in its own byte structure instead of having its values directly in the certificate. 
 n  The RSA modulus of the public key for this certificate.   
 serial  64 bit unsigned long with a serial number - up to the CA to determine the scheme
 type  32 bit unsigned integer containing a 1 (for user certificates) or a 2 (host certificates) 
 key id  A string filled in by the CA to identify the holder (end entity in x509 terms) owning the certificate.
 valid principals  Our first internal byte structure. The list of principals contains the accounts on the host machine which may be used with this certificate. An empty list will allow any user to make use of this certificate. The structure will look as follows:


 valid after  A 64 bit unsigned long containing the lower bounds of the certificate's validity. 
 valid before  A 64 bit unsigned long containing the upper bounds of the certificate's validity.
 critical options  These will only be relevant for user certificates (as there are no official options for host certificates) and may be force-command (to have the client execute a certain command on authentication to the host) and/or source-address in order to bind the client to a single IP. This is a key-value pair, so adds another layer of complexity to the byte structure


 extensions    The equivalent of x509 key usages, tells SSH what this certificate is authorized to do. There are extensions pre-defined in the specification, but it's up to you if you want to add your own as well. The structure is an array of strings much like principals


 reserved   A blank string, declared but not used at the moment.
 signature key  This is where it starts getting fun. OpenSSH allows the signature key to be of any OpenSSH usable format regardless of the key being signed, so there is for example no reason why a RSA CA can't sign a set of EC keys. The signature key is going to be parsed as a byte structure and then parsed up into its component. The structure of the key is defined in RFC 4253, and for an RSA key would be as follows:
 string "ssh-rsa"
mpint e
mpint n
The nice part is that the first thing the key does is declare itself, so you know exactly how to parse the rest of the structure. 


 signature   Last but not least, the last byte array you're going to read is the signature. This is going to be again an embedded byte structure, starting with a string declaring the signature algorithm, and after that the actual signature, the data for which is all of the preceding fields including the signing key. 


And that's pretty much it! Happy hacking, and I hope I've managed to make somebody's day a bit better.

Cheers,
Mike Agrenius Kushner
Product Owner, EJBCA