Services
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
StoreEncryptionService be.securit.trustbuilder.service.StoreEncryptionService
Radius Endpoint Service be.securit.trustbuilder.service.RadiusService
Ldap Endpoint Service be.securit.trustbuilder.service.LdapService
Domtai Service be.securit.trustbuilder.service.DomTai
AMQProducerService: be.securit.trustbuilder.service.AMQProducerService
AMQConsumerService: be.securit.trustbuilder.service.AMQConsumerService
Getting direct access to a service from within the workflow can be done via the following
tb.getService("urlStore");
Session Management
Basic Session management in Trustbuilder can be enabled by adding the following property in trustbuilder.properties in the TB_HOME folder. This will delegate the storage of the session attributes into the container session.
sessionService=true
The sessions can be stored in third-party storage services too. For this, you should set the property to the id of the service handling the storing/retrieval. Currently 3 other backends are available: Database, Memcached and Redis (For configuration see the services section). But it's pretty trivial to write your own, provided that this service implements TrustBuilderCacheService.
In order to use the session service in the workflow 4 functions were created:
// Get a session variable by it's key
getSessionVariable(key)
// Set a session variable with a specific key/value pair
setSessionVariable(key,value)
// Set the timeout of a session in case of a servlet backed session
setSessionTimeoutInSec(sec)
// InvalidateSession Invalidate the session in case of a servlet backed session
invalidateSession()
For example an in-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 specifies how long a key exists in the store in milliseconds.
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
Properties
keySpec password tool encoded key key raw base64 encoded key iv initialization vector for ciphers in feedback mode (encoded with password tool) encoding Sets the character encoding , default is UTF-8
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 |
sign(algorithm,data,decodingFormat,encodingFormat) | Sign the data decoded with decodingFormat and return the signature in the encodingFormat (base64,hex,y64) |
verify(algorithm,data,signature,decodingFormat) | Verify the data by decoding in decodingFormat (base64,hex,y64) |
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 |
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
Store Encryption Service
Same as the encryption service but uses key/truststores to encrypt/decrypt/sign/verify
Properties
encoding Sets the character encoding , default is UTF-8
Functions
function | Description |
---|---|
encrypt(cipher,keyname,data,format) | Encrypt the data and return the encrypted data in the format (base64,hex,y64) using the public key from the certificate found in the truststore |
decrypt(cipher,keyname,encryptedString,format) | Decrypt the encryptedString by decoding in format (base64,hex,y64) and return the original string using the private key from the keystore |
sign(algorithm,keyname,data,decodingFormat,encodingFormat) | Sign the data decoded with decodingFormat and return the signature in the encodingFormat (base64,hex,y64) using the private key found in the keystore. |
verify(algorithm,keyname,data,signature,decodingFormat) | Verify the data by decoding in decodingFormat (base64,hex,y64) using the public key of the certificate found in the truststore. |
generateHMac(cipher,keyname,data,inputformat, outputformat) | Encrypt the data with hmac and return the result in the outputformat (base64,hex, y64). |
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
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
redis: be.securit.trustbuilder.service.RedisService
Properties: * host (supports multiple addresses) * 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
AMQProducerService
Classname: be.securit.trustbuilder.service.AMQProducerService
This service (from here on referred to as producer) is used for sending a message with a certain topic to an exchange, which will deliver it to the consumer(s) (configured by AMQProducerServices) listening to that topic. The delivering and handling of the message is done asynchronously.
Properties
Username: Username for accessing the queuingserver.
Password: Password for accessing the queuingserver.
Host: Host of the queuingserver this producer will send messages to.
Port: Port of the queuingserver this producer will send messages to.
Exchange: The exchange this producer will send messages to.
Topics: The topics this producer is allowed to send messages with.
Functions
send(message, topic): Send a message; message can be any JavaScript object, topic must be a String. Returns an object containing a status key and a message key. Below you can find the different possible status values and corresponding information:
0: OK.
1: This producer is not allowed to send messages with this topic.
2: Internal error.
AMQConsumerService
Classname: be.securit.trustbuilder.service.AMQConsumerService
This service (from here on referred to as consumer) is used for receiving and handling messages.
Properties
Username: Username for accessing the queuingserver.
Password: Password for accessing the queuingserver.
Host: Host of the queuingserver this consumer will receive messages from.
Port: Port of the queuingserver this consumer will receive messages from.
Queue: The queue this consumer is accepting messages from.
Exchange: The exchange the aforementioned queue is getting messages from.
Topics: The topics the queue associated with this consumer will accept from the exchange. (special case: If the same queue is already bound to another consumer or other consumers, the topics this queue will listen to will be the union of the topics for each consumer)
Workflow: The workflow that will handle the messages.