# Key Management

The Swirlds platform uses cryptographic keys to perform encryption and digital signatures, and to enable TLS protection of the communication between computers. It supports various methods to manage those keys. Two key management methods currently exist, and more will be added in the future. The existing methods are described below.

## Default keys

In this option, every computer in the network is provisioned with a config.txt file, but not with any key files. That means the /sdk/data/keys directory contains no *.pfx files.

In this case, the browser creates all the keys deterministically. This provides no security, because the keys are always the same. But it can be useful for things such as keeping firewalls from analyzing the information being sent through them.

## Key files

In this option, a single person generates all the keys to be used by all the computers running this network. If the network will have three computers (full nodes), named Alice, Bob, and Carol, then the keys can be generated by modifying and running the script in the sdk/data/keys directory. On Linux and MacOS, this is done by typing this on the command line:

         ./generate.sh

On Windows, this is typed into the command line console:

         generate.bat

Before running the script, it must be edited. There is one line near the top containing a list of names. That should be changed to match all the names that are in the config.txt file. The names should all have their uppercase letters changed to lowercase, and should have removed all their accents, spaces, and punctuation. So for this example, the list wouldn't be ("Alice" "Bob" "Carol"), but would actually need to be ("alice" "bob" "carol"). A name like "5- John O'Donald, Sr." in the config.txt would need to be listed as "5johnodonaldsr" in the script. And if the "o" had an umlaut above it or a grave accent above it in the config.txt, then it would need to be entered as a plain "o" in the script.

å For the Windows generate.bat script, there is also a line near the top for JAVA_HOME. This needs to be changed to match the location on the hard drive that the JDK was installed. This can be found by searching for Java in the search box at the top of any folder window.

The scripts use the Oracle keytool program that is installed when Java is installed. In this example, the script will use it to create these files:

         public.pfx
         private-alice.pfx
         private-bob.pfx
         private-carol.pfx

These are created on a single computer, when someone runs the script. They must then put these two files into the sdk/data/keys directory on Alice's computer:

         public.pfx
         private-alice.pfx

Similarly, the files public.pfx and private-bob.pfx must be put into the skd/data/keys directory on Bob's computer. And similarly for Carol's computer. Then the original three files should be deleted.

At this point, all three computers can start the browser, and run the app. All three computers will communicate to each other with strong encryption, to prevent eavesdroppers from knowing what they are communicating. They will also sign all their messages with strong digital signatures, to prevent attackers from forging messages in their name.

All communication is encrypted with TLS 1.2, with algorithms and key sizes chosen to conform to the Commercial National Security Algorithm Suite (CNSA suite), using the Java 8 cipher suite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384. That is the standard the US government requires for protecting top secret information. This is intended to provide good security, but there are several issues to keep in mind to make it secure.

The private-*.pfx files contain the private keys. If the attacker can get a copy of one of them, then the attacker can eavesdrop and forge messages. So each computer must be kept physically secure, and must be protected from any virus, worm, malware, insider attack or hacking attack. In addition, it is important to remember that even when files are deleted from a hard drive, an attacker may still be able to recover them later. So if a particular hard drive has ever held a certain file, even briefly, it should forever be treated as if it still had that file, until the drive has been securely erased by overwriting with random bits. Most operating systems have a utility for doing that.

The public.pfx file does not need to be kept secret. If an attacker obtains a copy of it, the attacker will merely learn the names of the members (similar to obtaining a copy of config.txt), but the attacker will not be able to eavesdrop or forge messages.

Also, of course, the files must be protected as they are moved from the computer where they are created to the computers where they are used. Emailing them would not be secure! It is recommended that they be carried from one computer to the other using a USB thumb drive. Afterwards, the thumb drive should be securely erased by repeatedly overwriting with random bits.

Back