3. Using the Handle Administration Tool

The handle administration tool is a graphical utility for performing handle operations. Before using this tool it is important you read How Your Naming Authority is Set Up.

Resolving Handles

The 'Query Handle' button on the main Handle Admin Tool window will display the window below.

Only authenticated users can query restricted handle values(non public read). Other users can query public read handle values. Users can query specific types of handle values or specific index handle values.

Input handle name (NamingAuthority/LocalName)
Type a handle in the 'Handle Name' text box.
Input query indices
Type the indexes of the handle values which you want to query in the 'Handle Index' text field. Use commas to separate multiple index values.
Input query types
Users can select one, more or all handle value types to query by highlighting the types in the 'Handle Type' field.
Input query properties
- Certify -- indicates that the server must return the response message with the digital signature using the server's private key. If the session is used, the server must return the response message with the MAC code using a pre-established session key. On the Session Setup panel, if the "Certified" checkbox is checked, the query will be certified.
- Certify Cache -- will require all cached values returned be signed by the originating server.
- Authoritative -- do not use cache, always retrieve from responsible server.
- Ignore Restricted Values -- Unauthenticated users check this to ignore non-public read handle values. Authenticated users can check this off to retrieve non-public read handle values.
Display handle values
The 'Handle Data' box displays the handle data values being queried. Highlight selected handle values from this list to display their content.
Submit the query
Press the 'Submit' button to process the query. A 'Resolving handle' window with a 'Cancel' button will pop up during processing. You can interrupt the query with the 'Cancel' button. An error message will pop up if the query failed.

Creating a Handle

The 'Create Handle' button on the main Handle Admin Tool window will display the window below.

Only authenticated users can create handles. Every handle MUST have at least one administrator. Every handle has a handle name and a group of handle values. Every handle value has an index, type, data, TTL(time to live), timestamp, permission set and references.

Input new handle name (NamingAuthority/LocalName)
Type a new handle in the 'Handle' text box. Press 'Return'. This will check the authentication information, if left blank, an authentication box will pop up. To change the authentication information between handle creations, select 'Setup' from the main Handle Admin Tool menu, then click 'Authentication'.
Add Handle Data
The 'Add Handle Data' box contains shortcut buttons for quick addition of certain handle types with defaults already set. The 'Add Custom' box is used to add handle values with custom types. Every handle value must have an index to identify it in the handle value group.
- Add Admin: used to create an administrator for the new handle. Every handle MUST have at least one administrator. Every administrator value is made up of a handle and handle value index. The 'Admin ID Index' can be any unique number within the handle data for the handle being created. The 'Admin ID Handle' and 'Admin ID Index' identify either:
  - A public key or secret key that an administrator must authenticate against.
  - An admin group that references (possibly indirectly through multiple admin groups) a handle value with either a public key or secret key that an administrator must authenticate against.
  Be sure to check the appropriate permissions for the administrator handle. The 'More' button to view or modify the Type, TTL, timestamp, permissions, and references related to this handle value.
- Add URL: used for the creation of a URL data type for the new handle. Click the 'More' button to view or modify the Type, TTL, timestamp, permissions, and references related to this handle value.
- Add Email: used for the creation of an email address for the new handle. The 'More' button to view or modify the Type, TTL, timestamp, permissions, and references related to this handle value.
- Add Custom Data: used to create additional data values not shown on the 'Create Handle' window and the customization of permissions and TTL values. This button will bring up the following window:
  
  Select type(HS_ADMIN, HS_SITE, HS_ALIAS, HS_VLIST, HS_SECKEY, HS_PUBKEY, HS_SERV, EMAIL, URL, URN, INET_HOST) in the 'Type' box or input a new one.
  The 'Value Data' button inputs the data corresponding to the type.
  HS_SITE type data adds the site information for naming authority handles to indicate where handles with that naming authority are resolved. The data value must have an index value which can be any unique number within the handle record data. The data version, protocol and serial number are values that have to do with the current handle system version. Check whether the site is a primary or a multi primary. Choose whether the handle will be hashed by the entire handle, just the naming authority, or a local name. Add the IP addresses of the servers that exist in the site. Add attribute value pairs.
  HS_ALIAS type data is used to add a handle alias as a handle value.
  HS_PUBKEY type data adds a public key as handle value. Generate key pairs (private key, public key) using the 'Generate Key Pair' button. Load a public key from the file system using the 'Load Key' button then add the public key to the key field. Click the 'Clear' button to clear the key field. Click the 'Ok' button to confirm.
  HS_VLIST type data is used to define administrator groups with a list of other handle values.
  HS_SECKEY type data adds a secret key as handle value. Generally, you should check the 'public read permission' off.
  HS_SERV type data is a handle value which has the site information.
  URN type data is a handle value which stores a URN.
  INET_HOST type data is a handle value which has an IP address or host name.
