Welcome to the Handle System Administration Tool. This tool was developed for current users of CNRI's Handle System Server (HSj 5.2). The functions listed below allow authorized users (Administrators) to create, modify, and delete handles as well general users to resolve handles. The Help text can be accessed under each of the functions by pressing the Help button at the top of the active window.
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.
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.
backto: Create Handle HelpWhen 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 authenticaion 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.
backto: Create Handle HelpThe '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.
a) a public key or secret key that an administrator must authenticate against, or
b) 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.
'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 a handle value. You could generate key pairs here(private key,public key) through 'Generate Key Pair' or load pubic 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 adminstration groups with a list of other handle values.
'HS_SECKEY' type data adds a secret key as a handle value. Generally, you should check the 'public read pemission' off.
'HS_SERV' type data is a handle value which has the site inforamtion.
'MORE_DATA_TYPE' you could input your own (custom) data type here.
This box displays the handle data values being added.
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 all steps from entering the new handle name.
Press the 'Close' button when the transaction has been completed.
backto: Create Handle HelpOnly authenticated users can edit handles, by adding, changing, and removing values. 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 and references.
Type a handle in the 'Handle Name' text box.Pressing 'Return', will check the authentication information and fetch the handle values. If left blank, an authentication box will pop up. The 'Change Authentication' button can be used to change the authentication information.
After authentication approval, all handle values will be displayed at the data list field. Without proper authentication only the 'public read' values will be displayed.
backto: Modify Handle HelpWhen an 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 authenticaion or Click 'CANCEL' to cancel it. When authenticationIS approved, a window will pop up, you could click its 'Cancel' to interrupt the process. If the values entered are incorrect, an unsuccessful message will appear.
backto: Modify Handle HelpThe '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.
The add value request will be sent to handle system.
add 'HS_ADMIN", is used to create an administrator for the 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. The 'Admin ID Handle' and 'Admin ID Index' identify either
a) a public key or secret key that an administrator must authenticate against, or
b) 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.
add 'URL', is used for the creation of a url data type for
the handle.
'More' button to view or modify TTL, timestamp, permission
references related to this handle value.
add 'EMAIL', is used for the creation of an email address for the
handle.
'More' button to view or modify TTL, timestamp, permission
references related to this handle value.
is used for to create additional data values not shown in the 'Shortcuts' box and the customization of permissions and TTL values. 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. 'Value Data' button to input the data correspondent 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 server's ip addresses that exist in the site. Add attribute-value pairs.
'HS_DSAPUBKEY' type data adds a public key as a handle value. You could generate key pairs here(private key, public key) through 'Generate Key Pair' or load pubic key from file 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 adminstration groups with a list of other handle values.
'HS_SECKEY' type data adds a secret key as a handle value. Generally, you should check the public read permission off.
'HS_SERV' type data is a handle value which has the site information.
'MORE_DATA_TYPE' you could input your own un-pre-defined data type here.
This box displays the handle data values being added.
'SaveToFile' button will allow saving the handle values to a file
Redo all steps from entering the new handle name.
Press the 'Close' button when the transaction has been completed.
back to: Modify Handle HelpOnly authenticated users can remove an existing handle.
Type a new handle in the 'Handle Name' text box.By pressing 'Return', the authentication information is checked, if the text box is empty, you will need to enter the information. The 'Change Authentication' button can be used to change the authentication information.
The handle values will be fetched and displayed in the List field.
back to: Remove Handle HelpWhen an 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.
back to: Remove Handle HelpPress the 'Remove Handle' button to confirm the remove operation. It will respond with an indication of success or failure.
Redo all steps from entering the handle name.
Press the 'Close' button when the transaction has been completed.
back to: Remove Handle HelpOnly 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.
Type a handle in the 'Handle Name' text box.
back to: Query Handle Help'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.
back to: Query Handle HelpType the indexes of the handle values which you want to query in the 'Handle Index' text field. Use commas to separate multiple index values.
back to: Query Handle HelpUsers could select one, more or all handle value types for query by highlighting the selected types in 'Handle Type' field.
back to: Query Handle Help'Certify' --
'Certify Cache' --
'Authoritative' --
'Encrypt' --
'Ignore Restricted Values' -- Unauthenticated users check this to ignore non-public read handle values. Authenticated users could check this off to get non-public read handle values.
back to: Query Handle Help'Handle Data' box displays the handle data values being queried. Highlight selected handle values from this list to display their content.
back to: Query Handle HelpPress the 'Submit' button to process the query, a window with 'Cancel' button will pop up during processing. You could interrupt the query through the 'Cancel' button. An error message will pop up if the query failed.
Redo all steps from entering the new handle name.
Press the 'Close' button when the transaction has been completed.
back to: Query Handle Help
Users need to create a batch file before using the batch submission
tool. All batch files are general text format. One batch file could have
more than one handle operation. The handle operations are:
Create Handle,
Delete Handle,
Home/UNHome Naming Authority Handle,
Add Handle Value,
Remove Handle Value,
Modify Handle Value,
Authenticate User.
Each operation has a different batch format.
If you need to change authentication for subsequent batch operations,
the new authentication information should be put before the batch block.
You could authenticate during the batch submission, then you need not include
the authentication information in the batch file.
Operation name is 'CREATE'. The first line is composed of the following:
CREATE + space + handle name
The next lines contain the handle value types and their data. There must
be a line to define the administrator of the handle. End the CREATE handle
operation with a blank line.
The list of pre-defined handle value types is as follows: HS_ADMIN, HS_VLIST,
HS_SECKEY, HS_DSAPUBKEY, HS_SERV, EMAIL, URL, URN. Each handle value
line must start with a unique index number, followed by the handle value type
from the list above, ttl(the time to live in seconds), the permission
set(admin read, admin write, public read, public write), and the value.
See the 'Handle Value Line format' section below for
more detail.
Example:
CREATE TEST/ts1
100 HS_ADMIN 86400 1110 ADMIN 300:111111111111:TEST/ts1
300 HS_SECKEY 86400 1100 UTF8 my password
1 URL 86400 1110 UTF8 http://www.handle.net
CREATE TEST/ts2
100 HS_ADMIN 86400 1110 ADMIN 300:111111111111:TEST/ts2
1 URL 86400 1110 UTF8 http://www.cnn.com
3 EMAIL 86400 1110 UTF8 hdladmin@cnri.reston.va.us
400 HS_SERV 86400 1110 UTF8 0.NA/TEST
300 HS_DSAPUBKEY 86400 1110 FILE c:\somewhere\pubkey.bin
back to: Batch Handle Help
Operation name is 'DELETE'. This operation deletes an existing handle completely.
Every record is a line with:
DELETE + space + handle name
Example:
DELETE TEST/ts1
DELETE TEST/ts2
back to: Batch Handle Help
Operation name is 'HOME/UNHOME'. This operation associates
service information with a specified naming authority. It Only works on existing naming
authority handles. The first line gives the service information:
HOME/UNHOME + space + ipAddress:portNumber:protocolType(tcp,udp,http)
The next lines give the naming authority handle names which will be
homed/unhomed at this service.
Example:
HOME 10.27.10.28:2641:TCP
0.NA/TEST1
0.NA/TEST1.T1
UNHOME 10.27.10.28:2641:UDP
0.NA/TEST1
0.NA/TEST1.T1
back to: Batch Handle Help
Operation name is 'ADD'. This operation adds a new handle value to an existing handle.
The first line is composed of the following:
ADD + space + handle name
The next lines contain the handle value types and their data. End the ADD
handle operation with a blank line.
The list of pre-defined handle value types is as follows: HS_ADMIN, HS_VLIST,
HS_SECKEY, HS_DSAPUBKEY, HS_SERV, EMAIL, URL, URN. Each handle value
line must start with a unique index number, followed by the handle value type
from the list above, ttl(the time to live in seconds), the permission
set(admin read, admin write, public read, public write), and the value.
See the 'Handle Value Line format' section below for
more detail.
Example:
ADD TEST/ts1
2 URL 86400 1110 UTF8 http://www.handle.net/admin.html
3 EMAIL 86400 1110 UTF8 hdladmin@cnri.reston.va.us
ADD TEST/ts2
2 URL 86400 1110 UTF8 http://www.cnn.com/entertainment.html
3 URL 86400 1110 UTF8 http://www.cnn.com/show.html
back to: Batch Handle Help
Operation name is 'REMOVE'. This operation removes one or more handle
values from an existing handle. Every record is a line with:
REMOVE + space + value indexes:handle name
Each index is separated by ','.
Example:
REMOVE 2:TEST/ts2
REMOVE 2,3,4:TEST/ts5
back to: Batch Handle Help
Operation name is 'MODIFY'. This operation changes one or more handle values
for an existing handle. The first line is composed of the following:
MODIFY + space + handle name
The next lines contain the handle value types and their data. End the
MODIFY handle operation with a blank line.
The list of pre-defined handle value types is as follows: HS_ADMIN, HS_VLIST,
HS_SECKEY, HS_DSAPUBKEY, HS_SERV, EMAIL, URL, URN. Each handle value
line must start with a unique index number, followed by the handle value type
from the list above, ttl(the time to live in seconds), the permission
set(admin read, admin write, public read, public write), and the value.
See the 'Handle Value Line format' section below for
more detail.
Example: MODIFY TEST/ts1 2 URL 86400 1110 UTF8 http://www.handle.net/newadmin.html 3 EMAIL 86400 1110 UTF8 hdladmin@cnri.reston.va.us MODIFY TEST/ts2 2 URL 86400 1110 UTF8 http://www.cnn.com/newentertainment.html 3 URL 86400 1100 UTF8 http://www.cnn.com/newshow.htmlback to: Batch Handle Help
Operation name is 'AUTHENTICATE'.
For secret key authentication:
First line: AUTHENTICATE SECKEY:admin handle index:admin handle name
Second line: password
Example:
AUTHENTICATE SECKEY:300:TEST/ts1
my_password
For private key authentication:
Example:
AUTHENTICATE PUBKEY:300:TEST/ts2
c:\home\keyfile
my_pass_phrase
back to: Batch Handle Help
Operation name is 'SESSIONSETUP'.
Specify mandatory "use session flag", optional RSA public key pair information, and optional session attributes ("Encrypted", "Authenticated", "If session fails, use challenge response" flag, and "Time Out"). End the SESSIONSETUP operation with a blank line.
Use the following format to specify mandatory and optional session setup data:
USESESSION:<session_on_or_off_flag>USESESSION:, is mandatory. Either PUBEXNGKEYFILE: or PUBEXNGKEYREF:, and PRIVEXNGKEYFILE:, OPTIONS: and TIMEOUT: are optional. PASSPHRASE: is conditional.
PUBEXNGKEYFILE:rsa_public_exchange_key_file
PUBEXNGKEYREF:rsa_public_exchange_key_reference_index:rsa_public_exchange_key_reference_handle PRIVEXNGKEYFILE:rsa_private_exchange_key_file
PASSPHRASE:pass_phrase_to_decode_the_private_exchange_key
OPTIONS:<encrypt session flag><authenticate session flag><if session fails, use challenge response model flag>
TIMEOUT:time_out_in_hours
Example 1: use public exchange key from server.
SESSIONSETUP
USESESSION:1
Example 2: use public exchange key from a file (client provides RSA exchange keys.)
SESSIONSETUP
USESESSION:1
PUBEXNGKEYFILE:c:\hs\bin\RSAPubKey.bin
PRIVEXNGKEYFILE:c:\hs\bin\RSAPrivKey.bin
PASSPHRASE:secret
OPTIONS:111
TIMEOUT:24
Example 3: use public exchange key from a handle value reference (client provides exchange keys).
SESSIONSETUP
USESESSION:1
PUBEXNGKEYREF:300:0.NA/TEST.ts1
PRIVEXNGKEYFILE:c:\hs\bin\RSAPrivKey.bin
Please see the Session Setup panel for related information.
back to: Batch Handle Help
Every handle value line is composed of :
value index + space + value type + space + ttl +
space + permission set + space + value data
The value index is a unique integer within the specific handle.
The value types are: 'HS_ADMIN', 'HS_SEKCEY', 'EMAIL',
'URL', 'HS_DSAPUBKEY', 'URN', 'HS_SITE', 'HS_VLIST'.
ttl: handle's time to live in cache counted by seconds. Default is 86400(24 hours).
Permission set: permission values indicated by 4 characters, '1' is
true, '0' is false, order is: admin read, admin write, public read, public write
Value data:
If the handle value data defines an Administrator, its data format is:
ADMIN + space + admin handle index:admin permission set + admin handle name
The admin permission set is 11 characters with the following order: add handle, delete
handle, add naming authority, delete naming authority, modify value, remove
value, add value, read value, modify administrator, remove administrator, and
add administrator.
If the handle value data is a string, its data format is:
UTF8 + space + string content
If the handle value data is a local file, its data format is:
FILE + space + file path
If the handle value data is a value reference list, its data format is:
LIST + space + index1:handle1;index2:handle2;
Example:
Administrator record handle value:
100 HS_ADMIN 86400 1110 ADMIN 300:111111111111:0.NA/TEST
Explanation:
100 is index;
HS_ADMIN is type;
86400 is the time to live in cache in seconds;
1110 is the value permission which allow admin write, admin read, public read;
ADMIN tells this value data is an administrator record;
300 is the administrator handle index;
111111111111 defines the administration permissions;
0.NA/TEST is the administrator handle name;
Handle value data is string:
2 URL 86400 1110 UTF8 http://www.handle.net/
Handle value data comes from local file:
300 HS_DSAPUBKEY 86400 1110 FILE c:\somewhere\pubkey.bin
2 HS_SITE 86400 1110 FILE c:\somewhere\siteinfo.bin
Handle value data is handle value reference list:
1 HS_VLIST 86400 1110 LIST 300:100.ADMIN/USER1; 300:100.ADMIN/USER2;
-------------------------------------------------------------------------------------
Example of all the handle value types:
1 HS_ADMIN 86400 1110 ADMIN 300:111111111111:0.NA/TEST
2 HS_SITE 86400 1110 FILE c:\somewhere\siteinfo.bin
3 HS_VLIST 86400 1110 LIST 300:10.ADMIN/USER1; 300:10.ADMIN/USER2;
4 HS_SERV 86400 1110 UTF8 0.NA/TEST
5 HS_SECKEY 86400 1100 UTF8 my password
6 HS_DSAPUBKEY 86400 1110 FILE c:\somewhere\publickey.bin
7 EMAIL 86400 1110 UTF8 hdladmin@cnri.reston.va.us
8 URL 86400 1110 UTF8 http://www.handle.net
9 URN 86400 1110 UTF8 100/Repository
Clicking 'Add' button to enter the batch file path. This
will be added to the batch file list window. You also could put all batch file paths
in a list file and use 'LoadfromFile' to load and add to the batch file
list window. The 'SavetoFile' allows you to save all file paths in the
file list window into a file for future reference.
There are 2 ways to authenticate: via the tool or from the batch
file. See Authentication Information format above.
Click the 'Submit Batch' button to submit the batch operation.
There will be output from the batch operation. To save successful
messages to your specified Succ Log File and error messages to your specified
Error Log File, you must check 'Save Log File' or the messages will
go to stderr.
"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.
Top"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.
TopThe "List Handles" function of the admin tool sends a request to a service to list all of the handles for a specific naming authority. 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.
TopThe Backup Server function of the admin tool sends a request to a server to checkpoint its internal handle database. To perform a checkpoint, the administrator must be identified as an administrator for that server in the server_admins section of the config.dct file.
The checkpoint operation has two steps. Upon receipt of an authenticated request to backup the database, the server will:
The handles.bak and nas.bak files can be safely copied to another location for storage. 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 database from the backup up, to the last transaction that was successfully performed.
To begin the checkpointing process, enter the IP address and port number of the server. Note: During the checkpoint process, the server will reject all requests to create, modify, or delete handles. Perform the checkpoint operation when there is little administrative activity. Checkpoint operations should only be performed on primary servers. Secondary servers do not keep transaction logs for their databases.
To recover the database using the backup files and transaction log, perform the following steps:
java -cp handle.jar net.handle.server.RecoverJDB <server_dir>
Using a Session reduces 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.
Check the "Use Session" checkbox to enable the session parameter entries. Each user explicitly sets session setup options via this panel.
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.
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.
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 RDA Key" checkbox, and specify the public key using one the following methods, and specify the private key in the 'Private Exchange Key File' field.
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.
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.
These controls are for specifying session options.
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.
Click the 'Cancel' button to cancel the session setup changes.