[Index]

3. Using the Handle Administration Tool

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

3.1 Resolving Handles

The 'Query Handle' button on the main Handle Admin Tool window will bring up 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 authentication information
'Authentication' button will display an authentication box. When the authentication box appears, choose secret key or public key to authenticate. You must enter a handle, the handle value index and a secret key or load private key in this box. Click 'OK' to begin authentication or Click 'Cancel' to cancel it. Click "Cancel" to interrupt the process. If the values entered are incorrect, an unsuccessful message will appear.
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 for query by highlighting the selected types in 'Handle Type' field.
Input query properties
- Authenticate -- indicates that server must return the response message with the digital signature using server's private key. If the session is used, server must return the response message with MAC code using pre-established session key. On Session Setup panel, if the "Authenticated" checkbox is checked, this "Authenticated" flag will be always checked on this query panel.
- Authenticate Cache -- will require all cached values returned be signed by the originating server.
- Authoritative -- do not use cache, always retrieve from responsible server.
- Encrypt -- indicates that server must encrypt any response using pre-established session key before sending back to client. On Session Setup panel, if the "Encrypted" checkbox is checked, this "Encrypted" flag will be always checked. On Session Setup panel, if the "Encrypted" checkbox is not checked, but client has a valid session setup with "Use Session" checked, this checkbox only be enabled and not checked on this query panel.
- 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 start to process the query, a window with 'Cancel' button will pop up during processing. You can interrupt the query through the 'Cancel' button. An error message will pop up if the query failed.

3.2 Creating a Handle

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. Below is an image of the Handle creation window.

Input new handle name (NamingAuthority/LocalName)
Type a new handle in the 'Handle Name' text box.Press 'Return'. This will check the authentication information, if left blank, an authentication box will pop up. The 'Change Authentication' button can be used to change the authentication information between handle creations.
Input authentication information
When an authentication box appears, choose secret or public key to authenticate. You must enter a handle, the handle value index and a secret key or private key file path in this box. Click 'Ok' to begin authentication or Click 'Cancel' to cancel it. When approving authentication, a pop up window will appear. If you want to interrupt the process, click 'Cancel to interrupt the process. If the values entered are incorrect, an unsuccessful message will appear.
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 Index Value' 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 TTL, timestamp, permissions, 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 TTL, timestamp, permissions, 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 TTL, timestamp, permissions, references related to this handle value.
- Add Custom Data: used for to create additional data values not shown in the shortcut' box and the customization of permissions and TTL values. This button will bring up the following window:
  
  Select type(HS_ADMIN, HS_SITE, HS_VLIST, HS_SECKEY, HS_DSAPUBKEY, HS_SERV, EMAIL, URL, MORE_DATA_TYPE) in '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 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_DSAPUBKEY type data adds a public key as handle value. You can generate key pairs here(private key,public key) through 'Generate Key Pair' or load public key from file system through 'Load Key' and add public key to key field. 'Clear' to clear the key field.'Ok' 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.
Handle Data View
This box displays the handle data values being added. 'Modify' button allows you to change a part of the selected handle value. 'Remove' button allows you to remove the selected handle value. 'View' button allows you to view the selected handle value. 'Clear All' button allows you to remove all handle values.
Save and Load
The 'SaveToFile' button allows saving the handle values to a file. The 'LoadFromFile' button allows loading the handle values from a file, and append to current handle value group or reset as current handle value group.
Submit the created handle
Press the 'Create Handle' button after the addition of all the handle values is complete. This will respond with an indication of success or failure. The absence of a administrator and handle name is considered a failure. Redo creation Redo all steps from entering the new handle name.

3.3 Modifying a Handle

The 'Modify Handle' button on the main Handle Admin Tool window will bring up 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.

3.4 Removing a Handle

The 'Remove Handle' button on the main Handle Admin Tool window will bring up 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.

3.5 Running Batch Files

