Classes

Currently the following services are available

• Memory / Session service be.securit.trustbuilder.util.TimedBlockingHashMap

• MemCached / Session service be.securit.trustbuilder.service.MemcachedService

• DateService be.securit.trustbuilder.service.DateService

• EncryptionService be.securit.trustbuilder.service.EncryptionService

• Radius Endpoint Service be.securit.trustbuilder.service.RadiusService

• Ldap Endpoint Service be.securit.trustbuilder.service.LdapService

• Domtai Service be.securit.trustbuilder.service.DomTai

• Redis Service be.securit.trustbuilder.service.RedisService

The Service section can be used to call different services, for example a memory store.

<stb:Service stb:id="urlStore" stb:type="be.securit.trustbuilder.util.TimedBlockingHashMap" stb:singleton="true">
   <stb:property stb:name="ttl">30000</stb:property>
</stb:Service>
<stb:Service stb:id="objectStore" stb:type="be.securit.trustbuilder.util.TimedBlockingHashMap" stb:singleton="true">
  <stb:property stb:name="ttl">30000</stb:property>
</stb:Service>

In this example we configure 2 memory stores, this can be used to store a session, send information between threads and so on. The ttl property specify's how long a key exists in the store in milliseconds.

Getting access to a service from within the workflow can be done via the following

tb.getService("urlStore");

NOTE in order to enable / change session service provider the trustbuilder application needs to be restarted on application server level.

You can create your own service by setting the type to the fully qualified name of your java class. Requirements for this class are:

• It should have a public constructor

• Functions that need to be called in the workflow should work with primitives and return primitives.

• Setters and getters can be used to change the internal state of the service.

TimedBlockingHashMap Service

Classname: be.securit.trustbuilder.service.TimedBlockingHashMap

This service allows TrustBuilder workflows to store key/value pairs in memory for a certain time.

Property:

• TimeoutInSec Timeout of hashmap in seconds

• ttl Timeout of hashmap in milliseconds

If both are used, the last property in the config is used. Best practice is use only one property.

Functions:

• get(key) Get item by key

• get(key,timeout) Get item by key , timeout optional

• put(key,value) Put key/value pair

• remove(key) Remove item from store

DateService

Classname : be.securit.trustbuilder.service.DateService

Format variables

• Letter Date or Time Component Presentation Examples

• G Era designator Text AD

• y Year Year 1996; 96

• M Month in year Month July; Jul; 07

• w Week in year Number 27

• W Week in month Number 2

• D Day in year Number 189

• d Day in month Number 10

• F Day of week in month Number 2

• E Day in week Text Tuesday; Tue

• a Am/pm marker Text PM

• H Hour in day (0-23) Number 0

• k Hour in day (1-24) Number 24

• K Hour in am/pm (0-11) Number 0

• h Hour in am/pm (1-12) Number 12

• m Minute in hour Number 30

• s Second in minute Number 55

• S Millisecond Number 978

• z Time zone General time zone Pacific Standard Time; PST; GMT-08:00

• Z Time zone RFC 822 time zone -0800

Functions

• now(format) Format now as specified

• epoch() Now as epoch number (seconds since 1970)

• inRange(start,end) Returns true if now is between start and end as epoch dates

• nowISO8601() Now in ISO8601 format

• formatISO8601(date,timezone) Date in ISO8601 format where date is in epoch, timezone is a string

• format(date,format) Date in specific format where date is in epoch

• calcDateISO8601(expression) Date in expression in ISO8601 format where expression can be +/- x [s|m|h|d]

• calcDate(expression,format) Date in expression in format where expression can be +/- x [s|m|h|d]

• calcDateAsEpoch(expression) Date as epoch where expression can be +/- x [s|m|h|d]

• calcDateAsEpoch(date,expression) Calculate date with expression using date as starting point

formatISO8610()

NormalizedCustomID:
         GMT Sign TwoDigitHours : Minutes
 Sign: one of
         + -
 TwoDigitHours:
         Digit Digit
 Minutes:
         Digit Digit
 Digit: one of
         0 1 2 3 4 5 6 7 8 9

Example :

var time = tb.getService("dateService");
var now = time.epoch();                        // EPOCH : 1395996050671
var iso = time.formatISO8601(now);             // ISO DATE : 2014-03-28T09:40:50.671+01:00
var gmt5 = time.formatISO8601(now,'GMT+05:00'); // NO SPACES !   GMT+5 DATE: 2014-03-28T13:40:50.671+05:00
var zulu = time.formatISO8601(now,'UTC');       // ZULU DATE: 2014-03-28T08:48:38.075Z

Domtai Service

