24
Handle Client - Java Version Handle Client - Java Version Sean Reilly [email protected]

Handle Client - Java Version

  • Upload
    fia

  • View
    50

  • Download
    0

Embed Size (px)

DESCRIPTION

Handle Client - Java Version. Sean Reilly [email protected]. 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 - PowerPoint PPT Presentation

Citation preview

Page 1: Handle Client - Java Version

Handle Client - Java VersionHandle Client - Java Version

Sean [email protected]

Page 2: Handle Client - Java Version

Outline - Understanding the Handle Client Library for JavaOutline - Understanding the Handle Client Library for Java

• Resolving handles programmaticallyResolving handles programmatically

• AuthenticationAuthentication– How it worksHow it works

– Public/private vs. secret keysPublic/private vs. secret keys

• Handle AdministrationHandle Administration– Administrators, Permissions, GroupsAdministrators, Permissions, Groups

• Programming hints and advanced Programming hints and advanced featuresfeatures

Page 3: Handle Client - Java Version

Resolving Handles ProgrammaticallyResolving Handles Programmatically

• The client library is contained in the The client library is contained in the net.handle.hdllib package.net.handle.hdllib package.

• All interaction with the Handle System is All interaction with the Handle System is done with exchanges of request/response done with exchanges of request/response messages.messages.

• The core of the client library is the The core of the client library is the HandleResolver class in the HandleResolver class in the net.handle.hdllib package.net.handle.hdllib package.

• HandleResolver objects are responsible for HandleResolver objects are responsible for sending, receiving, and managing the sending, receiving, and managing the exchange of Handle System messages.exchange of Handle System messages.

Page 4: Handle Client - Java Version

•What does “Resolving a Handle” mean?What does “Resolving a Handle” mean?

• When we resolve a handle we are looking When we resolve a handle we are looking up the values that are associated with a up the values that are associated with a handle.handle.

• There are couple of parameters that we There are couple of parameters that we can supply to handle resolution:can supply to handle resolution:

– Handle value types: “give me all URL and Handle value types: “give me all URL and EMAIL values for 10.1000/29”EMAIL values for 10.1000/29”

– Handle value indexes: “give me values 12 Handle value indexes: “give me values 12 and 2 for 10.1000/29”and 2 for 10.1000/29”

– We can combine these parameters: “give me We can combine these parameters: “give me values 12, 2 and all URL values for values 12, 2 and all URL values for 10.1000/29”10.1000/29”

Page 5: Handle Client - Java Version

Resolving a Handle (the easy way)Resolving a Handle (the easy way)

The easiest way to resolve a handle programmatically is The easiest way to resolve a handle programmatically is with the resolveHandle() method of a HandleResolver with the resolveHandle() method of a HandleResolver object.object.

Example 1Example 1

Page 6: Handle Client - Java Version

Resolving a Handle (the powerful way)Resolving a Handle (the powerful way)

Using a ResolutionRequest object gives Using a ResolutionRequest object gives you more control over how a handle is you more control over how a handle is resolved.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();

Page 7: Handle Client - Java Version

The HandleResolver Class: How it WorksThe HandleResolver Class: How it Works

The HandleResolver class:The HandleResolver class:– locates local siteslocates local sites

– negotiates protocolsnegotiates protocols

– uses and updates the cacheuses and updates the cache

– verifies signatures on certified messagesverifies signatures on certified messages

Page 8: Handle Client - Java Version

The HandleResolver Class: Important MethodsThe HandleResolver Class: Important Methods

– processRequestprocessRequest(AbstractRequest):(AbstractRequest):• Checks the cache to see if we already have the Checks the cache to see if we already have the

response for this message. If so, return it.response for this message. If so, return it.

• Locates the service that is responsible for the Locates the service that is responsible for the message, possibly using several intermediate message, possibly using several intermediate messages to retrieve the service information.messages to retrieve the service information.

• Finds the correct server(s) within the service Finds the correct server(s) within the service and contacts each one until it receives a and contacts each one until it receives a response.response.

• If the request had the If the request had the certifycertify flag set, then flag set, then verify the signature of the response.verify the signature of the response.

• If the response is a If the response is a challengechallenge, and an , and an authentication object is available, return an authentication object is available, return an answer to the challenge (for admin messages).answer to the challenge (for admin messages).

• Return the responseReturn the response

Page 9: Handle Client - Java Version

The HandleResolver Class: Important MethodsThe HandleResolver Class: Important Methods

