Handle Client - Java Version

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

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

3. Resolving Handles Programmatically • 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. • 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.

4. What does “Resolving a Handle” mean? • 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: • 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

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. • 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. • 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). • Return 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}; resolver.setPreferredProtocols(protocols);

11. Resolution Parameters • 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 isn’t 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 requestor • Can be done with public/private key pairs or secret keys • 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. • 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.

14. Authentication: How it Works • The client sends a request to a server • Server 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: • a digest of the original request • a random set of bytes (nonce)

15. Authentication: How it Works (continued) • 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) • signature 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: • 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 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: PublicKeyAuthenticationInfoExample 3 • Secret key authentication: 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.

19. Handle Administration • Handle administration consists of creating, modifying, deleting (and soon, listing) handles. • From a programming standpoint, administration is just as easy as resolution. • Instead 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. • 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 shouldn’t! • 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)

22. Example Administrative Request: Creating a Handle • Creating a handle is done with a CreateHandleRequest: Example 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[] • Message 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.” • 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.