Only authenticated users can submit batch files. Batch files need to follow the file format described in the section below, Batch Operation. Every batch file can include more than one kind of handle operations (CREATE/DELETE/ADD/REMOVE/MODIFY/HOME/UNHOME). Users can authenticate themselves either through the batch files or through the GUI tools.

3.5.1 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 'Delete' button to delete the selected file's path from list. Click the 'Clear All' button to delete all files from list.

3.5.2 Authenticate

There are 2 ways to authenticate: via the Handle Administration tool's 'Setup-> Authentication' button or through authentication information in the batch file as in the 'Authentication Information Format' section above.

3.5.3 Submit Batch

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

3.5.4 Batch Submission Log

There will be output from the batch submission. You could choose to output log to specified file, to stdout, to log window by selecting the choice. If output log to file, you need to input the log file path. There are three types of log messages:

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

3.6 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 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.server.RecoverJDB  <server_dir>

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

3.7 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. 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.

3.8 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.

3.9 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.

3.10 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 "Use Session" option, generating (or using an existing) exchange key pair, and setting session attributes using the Session Setup panel displayed below.

To enable sessions:

Click the "Use Session" checkbox
Check the "Use Session" checkbox to enable the session parameter entries. Each user explicitly sets session setup options via this panel.
Click the "Use Server RSA Key" checkbox
Check the "Use Server RSA Key" checkbox to use the server's RSA keys for the session exchange keys. (Ensure that the server has a pair of RSA keys before selecting this option.) This is the default setting. Server with session version always has a pair of RSA for exchange keys.
Specify exchange keys by generating RSA key
A server must have a pair of RSA keys in order to exchange a session key with the client. A client that wants to use its own RSA keys must uncheck the "Use Server RSA Key" checkbox, and then click the "Generate Key Pair" button to generate a new pair of RSA keys. When the "Generate Key Pair:" window comes up, choose "RSA" and click "GenKeys". After the keys are generated, close the "Generate Key Pair" window. The two key file names will be populate the "Public key file" and "Private exchange key file" fields.
Specify exchange keys from existing RSA keys
A server must have a pair of RSA keys in order to exchange a session key with the client. If a client wants to use its own RSA keys, and a pair of RSA keys has already been generated, uncheck the "Use Server RSA Key" checkbox, and specify the public key using one the following methods, and specify the private key in the 'Private Exchange Key File' field.
- From Authentication Info' radio button
  Select the "From Authentication Info" radio button if the public exchange key can be obtained from the Handle and Index fields of authentication information. The authentication information must contain an RSA key.
- 'Public Key File' radio button and text field
  Select the "Public Key File" radio button and input the file name, if the public exchange key can be obtained from a file. Type the name of the public key file into the text field, or use the "Browse" button to find the public key file. The file must contain a public RSA key.
- 'Public Key Reference' radio button and handle/index fields
  Select the "Public Key Reference" radio button and fill in the handle and index text fields if the public exchange RSA key can be obtained by server in a handle value reference. The handle value reference must contain a public RSA key.
- 'Private Exchange Key File' text field
  Type the name of the private exchange file in the text field or use the "Browse" button to find the private key file. The file must contain a private RSA key. The private file can be either encrypted or non-encrypted.
Specify session options
These controls are for specifying session options.
- 'Encrypted' checkbox
  Allows you to specify that all session messages from the server must be encrypted using the session key. The default is "not encrypted".
- 'Authenticated' checkbox
  Allows you to specify that all session messages from the server must be authenticated (MAC code) using the session key. The default is "not authenticated"
- 'If session fails, use challenge response model' checkbox
  Allows you to specify that if communication errors occur during the session, use the challenge response model to process the request. Set this flag if you want your request be processed even if session fails. The default is "not to continue with a challenge response model if session fails". If the server has not been upgraded to a version that has implemented sessions, you will get an "Incomplete Session Setup" error from the client library when you attempt to use a session. You may want to check this flag, then try your request again.
- 'Time Out' text field
  Allows you to specify a session time out in hours. The default sets a server session time out, usually 24 hours. 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.

[ << ] [ >> ] [Top] [Contents] [Index] [ ? ]