– setCache(Cache): Tells the resolver to use setCache(Cache): Tells the resolver to use the specified cache object to reduce the the specified cache object to reduce the amount of redundant messages.amount of redundant messages.

– setCheckSignatures(boolean): Tells the setCheckSignatures(boolean): Tells the resolver to verify signatures of responses to resolver to verify signatures of responses to certified requests.certified requests.

Page 10: Handle Client - Java Version

The HandleResolver Class: Important MethodsThe HandleResolver Class: Important Methods

– setTcpTimeoutsetTcpTimeout(int): Sets the timeout that is (int): Sets the timeout that is used when sending messages via TCP/IP used when sending messages via TCP/IP connections.connections.

– setPreferredProtocolssetPreferredProtocols(int[]): Tells the (int[]): Tells the resolver what protocols to use when talking resolver what protocols to use when talking to handle servers. For example: to handle servers. For example:

int protocols[] = { Interface.SP_HDL_UDP, int protocols[] = { Interface.SP_HDL_UDP,

Interface.SP_HDL_TCP};Interface.SP_HDL_TCP};

resolver.setPreferredProtocols(protocols);resolver.setPreferredProtocols(protocols);

Page 11: Handle Client - Java Version

Resolution ParametersResolution Parameters

• Some parameters that are associated Some parameters that are associated with all Handle System messages:with all Handle System messages:– authoritativeauthoritative [boolean]: Indicates that [boolean]: Indicates that

resolution of the message should not use a resolution of the message should not use a cache and the resolver should only talk to cache and the resolver should only talk to primaryprimary handle servers. handle servers.

– certifycertify [boolean]: Tells the server to [boolean]: Tells the server to digitally sign the response to this message.digitally sign the response to this message.

– recursive [boolean]: If the server that recursive [boolean]: If the server that receives this request isn’t responsible for it, receives this request isn’t responsible for it, it may be forwarded to the responsible it may be forwarded to the responsible server.server.

Page 12: Handle Client - Java Version

Authentication: Establishing an IdentityAuthentication: Establishing an Identity

Authentication is a vital component of the Authentication is a vital component of the current Handle System.current Handle System.

• Establishes identity of the requestorEstablishes identity of the requestor

• Can be done with public/private key Can be done with public/private key pairs or secret keyspairs or secret keys

• Identifying requestor allows servers to Identifying requestor allows servers to determine the level of access granted determine the level of access granted for different operations.for different operations.

Page 13: Handle Client - Java Version

Authentication: How is an Administrator Identified?Authentication: How is an Administrator Identified?

• Every administrator in the Handle Every administrator in the Handle System must be identified by a handle.System must be identified by a handle.

• That handle, and the index of a value That handle, and the index of a value within the handle is used to identify the within the handle is used to identify the administrator.administrator.

• The handle/index can reference a public The handle/index can reference a public key, or a secret key. If it references a key, or a secret key. If it references a secret key, verification of an secret key, verification of an administrators identity is done with a administrators identity is done with a VerifyAuthRequestVerifyAuthRequest..

Page 14: Handle Client - Java Version

Authentication: How it WorksAuthentication: How it Works

• The client sends a request to a serverThe client sends a request to a server

• Server checks if authentication is Server checks if authentication is required to perform the operationrequired to perform the operation

• If authentication is required, the server If authentication is required, the server generates a challenge generates a challenge ((ChallengeResponseChallengeResponse) and sends it back ) and sends it back to the client. The challenge contains:to the client. The challenge contains:– a digest of the original requesta digest of the original request

– a random set of bytes (nonce)a random set of bytes (nonce)

Page 15: Handle Client - Java Version

Authentication: How it Works (continued)Authentication: How it Works (continued)

• The client receives the challenge and:The client receives the challenge and:– verifies that the request digest matches the verifies that the request digest matches the

request that was sent.request that was sent.

– creates an answer creates an answer ((ChallengeAnswerRequestChallengeAnswerRequest) that includes:) that includes:• the identity of the client (handle, and index the identity of the client (handle, and index

value of the key)value of the key)

• signature of the challenge using a secret or signature of the challenge using a secret or private keyprivate key

– sends the answer to the challenge back to sends the answer to the challenge back to the serverthe server

Page 16: Handle Client - Java Version

Authentication: How it Works (continued)Authentication: How it Works (continued)

• The server, upon receiving the answer to The server, upon receiving the answer to the challenge:the challenge:– checks that the requestor identified in the checks that the requestor identified in the