Classname : be.securit.trustbuilder.service.DomTai

Properties:

• keySpec generated base64 encoded Key for the DomTai plugin in Lotus Notes

• charSet charset for the encryption (normally ISO-8859-1)

Example:

DOMTAI = tb.getService("domtai service");
var domtaiattr = DOMTAI.encrypt("some string");

Encryption Service

be.securit.trustbuilder.service.EncryptionService

Properties:

Ciphers:

The following ciphers are supported (key length between parentheses)

• AES/CBC/NoPadding (128)

• AES/CBC/PKCS5Padding (128)

• AES/ECB/NoPadding (128)

• AES/ECB/PKCS5Padding (128)

• DES/CBC/NoPadding (56)

• DES/CBC/PKCS5Padding (56)

• DES/ECB/NoPadding (56)

• DES/ECB/PKCS5Padding (56)

• DESede/CBC/NoPadding (168)

• DESede/CBC/PKCS5Padding (168)

• DESede/ECB/NoPadding (168)

• DESede/ECB/PKCS5Padding (168)

• RSA/ECB/PKCS1Padding (1024, 2048)

• RSA/ECB/OAEPWithSHA-1AndMGF1Padding (1024, 2048)

• RSA/ECB/OAEPWithSHA-256AndMGF1Padding (1024, 2048)

Functions:

Available ciphers can be found for the sun at jdk6 jdk7

Example

var encryptionService = tb.getService("encryption"); // encryption is the name of the service
var pwd_hash_user = encryptionService.hash("SHA-512",workItem.input.credentials.password+salt,"base64");

// Encrypts the signaturebase with HMAC-SHA1 and returns a BASE64 encoded string
var signature = encryptionService.generateHMac( "HmacSHA1", signaturebase, null, "base64");

.setKey

When using the setKey functionality it's recommended to use the Encryption Service with the singleton flag set to false. If the singleton is set to true, the key is persistent until the next .setKey call or restart of the TrustBuilder Server.

Some cases another key must be used instead of the default one. This key can be set dynamic as an BASE64 encoded string.

encryptionService.setKey(tb.base64Encode("5VRtmBeg9jRJ5mRAsncaGwCGJ2YazTxReQIqbcHqZc",true));   // Encode as string true
var signature = encryptionService.generateHMac( "HmacSHA1", signaturebase, "base64");   // base64 is default

encodingFormat/decodingFormat

• base64 ; Base64 encode / decode

• y64 : (urldecode) + base64 + (urlencode)

• hex : hex encode / decode

• none : take the bytes from the string as UTF-8

LDAP Endpoint Service

classname : be.securit.trustbuilder.service.LdapService

The LDAP endpoint service is opening a listener port for the ldap endpoint.

Currently only a search and authenticate is supported. Search is however limited to what you define in the workflows. Using a normal ldap client to browse the server isn't possible as the endpoint is ment for authentication only.

Properties:

• port : Port used for the listener

• workflow : Which workflow has to be run by the engine when this service is called

Note on ldap port

If you running your as non-root user you can't open ports under 1024. We recommend setting the ldap port higher and if you want to use port 389 fpr ldap make usage of software that forwards the connection from port 389 to your trustbuilder ldap endpoint.

Config:

<stb:Service stb:id="ldapserv" stb:singleton="false" stb:synchronised="false" stb:type="be.securit.trustbuilder.service.LdapService">
   <stb:property stb:name="port">1389</stb:property>
   <stb:property stb:name="workflow">ldapworkflow</stb:property>
</stb:Service>

We set the listener to port 1389 and attach the "ldapworkflow" to it. Each requests to this endpoint starts the configured workflow.

Requests:

Bind Request

{"user":"null","type":"bind","ip":"10.0.10.243","dn":"cn=administrator,dc=securit,dc=biz","password":"somepasswd"}

Exposed fields in the input :

user :
type : bind
ip : ip of requesting host
dn : DN to bind to
password : the given password to bind

Search Request

Engine.WorkItem - set ___INPUT___=LdapEndpointSearchRequest: {
       baseDN: 'dc=securit,dc=biz',
       scope: 'SUB',
       filter: '(&(objectclass=posixaccount)(uid=ewold))',
       attributes: '[userPassword, cn, gidNumber, uidNumber, loginShell, objectClass, gecos, uid, homeDirectory]',
} []

{"user":"null","type":"search","base":"dc=securit,dc=biz","scope":"SUB","filter":"(&(objectclass=posixaccount)(uid=username))","attributes":["userPassword","cn","gidNumber","uidNumber","loginShell","objectClass","gecos","uid","homeDirectory"]}

Exposed fields in input :

