1.1. Terms and Definitions

• Authentication XML Signing Key (Signing Key) - is a private, 2048 bit PKCS#8 RSA key with 0x10001exponent, used for Authentication XML signature generation in the KeyOS MultiKey Service.

2. Automatically Generating and Importing New Keys

In order to acquire a license from the KeyOS MultiKey License API, you must have a security token, which is called the “Authentication XML.” Each Authentication XML is signed with your Authentication XML Private Signing Key (Signing Key). You can have multiple Signing Keys, and you can rotate them if required, but the public versions of those Signing Keys must first be registered in the KeyOS system.

Below are the instructions for generating and importing new Signing Keys into the KeyOS platform using only a couple of clicks:

• Log in to your KeyOS account at keyos.com
• Navigate to "Authentication XML -> Import Signing Key" in your KeyOS Console. 
• Select "Generate Random Keys" in the dropdown menu.
• Click “Generate.”

Figure 1. Generating a random Signing Key.

The process of key generation may take a moment (2-10 seconds), but do not close the page.

When the keys are generated, you will see a form as shown below:

Figure 2. Random Signing Key's public key information before import.

• Key Hash - A unique Signing Key identifier that is used inside the Authentication XML's RSAPubKeyId field. When using KeyOS Authentication XML generators, the value for this field is picked up from the name of the key, which is why we strongly recommend naming your keys as follows - "[hash].[ext]".   For example, 30d7ce2a1da161e03bba15e919a19321.pem. If the file that contains the Signing Key has a name that is different from the Key Hash from which it was generated, you must set the RSAPubKeyId field of the Authentication XML manually. Otherwise, the KeyOS MultiKey License Service API won't be able to identify the key that was used to sign your Authentication XML and it won't issue a license.
• Key Description - A Signing Key description to help you identify the key within the list of other Signing Keys in your account. When you generate the random key, this field is pre-populated for you, though you can alter it if necessary.
• Public Key - Your private Signing Key's corresponding public key, which will be imported into the KeyOS system.
• Is Key Enabled? - Flag that defines a key's status, i.e., whether it is enabled and ready to be used, or disabled and any Authentication XML signed using this key is considered invalid.
• Private/Public Keys - This button allows you to download the archive with private and public Signing Keys in different formats:
• PEM-formatted private and public keys
• DER-formatted private key
• XML-formatted private and public keys 

Note: You can download your private keys only on this screen before you click the Import button. For security reasons, we do not store your private keys. Please make sure you have downloaded them here.

• I have downloaded keys - Enables the Import button and allows you to move forward.
  
  

By clicking “Import,” you import the public key into the KeyOS platform and if there were no errors, you will see a success message in the usual place for KeyOS console notifications in  the upper right corner.

Note: It may take up to 10 minutes for newly imported keys to become active. 

Shortly after that, you will be automatically redirected to the list of available Signing Keys where you can remove your keys or alter their state:

Figure 3. Signing Keys available in the system.

3. Manually Importing Existing Key

If you want to manually import information about your own Signing Key into the system, for example if you have removed the Signing Key from the system and now want return it, you must register each Signing Key’s corresponding public key in the KeyOS platform.

To register the public key(s), select the "Import Existing Public Key" on the Import Signing Key page and you will see the following form:

Figure 4. Manually Importing the existing Signing Key.

• Public Key - The ASCII PEM-formatted PKCS#8 public key that corresponds to the private key that you want to use to sign the Authentication XML.
• Key Hash - Unique key identifier.
• Key Description - A Signing Key description to help identify the key within the list of other Signing Keys in your account.
• Public Key - The public key you are about to import.
• Is Key Enabled - Flag that defines a key's status, i.e., whether it is enabled and ready to be used, or disabled and any Authentication XML signed using this key is considered invalid.

Browse for the public key and open it to load the information. You will see something similar to what is shown on this image:

Figure 5. Existing Signing Key's public key information.

As you can see, the tool loaded the public key information. The Key Hash was automatically extracted from the name of the file - "0d9d23deb76def4a0d685ee43a7db988.pem.pub" and is valid. If you try to import a valid public key with a filename that doesn't contain a valid hash, you will get the following notice:

Figure 6. Wrong filename notification.

This notification simply means that while your key is valid, the filename doesn't contain the valid hash. If you use this key with the KeyOS Authentication XML generators, they won't be able to pick up the value for the required Authentication XML's RSAPubKeyId field and your Authentication XML will be invalid. Note: this is not an error, but rather a notice. After the import, you can either rename your files (the corresponding private key you use for signing the Authentication XML), or set the RSAPubKeyId field manually in your code to let the KeyOS MultiKey Licensing API know which key you have used to sign the Authentication XML.

If necessary, you can add the description and click “Import” to import the public key into the KeyOS platform. When the import is done, if there were no errors, you will see a success message and will be redirected to the list of available Signing Keys.