1. Handle Client - Java Version Sean Reilly sreilly@cnri.reston.va.us

2. Outline - Understanding the Handle Client Library for Java Resolving handles programmaticallyResolving handles programmatically AuthenticationAuthentication –How it works –Public/private vs. secret keys Handle AdministrationHandle Administration –Administrators, Permissions, Groups Programming hints and advanced featuresProgramming hints and advanced features

3. Resolving Handles Programmatically The client library is contained in the net.handle.hdllib package.The client library is contained in the net.handle.hdllib package. All interaction with the Handle System is done with exchanges of request/response messages.All interaction with the Handle System is done with exchanges of request/response messages. The core of the client library is the HandleResolver class in the net.handle.hdllib package.The core of the client library is the HandleResolver class in the net.handle.hdllib package. HandleResolver objects are responsible for sending, receiving, and managing the exchange of Handle System messages.HandleResolver objects are responsible for sending, receiving, and managing the exchange of Handle System messages.

4. What does Resolving a Handle mean?What does Resolving a Handle mean? When we resolve a handle we are looking up the values that are associated with a handle.When we resolve a handle we are looking up the values that are associated with a handle. There are couple of parameters that we can supply to handle resolution:There are couple of parameters that we can supply to handle resolution: –Handle value types: give me all URL and EMAIL values for 10.1000/29 –Handle value indexes: give me values 12 and 2 for 10.1000/29 –We can combine these parameters: give me values 12, 2 and all URL values for 10.1000/29

5. Resolving a Handle (the easy way) The easiest way to resolve a handle programmatically is with the resolveHandle() method of a HandleResolver object. Example 1 Example 1Example 1Example 1

6. Resolving a Handle (the powerful way) Using a ResolutionRequest object gives you more control over how a handle is resolved. ResolutionRequest request = new ResolutionRequest(handle, types, indexes, null); request.certify = true; request.authoritative = true; AbstractResponse response = resolver.processRequest(request); if(response instanceof ResolutionResponse) values = ((ResolutionResponse)response).getHandleValues();

7. The HandleResolver Class: How it Works The HandleResolver class: –locates local sites –negotiates protocols –uses and updates the cache –verifies signatures on certified messages

8. The HandleResolver Class: Important Methods –processRequest(AbstractRequest): Checks the cache to see if we already have the response for this message. If so, return it.Checks the cache to see if we already have the response for this message. If so, return it. Locates the service that is responsible for the message, possibly using several intermediate messages to retrieve the service information.Locates the service that is responsible for the message, possibly using several intermediate messages to retrieve the service information. Finds the correct server(s) within the service and contacts each one until it receives a response.Finds the correct server(s) within the service and contacts each one until it receives a response. If the request had the certify flag set, then verify the signature of the response.If the request had the certify flag set, then verify the signature of the response. If the response is a challenge, and an authentication object is available, return an answer to the challenge (for admin messages).If the response is a challenge, and an authentication object is available, return an answer to the challenge (for admin messages). Return the responseReturn the response

9. The HandleResolver Class: Important Methods –setCache(Cache): Tells the resolver to use the specified cache object to reduce the amount of redundant messages. –setCheckSignatures(boolean): Tells the resolver to verify signatures of responses to certified requests.

10. The HandleResolver Class: Important Methods –setTcpTimeout(int): Sets the timeout that is used when sending messages via TCP/IP connections. –setPreferredProtocols(int[]): Tells the resolver what protocols to use when talking to handle servers. For example: int protocols[] = { Interface.SP_HDL_UDP, Interface.SP_HDL_TCP}; Interface.SP_HDL_TCP};resolver.setPreferredProtocols(protocols);

11. Resolution Parameters Some parameters that are associated with all Handle System messages:Some parameters that are associated with all Handle System messages: –authoritative [boolean]: Indicates that resolution of the message should not use a cache and the resolver should only talk to primary handle servers. –certify [boolean]: Tells the server to digitally sign the response to this message. –recursive [boolean]: If the server that receives this request isnt responsible for it, it may be forwarded to the responsible server.

12. Authentication: Establishing an Identity Authentication is a vital component of the current Handle System. Establishes identity of the requestorEstablishes identity of the requestor Can be done with public/private key pairs or secret keysCan be done with public/private key pairs or secret keys Identifying requestor allows servers to determine the level of access granted for different operations.Identifying requestor allows servers to determine the level of access granted for different operations.

13. Authentication: How is an Administrator Identified? Every administrator in the Handle System must be identified by a handle.Every administrator in the Handle System must be identified by a handle. That handle, and the index of a value within the handle is used to identify the administrator.That handle, and the index of a value within the handle is used to identify the administrator. The handle/index can reference a public key, or a secret key. If it references a secret key, verification of an administrators identity is done with a VerifyAuthRequest.The handle/index can reference a public key, or a secret key. If it references a secret key, verification of an administrators identity is done with a VerifyAuthRequest.