Handle Data View
This box displays the handle data values being added. The 'Modify' button allows you to change the selected handle value. The 'Remove' button allows you to remove the selected handle value. The 'View' button allows you to view the selected handle value. The 'Clear All' button allows you to remove all handle values.
Save and Load
The 'Save' button allows you to save the handle values to a file. The 'Load' button allows you to load the handle values from a file, and append those values to the current handle value group or reset them as the current handle value group.
Submit the created handle
Press the 'Create' button after the addition of all the handle values is complete. This will respond with an indication of success or failure. The absence of an administrator and a handle name is considered a failure.

Modifying a Handle

The 'Modify Handle' button on the main Handle Admin Tool window will display a window that looks much like the handle creation window. To modify a handle, first type it into the text box at the top of the window. Then hit the ENTER key to retrieve the handle's current values. You can then operate on the handle using the modify, remove, and add buttons.

It is important to note that the handle will be modified after each operation. If you plan on replacing an admin value, you should always add the new value first, then remove the old.

Removing a Handle

The 'Remove Handle' button on the main Handle Admin Tool window will display a simple window for handle deletion. Enter in the handle to remove into the text box at the top of the window. Then hit the ENTER key to view the handle's current values. Finally, click the 'Remove' button to delete the handle.

Running Batch Files

The 'Run Batch' button on the main Handle Admin Tool window will display a window for submitting batch files. Only authenticated users can submit batch files. Batch files need to follow the file format described in the 4. Batch Operation. Every batch file can include more than one kind of handle operation (CREATE, DELETE, ADD, REMOVE, MODIFY, HOME, UNHOME). Users can authenticate themselves either through the batch files or through the GUI tools.

Load Batch file

Click the 'Add' button to enter the batch file path. This will be added to the batch file list window. Click the 'Modify' button to change the selected file's path. Click the 'Remove' button to delete the selected file's path from the list. Click the 'View' button to view the selected batch file's path fully without editing. Click the 'Clear All' button to delete all files from list.

Authenticate

There are 2 ways to authenticate:

Select 'Setup' from the main Handle Admin Tool menu, then click 'Authentication'.
Include authentication information in the batch file as in the 'Authentication Information Format' section above.

Batch Submission Log

There will be output from the batch submission. Select the corresponding radio button to output the log information to a specified file, to stdout, or to the log window. If you chose to output the log to a file, enter the log file path. There are three types of log messages:

'SUCCESS' means the operation completed successfully.
'FAILURE' means the operation failed.
'INVALID' means the format of the operation was invalid.

Submit Batch

Click the 'Submit Batch' button to submit the batch operation. If you want to interrupt the batch submission process, click the 'Stop Batch' button.

Homing a Naming Authority

"Homing" a naming authority on a particular site tells the server(s) that make up the site that they are responsible for the given naming authority. This way, when a resolver comes along and asks for a handle under that naming authority, the server can say "here it is" or "it doesn't exist" or even "Why are you asking me? I don't have it."

If you enter the naming authority handle as well as the address and port number of one of the primary servers for the desired site, this tool will "home" the given naming authority to that site. A message will be sent to each server in the site indicating that that site will now be responsible for the given naming authority. From then on that server will accept and handle requests for the given naming authority.

Unhoming a Naming Authority

"Un-homing" a naming authority on a particular site tells the server(s) that make up the site that they are no longer responsible for the given naming authority, and that they should behave accordingly.

If you enter the naming authority handle as well as the address and port number of one of the primary servers for the desired site, this tool will "unhome" the given naming authority on that site. A message will be sent to each server in the site indicating that that site will no longer be responsible for the given naming authority. From then on that server will reject requests for the handles under the given naming authority.

Backing Up a Server

