Handle System Web Admin App
Version 0.9 beta
Adding a URL Value to a Handle
Sending Requests to a Different Handle Server
Locate the file admin.war in the top level of the handle server distribution directory. There is a folder called "webapps" in your handle servers storage directory. Copy the admin.war file into the webapps folder. You do not need to restart your handle server. If your handle server is running it will notice the new web app after a few seconds and load it.
Open a web browser (Chrome or Firefox recommended) and enter the following URL:
https://<ipaddress-of-your-handle-server>:8000/admin
If you changed the default http port on your handle server to something other than 8000 use the http port your handle server is listening on.
The handle server is using a self signed certificate so you will have to accept the certificate the first time your visit the site.
Click the "Authenticate" button top right. This will show the "Authenticate" dialog below.
When you registered your prefix a handle was created on the root. That is you prefix handle. It will have the from 0.NA/<your-prefix>. Your prefix handle contains the admin public key that corresponds with your admin private key.
Enter your prefix handle in the handle box on the right. e.g. 0.NA/<your-prefix>
Click the "Select private key" button and select your admin private key file. It is called "admpriv.bin" and can be found in your handle server directory. Once you have selected the private key click the "Authenticate" button.
Authentication does not send you private key to the server, rather the private key is used solely in the browser and authenticates using a cryptographic challenge response protocol.
A handle server needs to be told which prefixes it is responsible for. This step is called "homing a prefix". If you have not already homed your prefix on your handle server the web admin app will detect this and show the "Home Prefix" tool when you authenticate. You can also manually bring up this tool by selecting Tools->Home Prefix.
Enter your prefix in the text box and click the "Home Prefix" button.
You can then verify that your prefix is homed by selecting Tools->List Prefixes and click the "List Prefixes" button.
At the top of the app you will see a tool for creating and resolving handles. To create a handle record enter the handle you want to create in the text box:
The handle you create should start with your prefix. In this example my prefix is "cnri.test.ben". After you enter the handle click the green "Create" button.
The handle was created with a single value of type HS_ADMIN. This value defines who can do what to the handle.
In some cases it is desirable to atomically create a handle fully formed with all of its values rather than to create a handle record on the server and then as a separate operation add its values. In such cases you can click the "Create without saving" button instead of the "Create" button. This will open the handle editor in the browser and let you edit a handle before it is created. When you are ready click the "Save" button to save and create the handle in a single atomic operation.
It is considered best practice for the suffix of a handle to be opaque. If you want to create a handle with a random opaque suffix, rather than defining the suffix your self, you can click the "Create With Random Suffix" button instead of the "Create" button. You still need to provide the prefix the handle will be created under and you need to include the slash. For example if you enter:
12345/
Click the "Create With Random Suffix" and you will get a handle with a new UUID as the suffix similar to this:
12345/e1ec2e3e-c0fd-4c38-afb9-99055bc9458c
One of the most common uses of handles it to point at a URL. This is done by adding a value to the handle of type URL. Once you have created a handle click in the "Create new value" select box and select the type "URL".
Specify the URL you want the handle to point at and click the green "Save handle" button to persist the change. You can now resolve this handle at the proxy http://hdl.handle.net and it will redirect you to the URL value in the handle.
Changes made to a handle are local in the client until you click the save button. An asterix is prepended to the handle to indicate that there are unsaved changes.
To resolve a handle enter the handle in the resolution bar at the top of the screen and click the blue "Resolve" button.
To delete a handle first resolve it and then in the handle editor click the red "Delete" button. Note that you need to be authenticated in order to delete a handle.
Click the "Tools" menu and select "List Prefixes". This will show the list prefixes tool. Click the "List Prefixes" button to show all prefixes listed on the current server. If there are more prefixes that can be shown a paginated navigation is provided. If you click on a prefix the list handles tool will be shown listing the handles under that prefix.
Click the "Tools" menu and select "List Handles". This will show the list handles tool. Enter the prefix for the handles you want to list and click the "List Handles" button. If you click on a handle it will be resolved and show in the handle viewer/editor.
By default the admin app is configured to send requests to the "Source server". The "Source server" is the handle server hosting the admin app (your handle server). However the web based handle admin app can administer any version 8 handle server on the Internet. Select Tools->Query Specific Site.
By default the admin app will only send requests to your handle server (The "Source" option). By setting the Query Specific Site tool "Global" you can resolve any handle in the handle system. If the handle is stored on a handle server that is older than version 8 the admin app will automatically fall back to resolving the handle at the proxy. When the "Global" option is selected and a resolution is performed the root handle service is queried first to determine the specific site to perform the operation at and then the request is sent to that specific site. You can see below an image of admin app resolving the handle 4263537/5555.
Note that if you resolve a handle through the proxy it will be displayed in view only mode.
If you want to send administrative requests such as list handles or home prefix to a different handle server you can specify the target server either by ip:port or by site value in handle.
You can always see at a glance which site you are talking to by looking at the "Currently resolving at" label under the resolution bar.
If you are authenticated as a server administrator you can view information on the status of the server. Click the "Tools" menu and select "Site Status". This will show percent memory use, percent disk use, CPU load and the number of requests the server has handled since its last restart.
The values of a handle can be digitally signed with a private key and then verified with a public key to confirm that the handle values have not been modified. To sign a handle record first resolve it and then click the "Sign" button in the handle tool bar to bring up the "Create Signature" dialog.
In the "Create Signature" dialog you should select the handle values you want to sign.
You need to supply a private key and specify the handle system identity you are going to sign with. i.e. the index and handle of the public key that corresponds to the supplied private key.
Then click the "Sign Values" button. If the signature was created successfully you will see a green success message. You can then click the close button.
The entire signing and verification process is performed locally in the browser. Your private key is not sent to a remote server.
You should now see two handle values added to the handle record. Once of type "10320/sig.digest" and another of type "10320/sig.sig".
The "10320/sig.digest" contains hashes of the selected handle values and the "10320/sig.sig" is a signature over the "10320/sig.digest" handle value.
Note that the handle record has not yet been saved with the new handle values. You can see the handle record has not been saved by the presence of the asterix before the handle.
You can now click the "Verify" button to check the signature.
Each handle value that has been signed and successfully verified will have a green success label appended to it indicating the identity of the signer.
If you now edit a handle value and then verify again you will see that the modified handle value gets flagged as failing to verify.
In the above example the URL handle value was changed. Verifying this handle resulted in the a red error label being appended to the URL handle value. This signifies that signature that refers to this handle value did not verify.
You can create multiple signatures on a handle record. Each of those signatures may be by different identities and each signature can, if desired, sign different handle values.
Select Tools->Client Configuration… to show the client configuration tool.
useProxyAsRoot: if set to try the resolver will contact the http handle proxy service to resolve root handles rather than going to the root servers directly. This is only needed in the transition period where not all root handle servers are running version 8.
useAuthoritativeResolutionWithProxy: if true when resolution calls are made to the proxy the proxy is instructed not to resolve from its cache.
proxyUrl: The URL of the proxy handle resolution service.
rootUrls: An array of URL that define how to contact the root handle service.
Changes made to this configuration are stored in the browser's local storage.