User :
Type : Search
Base : Search base
Scope : Search scope
Filter : Search filter
Attributs : Required attributes in return

Response

To create a response to the ldap client TrustBuilder uses a function that called on the input object.

Bind Response :

// Authentication accepted
workItem.output = workItem.input.generateResponse(0);

// Authentication rejected
workItem.output = workItem.input.generateResponse(49);

Search Response :

var username = "testuser";
var response = {
                       "host" : "10.0.10.243",
                       "gidNumber" : info.gidNumber,
                       "uidNumber" : info.uidNumber,
                       "homeDirectory" : info.homeDirectory,
                       "loginShell" : info.loginShell,
                       "userPassword" : "password"
               };
workItem.output = workItem.input.generateResponse(0);
// Add search Result and attributes
workItem.output.addResult("cn="+username,response);

The addResult function can be called multiple times.

Returning error codes

The 49 is an invalid credentials error code. If you wish to use other codes you can have a look at : http://docs.oracle.com/javase/jndi/tutorial/ldap/models/exceptions.html

MemCached Service

Classname: be.securit.trustbuilder.service.MemcachedService

To use this service an extra jar has to be included in your trustbuilder-web.war file. Download the latest xmemcached jar file and place it in the /lib folder of your TrustBuilder package.

Property:

• address Address of the remote memcached service

• poolsize Size of the connectionpool to use

Functions:

• get(key) Get item by key

• put(key,value) Put key/value pair

• add(key,value) Set key/value pair

• replace(key,value) Replace key/value pair

• set(key,expiry,value) Put key/value pair with expiry

• add(key,expiry,value) Set key/value pair with expiry

• replace(key,expiry,value) Replace key/value pair with expiry

• remove(key) Remove item from store

Memory / Session service:

There are 3 different session services available. They allow to integrate a session service in the workflow. However, it's not limited to only sessions, they can be used as a way to pass information between requests.

Possible implementations:

database: be.securit.trustbuilder.util.DatabaseCacheService

Properties: * jndi * putStatement (optional) * getStatement (optional) * remStatement (optional)

memcached: be.securit.trustbuilder.service.MemcachedService

Properties: * address (supports multiple addresses) * poolsize * memory be.securit.trustbuilder.util.SimpleCacheService

expiring memory: be.securit.trustbuilder.util.TimedBlockingHashMap

Properties: * ttl Time to keep the entries in memory before removing them

These implementations can be used as backend for sessionmanagement, see the section over sessionmanagement.

Functions:

• put(key,object) Put a key in the store with a value (expiring after ttl defined in the config)

• get(key) Get the value from the store by its key

• get(key,timeoutSeconds) Get the value from the store by its key with a timeout in seconds

• remove(key) Remove a value from the store

Radius Endpoint Service

Classname: be.securit.trustbuilder.service.RadiusService

The radius endpoint service is opening a listener port for the radius endpoint.

Properties:

• sharedSecret : The shared secret between the client and the endpoint. This is encoded by the Trustbuilder password tool.

• port : Port used for the listener

• workflow : Which workflow has to be run by the engine when this service is called

Redis Service

Classname: be.securit.trustbuilder.service.RedisService

Requirements:

To use this service you must install to following jar in your application servers library. For TrustBuilder appliance this location is /opt/trustbuilder/tomcat-core/lib/ext

• Jedis> 2.9.0

Property:

• host Set the hostname of the redis server (only for single node)(this is for backwards compatibility and will be removed in the next major release)

• timeOutInSec Default time to live for a key that gets added in seconds.

• master Name of the master node.

• sentinels ";" - separated list with addresses of the sentinels.

• password Optional password for the redis cluster.

Invoking Redis in the scripts:

Since the Redis Service is a wrapper around the jedis calls we have to threat the function somewhat different than other services. The Redis Service is using a Pool of connections with tha Apache Commons pooling library.

Creating a pool :

var redispool = tb.getService("Redis");

Invoke the pool :

redispool.invoke(function(jedis){
    // Your redis commands are place here. The jedis name can be anything you want
    but you need it to call the commands
    jedis.set("foo", "bar");
});

This wil set a key "foo" with value "bar" in the Redis Server.

Functions:

Since redis has a lot of functions we will only explain the basics. Most functions are derived from the original redis commands fount on the Redis website.

Basic Functions:

set(key,data)

Set key to hold the string value. If key already holds a value, it is overwritten, regardless of its type. Any previous time to live associated with the key is discarded on successful SET operation.

jedis.set("foo", "bar");

get(key)

Get the value of key. If the key does not exist the special value nil is returned. An error is returned if the value stored at key is not a string, because GET only handles string values.

