Managing Keys

Overview

This page describes how to create, manage and best practices for your master keys and join keys.

Important

Remember to keep the join key, master key, and other trusted keys safe; they should not be shared with external parties.

Join Key

The JFrog join.key feature establishes trust between the JFrog services based on symmetric encryption (AES-128 bit or AES-256 bit). The join.key is used internally for creating trust between microservices of the same service, for example between Artifactory and Access.

Once trust is established (meaning the join.key is shared between all the different services), the services can continue using the standard token-based authentication for communication. This is accomplished by having each service create the tokens used for the inter-service communication and signing those tokens with the join.key.

Access will then use the provided join.key instead of the auto-generated one, save it to its database, and share it with Artifactory.

If the join.key is not identical on the trusted services, communication between services fail.

For automation purposes, it is recommend to generate your own Join Key and share it with every new instance.

Fetching the JPD join.key

The JPD join key can be found either in the JPD UI in the Administration module | Security | Settings | Join Key
or (encrypted) in the join.key file in the Artifactory file-system under $JFROG_HOME/artifactory/var/etc/security
Note: you can only share the encrypted join.key with services using the same mater.key

Master Key

The Master key is an AES secret key (128 or 256 bit) that's used by Artifactory to securely synchronize files between cluster nodes. It is responsible for encrypting and decrypting the shared data in the database.

If the master.key is not identical on the cluster nodes, the service will not be able to decrypt configuration files from the database.

The master key is not used for communication between the different JFrog Platform products (unlike the join key, which is used to communicate between Artifactory, Xray, and other JFrog services).

The master key is set per product, and must be the same for all the nodes in the same service (when using HA).

Master.key Load and Retention in Memory

To improve security around the storage of the master.key, from Artifactory version 7.29.7, JFrog supports loading the master.key at startup and keeping it in memory. This is achieved by removing the master key from the file system by each application, after it was read by the application node during bootstrapping.

Important

Before every restart, you will need to place the master.key file in the filesystem.

Remember to keep the master.key in a separate, safe location.

Customers who wish to use this capability will need to do the following:

Enable the master key removal by setting the flag shared.security.masterKeyExternal to true
Fetch the master key and place it in the correct path on the application's file system whenever a new node is bootstrapped

When the flag above is set to true:

The router will remove the master.key file once each service is up and running.
Pipelines will not generate a master.key and will instead read the master.key from the database.

Page Contents

Creating Your Keys

By default the join.key and master.key files are automatically generated by Artifactory during the initial start up of the service.

A different key (hexadecimal encoded) can be created using the following command.

openssl rand -hex 16 
/or
openssl rand -hex 32

Bootstrapping with Your Own Keys

There are two ways to manually update your keys: file copy and/or bootstrap via system.yaml file.

Bootstrapping Keys Using the system.yaml File

This method only applies if you have installed but not started your service yet.

Save the security section of the system yaml file with the generated string for each key using masterKey parameter for the Master Key and joinKey parameter for the Join Key.
Start the service.

Bootstrapping the join.key Using File System

This method can be used even if you already have a join.key

Save the generated string file as join.key.
Place each file in the $JFROG_HOME/artifactory/var/bootstrap/access/etc/security directory.
Add the Artifactory permissions to the directories and the join.key file. For example,
```
chown -R artifactory:artifactory access/etc/security/join.key
```
Start the service.

Managing the join.key

By default, a join.key is automatically generated and stored in the Access database during Access startup.

The join.key is then automatically copied by Access to Artifactory over the file system and is re-provisioned every time the services are restarted.
Access shares the join.key with Artifactory by copying it to the following location:

$JFROG_HOME/artifactory/var/etc/security/join.key

Upgrading to Artifactory 6.8 automatically initiates and generates the join.key mechanism.

Managing join.keys in HA

There should only be one join.key per HA cluster since the Access database is shared across all nodes of an HA cluster.

In case a join key is provided and not generated by the system, it can be provided to a single cluster node as it will be propagated to all nodes of the cluster by the system.

Content

Space Tools