DETER Testbed API

The DETER testbed API is broken up into 5 services, each covering one of the major abstractions that the testbed exports. The services are:

• ApiInfo
• Users
• Projects
• Resrources
• Experiments

We discuss each in detail and provide links to the detailed javadoc of the implementation, where applicable and available.

The document and API are both works in progress and will be fleshed out and changed as the API is modified.

General Info

The API is implemented as a SOAP web service over TLS secured connections. The user's identity is generally provided by a client certificate, but the client certificates are generally transient. A valid temporary client certificate can be requested from the API by correctly responding to a challenge keyed on the user's password.

The API is implemented using the axis web service framework, which means that javadocs are provided for the various calls.

Each service and call are accessed by appending servicename/operation to the base URL of the API server. On DETERlab the base URL will be ​https://api.isi.deterlabnet:52323/axis2/service. For example, one can access the getVersion operation below at ​https://api.isi.deterlabnet:52323/axis2/service/ApiInfo/getVersion

Each operation returns useful parameters on success and throws a fault, called a DeterFault, on an error. Faults are standard SOAP faults with a detail section that includes the following fields:

• ErrorCode - a 32-bit integer encoding the type of error. Constants are available in the ​javadoc for DeterFault. Values are:
  • access - access denied
  • request - bad request
  • internal - internal server error
• ErrorString - a string describing the broad error
• DetailString - a string describing the details that caused the error

The ErrorString and ErrorCode are equivalent, but the information in the DetailString is generally more informative about the specifics. Request or access errors are generally correctable on the client side while internal errors are not.

​javadoc for DeterFault

ApiInfo

The ApiInfo service provides metadata about the running DETER API. It also provides a simple check that a user is presenting authentication credentials correctly.

​javadoc for ApiInfo

The sole operation in the ApiInfo service is getVersion. The call is unauthenticated and can be made driectly from a web browser to confirm that the API is functioning and that the user can see DETERlab.

• Service: ApiInfo
• Operation: getVersion
• Input Parameters:
  • None
• Return Values:
  • Version - A string containing the API version number
  • PatchLevel - A string containing the patch level
  • KeyID - A string. If the user presented a valid public key and passed the challenge, this is the sha1 hash of that key. If no key was presented or an invalid one, this filed is not returned.

Users

The Users API is concerned with managing users and their profiles as well as authenticating to the testbed and receiving a client certificate for later calls.

​javadoc for Users

Authentication

A user can authenticate to the testbed and receive a short-lived client x.509 certificate by requesting a challenge using the requestChallenge operation and responding to the challenge via the challengeResponse operation.

Currently only one challenge type is defined. The challenge is an array of bytes and the response is return an SHA1 HMAC of that string keyed by the user's password.

• Service: Users
• Operation: requestChallenge
• Input Parameters:
  • userid - the identity to authenticate
• Return Values:
  • Type - the kind of challenge
  • Data - the data needed for the challenge
  • Validity - number of seconds the challenge may be responded to
  • ChallengeID - a 64-bit identifier that allows the server to validate the reply

• Service: Users
• Operation: challengeResponse
• Input Parameters:
  • ResponseData - a binary string, the response to the challenge
  • ChallengeID - The 64-bit identifier of the challenge being responded to
• Return Values:
  • Certificate - a binary string containing a PEM-encoded X.509 certificate and private key. (Passed down the encrypted connection)

Profile Manipulation

DETER keeps metadata about each user called a profile. The API provides an authenticated user with several interfaces to query and modify their profile information.

In the API each element of profile data is represented as a structure with the following data in it:

• name of the element
• type of the element
  • string
  • integer
  • double
  • binary/opaque
• value(s) of the element
• a flag set if the element is optional
• A flag set if the field can be removed from the profile
• a modification type: elements may be read/write, read-only (e.g., username) or write-only (e.g., password)
• a brief description of the field, intended to be presented by a web interface or other third party program

To get a profile schema, for example to create an empty web page,

• Service: Users
• Operation: getProfileDescription
• Input Parameters:
• Return Values:
  • Uid - always empty
  • A list of profile elements each containing
    • Name - a string, the element's name
    • DataType - a string giving the element's
      • string
      • integer
      • double
      • binary/opaque
    • StringValue - a string containing the element's value, unless it is binary/opaque
    • BinaryValue - a byte string containing the element's value if it is binary/opaque
    • Access - a 32-bit integer describing the access values (values at ​Attribute's javadoc)
      • READ_WRITE
      • READ_ONLY
      • WRITE_ONLY (e.g., password)
    • Optional - a flag true if the field is optional (must be present but may be empty)
    • Removable - a flag true if the field can be removed
    • Description - a string explaining the field

To read a user's profile (generally only users can read their own profile).

• Service: Users
• Operation: getProfileDescription
• Input Parameters:
  • userid - a string naming the user to be retrieved
• Return Values:
  • Userid - the user whose profile is returned
  • A list of profile elements each containing
    • Name - a string, the element's name
    • DataType - a string giving the element's
      • string
      • integer
      • double
      • binary/opaque
    • StringValue - a string containing the element's value, unless it is binary/opaque
    • BinaryValue - a byte string containing the element's value if it is binary/opaque
    • Access - a 32-bit integer describing the access values (values at ​Attribute's javadoc)
      • READ_WRITE
      • READ_ONLY
      • WRITE_ONLY (e.g., password)
    • Optional - a flag true if the field is optional (must be present but may be empty)
    • Removable - a flag true if the field can be removed
    • Description - a string explaining the field

Finally a user can modify a profile:

• Service: Users
• Operation: getProfileDescription
• Input Parameters:
  • Userid - the user's profile to modify
  • A list of change requests. Each request contains
    • Name - the name of the field to change
    • StringValue - the new value of the field if this is not an opaque/binary field
    • BinaryValue - the new value of the field if this is an opaque/binary field
    • Delete - a flag, if true delete the field rather than modify it
• Return Values:
  • A list of responses each containing
    • Name - astring with the name of the field
    • Success - a flag indicating if the request succeeded
    • Reason - a string indicating the reason if Success is false

Creation

Finally a user can request access to the testbed by creating a profile. The user has no privileges and consumes minimal resources until they join a vetted project. This is an unauthenticated call, but the user profile is not created until an automated e-mail exchange is made between the testbed and the proto-user.

• Service: Users
• Operation: getProfileDescription
• Input Parameters:
  • Userid - the requested userid
  • A list of profile elements each containing
    • Name - a string, the element's name
    • StringValue - a string containing the element's value, unless it is binary/opaque
• Return Values:
  • None

Note that all non-optional fields must be provided, so this is best preceeded by a call to getProfileDescription to learn the fields.