App private keys

Each ICR app needs at least on RSA keypair. The keypair identifies an app and is the way your app authenticates app specific requests to ICR servers

About private keys for ICR apps

After you create an ICR App, you'll need to generate a private key in order to make requests to the ICR API as the application itself. For example, you need a private key to sign a JSON Web Token (JWT) in order to request an installation access token. For more information, see "Generating a JSON Web Token (JWT) for an ICR App"

You can create multiple private keys and rotate them to prevent downtime if a key is compromised or lost. To verify that a private key matches a public key, see "Verifying private keys".

Private keys do not expire and instead need to be manually revoked. For more information about how to revoke a private key, see "Deleting private keys."

You must keep private keys for ICR apps secure. For more information, see "Storing private keys".

Generating private keys

To generate a private key:

1. Go to the "Credentials" tab of your app's dashboard.

2. Click the button "Generate a private key"

3. You will see a private key in PEM format downloaded to your computer. Make sure to store this file because ICR only stores the public portion of the key. For more information about securely storing your key, see "Storing private keys."

Verifying private keys

ICR generates a fingerprint for each private and public key pair using the SHA-256 hash function. You can verify that your private key matches the public key stored on ICR by generating the fingerprint of your private key and comparing it to the fingerprint shown on ICR.

To verify a private key:

1. Find the fingerprint for the private and public key pair you want to verify in the "Private keys" section of the "Credentials" tab on your ICR app dashboard. For more information, see "Generating private keys".

   
2. Generate the fingerprint of your private key (PEM) locally by using the following command:

   openssl rsa -in PATH_TO_PEM_FILE -pubout | openssl sha256 -binary | openssl base64

3. Compare the results of the locally generated fingerprint to the fingerprint you see on your app's dashboard on Carbonregistry.com.

Deleting private keys

You can remove a lost or compromised private key by deleting it, but you must regenerate a new key before you can delete the existing key.

Storing private keys

The private key is the single most valuable secret for an ICR App. So make sure it is securely stored. You can store the key as an environment variable but just make sure you know the security implications of doing that. If an attacker gains access to the environment, they can read the private key and gain persistent authentication as the ICR App.

You should not hard-code your private key in your app, even if your code is stored in a private repository.

For more information, see "Best practices for creating an ICR App."