14. Authentication: How it Works The client sends a request to a serverThe client sends a request to a server Server checks if authentication is required to perform the operationServer checks if authentication is required to perform the operation If authentication is required, the server generates a challenge (ChallengeResponse) and sends it back to the client. The challenge contains:If authentication is required, the server generates a challenge (ChallengeResponse) and sends it back to the client. The challenge contains: –a digest of the original request –a random set of bytes (nonce)

15. Authentication: How it Works (continued) The client receives the challenge and:The client receives the challenge and: –verifies that the request digest matches the request that was sent. –creates an answer (ChallengeAnswerRequest) that includes: the identity of the client (handle, and index value of the key)the identity of the client (handle, and index value of the key) signature of the challenge using a secret or private keysignature of the challenge using a secret or private key –sends the answer to the challenge back to the server

16. Authentication: How it Works (continued) The server, upon receiving the answer to the challenge:The server, upon receiving the answer to the challenge: –checks that the requestor identified in the answer has permission to perform the requested operation –checks the identity of the requestor by verifying the signature in the answer for public key authentication the server simply retrieves the public key of the administrator and checks it.for public key authentication the server simply retrieves the public key of the administrator and checks it. for secret key authentication, the server sends both the challenge and answer to the server with the secret key and asks is this right?for secret key authentication, the server sends both the challenge and answer to the server with the secret key and asks is this right? –performs the requested operation

17. Authentication: All You Really Need to Know Authentication is actually fairly simple to do programmatically: Public key authentication: PublicKeyAuthenticationInfo Example 3Public key authentication: PublicKeyAuthenticationInfo Example 3 PublicKeyAuthenticationInfoExample 3 PublicKeyAuthenticationInfoExample 3 Secret key authentication: SecretKeyAuthenticationInfo Example 2Secret key authentication: SecretKeyAuthenticationInfo Example 2 SecretKeyAuthenticationInfoExample 2 SecretKeyAuthenticationInfoExample 2

18. Authentication: Using the Admin Tool The parameters required for administration can be seen in the login panel of the Handle Admin Tool.The parameters required for administration can be seen in the login panel of the Handle Admin Tool.

19. Handle Administration Handle administration consists of creating, modifying, deleting (and soon, listing) handles.Handle administration consists of creating, modifying, deleting (and soon, listing) handles. From a programming standpoint, administration is just as easy as resolution.From a programming standpoint, administration is just as easy as resolution. Instead of ResolutionRequest messages, administration is done with messages like CreateHandleRequest, DeleteHandleRequest, etcInstead of ResolutionRequest messages, administration is done with messages like CreateHandleRequest, DeleteHandleRequest, etc

20. Administration: Admin Handle Values Every handle needs to have at least one value with type HS_ADMIN.Every handle needs to have at least one value with type HS_ADMIN. HS_ADMIN handle values identify who has permission to modify the handle and what type of modifications they can do.HS_ADMIN handle values identify who has permission to modify the handle and what type of modifications they can do.

21. Administration: Admin Groups HS_ADMIN values can directly reference the authentication key of administrators… but shouldnt!HS_ADMIN values can directly reference the authentication key of administrators… but shouldnt! HS_ADMIN values should reference a group value as an administrator instead.HS_ADMIN values should reference a group value as an administrator instead. An admin group is a handle value with type HS_VLIST, and contains a list of admin handles and indexes that identifier administrators (or other HS_VLIST values)An admin group is a handle value with type HS_VLIST, and contains a list of admin handles and indexes that identifier administrators (or other HS_VLIST values)

22. Example Administrative Request: Creating a Handle Creating a handle is done with a CreateHandleRequest:Creating a handle is done with a CreateHandleRequest: Example 4 Example 4Example 4Example 4

23. Programming Hints The handle API represents text strings as UTF-8 byte arrays. Use Util.encodeString(String) and Util.decodeString(byte[]) to convert between java.lang.String and byte[]The handle API represents text strings as UTF-8 byte arrays. Use Util.encodeString(String) and Util.decodeString(byte[]) to convert between java.lang.String and byte[] Message encoding is cached. If you would like to reuse a message after changing the message, use the.clearBuffers() method to uncache the encoded messageMessage encoding is cached. If you would like to reuse a message after changing the message, use the.clearBuffers() method to uncache the encoded message

24. Advanced Topics: The Next Version Some operations may require a response to be streamed.Some operations may require a response to be streamed. Since the handle system uses discreet messages, streamed responses can be sent in several continuous responses. These are handled by giving the resolver object a ResponseMessageCallback which the resolver will call with each message of a continuous set. This has been used to implement a list handles response.Since the handle system uses discreet messages, streamed responses can be sent in several continuous responses. These are handled by giving the resolver object a ResponseMessageCallback which the resolver will call with each message of a continuous set. This has been used to implement a list handles response.