var data = jedis.get("foo");   // bar 

incr(key) incrBy(key, increment)

Increments the number stored at key by one. If the key does not exist, it is set to 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64 bit signed integers.

Note: this is a string operation because Redis does not have a dedicated integer type. The string stored at the key is interpreted as a base-10 64 bit signed integer to execute the operation.

Redis stores integers in their integer representation, so for string values that actually hold an integer, there is no overhead for storing the string representation of the integer.

jedis.incr("foo");  // increment 1 
jedis.incrBy("foo", 10);  // increment by 10

decr(key) decrBy(key)

Decrements the number stored at key by one. If the key does not exist, it is set to 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64 bit signed integers.

jedis.decr("foo");
jedis.decrBy("foo", 10);

Expire(key, seconds)

Set a timeout on key. After the timeout has expired, the key will automatically be deleted. A key with an associated timeout is often said to be volatile in Redis terminology. The timeout is cleared only when the key is removed using the DEL command or overwritten using the SET or GETSET commands. This means that all the operations that conceptually alter the value stored at the key without replacing it with a new one will leave the timeout untouched. For instance, incrementing the value of a key with INCR, pushing a new value into a list with LPUSH, or altering the field value of a hash with HSET are all operations that will leave the timeout untouched. The timeout can also be cleared, turning the key back into a persistent key, using the PERSIST command.

Refreshing expires

It is possible to call EXPIRE using as argument a key that already has an existing expire set. In this case the time to live of a key is updated to the new value. There are many useful applications for this, an example is documented in the Navigation session pattern section below.

jedis.expire("foo", 300);   // Expire foo in 5 minutes

expireAt(key, timestamp)

EXPIREAT has the same effect and semantic as EXPIRE, but instead of specifying the number of seconds representing the TTL (time to live), it takes an absolute Unix timestamp (seconds since January 1, 1970).

Please for the specific semantics of the command refer to the documentation of EXPIRE. Background

EXPIREAT was introduced in order to convert relative timeouts to absolute timeouts for the AOF persistence mode. Of course, it can be used directly to specify that a given key should expire at a given time in the future.

