Batch Submission

Only authenticated users can submit batch files. Batch files need to follow the batch file format. 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.

Batch File Formats
Load Batch file
Authenticate
Submit Batch
Log files

To submit a batch:

Batch File Formats
Users need to create a batch file before using the batch submission tool. All batch files are plain text format. One batch file could have more than one handle operation. The handle operations are: Create Handle, Delete Handle, Home/UnHome Naming Authority Handles, Add Handle Values, Remove Handle Values, Modify Handle Values, Authenticate User, Setup Session.
If you need to change authentication for subsequent batch operations, the new authentication information should be put before the batch block. If you authenticate during the batch submission, then you need not include the authentication information in the batch file.
- Create Handle Batch Format
  Operation name is 'CREATE'.
  The first line is composed of the following:
  CREATE + space + handle_name
  
  The next lines are handle value lines. There must be a handle value 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_PUBKEY, HS_SITE, HS_SERV, HS_ALIAS, EMAIL, URL, URN, INET_HOST. 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 data. 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 0.NA/TEST.ts1
  100 HS_ADMIN 86400 1110 ADMIN 300:111111111111:0.NA/TEST.ts1
  300 HS_PUBKEY 86400 1110 FILE c:\somewhere\pubkey.bin
  101 HS_ADMIN 86400 1110 ADMIN 301:111111111111:0.NA/TEST.ts1
  301 HS_SECKEY 86400 1110 FILE my_password
  1 HS_SERV 86400 1110 UTF8 0.NA/TEST
  3 URL 86400 1110 UTF8 http://www.cnn.com
  4 EMAIL 86400 1110 UTF8 hdladmin@cnri.reston.va.us
```
- Delete Handle Batch Format
  Operation name is 'DELETE'. This operation deletes an existing handle completely.
  Every line should resemble the following:
  DELETE + space + handle_name
```
Example:
  DELETE TEST/ts1
  DELETE 0.NA/TEST.ts1
```
- Home/UnHome Naming Authority Handle Batch Format
  Operation name is 'HOME' or 'UNHOME'. This operation associates server information with a specified naming authority. It only works on existing naming authority handles and active handle servers. It tells the server which naming authority handles will be homed or unhomed to it.
  The first line provides the service information:
  HOME/UNHOME + space + server_ip:server_port:communicate_protocol(tcp,udp,http)
  
  The next lines provide the naming authority handle names which will be homed/unhomed at this server.
```
Example:
  HOME 10.27.10.28:2641:TCP
  0.NA/TEST1
  0.NA/TEST1.t1

  UNHOME 10.27.10.28:2641:TCP
  0.NA/TEST1
  0.NA/TEST1.t1
```
- Add Handle Value Batch Format
  Operation name is 'ADD'. This operation adds new handle values to an existing handle.
  The first line is composed of the following:
  ADD + space + handle_name
  
  The next lines are handle value lines. There must be a handle value 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_PUBKEY, HS_SITE, HS_SERV, HS_ALIAS, EMAIL, URL, URN, INET_HOST. 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 data. See the 'Handle Value Line Format' section below for more detail.
```
Example:
  ADD TEST/ts1
  5 URL 86400 1110 UTF8 http://www.handle.net/admin.html
  6 EMAIL 86400 1110 UTF8 hdladmin@cnri.reston.va.us

  ADD TEST/ts2
  5 URL 86400 1110 UTF8 http://www.cnn.com/entertainment.html
  6 URL 86400 1110 UTF8 http://www.cnn.com/show.html
  7 EMAIL 8600 1110 UTF8 hdladmin@cnri.reston.va.us
```
- Remove Handle Value Batch Format
  Operation name is 'REMOVE'. This operation removes one or more handle values from an existing handle.
  Every line should resemble the following:
  REMOVE + space + indexes:handle_name
  Each index is separated by ','.
```
Example:
  REMOVE 5:TEST/ts1
  REMOVE 5,6,7:TEST/ts5
