Shaman  >  Setup  >  Key management

Shaman Setup is a graphical utility that supports end users with SSH Key management, including enabling or disabling OpenSSH access to remote servers. The private side of the SSH Key pair always remains encapsulated in a cryptographic token.

intro  usage  setup  product info

This window lists the SSH Keys that are currently available on the token that is selected under the Token list tab. Most users will setup a single SSH Key here, which can be used to access a diversity of servers using the Remote server tab.

• Login enables the Shaman to access user functions on the token.
• Logout disables the Shaman from access to user functions on the token.
• Create creates a new SSH Key on your token.
• Destroy destroys an SSH Key stored on your token.
• Export provides advanced users with detailed information about the SSH Key.

This software has been constructed to make it safe to use tokens with pre-created SSH Keys. This is because the software can verify that the private key has never been anywhere but encapsulated inside the token -- and if not, the problems are logged.

A system administrator or a token vendor may thus create SSH Keys on the token to simplify matters for end users. The system administrator can install such SSH Keys on the servers to which the user can have access, even before handing out the token. All this could greatly simplify matters for the end user.

Login to your token

The Login button is needed to gain privileged access to the token. This is needed to create or destroy SSH Keys on the token. Please note that the Shaman is a different program from the agent that runs in the background, and as a consequence it must login separately.

When you click the Login button, you will be prompted to enter your token's PIN. This popup looks like:

The logged-in status automatically ends when the token is removed, although the display will not follow that change. After clicking the Reload button under the Token tab your display will show that you are logged out of the token.

Logout from your token

The Logout button ends privileged access to the token by the Shaman. Please note that the Shaman is a different program from the agent that runs in the background, so the Logout button only disables the creation and destruction of SSH Keys, not the unrelated rights of remote server access.

Back to screenshot (logged out)

Create a fresh SSH Key

The Create button is used to create a fresh SSH Key on the token. This operation creates a so-called key pair, which consists of a private key and a related public key. The private key is generated inside the token which is usually well-protected, and it will always remain there.

The public key from a key pair can be exported from the token without fear for security matters. Most usefully, it can be installed in the proper location on a server system, where it will be used to identify your hardware token when you try to login. The private key that is only available in the token is a necessary part of such authentications, so that you will need the token for such forms of login. Intermediate networks need not be trusted for this form of authentication remain reliable!

When you create a key pair, you must provide two strings that refer to the SSH Key. One string is the key identifier, which is used to uniquely identify the key pair on the token. The other string is a key description, which is an informal string for your own tracking purposes. Most users set the identifier to their email address and the description to their name, sometimes with an additional note such as Work.

In the SSH Key Generator popup, there are a few toggles that indicate technical quality aspects that help protect the private key. The software verifies these to ensure that your token is as secure as may be expected. The OK button is only clickable if all three issues are checked. If any of the toggles should ever remain unchecked, you may opt to check it yourself and verify whether this was indeed correct before actually relying on the SSH Key.

Once the OK button is clicked, the token suddenly gets very busy, sometimes for a few minutes. The Shaman display is frozen while it awaits the token's response. Please wait patiently, this can take a while because it is a security-intensive process. This is just a one-time effort for most people, the repetitive actions of access to a remote server will be much faster.

It is possible to have multiple SSH Keys on one token. The value of this flexibility is quite limited, and it could be somewhat confusing. The rule to keep in mind is that a remote login succeeds if at least one of the SSH Keys on the token is enabled for access to that remote server.

Back to screenshot

Destroy an SSH Key

The Destroy button is used to completely terminate the use of an SSH Key. Since this thoroughly destroys the private key (that has never been exported off the card), no further logins will ever be possible with a destroyed SSH Key. This is even true if remote servers still have the SSH Key enabled.

This means that destroying an SSH Key can have quite some impact. Sometimes this is desirable, on other occasions it is too much. You will therefore be prompted to confirm your action. As a finer-grained alternative, you may want to use the Disable button under the Remote server tab.

Back to screenshot

Export SSH Key descriptive information

The Export button can be used to extract information about the public SSH Key from the token. Advanced users can use this information to manually enable or disable SSH Keys for server access. But most users will prefer to do this with the Enable button under the Remote server tab.

Back to screenshot

When the Export button is clicked, a popup appears that exports the requested key information. It taps directly into the token, so the popup only appears after a few seconds. It has a pulldown menu that allows you to switch to another representation which, again, will take a few seconds to complete.

Export formats available are OpenSSH public key, SECSH public key, Key Fingerprint and Bubble-Babble Digest.

The OpenSSH public key export shows the public key as an OpenSSH-styled `blob' which is one long line. The GUI breaks that line for presentation reasons. This key could be manually installed in the remote account's file .ssh/authorized_keys to allow access with this key to an OpenSSH server.

The SECSH public key export is an alternative representation of the `blob' with the public key. It is used by the commercial SSH version. This multi-line information can be manually installed in .ssh2/keyname.pub on a commercial SSH server, after which it is mentioned with a line Key keyname.pub in the file .ssh2/authorization on the remote account.

The Key Fingerprint export provides a common way to quickly identify a key without having to verify the entire `blob' formats of OpenSSH or SECSH. The format is constructed using the MD5 secure hash algorithm, so that you may reasonably assume that two keys are the same if their fingerprints are the same.

The Bubble-Babble Digest export is a common way to quickly identify a key without having to verify the entire `blob' formats of OpenSSH or SECSH. The format is constructed using a funny write-up of the SHA1 secure hash algorithm, so that you may reasonably assume that two keys are the same if their fingerprints are the same.

The differences between the fingerprint and Bubble-Babble are not very big. The latter is more secure, but most importantly the printed format is much easier to handle for humans. If you have a choice, use Bubble-Babble.

The Copy button is available for all the export formats. It copies the currently presented information to your desktop's clipboard, so you can paste the text into any other application.

The clipboard receives the text with proper line breaking, and it may appear slightly different from the display in the exporter window. The clipboard is right in such cases. Do keep in mind though, that the application into which it is pasted should not add any line-breaks of its own, as this may cause problems. In case of doubt about added line-breaks, resize the window into which it was pasted, and/or try to paste into two differently sized windows.

Back to screenshot