HCD-147: Add createsystemkey subcommand to nodetool (#1759)

szymon-miezal · driftx · commit 3b910751ec16 · 2025-07-30T14:07:41.000-05:00
This commit extends nodetool with createsystemkey command. The motivation is to allow users to create encryption keys that can be used for flat-file based encryption in TDE. CNDB PR: riptano/cndb#14205.
diff --git a/src/java/org/apache/cassandra/crypto/LocalFileSystemKeyProvider.java b/src/java/org/apache/cassandra/crypto/LocalFileSystemKeyProvider.java
@@ -47,6 +47,11 @@ public class LocalFileSystemKeyProvider implements IKeyProvider
 
     public LocalFileSystemKeyProvider(Path keyPath) throws IOException
     {
+        if (keyPath.getParent() == null)
+        {
+            throw new IllegalArgumentException("The key path must be absolute");
+        }
+
         if (Files.exists(keyPath))
         {
             this.keyPath = keyPath;
diff --git a/src/java/org/apache/cassandra/tools/NodeTool.java b/src/java/org/apache/cassandra/tools/NodeTool.java
@@ -104,6 +104,7 @@ public int execute(String... args)
                 Compact.class,
                 CompactionHistory.class,
                 CompactionStats.class,
+                CreateSystemKey.class,
                 DataPaths.class,
                 Decommission.class,
                 DescribeCluster.class,
diff --git a/src/java/org/apache/cassandra/tools/nodetool/CreateSystemKey.java b/src/java/org/apache/cassandra/tools/nodetool/CreateSystemKey.java
@@ -0,0 +1,83 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.cassandra.tools.nodetool;
+
+import java.io.IOException;
+import java.io.PrintStream;
+import java.nio.file.Path;
+import java.security.InvalidParameterException;
+import java.security.NoSuchAlgorithmException;
+import java.util.ArrayList;
+import java.util.List;
+import javax.crypto.NoSuchPaddingException;
+
+import io.airlift.airline.Arguments;
+import io.airlift.airline.Command;
+import io.airlift.airline.Option;
+import org.apache.cassandra.crypto.LocalSystemKey;
+import org.apache.cassandra.tools.NodeProbe;
+import org.apache.cassandra.tools.NodeTool.NodeToolCmd;
+
+@Command(name = "createsystemkey", description = "Creates a system key for sstable encryption")
+public class CreateSystemKey extends NodeToolCmd
+{
+    @Arguments(usage = "[<algorithm> <key strength> [<filename>]", description = "<algorithm[/mode/padding]>\n" +
+                                                                                 "<key strength>\n" +
+                                                                                 "[<file>]\n" +
+                                                                                 "Key strength not required for Hmac algorithms. <file> will be appended to the directory defined in system_key_directory.")
+    private List<String> args = new ArrayList<>();
+
+    @Option(title = "directory", name = "-d", description = "Output directory")
+    private String directoryOption = null;
+
+    @Override
+    public void execute(NodeProbe probe)
+    {
+        if (args.size() < 2)
+        {
+            throw new RuntimeException("Usage: nodetool createsystemkey <algorithm> <key strength> [<file>]");
+        }
+
+        String cipherName = args.get(0);
+        int keyStrength = cipherName.startsWith("Hmac") ? 0 : Integer.parseInt(args.get(1));
+
+        Path directory = directoryOption != null ? Path.of(directoryOption) : null;
+        String keyLocation = null;
+        PrintStream out = probe.output().out;
+        PrintStream err = probe.output().err;
+
+        try
+        {
+            keyLocation = args.size() > 2 ? args.get(2) : "system_key";
+            Path keyPath = LocalSystemKey.createKey(directory, keyLocation, cipherName, keyStrength);
+
+            out.printf("Successfully created key %s%n", keyPath.toString());
+        }
+        catch (NoSuchAlgorithmException e)
+        {
+            err.printf("System key (%s %s) was not created at %s%n", cipherName, keyStrength, keyLocation);
+            err.println(e.getMessage());
+            err.println("Available algorithms are: AES, ARCFOUR, Blowfish, DES, DESede, HmacMD5, HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512 and RC2");
+            System.exit(1);
+        }
+        catch (InvalidParameterException | NoSuchPaddingException | IOException e)
+        {
+            err.printf("System key (%s %s) was not created at %s%n", cipherName, keyStrength, keyLocation);
+            err.println(e.getMessage());
+            System.exit(1);
+        }
+    }
+}
diff --git a/test/distributed/org/apache/cassandra/distributed/test/NodeToolTest.java b/test/distributed/org/apache/cassandra/distributed/test/NodeToolTest.java
@@ -19,19 +19,26 @@
 package org.apache.cassandra.distributed.test;
 
 import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
 import java.util.function.Consumer;
 
 import org.junit.AfterClass;
 import org.junit.BeforeClass;
 import org.junit.Test;
 
+import org.apache.cassandra.config.CassandraRelevantProperties;
 import org.apache.cassandra.config.DatabaseDescriptor;
+import org.apache.cassandra.crypto.TDEConfigurationProvider;
 import org.apache.cassandra.distributed.Cluster;
 import org.apache.cassandra.distributed.api.ICluster;
 import org.apache.cassandra.distributed.api.IInvokableInstance;
 import org.apache.cassandra.distributed.api.NodeToolResult;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
 
 public class NodeToolTest extends TestBaseImpl
 {
@@ -161,4 +168,85 @@ public void testCompactionStats() throws Throwable
         result.asserts().success().stdoutNotContains("system.peers");
         result.asserts().success().stdoutNotContains("system_schema.keyspaces");
     }
+
+    @Test
+    public void testSuccesfulSystemKeyCreation() throws Throwable
+    {
+        try
+        {
+            // given a command with default key name and location
+            Path testDir1 = Files.createTempDirectory("test_1");
+            CassandraRelevantProperties.SYSTEM_KEY_DIRECTORY.setString(testDir1.toString());
+            Path systemKey = Paths.get(TDEConfigurationProvider.getConfiguration().systemKeyDirectory).resolve("system_key");
+            assertFalse(Files.exists(systemKey));
+            // when
+            NodeToolResult result = NODE.nodetoolResult("createsystemkey", "AES/CBC/PKCS5Padding", "128");
+            // then should create a key
+            result.asserts().success();
+            result.asserts().stdoutContains("Successfully created key");
+            assertTrue(Files.exists(systemKey));
+
+            // given a command with specified key name and default key location
+            Path testDir2 = Files.createTempDirectory("test_2");
+            CassandraRelevantProperties.SYSTEM_KEY_DIRECTORY.setString(testDir2.toString());
+            systemKey = Paths.get(TDEConfigurationProvider.getConfiguration().systemKeyDirectory).resolve("system_key_2");
+            assertFalse(Files.exists(systemKey));
+            // when
+            result = NODE.nodetoolResult("createsystemkey", "AES/CBC/PKCS5Padding", "128", "system_key_2");
+            // then should create a key
+            result.asserts().success();
+            result.asserts().stdoutContains("Successfully created key");
+            assertTrue(Files.exists(systemKey));
+
+            // given a command with specified key location and default key name
+            Path testDir3 = Files.createTempDirectory("test_3");
+            assertFalse(Files.exists(testDir3.resolve("system_key")));
+            // when
+            result = NODE.nodetoolResult("createsystemkey", "AES/CBC/PKCS5Padding", "128", "-d", testDir3.toString());
+            // then should create a key
+            result.asserts().success();
+            result.asserts().stdoutContains("Successfully created key");
+            assertTrue(Files.exists(testDir3.resolve("system_key")));
+        }
+        finally
+        {
+            CassandraRelevantProperties.SYSTEM_KEY_DIRECTORY.reset();
+        }
+    }
+
+    @Test
+    public void testUnsuccesfulSystemKeyCreation()
+    {
+        try
+        {
+            // given a command without key type and strength
+            NodeToolResult result = NODE.nodetoolResult("createsystemkey");
+            // then should fail creation
+            result.asserts().failure();
+            result.asserts().stderrContains("Usage: nodetool createsystemkey <algorithm> <key strength> [<file>]");
+
+            // given a command without key strength
+            result = NODE.nodetoolResult("createsystemkey", "AES/CBC/PKCS5Padding");
+            // then should fail creation
+            result.asserts().failure();
+            result.asserts().stderrContains("Usage: nodetool createsystemkey <algorithm> <key strength> [<file>]");
+
+            // given a command with incorrect algorithm name
+            result = NODE.nodetoolResult("createsystemkey", "INVALIDNAME", "128");
+            // then should fail creation
+            result.asserts().failure();
+            result.asserts().stderrContains("System key (INVALIDNAME 128) was not created");
+            result.asserts().stderrContains("Available algorithms are: AES, ARCFOUR, Blowfish, DES, DESede, HmacMD5, HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512 and RC2");
+
+            // given a command with incorrect algorithm strength
+            result = NODE.nodetoolResult("createsystemkey", "AES", "99");
+            // then should fail creation
+            result.asserts().failure();
+            result.asserts().stderrContains("System key (AES 99) was not created");
+        }
+        finally
+        {
+            CassandraRelevantProperties.SYSTEM_KEY_DIRECTORY.reset();
+        }
+    }
 }
diff --git a/test/distributed/org/apache/cassandra/distributed/test/SSTableEncryptionTest.java b/test/distributed/org/apache/cassandra/distributed/test/SSTableEncryptionTest.java
@@ -1,13 +1,11 @@
 /*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
+ * Copyright DataStax, Inc.
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
@@ -23,6 +21,7 @@
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.Paths;
 import java.security.NoSuchAlgorithmException;
 import java.util.List;
 import java.util.stream.Collectors;
@@ -34,11 +33,13 @@
 import org.junit.BeforeClass;
 import org.junit.Test;
 
+import org.apache.cassandra.config.CassandraRelevantProperties;
 import org.apache.cassandra.crypto.LocalSystemKey;
 import org.apache.cassandra.crypto.TDEConfigurationProvider;
 import org.apache.cassandra.db.Keyspace;
 import org.apache.cassandra.distributed.Cluster;
 import org.apache.cassandra.distributed.api.ConsistencyLevel;
+import org.apache.cassandra.distributed.api.NodeToolResult;
 import org.apache.cassandra.io.sstable.Component;
 import org.apache.cassandra.io.sstable.format.SSTableFormat;
 import org.apache.cassandra.io.sstable.format.bti.BtiFormat;
@@ -60,22 +61,20 @@ public class SSTableEncryptionTest extends TestBaseImpl
     private static final String KEYSPACE_PREFIX = "ks";
     private static final String TABLE_PREFIX = "tbl";
     private static final String SENSITIVE_KEY = "Key with sensitive information";
-    private static final int ROWS_COUNT = 10000;
+    private static final int ROWS_COUNT = 20000;
 
-    private static String defaultSystemKeyDirectory;
 
     @BeforeClass
     public static void beforeAll() throws IOException
     {
-        defaultSystemKeyDirectory = TDEConfigurationProvider.getConfiguration().systemKeyDirectory;
         Path systemKeyDirectory = Files.createTempDirectory("system_key_directory");
-        TDEConfigurationProvider.setSystemKeyDirectoryProperty(systemKeyDirectory.toString());
+        CassandraRelevantProperties.SYSTEM_KEY_DIRECTORY.setString(systemKeyDirectory.toString());
     }
 
     @AfterClass
     public static void tearDown()
     {
-        TDEConfigurationProvider.setSystemKeyDirectoryProperty(defaultSystemKeyDirectory);
+        CassandraRelevantProperties.SYSTEM_KEY_DIRECTORY.reset();
     }
 
     @Test
@@ -87,7 +86,7 @@ public void shouldCreateQueryableEncryptedSSTables() throws Throwable
         {
             // given a table with data encrypted using local key
             String keyspace = createKeyspace(cluster);
-            Path secretKey = createLocalSecretKey();
+            Path secretKey = createLocalSecretKey(cluster);
             String table = createEncryptedTable(cluster, keyspace, secretKey);
             int numberOfRows = 10;
 
@@ -141,7 +140,7 @@ public void shouldEncryptSensitiveData() throws Exception
             // given tables with and without encryption
             String keyspace = createKeyspace(cluster);
             TestTable nonEncryptedTable = createTableWithSampleData(cluster, keyspace, "");
-            Path secretKey = createLocalSecretKey();
+            Path secretKey = createLocalSecretKey(cluster);
             TestTable encryptedTable = createTableWithSampleData(cluster, keyspace, localSystemKeyEncryptionCompressionSuffix("Encryptor", secretKey.toAbsolutePath().toString()));
 
             // then
@@ -156,6 +155,7 @@ public void shouldEncryptSensitiveData() throws Exception
 
             // indexes with encryption should pass the checksum check
             assertThat(checkEncryptionCrc(encryptedTable.partitionIndexBytes)).isTrue();
+            assertThat(encryptedTable.rowIndexBytes.length).isGreaterThan(0);
             assertThat(checkEncryptionCrc(encryptedTable.rowIndexBytes)).isTrue();
             // indexes without encryption should fail the checksum check
             assertThat(checkEncryptionCrc(nonEncryptedTable.partitionIndexBytes)).isFalse();
@@ -193,7 +193,7 @@ public void shouldNotReadRowsFromEncryptedTableWithoutTheSecretKey() throws Exce
 
             // given a table with data encrypted using local key
             String keyspace = createKeyspace(cluster);
-            Path secretKey = createLocalSecretKey();
+            Path secretKey = createLocalSecretKey(cluster);
             String encryptedTableName = createEncryptedTable(cluster, keyspace, secretKey);
             String nonEncryptedTableName = createTable(cluster, keyspace);
             int numberOfRows = 10;
@@ -230,7 +230,7 @@ public void shouldFailWhenReadingWithDifferentKey() throws Exception
 
             // given a table with data encrypted using local key
             String keyspace = createKeyspace(cluster);
-            Path secretKey = createLocalSecretKey();
+            Path secretKey = createLocalSecretKey(cluster);
             String encryptedTableName = createEncryptedTable(cluster, keyspace, secretKey);
             String nonEncryptedTableName = createTable(cluster, keyspace);
             int numberOfRows = 10;
@@ -342,10 +342,15 @@ private String createKeyspace(Cluster cluster)
         return randomKeyspaceName;
     }
 
-    private Path createLocalSecretKey() throws IOException, NoSuchAlgorithmException, NoSuchPaddingException
+    private Path createLocalSecretKey(Cluster cluster)
     {
         String keyPath = "system_key_" + RandomStringUtils.random(10, true, true);
-        return createLocalSecretKey(keyPath);
+        Path keyFullPath = Paths.get(TDEConfigurationProvider.getConfiguration().systemKeyDirectory).resolve(keyPath);
+        assertThat(Files.exists(keyFullPath)).isFalse();
+        NodeToolResult result = cluster.get(1).nodetoolResult("createsystemkey", "AES/CBC/PKCS5Padding", "256", keyPath);
+        result.asserts().success();
+        assertThat(Files.exists(keyFullPath)).isTrue();
+        return keyFullPath;
     }
 
     private Path createLocalSecretKey(String keyPath) throws IOException, NoSuchAlgorithmException, NoSuchPaddingException
diff --git a/test/unit/org/apache/cassandra/crypto/LocalFileSystemKeyProviderTest.java b/test/unit/org/apache/cassandra/crypto/LocalFileSystemKeyProviderTest.java
@@ -27,6 +27,7 @@
 import org.junit.Test;
 
 import org.apache.cassandra.io.util.FileUtils;
+import org.assertj.core.api.Assertions;
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
@@ -234,4 +235,12 @@ public void testKeyGenerationExceptionForInvalidCipherMode() throws IOException
             Files.deleteIfExists(secretKeyPath);
         }
     }
+
+    @Test
+    public void shouldDisallowNonAbsoluteKeyPath()
+    {
+        Assertions.assertThatThrownBy(() -> new LocalFileSystemKeyProvider(Path.of("foobar")))
+                  .isInstanceOf(IllegalArgumentException.class)
+                  .hasMessage("The key path must be absolute");
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,11 @@ public class LocalFileSystemKeyProvider implements IKeyProvider`
`47`	`47`
`48`	`48`	`public LocalFileSystemKeyProvider(Path keyPath) throws IOException`
`49`	`49`	`{`
	`50`	`+ if (keyPath.getParent() == null)`
	`51`	`+ {`
	`52`	`+ throw new IllegalArgumentException("The key path must be absolute");`
	`53`	`+ }`
	`54`	`+`
`50`	`55`	`if (Files.exists(keyPath))`
`51`	`56`	`{`
`52`	`57`	`this.keyPath = keyPath;`
Original file line number	Diff line number	Diff line change
`@@ -27,6 +27,7 @@`
`27`	`27`	`import org.junit.Test;`
`28`	`28`
`29`	`29`	`import org.apache.cassandra.io.util.FileUtils;`
	`30`	`+import org.assertj.core.api.Assertions;`
`30`	`31`
`31`	`32`	`import static org.junit.Assert.assertEquals;`
`32`	`33`	`import static org.junit.Assert.assertFalse;`
`@@ -234,4 +235,12 @@ public void testKeyGenerationExceptionForInvalidCipherMode() throws IOException`
`234`	`235`	`Files.deleteIfExists(secretKeyPath);`
`235`	`236`	`}`
`236`	`237`	`}`
	`238`	`+`
	`239`	`+ @Test`
	`240`	`+ public void shouldDisallowNonAbsoluteKeyPath()`
	`241`	`+ {`
	`242`	`+ Assertions.assertThatThrownBy(() -> new LocalFileSystemKeyProvider(Path.of("foobar")))`
	`243`	`+ .isInstanceOf(IllegalArgumentException.class)`
	`244`	`+ .hasMessage("The key path must be absolute");`
	`245`	`+ }`
`237`	`246`	`}`