Version 1 (modified by faber, 7 years ago) (diff)

--

New API Implementation Notes

This page keeps track of the internals of the Deter API implementation.

Configuration Files

Both the test utilities and the service itself have configuration files.

Service Configurations

Service configuration file a are java properties files stored in /usr/local/etc/deter/. The main configuration file is

/usr/local/etc/deter/service.properties which consists of (passwords and usernamed expunged):

#DETER utilities properties
#Thu Jul 18 16:27:29 PDT 2013
emulabDbUrl=jdbc\:mysql\://localhost/tbdb?user\=auser&password\=apassword
keystorefilename=/usr/local/apache-tomcat-7.0/conf/tomcat.keystore
logconfig=/usr/local/etc/deter/log4j.properties
deterDbUrl=jdbc\:mysql\://localhost/deter?user\=auser&password\=apassword
keystorepw=apassword

Contents are:

  • the URL to read and write the emulab DB (emulabDbUrl)
  • the URL to read and write the deter DB (deterDbUrl)
  • the keystore containing the id used to sign new credentials (keystore)
  • the peystore passowrd (keystorepw)
  • the log4j properties file used to configure the service logging (logconfig)

The loggingconfiguration syntax is defined by log4j. Current contents are:

# logging for DeterServices
#

# For debugging this configuration set this variable true and look at tomcat's
# stderr.
log4j.debug=true

# Rolling log appender to put out into /var/log/deter
log4j.appender.A1=org.apache.log4j.RollingFileAppender
log4j.appender.A1.MaxFileSize=10MB
log4j.appender.A1.MaxBackupIndex=3
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d{MM/dd HH:mm:ss} %-5p %c{1}: %m%n
log4j.appender.A1.file=/var/log/deter/service.log

# The net.deterlab logger will inherit the root level and use the
# /var/log/deter appender above.  It will not log to the root.
log4j.logger.net.deterlab=DEBUG, A1
log4j.additivity.net.deterlab=false

That defines a service log in /var/log/deter/services.log logging at DEBUG and higher. It is automatically rotated at 10 MB with 3 copies kept around. We use the log4j rotator rather than newsyslog to avoid disruption.

Utility Configurations

Utilities read from a configuration in the users $HOME/.deterutils.properties. This is a java properties file. A simple setup looks like (passwords and users purged):

#DETER utilities properties
#Wed Aug 14 18:09:13 PDT 2013
useridpw=apassword
serviceurl=https\://localhost\:52323/axis2/services/
trustpw=apassword
useridfilename=/usr/home/faber/myID
trustfilename=/usr/home/faber/keystore

This keeps track of

  • Trusted certificates - the DETER service id (trustfilename & trustpw)
  • User identity certificate - useridfilename, useridpw)
  • The service base URL - ( serviceurl)

Both files can be modified by the SetProperty utility.

Database tables

Users

Users are kept in a table of this format called users:

Field Type Null Key Default Extra
idx int(11) NO PRI NULL auto_increment
uid varchar(20) YES NULL
password varchar(255) YES NULL
hashtype varchar(32) YES NULL
passwordexpires datetime YES NULL

Most of that is straightforward. The password is a hash with type defined by hashtype. Currently all are crypt format hashes.

Passowrds are checked using a challenge system and password resets also populate the same table. When created a challenge is put in the userchallenge table:

Field Type Null Key Default Extra
uidx int(11) YES NULL
data blob YES NULL
validity datetime YES NULL
challengeid bigint(20) YES UNI NULL
type varchar(20) YES NULL

A password challenge - checking a login - has type "clear." The data is the challenge issued with enough info to check the response. Currently, only a clear challenge is used, meaning that the data contains the crypt hash of the password to check. The validity field is checked and old challenges discarded whenever a challeng is accessed. uidx is the index (idx) of the user for whom the challenge was issued. As with all DB fields the links are through integer indices.

When used to reset a password the challenge is issued with type "PasswordReset". The presence of such a challenge is all that is checked. A user who calls changePasswordChallenge with a the ID of a valid "PasswordReset" challenge can change the password of the user pointed to by the uidx field.

The body of a notification is stored in the notification table:

Field Type Null Key Default Extra
idx int(11) NO PRI NULL auto_increment
created timestamp NO CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP
body text YES NULL

When delivered to a user a row is added to the usernotification table for each user:

Field Type Null Key Default Extra
nidx int(11) YES MUL NULL
uidx int(11) YES MUL NULL
flags int(11) YES NULL

nidx and uidx are both constrained to be foreign key indices unto the notification and users tables respectively. This means that all notifications to a user are removed before the user is removed. Each entry in the usernotification table is a status for that message to a user (urgent/read).

Profiles

Most objects in the Deter API have a profile attached to them and all of these tables are the same with minor tweaks. Here is the schema for user profile entries (the userattribute table):

Field Type Null Key Default Extra
idx int(11) NO PRI NULL auto_increment
name varchar(20) YES NULL
datatype enum('STRING','INT','FLOAT','OPAQUE') YES NULL
optional tinyint(4) YES NULL
access enum('READ_WRITE','READ_ONLY','WRITE_ONLY','NO_ACCESS') YES NULL
description text YES NULL
format varchar(256) YES NULL
formatdescription text YES NULL
sequence int(11) NO 0
length int(11) NO 0

This is a description of the attribute. Note that attribute descriptions have indices.

To assign a value in a given user's profile, an entry is added to the userattributevalue table:

Field Type Null Key Default Extra
uidx int(11) YES MUL NULL
aidx int(11) YES MUL NULL
value text YES NULL