answer has permission to perform the requested answer has permission to perform the requested operationoperation

– checks the identity of the requestor by verifying checks the identity of the requestor by verifying the signature in the answerthe signature in the answer• for public key authentication the server simply for public key authentication the server simply

retrieves the public key of the administrator and retrieves the public key of the administrator and checks it.checks it.

• for secret key authentication, the server sends for secret key authentication, the server sends both the challenge and answer to the server with both the challenge and answer to the server with the secret key and asks “is this right?”the secret key and asks “is this right?”

– performs the requested operationperforms the requested operation

Page 17: Handle Client - Java Version

Authentication: All You Really Need to KnowAuthentication: All You Really Need to Know

Authentication is actually fairly simple to Authentication is actually fairly simple to do programmatically:do programmatically:

• Public key authentication: Public key authentication: PublicKeyAuthenticationInfoPublicKeyAuthenticationInfo Example 3Example 3

• Secret key authentication: Secret key authentication: SecretKeyAuthenticationInfoSecretKeyAuthenticationInfo Example 2Example 2

Page 18: Handle Client - Java Version

Authentication: Using the Admin ToolAuthentication: Using the Admin Tool

• The parameters required for The parameters required for administration can be seen in the login administration can be seen in the login panel of the Handle Admin Tool.panel of the Handle Admin Tool.

Page 19: Handle Client - Java Version

Handle AdministrationHandle Administration

• Handle administration consists of Handle administration consists of creating, modifying, deleting (and soon, creating, modifying, deleting (and soon, listing) handles.listing) handles.

• From a programming standpoint, From a programming standpoint, administration is just as easy as administration is just as easy as resolution.resolution.

• Instead of Instead of ResolutionRequestResolutionRequest messages, messages, administration is done with messages administration is done with messages like like CreateHandleRequestCreateHandleRequest, , DeleteHandleRequestDeleteHandleRequest, etc, etc

Page 20: Handle Client - Java Version

Administration: Admin Handle ValuesAdministration: Admin Handle Values

• Every handle needs to have at least one Every handle needs to have at least one value with type HS_ADMIN.value with type HS_ADMIN.

• HS_ADMIN handle values identify HS_ADMIN handle values identify whowho has permission to modify the handle and has permission to modify the handle and whatwhat type of modifications they can do. type of modifications they can do.

Page 21: Handle Client - Java Version

Administration: Admin GroupsAdministration: Admin Groups

• HS_ADMIN values can directly reference HS_ADMIN values can directly reference the authentication key of the authentication key of administrators… administrators… but shouldn’t!but shouldn’t!

• HS_ADMIN values should reference a HS_ADMIN values should reference a group value as an administrator instead.group value as an administrator instead.

• An admin group is a handle value with An admin group is a handle value with type HS_VLIST, and contains a list of type HS_VLIST, and contains a list of admin handles and indexes that admin handles and indexes that identifier administrators (or other identifier administrators (or other HS_VLIST values)HS_VLIST values)

Page 22: Handle Client - Java Version

Example Administrative Request: Creating a HandleExample Administrative Request: Creating a Handle

• Creating a handle is done with a Creating a handle is done with a CreateHandleRequest:CreateHandleRequest:

Example 4Example 4

Page 23: Handle Client - Java Version

Programming HintsProgramming Hints

• The handle API represents text strings as The handle API represents text strings as UTF-8 byte arrays. Use UTF-8 byte arrays. Use Util.encodeString(String) and Util.encodeString(String) and Util.decodeString(byte[]) to convert Util.decodeString(byte[]) to convert between java.lang.String and byte[]between java.lang.String and byte[]

• Message encoding is cached. If you would Message encoding is cached. If you would like to reuse a message after changing the like to reuse a message after changing the message, use the .clearBuffers() method to message, use the .clearBuffers() method to uncache the encoded messageuncache the encoded message

Page 24: Handle Client - Java Version

Advanced Topics: The Next VersionAdvanced Topics: The Next Version

• Some operations may require a response Some operations may require a response to be “streamed.”to be “streamed.”

• Since the handle system uses discreet Since the handle system uses discreet messages, streamed responses can be messages, streamed responses can be sent in several continuous responses. sent in several continuous responses. These are handled by giving the resolver These are handled by giving the resolver object a ResponseMessageCallback which object a ResponseMessageCallback which the resolver will call with each message the resolver will call with each message of a continuous set. This has been used of a continuous set. This has been used to implement a list handles response.to implement a list handles response.