<< back to the Securely main page
BenCoding.Securely.Properties
The Securely Properties module is used to store values in the KeyChain using the same API as Titanium.App.Properties.
* First you need to download and install the module as discussed [here.](https://github.com/benbahrenburg/Securely) * You can now use the module via the commonJS require method, example shown below.
var securely = require('bencoding.securely');
Requiring the module into your project
//Require the securely module into your project
var securely = require('bencoding.securely');
Parameters
identifier : String
This parameter is optional. If no value is provided, the bundle name on iOS or the PackageName on Android is used. identifier allows you to segment each property with an identifier, if needed.
accessGroup : String
This parameter is an optional value used on the iOS platform. Access groups can be used to share keychain items among two or more applications. If no access group is provided, the keychain values will only be accessible within the app saving the values.
secret : String
This is a required parameter. secret is the password used to encrypt and decrypt all property values. The same secret used to encrypt must be used during the decryption process or a null value will be returned.
encryptFieldNames : Boolean
This parameter is an optional value only used on the Android platform. When set to true, Securely will create an MD5 hash using the provided secret for all property names.
var properties = securely.createProperties({
secret:"sshh_dont_tell",
identifier:"myPropertyIdentifier",
accessGroup:"myAccessGroup",
encryptFieldNames:false
});
addEventListener( String name, Callback callback ) Adds the specified callback as an event listener for the named event.
Parameters name : String Name of the event. callback : Callback Callback function to invoke when the event is fired.
Returns void
Example
function onChange(e){
Ti.API.info("Property " + e.source + " changed");
};
//Use the properties variable shown in the require section
properties.addEventListener('changed',onChange);
getBool( String property, [Boolean default] ) : Boolean Returns the value of a KeyChain Property as a boolean data type.
Parameters property : String Name of property. default : Boolean (optional) Default value to return if KeyChain Property does not exist.
Returns Boolean
Example
//Use the properties variable shown in the require section
Titanium.API.debug('Bool: ' + properties.getBool('whatever',true));
getDouble( String property, [Number default] ) : Number Returns the value of a KeyChain Property as a double (double-precision, floating point) data type. This method must only be used to retrieve properties created with setDouble.
Parameters property : String Name of property. default : Number (optional) Default value to return if KeyChain Property does not exist.
Returns Number
Example
//Use the properties variable shown in the require section
Titanium.API.debug('Double: ' + (properties.getDouble('whatever',2.5));
getInt( String property, [Number default] ) : Number Returns the value of a KeyChain Property as an integer data type. This method must only be used to retrieve properties created with setInt. Use getDouble and setDouble to store values outside the integer data type range of -2,147,483,648 to 2,147,483,647.
Parameters property : String Name of property. default : Number (optional) Default value to return if KeyChain Property does not exist.
Returns Number
Example
//Use the properties variable shown in the require section
Titanium.API.debug('int: ' + properties.getInt('whatever',1));
getList( String property, [Object[] default] ) : Object[] Returns the value of a KeyChain Property as an array data type.
Parameters property : String Name of property. default : Object[] (optional) Default value to return if KeyChain Property does not exist.
Returns Object[]
Example
//Use the properties variable shown in the require section
Titanium.API.debug('StringList: ' + properties.getList('whatever'));
getObject( String property, [Object default] ) : Object Returns the value of a KeyChain Property as an object.
Parameters property : String Name of property. default : Object (optional) Default value to return if KeyChain Property does not exist.
Returns Object
Example
//Use the properties variable shown in the require section
Titanium.API.debug('Object: ' + properties.getObject('whatever'));
getString( String property, [String default] ) : String Returns the value of a KeyChain Property as a string data type.
Parameters property : String Name of property. default : String (optional) Default value to return if KeyChain Property does not exist.
Returns String
Example
//Use the properties variable shown in the require section
Titanium.API.debug('String: ' + properties.getString('whatever','foo'));
hasProperty( String property ) : Boolean Indicates whether a KeyChain Property exists.
Parameters property : String Name of property.
Returns Boolean
Example
//Use the properties variable shown in the require section
var exists = properties.hasProperty('String');
Titanium.API.info('String Property '+ ((exists)? " Exists" : " Doesn't Exist"));
listProperties( ) : Object[] Returns an array of KeyChain Property names.
If field name encryption is enabled ( android only ) null will always be returned.
Returns Object[]
Example
//Use the properties variable shown in the require section
//Will provide the name of all properties
var foo = properties.listProperties();
removeEventListener( String name, Callback callback ) Removes the specified callback as an event listener for the named event. Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove. When adding a listener, you must save a reference to the callback function in order to remove the listener later: var listener = function() { Ti.API.info("Event listener called."); } window.addEventListener('click', listener); To remove the listener, pass in a reference to the callback function: window.removeEventListener('click', listener);
Parameters name : String Name of the event. callback : Callback Callback function to remove. Must be the same function passed to addEventListener.
Returns void
Example
//Use the properties variable shown in the require section
//Remove the method we added in the addEventListener section
properties.removeEventListener('changed',onChange);
removeProperty( String property ) Removes a KeyChain Property if it exists, or does nothing otherwise.
Parameters property : String Name of property.
Returns void
Example
//Use the properties variable shown in the require section
var exists = properties.hasProperty('String');
Titanium.API.info('String Property '+ ((exists)? " Exists" : " Doesn't Exist"));
properties.removeProperty('String');
exists = properties.hasProperty('String');
Titanium.API.info('String Property '+ ((exists)? " Exists" : " Doesn't Exist"));
removeAllProperties Removes all KeyChain properties
Parameters N/A
Returns void
Example
//Use the properties variable shown in the require section
var exists = properties.hasProperty('String');
Titanium.API.info('String Property '+ ((exists)? " Exists" : " Doesn't Exist"));
properties.removeAllProperties();
exists = properties.hasProperty('String');
Titanium.API.info('String Property '+ ((exists)? " Exists" : " Doesn't Exist"));
setBool( String property, Boolean value ) Sets the value of a KeyChain Property as a boolean data type. The KeyChain Property will be created if it does not exist.
Parameters property : String Name of property. value : Boolean Property value.
Returns void
Example
//Use the properties variable shown in the require section
properties.setString('String','I am a String Value ');
setDouble( String property, Number value ) Sets the value of a KeyChain Property as a double (double-precision, floating point) data type. The KeyChain Property will be created if it does not exist.
Parameters property : String Name of property. value : Number Property value.
Returns void
Example
//Use the properties variable shown in the require section
properties.setDouble('Double',10.6);
setInt( String property, Number value ) Sets the value of a KeyChain Property as an integer data type. The KeyChain Property will be created if it does not exist. Use getDouble and setDouble to store values outside the integer data type range of -2,147,483,648 to 2,147,483,647.
Parameters property : String Name of property. value : Number KeyChain Property value, within the range -2,147,483,648 to 2,147,483,647.
Returns void
Example
//Use the properties variable shown in the require section
properties.setInt('Int',10);
setList( String property, Object[] value ) Sets the value of a KeyChain Property as an array data type. The KeyChain Property will be created if it does not exist.
Parameters property : String Name of property. value : Object[] Property value. Returns void
Example
var array = [
{name:'Name 1', address:'1 Main St'},
{name:'Name 2', address:'2 Main St'},
{name:'Name 3', address:'3 Main St'},
{name:'Name 4', address:'4 Main St'}
];
//Use the properties variable shown in the require section
properties.setList('MyList',array);
setObject( String property, Object value ) Sets the value of a KeyChain Property as an object data type. The KeyChain Property will be created if it does not exist.
Parameters property : String Name of property. value : Object Property value. Returns void
Example
var array = [
{name:'Name 1', address:'1 Main St'},
{name:'Name 2', address:'2 Main St'},
{name:'Name 3', address:'3 Main St'},
{name:'Name 4', address:'4 Main St'}
];
//Use the properties variable shown in the require section
properties.setObject('MyObject',array);
hasFieldsEncrypted( ) : Boolean Returns true if field name encryption is enabled or false if not.
Please note to enable this feature you must create a new property object using the encryptFieldNames set to true.
Parameters property : String Name of property. default : Number (optional) Default value to return if KeyChain Property does not exist.
Returns Number
Example
//Use the properties variable shown in the require section
Titanium.API.debug('int: ' + properties.getInt('whatever',1));
changed The event is fired when the application changes a KeyChain Property directly using one of the Properties methods.
Securely for iOS uses several wonderful open source projects. I highly encourage you to check them out using the information below.JSONKit
Project: https://github.com/johnezang/JSONKit
PDKeychainBindingsController
Project: https://github.com/carlbrown/PDKeychainBindingsController
Please note the keyChain entries will still present on the device after you uninstall your app. You will need to design your app workflow to handle this if there is a need to remove or refresh these entries.This is a feature of the Apple KeyChain API itself and beyond the control of the module.