6. Batch Operation

It may often be desirable to perform more handle operations than possible by hand. In these cases it is best to use the batch facilities included with the Handle System distribution.

You can submit batches through the Handle Administration Tool, as detailed in the previous section "Using the Handle Administration Tool." You can also submit batches using the GenericBatch command line utility. It can be invoked using the following command:

java net.handle.apps.batch.GenericBatch <batchfile> [<LogFile>]

All batch files are plain text format. One batch file can have more than one handle operations. 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.

6.1 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 line. 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. 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.handle.net 4 EMAIL 86400 1110 UTF8 hdladmin@cnri.reston.va.us

6.2 Delete Handle Batch Format

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 0.NA/TEST.ts1

6.3 (Un)Home Naming Authority 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 server. Tell the server which naming authority handles will be homed or unhome to it. The first line gives the service information:

HOME/UNHOME + space + server_ip:server_port:protocol(tcp,udp,http)

The next lines give 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

6.4 Add Handle 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 line. 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. 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.

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/entainment.html 6 URL 86400 1110 UTF8 http://www.cnn.com/show.html 7 EMAIL 8600 1110 UTF8 hdladmin@cnri.reston.va.us

6.5 Remove Handle Batch Format

Operation name is 'REMOVE'. This operation removes one or more handle values from an existing handle. Every record is a line with:

REMOVE + space + indexes:handle_name

Each index is separated by ','.

Example:

REMOVE 5:TEST/ts1 REMOVE 5,6,7:TEST/ts5

6.6 Modify Handle 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 line. 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. 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/newentainment.html 3 URL 86400 1100 UTF8 http://www.cnn.com/newshow.html

6.7 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: If your private key was created and encrypted by passphrase, then: private_key_file_path + '|' + passphrase.
  Otherwise: private_key_file_path

  Example:

  AUTHENTICATE PUBKEY:300:0.NA/TEST.ts1 c:\home\keyfile|my_pass_phrase AUTHENTICATE PUBKEY:300:0.NA/TEST.ts1 c:\home\keyfile

6.8 Session Setup Information Format

Operation name is 'SESSIONSETUP'. Specify mandatory "using session flag" and optional RSA public key pair information, session attributes such as "Encrypted", "Authenticated", "If session fails, use challenge response" flag and "Time Out".

End the SESSIONSETUP operation with a blank line.

Use the following lines to specify mandatory and optional session setup data:

USESESSION:<session_on_or_off_flag> PUBEXNGKEYFILE:public_exchange_key_file PUBEXNGKEYREF:pub_exchange_key_ref_index:pub_exchange_key_ref_handle PRIVEXNGKEYFILE:private_exchange_key_file PASSPHRASE:pass_phrase_for_private_exchange_key OPTIONS:<encrypt><authenticate><fallback on challenge response> TIMEOUT:time_out_in_hours

In above lines, "USESESSION:" 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 "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 order of the rest of the lines doesn't matter. Don't include any 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

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

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, 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 tells 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 a string:

  2 URL 86400 1110 UTF8 http://www.handle.net/

• Handle value data comes from 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 a handle value reference list:

  1 HS_VLIST 86400 1110 LIST 300:10.50/USR1; 300:10.50/USR2;

• 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.50/USR1; 300:10.50/USR2; 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