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:
property name | description |
---|---|
key | base64 encoded binary key |
iv | base64 encoded binary iv |
encryptedKey | password tool encoded key |
encryptedIv | password tool encoded iv |
PKCS8EncodedKeySpec | base64 encoded binary public key |
RsaPublicKey | base64 encoded binary public key |
RsaPkcs8PublicKey | base64 encoded binary public key |
encoding | sets the encoding format (default "UTF-8" |
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:
function | Description |
---|---|
encrypt(cipher,string,format) | Encrypt the string and return the encrypted data in the format (base64,hex,y64) |
decrypt(cipher,encryptedString,format) | Decrypt the encryptedString by decoding in format (base64,hex,y64) and return the original string |
generateHMac(cipher,string,inputformat, outputformat) | Encrypt the string with hmac and return the result in the outputformat (base64,hex, y64). |
hash(hashAlg, message, encodingFormat) | Hash (according to the hashAlg=algorithm) the message and return it in the encoding format (base64, hex, y64) |
saltedHash(password, salt) | Hashes (sha-1) the concatenated password+salt and retuns it base64 encoded |
generateSalt(int len) | Generates a salt with the specified length |
sign([algorithm](http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#Signature ), data, decodingFormat, encodingFormat) | Sign decoded data (using decodingFormat) and encode the signed data |
verify([algorithm](http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#Signature ), data, signature, decodingFormat) | Verify the signed data by first decoding it using the decodingFormat. Returns boolean indicating whether the signature matched or not. |
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
Property | Description |
---|---|
jdbcUrl | The JDBC Url you want to use to connect to the database. |
username | The username to use to connect to the database. |
password | The username password to connect to the database. |
Digipass Properties
Property | Default | Description |
---|---|---|
CheckChallenge | 1 | 0: No challenge checking |
CheckInactiveDays | 0 | Acceptable number of days of user/token inactivity. Past this number, returncode 205 will be genrated and the digipass will have to be reset. |
DeriveVector | 0 | Vector used to make the data encryption unique for a host |
DiagnosticLevel | 0 | Requested diagnostic level |
EventWindow | 100 | Expressed in number of iterations |
GMTAdjustment | 0 | GMT Time adjustment to perform in case the C language gmtime function doesn' t give an accurate value |
HSMSLotId | 0 | HSM Slot Id used to store Storage Key and Transport Key |
IdentificationTreshold | 0 | Number of successive identification errors that will cause server-side locking of the digipass. |
IdentificationTimeWindow | 100 | This size determines the acceptable time difference between a digipass and the host system for identification function. This difference is adjusted to the last knows shift for each token. |
OnlineSignature | 0 | Level of online signature |
SignatureTreshold | 0 | Number of successive signature errors that will cause server-side locking of the digipass. |
SignatureTimeWindow | 24 | Signature window size in number of time steps. |
StorageDeriveKey1 | 0 | Derivation key part 1 used to make data encryption unique for a host. |
StorageDeriveKey2 | 0 | Derivation key part 2 used to make data encryption unique for a host. |
StorageDeriveKey3 | 0 | Derivation key part 3 used to make data encryption unique for a host. |
StorageDeriveKey4 | 0 | Derivation key part 4 used to make data encryption unique for a host. |
StorageKeyId | 0 | Key Id used to read (Decrypt) DIGIPASS Blob from database. |
TransportKeyId | 8388607 | Key Id used to read (Decrypt) DIGIPASS Blob from database. |
SynchronizationWindow | 6 hours | The Initial Time Synchronization Window - for the first verification of a DIGIPASS. This |
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.
Property | Description |
---|---|
type | The type of the authenticator service. The type PULLING is already available. |
issuerAndTokenStoreJdbcUrl | The jdbc url for the issuerAndTokenStore |
issuerAndTokenStoreUsername | The username for the issuerAndTokenStore |
issuerAndTokenStorePassword | The password for the issuerAndTokenStore |
requestStoreJdbcUrl | The jdbc url for the requestStore |
requestStoreUsername | The username for the requestStore |
requestStorePassword | The password for the requestStore |
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()