The Backup Server function of the admin tool sends a request to a server to checkpoint its internal handle database. In order to be able to checkpoint a server, the administrator must be identified as an administrator for that server (in the backup_admins section of the `config.dct' file on the server).

The checkpoint operation consists of several steps. Upon receiving an authenticated request to backup the database, the server will

Copy the main database files (`handles.jdb' and `nas.jdb') to backup files (`handles.bak' and `nas.bak')
Reset the transaction log (`dbtxns.log')

After these steps the `handles.bak' and `nas.bak' files can be safely copied to another location for a backup. The `dbtxns.log' file will contain all of the changes made to the database since the `handles.bak' and `nas.bak' files were made. The `dbtxns.log' file will allow you to restore the backup up to the last transaction that was successfully performed if something were to go wrong with the main database.

To perform the checkpointing, enter the IP address and port number of the server that you want to perform the checkpoint operation.

Note: During the checkpoint process, the server will reject all requests to create, modify, or delete handles. For this reason, it is usually preferable to perform the checkpoint operation when there is little administrative activity on the server. Checkpoint operations should only be performed on primary servers since secondary servers do not keep transaction logs for their databases.

To recover the database using the backup files and transaction log you can perform the following steps:

Make sure that the server is NOT running.
Make extra copies of all files (doesn't hurt to be safe!)

Run the command:

  java -cp handle.jar net.handle.apps.tools.RecoverJDB  <server_dir>

Restart the server. The server should now have its database restored to it's pre-disaster state.

Listing Handles on a Server

The "List Handles" function of the admin tool sends a request to a service to list all of the handles for a specific naming authority. In order to be able to list handles the administrator must have the "List Handles" permission enabled in the naming authority handle.

To list handles, select 'Server Admin' from the main Handle Administration Tool menu, then click 'List Handles'.

The List Handles function is implemented in the most recent CNRI handle server, but if your handle database is very large, the list handles command may time-out since the database used by the CNRI handle server is not optimized for this kind of operation.

Authentication

In order to authenticate, the user will need a handle value and its associated secret key or private key.

To authenticate, select 'Setup' from the main Handle Administration Tool menu. Select 'Authentication'. Select the Authentication Type of 'Secret Key' or 'Public Key'. Enter the 'ID Handle' and 'ID Index'. Enter the 'Private Key File' path or the 'Secret Key'. Click 'OK' to begin authentication or click 'Cancel' to cancel it.

Generate Key Pairs

This window will enable the generation of a public key pair. Please reference Overview: Authentication and Security: Authentication for more information.

To generate key pairs:

Select 'Setup' from the main Handle Administration Tool menu.
Select 'Generate Key Pairs'.
Enter the paths of the private and public key files in the corresponding text fields or use the 'Browse' button to find the files.
Select the Algorithm to be used.
Enter the Strength of the key pair to be generated. The key length is variable from 512 to 1024 bits. The default is 1024 bits. The longer the length, the stronger the key pairs.
Select 'Encrypt' or 'Do not encrypt' of the private key. Encryption of the private key requires that you choose a secret passphrase that will need to be entered whenever authenticating using this key pair.
Click 'GenKeys'.
If 'Encrypt' was selected, a window will prompt you to enter your secret passphrase.
A message will confirm the generation of the keys. Click 'Close' to exit the 'Generate Key Pair' window.

Using Sessions

Sessions reduce the authentication processing time for performing a sequence of administrative operations. Sessions also enable encrypting transactions between the client and hosting server.

Authenticated users establish a session with a server by selecting the desired session mode from the "Session Mode" list and setting session attributes. Each user explicitly sets session setup options via this panel. The Session Setup panel is displayed below.

To enable sessions:

Choose a session mode
Note that not all modes may be available.
- Choosing a session mode of "disabled" will turn off sessions. The handle tool will use the standard method of communication with the server.
- Choosing a session mode of "Diffie-Hellman" will use a public key pair supplied by the Handle Admin Tool. This is the simplest mode to configure.
- Choosing a session mode of "client cipher" will use a public key pair supplied by the client. You must specify files for a public and private key pair in order to use this mode.
- Choosing a session mode of "cipher reference" will use a public key stored in a handle. You must specify the handle that contains this public key, the index at which the key is stored, and a file that contains the corresponding private key in order to use this mode.
Specify session options
These controls are for specifying session options.
- Encrypted - allows you to specify that all session messages from the server must be encrypted using the session key.
- Certified - allows you to specify that all session messages from the server must be certified with a (MAC code) using the session key.
- Max lifetime - allows you to specify a session time out in minutes. The default sets a server session time out, usually 24 hours(3600 minutes). Invalid characters are 0 and negative numbers. Very large numbers will not validate, and the default time out (or previous setting) will be used.
'Ok' your session setup information
Click the 'Ok' button to save your session setup information. All the parameters will be validated, and error messages will be displayed. Your new parameters for the session will take effect when your next administrative operation is executed.
'Cancel' your session setup information
Click the 'Cancel' button to cancel the session setup changes.

Console

The Console Window displays debugging messages concerning requests sent to a handle server such as resolution. This is useful to see where server packets are sent in the process of handle administration and/or resolution.

To display the console:

Select 'Setup' from the main Handle Administration Tool menu.
Select 'Show Console'.

Previous: Creating a Handle

Next: Batch Operation

Table of Contents