jedis.expireAt("foo", "1414500547"");

persist(key)

Remove the existing timeout on key, turning the key from volatile (a key with an expire set) to persistent (a key that will never expire as no timeout is associated).

jedis.persist("foo");   // persist the foo key

setbit(key, bit, boolean)

Sets or clears the bit at offset in the string value stored at key. The bit is either set or cleared depending on value, which can be either 0 or 1. When key does not exist, a new string value is created. The string is grown to make sure it can hold a bit at offset. The offset argument is required to be greater than or equal to 0, and smaller than 232 (this limits bitmaps to 512MB). When the string at key is grown, added bits are set to 0.

jedis.set("foo", "0");  // Set foo to 0
jedis.setbit("foo", 3, true);
jedis.setbit("foo", 7, true);

/*
 * byte: 0 1 2 3 4 bit: 00010001 
 */

getbit(key, bit)

Returns the bit value at offset in the string value stored at key. When offset is beyond the string length, the string is assumed to be a contiguous space with 0 bits. When key does not exist it is assumed to be an empty string, so offset is always out of range and the value is also assumed to be a contiguous space with 0 bits.

jedis.getbit("foo",3);  // true
jedis.getbit("foo",5);  // false

Hashes

hset(key,field,data)

Sets field in the hash stored at key to value. If key does not exist, a new key holding a hash is created. If field already exists in the hash, it is overwritten.

jedis.hset("foo", "bar", "car");

hsetnx(key,field,data)

Sets field in the hash stored at key to value, only if field does not yet exist. If key does not exist, a new key holding a hash is created. If field already exists, this operation has no effect.

jedis.hsetnx("foo", "bar", "car");

hget(key,field)

Returns the value associated with field in the hash stored at key.

jedis.hget("foo", "bar");    // car 

hmset(key, key/value object)

Sets the specified fields to their respective values in the hash stored at key. This command overwrites any existing fields in the hash. If key does not exist, a new key holding a hash is created.

jedis.hmset("foo", { bar : "car", user : "John");

hgetAll(key)

Returns all fields and values of the hash stored at key. In the returned value, every field name is followed by its value, so the length of the reply is twice the size of the hash.

var data = jedis.hgetall("foo");   
 var user = data.get("user");      // John 

hmget(key, field, [field])

Returns the values associated with the specified fields in the hash stored at key. For every field that does not exist in the hash, a nil value is returned. Because a non-existing keys are treated as empty hashes, running HMGET against a non-existing key will return a list of nil values.

var data = jedis.hmget("foo", "bar", "user");
var user = data.get("user");      // John 

hexists(key, field)

Returns if field is an existing field in the hash stored at key.

var dataexists = jedis.hexists("bar", "foo");  // true 
var datanotexists = jedis.hexists("bar", "example");  // false

hdel(key, field, [field])

Removes the specified fields from the hash stored at key. Specified fields that do not exist within this hash are ignored. If key does not exist, it is treated as an empty hash and this command returns 0.

Remark : to remove a complete hash you have to use the delete command (del)

// deleting a field 
jedis.hdel("foo", "bar"); 

// deleting a complete hash
jedis.del("foo");

hlen(key)

Returns the number of fields contained in the hash stored at key.

var length = jedis.hlen("foo");    // 2

Expiring hashes

Only a full hash can be set to expire, not the fields on their own.

Digipass Service

Requirements:

To use this service you must first install the VACMAN Controller. Then you need to do the following steps:

• Add the aal2wrap.jar to your classpath. The file can be found in your VACMAN controller installation directory.

• Add the VACMAN controller library to your classpath or to your java.library.path. The file can be found in your VACMAN controller installation directory. Make sure the version matches your platform.

• Create a MySQL database scheme and populate it using the digipassservicemysql.sql script. It can be found in the trustbuilder.war.

Property:

Database Properties

Digipass Properties

Invoking Digipass Service in the scripts:

The Digipass service is used to load the Digipass tokens into the database and use them to do validation.

Retrieving the service :

var digipassService = tb.getService("DigipassService");

Functions:

loadDPX(filename, transportkey, staticvector)

Loads the DPX file specified in the filename parameter and stores it into the database. The transportkey is the key used to decrypt the DPX file. If the staticvector parameter is not specified, the call will try to retieve it from the DPX file. If you specify the staticvector parameter, it should be the unencrypted staticvector.

digipassService.loadDPX("/opt/securit/dpx/demo.dpx", "11111111111111111111111111111111", null);

This method can throw SQLExceptions and DigipassExceptions which should be handled by the caller.

generateActivationCode(serialnumber)

This method activates the Digipass token and returns a digipass activation object. This digipass activation object contains 3 fields that can be retrieved: * Serial number with getSerialNumber(). * Activation code with getActivationCode(). * Encrypted event reactivation counter with getXerc().

var data = digipassService.generateActivationCode("VDS10000120");

This method can throw SQLExceptions and DigipassExceptions which should be handled by the caller.

validateOtp(serial, application, otp)

Validates the One Time Password (OTP) for that serial number and application. If the Digipass serial only has one Response Only application, then application should not be supplied in the parameters. Otherwise it is required.

digipassService.validateOtp("VDS10000120", null, "123456");

This method can throw SQLExceptions, DigipassExceptions and IllegalArgumentException which should be handled by the caller.

getFreeDigipass(dpType)

This method returns the serial number of the first available Digipass of that type or the first free Digipass that is available (if dpType is not specified). There are 5 different values for status.

• Free (0)

• Pending (1)

• Assigned (2)

• Revoked (99)

• Unavailable (-1)

Depending on the situation you may update the status from Free to Pending or from Free to Assigned.

digipassService.getFreeDigipass("DP300");

This method can throw SQLExceptions which should be handled by the caller.

getFreeLicense()

This method returns the serial number of the first available MDL Digipass license. We have 5 possible  status values:

• Free (0)

• Pending (1)

• Assigned (2)

• Revoked (99)

• Unavailable (-1)

digipassService.getFreeLicense();

This method can throw SQLExceptions which should be handled by the caller.

updateDigipassStatus(serialnumber, status, application)

Updates the status of the Digipass serial to the specified status. We have 3 statusses:

• Free (0)

• Pending (1)

• Assigned (2)

• Revoked (99)

• Unavailable (-1)

If the application is specified, only that application status is updated. In general you will want to update all the statusses of the Digipass applications to a certain value.

digipassService.getFreeDigipass("VDS10000120", 2, null);

This method can throw SQLExceptions and IllegalArgumentException which should be handled by the caller.

updateLicenseStatus(serialnumber, status)

Updates the status of a specific Digipass  MDL license to the specified status. We have 5 status values:

• Free (0)

• Pending (1)

• Assigned (2)

• Revoked (99)

• Unavailable (-1)

digipassService.updateLicenseStatus("VDS10000120", 2);

This method can throw SQLExceptions and IllegalArgumentException which should be handled by the caller.

updateInstanceStatus(serialnumber, instanceNumber, status)

Updates the status of a specific instance for a specific Digipass  MDL license to the specified status. We have 5 status values:

• Free (0)

• Pending (1)

• Assigned (2)

• Revoked (99)

• Unavailable (-1)

digipassService.updateInstanceStatus("VDS10000120",1,2);

This method can throw SQLExceptions and IllegalArgumentException which should be handled by the caller.

getDigipassStatus(serialnumber, application)

Returns the status of the Digipass as an integer based on the serial number and the application (optional). If the application is not supplied, all the applications should have the same status or -1 will be returned.

var status = digipassService.getDigipassStatus("VDS10000120");

getDigipassByDpType(dpType, status)

Returns an array of DigipassToken objects for a specific type and status

digipassService.getDigipassByDpType("DP300",0);

Returns an array of objects

[{"serialNumber":"VDS10000120",
  "dpMode":"CR", //possible values are CR, RO, SG and MM
  "dpBlob":"12f1ds231f23ds, //base64 encoded string of the blob
  "dpType":"DP300",
  "application":"APPL1",
  "sharedSecret":"1346", //aka Pin
  "staticVector":"456f4ds54fd65s",
  "statusChanged":1525770790000,
  "status":"FREE",
  "blobCounter":2
}]

getDigipassTypes()

Returns an array of strings of digipass types available in the database.

digipassService.getDigipassTypes();

Returns an array of strings

["DP300","DP700","DPMOB"]

resetTokenBlobs(serialnumber)

This method resets all the Digipass application blobs.

digipassService.resetTokenBlobs("VDS10000120");

changeStaticPassword(serialnumber, pwd1, pwd2)

This methods allows you to reset the static/server PIN from a Digipass token. The Digipass token will need to support the server PIN functionality (for example the Digipass GO 1). Generated OTPs will need to be prepended with this server PIN. The parameters pwd1 and pwd2 will need to be identical in order to successfully change the server PIN.

resetStaticPassword(serialnumber)

This function is used in combination with a DIGIPASS that can use a static PIN (e.g. DIGIPASS GO 1). The user will have to define his static PIN at the next authentication request. In order to activate this option, the PIN Change Allowed functionality has to be activated.

digipassService.resetStaticPassword("VDS10000120");

mdlGenerateLicenseActivationMsg(serialnumber, crontosize, crontoonpaper)

Generates the first activation message in the process of activation of a multi-device license

digipassService.mdlGenerateLicenseActivationMsg("VDS10000120",400,false);

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "challenge":"challengeString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>

mdlGenerateInstanceActivationMsg(serialnumber, challenge, devicecode, crontosize, crontoonpaper)

Generates the second activation message in the process of a multi device license.  The cronto size argument defines the size of the cronto image, in pixels, that is to be created

digipassService.mdlGenerateInstanceActivationMsg("VDS10000120","theChallenge","deviceID", 400, false);

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString",
 "instanceNumber":"12346"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>

mdlGenAuthRequest(serialnumber, DigipassMdlSignOptions)

Generates an authentication request which can be used to authenticate an end user when multi-device license is installed.  The serialnumber argument is the serial number of an instance token to generate the authentication request for. The options can be null to use the default signing options or an object.

digipassService.mdlGenAuthRequest("VDS10000120",null);

This is an example of the options object:

{"crontoSize":10,
 "crontoOnPaper":false,
 "crontoOnHw":false,
 "msgBase64":true,
 "spacesAsTabs:2,
 "spacesString":null,
 "title":null,
 "vascoAskApproval":true,
 "vascoAskPin":true,
 "vascoShowData":true,
 "vascoShowMac":true,
 "vascoShowWarning":true}

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>

mdlGenFTRequest(serialnumber, freetext, options)

Generates a free text request which can be used to authenticate an end user when using a multi-device license.

digipassService.mdlGenFTRequest("VDS10000120","freeTextString",{options});

This is an example of the options object:

{"crontoSize":10,
 "crontoOnPaper":false,
 "crontoOnHw":false,
 "msgBase64":true,
 "spacesAsTabs:2,
 "spacesString":null,
 "title":null,
 "vascoAskApproval":true,
 "vascoAskPin":true,
 "vascoShowData":true,
 "vascoShowMac":true,
 "vascoShowWarning":false}

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>

mdlGenSignRequest(serialnumber,  [{"key":"value"}], {options})

Generates a signing request which can be used to authorize a transaction of the end user

digipassService.mdlGenSignRequest("VDS10000120",[{"key":"value"}, {"key2","value2"}],{options});

This is an example of the options object:

{"crontoSize":10,
 "crontoOnPaper":false,
 "crontoOnHw":false,
 "msgBase64":true,
 "spacesAsTabs:2,
 "spacesString":null,
 "title":null,
 "vascoAskApproval":true,
 "vascoAskPin":true,
 "vascoShowData":true,
 "vascoShowMac":true,
 "vascoShowWarning":false}

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>

mdlValidateInstanceActivationMsg(serialnumber, sequencenumber, message, signature, expirationtimeSeconds)

Validates the response to the instance activation message

digipassService.mdlValidateInstanceActivationMsg("VDS10000120","1234","generatedActivationMessage","signatureToValidateString",120);

The returning object is as below. 

{"instanceToken":
   {"serialNumber":"VDS10000120",
    "instanceNumber":"12345",
    "applicationName":"APPL1",
    "deviceId":"458f7ds895fe4w4f8edw5f4af",
    "deviceType":"DP110" 
   },
 "statusCode":"203"
}

mdlValidateSignature(serialnumber, signedmessage, signature, expirationtime)

Validates a supplied signature to a signed message which was generated by mdlGenAuthRequest() mdlGenSignRequest()

digipassService.mdlValidateSignature("VDS10000120","originalSignedMessage","signatureToCheck",120);

The returning object is as below. 

{"instanceToken":
   {"serialNumber":"VDS10000120",
    "instanceNumber":"12345",
    "applicationName":"APPL1",
    "deviceId":"458f7ds895fe4w4f8edw5f4af",
    "deviceType":"DP110" 
   },
 "statusCode":"203"
}

generateActivationCode(serialnumber)

Generates an activation code for use with single lincense tokens. The response returns an XFAD for online activation.

digipassService.generateActivationCode("VDS10000120");

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "activationCode":"45fds4f94dsa65",
 "xerc":"456f4dsa56f4ds"
}

blockLicenseInstances(serialnumber, block)

Blocks a Digipass MDL licences. If block is true then the status is set to revoked. If block is false then status is set to assigned.

digipassService.blockLicenseInstances("VDS10000120",true);

blockSingleLicenseInstance(serialnumber, instanceNumber, block)

Blocks a single instance of a Digipass MDL licence. If block is true then the status is set to revoked. If block is false then status is set to assigned.

digipassService.blockSingleLicenseInstance("VDS10000120",1,true);

blockTokenApp(serialnumber, app, block)

Blocks a single application of a single token. If block is true then the status is set to revoked. If block is false then status is set to assigned.

digipassService.blockTokenApp("VDS10000120","APPL1",true);

getLicense(serialnumber)

Get a single license by it's serial number. Returns a DigipassLicense object

digipassService.getLicense("VDS10000120");

{serialNumber:"VDS10000120",
 "activationType":"online",
  "masterAppName":"ACTIV APP",
  "masterAppAMode":"MA",
  "masterAppBlob":"456f4dsa56f4ds",
  "activationVector":"456f4d5sf4d5s6ds",
  "payloadKeyBlob":"56f4dsa56f4d6",
  "status":PENDING,
  "messageVector":"1",
  "staticVector:"1",
  "tokens":[arrayOfTokenObjectsBeingActivatedInstances]
}

getInstance(serialnumber, instanceNumber)

Get a single token instance for a specific MDL license by the serial number of the license and the instance number of the token instance. Returns a DigipassToken object

digipassService.getInstance("VDS10000120",1);

{"serialNumber":"VDS10000120",
  "dpMode":"CR", //possible values are CR, RO, SG and MM
  "dpBlob":"12f1ds231f23ds, //base64 encoded string of the blob
  "dpType":"DP300",
  "application":"APPL1",
  "sharedSecret":"1346", //aka Pin
  "staticVector":"456f4ds54fd65s",
  "statusChanged":1525770790000,
  "status":"ASSIGNED",
  "blobCounter":2,
  "instanceNumber":1
}

QR Service

Invoking QR Service in the scripts:

The purpose of the QR service is to create a QR code based on an input string.

Retrieving the service :

var qrService = tb.getService("QRService");

Functions:

generateQrBase64(input,size)

Generates a QR code based on the string input. The optional size parameter specifies the size of the QR image. The default size is 125 pixels. The output is base64 encoded PNG image with the specified size.

qrService.generateQrBase64("http://mysite/context", 250);

Mobile Authenticator Service

This is a set of properties that have to be set on the service that define an issuer. Once these properties are set and the service is started, you cannot effectively change these properties.

• url

• mobileTimeoutInSeconds

• transactionTimeoutInSeconds

• issuerName

• otpLength

• algorithm

• qrCodeSizeInPixels

Properties:

These are other properties that have to be set on the service.

Functions:

pollStatus(actionUID) -> AuthenticationRequest

Fetches the authentication request linked to that actionUID. If there is no authentication request found, you will get null.

fetchAuthenticationRequest(deviceUID) -> AuthenticationRequest

Fetches the oldest new authentication request linked to that deviceUID. If there is no authentication request found, you will get null.

requestAuthentication(issuer, username, actionType, description) -> actionUID

Create an authentication request. actionType has to be AUTHENTICATE.

authenticate(message, actionUID) -> boolean

Confirm the request linked to that actionUID. Returns true if a request was found for that actionUID, otherwise returns false.

cancel(actionUID) -> boolean

Cancel the request linked to that actionUID. Returns true if a request was found for that actionUID, otherwise returns false.

register(issuer, username) -> qr code base64

registrationCallback(identifier, deviceUID) -> boolean

How to use:

First, a user has to register. You can use the register function to accomplish that. The mobile app will do a callback call to the url (defined in issuer properties) appended with "/register/callback". That callback request will contain the parameters "deviceUID" and "tbid" in the body, where "tbid" has as value the identifier. These parameters can be used to finalize the registration by calling the registrationCallback function.

When a user is registered that user can try to log in. We can start a login procedure by calling the requestAuthentication function. We can poll for the authentication request with the actionUID. The device polls for the authentication request with the deviceUID to the url (defined in issuer properties) appended with "/poll/{deviceUID}". The response from the device will arrive in the url (defined in issuer properties) appended with "/tokenresponse". The response consists of the properties "status", "message" and "actionUID" in the response body. If the status is not equal to "OK" (case is ignored), the login is cancelled, else the login succeeds.

Data:

AuthenticationRequest

The authentication request contains the following fields:

• issuer

• username

• actionType: For now actionType is always AUTHENTICATE

• deviceUID: UID of the device linked to this authentication request

• actionUID: UID of the request

• description

• authenticationStatus: The authenticationStatus can be any of the following (with accompanying value in the database): NEW(0), VALIDATED(1), CANCELLED(2), OTP_FAILED(3), TIMED_OUT(4), NOT_PRESENT(5)

InternalApiPublicService

io.trustbuilder.andromeda.internalapi.InternalApiPublicService

This service has a method available to make direct API calls to IDHub. This avoid the need to use a HTTP Adapter to make these calls. The method has one mandatory parameter and one optional parameter. 

.callInternalApi( request )

.callInternalApi( request, userName )

var loggingFormat = { name: 'frominternal', format: 'teststee' };
var request = {
  method: 'POST',
  path: '/admin/api/v1/gateway/loggingformats', 
  headers: {"Content-Type" : "application/json"},
  encoding: 'utf-8',
  body: JSON.stringify(loggingFormat)
};
var internalCall = tb.getService('internalCall');
var response = internalCall.callInternalApi(request); // session inherit

var request = {
  method: 'GET',
  path: '/admin/api/v1/'
};
var internalCall = tb.getService('internalCall');
var userName = 'IDHUB_ADMINISTRATOR';
var response = internalCall.callInternalApi(request, userName); // impersonate

Mobile Authenticator ScriptService

Service Description:

Service Class : io.trustbuilder.andromeda.protocols.mobile.MobileAuthenticatorScriptService

Functions :

(all functions will return null if a mobile idp is not properly configured)

getServer()

    Returns a java Server object (class : io.trustbuilder.andromeda.protocols.mobile.client.Server)

    It has the following getters, returning the Mobile IDP server properties :

    It has setters too, but they won't affect the actual server.

• getAccountCount()

• getAppandroid()

• getAppios()

• getAppname()

• getAppurl()

• getLastLogin()

• getLogo()

• getOwner()

• getPingTime()

• getPinTimeout()

• getPinTransTimeout()

• getServerFlags()

• getServerid()

• getServerName()

• getServerpk()

• getSiteurl()

• getWsurl()

register()

    Returns a String which is the base64 encoded PNG of the registration QR for the current user.

    This method will fail if no user is authenticated as principal

getQR()

    Returns a String which is the base64 encoded PNG of a login QR.

getVash()

    Returns a String which is the base64 encoded PNG of the server Vash.

provoke()

    Attempts to send a push notification to the user. 

    This will use the userid based on the login hint cookie handed out by idhub.

    Returns a boolean indicating success or failure.

provoke(userid)

    userid: String containing the userid as known on the Mobile IDP server.

    Returns a boolean indicating success or failure.

getStatus()

    Returns a java LoginStatus object (class : io.trustbuilder.andromeda.protocols.mobile.client.LoginStatus)

    It has the following getters, returning the login status properties :

    It has setters too, but they won't affect the actual login status.

• getAccountid()

• getHsid()

• getLoginqrdata()

• getPk()

• getUserid()

• isCanprovoke()

• isLoggedin()