```
- Modify Handle Value Batch Format
  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 are handle value lines. There must be a handle value line to define the administrator of the handle.
  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_PUBKEY, HS_SITE, HS_SERV, HS_ALIAS, EMAIL, URL, URN, INET_HOST. 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 data. 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/entertainment.html
  3 URL 86400 1100 UTF8 http://www.cnn.com/newshow.html
```
- Authentication Information Format
  Operation name is 'AUTHENTICATE'.
  - For secret key authentication:
    First line: AUTHENTICATE + space + SECKEY:admin_index:admin_handle
    Second line: password
```
Example:
  AUTHENTICATE SECKEY:301:0.NA/TEST.ts1
  my_password
```
  - For private key authentication:
    First line: AUTHENTICATE PUBKEY:admin_index:admin_handle
    Second line: private_key_file_path + '|' + passphrase (If your private key was created and encrypted by passphrase)
    Second line: private_key_file_path (If your private key was NOT created and encrypted by passphrase)
```
Example:
  AUTHENTICATE PUBKEY:300:0.NA/TEST.ts1
  c:\home\keyfile|my_pass_phrase

  AUTHENTICATE PUBKEY:300:0.NA/TEST.ts1
  c:\home\keyfile
```
- Session Setup Information Format
  Operation name is 'SESSIONSETUP'. Specify mandatory "USESESSION" flag. Specify optional RSA public key pair information, session attributes such as "Encrypted", "Authenticated", and "If session fails, use challenge response" flags, and "TIMEOUT".
  The first line is composed of the following:
  SESSIONSETUP
  
  Use the following lines to specify mandatory and optional session setup data:
  USESESSION:<session_on_or_off_flag>
  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
  
  End the SESSIONSETUP operation with a blank line.
  
  In the above lines, the "USESESSION:" flag is mandatory. Either "PUBEXNGKEYFILE:" or "PUBEXNGKEYREF:", and "PRIVEXNGKEYFILE", "OPTIONS:", "TIMEOUT:" are optional. "PASSPHRASE:" is conditional.
  
  If "OPTIONS:" is omitted, session messages will NOT be "encrypted", and NOT "authenticated" ; however, the "if session fails, use challenge response model" flag will be set to make sure requests carried through without session.
  
  The "SESSIONSETUP" line must come first. The remaining lines can be in any order. Do not include a blank line until it ends.
```
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.
- Handle Value Line Format
  Each 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_SECKEY, EMAIL, URL, HS_PUBKEY, URN, HS_SERV, HS_VLIST, HS_ALIAS, INET_HOST.
  
  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_index:admin_permission_set + admin_handle
    The admin permission set is twelve characters with the following order: add_handle, delete_handle, add_naming_authority, delete_naming_authority, modify_values, remove_values, add_values, read_values, modify_administrator, remove_administrator, add_administrator and list_handles.
  - If the handle value type is one of HS_SECKEY, HS_SERV, HS_ALIAS, EMAIL, URL, URN, and INET_HOST its data will be a string. The value_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;
```
Examples:
  Handle value data is an administration record:
    100 HS_ADMIN 86400 1110 ADMIN 300:110011111111:0.NA/TEST.ts1
   Explanation:
    100 is index;
    HS_ADMIN is type;
    86400 is the time to live in cache in seconds;
    1110 is the value permissions which allow admin write, admin read, public read;
    ADMIN indicates that this value data is an administrator record;
    300 is the administrator handle index;
    110011111111 defines the administration permissions (add_handle, delete_handle, 
        no add_naming_authority, no delete_naming_authority, 
        modify_values, remove_values, add_values, read_values, 
        modify_administrator, remove_administrator, add_administrator, list_handles);
    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 a local file:
    300 HS_PUBKEY 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: 
  100 HS_ADMIN 86400 1110 ADMIN 300:111111111111:0.NA/TEST
  1 HS_SITE 86400 1110 FILE c:\somewhere\siteinfo.bin
  2 HS_SERV 86400 1110 UTF8 0.NA/TEST		
  300 HS_PUBKEY 86400 1110 FILE c:\somewhere\publickey.bin  
  301 HS_SECKEY 86400 1100 UTF8 my password  
  400 HS_VLIST 86400 1110 LIST 300:10.ADMIN/USER1; 300:10.ADMIN/USER2;
  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
```
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 the 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 shown 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.

Home

hdladmin@cnri.reston.va.us