Securing the Carbon Engine

HTTPS

The Carbon Engine exposes two ports from its container: an HTTP server on port 80 and an HTTPS server on port 443. Cogo recommends that you use the HTTPS endpoint for all communications.

Custom TLS certificate

By default, a self-signed certificate is created on startup and used with the HTTPS server. This allows for secure communications, but is vulnerable to man-in-the-middle attacks if your network is compromised.

If you want to use a certificate that is signed by a global CA or your own CA, mount a volume in the container at path /tls and include two PEM-encoded files named server.key and server.crt in this directory. They will be used in preference to the self-signed certificate.

API access control

Carbon Engine offers two in-built authentication methods:

  1. a static shared secret that is required to be present on every request
  2. validation of JSON Web Tokens (JWT) against a web-accessible jwks.json file

Authentication can also be disabled.

To configure the authentication mode, set the COGO_AUTHENTICATION_MODE environment variable to one of none, static, or jwt.

If you want to place your own authentication method in front of Carbon Engine, Cogo recommends that you:

  1. enable static shared secret authentication to the Carbon Engine API (see below), and
  2. put an authenticating gateway in front of all requests to Carbon Engine to integrate with your existing internal authentication and auditing systems.

Cogo strongly recommends that some form of authentication is used either in or in front of Carbon Engine to prevent unauthorised access to customer transaction data.

Enabling static shared secret authentication

You can enable the Carbon Engine to can check for the presence of an Authorization header with a valid static secret before accepting requests.

Set the COGO_AUTHENTICATION_MODE environment variable to static.

Generate a random string to use as your shared secret. Then generate the base-64 encoded SHA-256 of your shared secret, and pass it to the Carbon Engine as the COGO_HASHED_ACCESS_KEY environment variable.

As an example, if your shared secret was my-secure-token, you can generate the base-64 encoded SHA-256 as follows:

> echo -n my-secure-token | openssl sha256 -binary | base64
S7PhOYRVu0t6nC6a9jthgm3ZV3D664BAJZK4jM3+DT4=

Then you would pass the following environment variables to the Carbon Engine: COGO_AUTHENTICATION_MODE=static COGO_HASHED_ACCESS_KEY=S7PhOYRVu0t6nC6a9jthgm3ZV3D664BAJZK4jM3+DT4= and now all requests to the Carbon Engine must have the following HTTP header included:

Authorization: Bearer my-secure-token

Requests without this header present will receive a 401 Unauthorized HTTP response.

Enabling JSON Web Token (JWT) authentication

If you are using "client credentials" JWT for authentication, they can be validated by Carbon Engine. The JWT must contain a kid key ID field, and your authentication provider must publish a jwks.json file at a URL which contains the public keys to validate the JWT against.

AWS Cognito and many other authentication providers are compatible with this system. Examples for AWS Cognito are provided below.

Set the COGO_AUTHENTICATION_MODE environment variable to jwt.

Set the COGO_JWT_ISSUER environment variable to the JWT issuer. This string must match with the iss field in the JWT otherwise the JWT will be rejected.

Using AWS Cognito, issuers have the format of https://cognito-idp.<Region>.amazonaws.com/<userPoolID>.

Set the COGO_JWKS_URL environment variable to the URL where the jwks.json file can be downloaded. This file is downloaded on startup, and every hour afterwards. The server will not start up unless this URL is accessible and returns a valid JWKS file.

Using AWS Cognito, JWKS URLs have the format of https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json.

When enabled, every request to the API requires an authorization header containing a valid JWT:

Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IlZVUVpCWjdUNk5BRktTMjR...

If the JWT is not valid, a 401 Unauthorized HTTP response will be returned. A detailed reason for the authentication failure can be found by looking at Carbon Engine's logging output.