- Created by Armando Carratala , last modified on Jun 01, 2020
You are viewing an old version of this content. View the current version.
Compare with Current View Version History
« Previous Version 3 Next »
Description
AlisonSDK Mobile is a native library for IOS and Android platform.
This library generates CAdES digital signatures for strings, and allows installation of digital certificates under a security policy that protect the certificate usage.
This library offers a similar behaviour under both platforms, complying with a common security policy layer. This security policy protects certificate usage, controlled by the certificate issuer.
Platform compatibility
Android | IOS |
Latest ✔ | Latest ✔ |
Download
You can download latest stable release of AlisonSDK-Mobile:
Future Releases
It is possible to access future releases of the library to test new features to be implemented.
.
Disclaimer
Disclaimer
This is a work in progress.
It may be subject to changes in the future.
Related Product
Security Policy
Security Policy defines rules to protect certificate usage.
Following fields can be included into a security policy.
Field | example | Description |
---|---|---|
name | client_name | Name of the policy. It can be used to recognise between different policies and values. |
version | 5.0.1 | Version of the policy. |
security_level | 2 | Security level required to protect the certificate. This value is explained below. |
max_try | 5 | Limit of tries to enter a password or biometric factor. After the second try, a "toast or flash" message is displayed on screen. After reach the limit defined with this value, action defined in "behaviour" is executed. |
fail_behavior* | lock || erase | This action is executed after reaching the max_try value.
|
fail_timeout | 10 | Minutes to lock the certificate usage. |
Note: a typo was introduced in original library and is maintained by backward compatibility.
Security Level table
Dec | Hex | Description |
---|---|---|
0 | 0x0000 | none security. Each certificate can be used without any kind of control. |
1 | 0x0001 | requires lock-screen of the device to activate the certificate usage. |
2 | 0x0001 | requires biometric lock. If biometric lock is not available, level 1 is requiered. |
3 | 0x0003 | any kind of lock (level_1 or level_2). |
4 | 0x0004 | the password that protect the certificate is requiered. |
1025 | 0x0401 | password AND lock-screen is required. Both factor must be entered by the user. |
1026 | 0x0402 | password AND biometric is required. |
.
Methods
List of available methods.
Initialize
AlisonMobileSDK is a static class used to define some general behaviours of the library and to obtain execution results..
This class must be used to initialize the library before of using any of its methods or classes.
This method must be invoked after OnCreate callback and before of SetContent function. This is required condition to setup the language correctly.
initializeAlisonMobile( String initializeName, String language, boolean notification, Context context, String baseUrl );
Argument | Values | Description |
---|---|---|
initializeName | string | it must indicate a unique identifier for the library. This identifier is used to mark those certificates related to this application. |
language | en | es | language of the messages to show to the user. Other values can be used but programmer must extend the language definitions provided by the library. if none (null) value is defined, then the library uses the OS language. |
notification | false | this value indicates to the library if toast messages must be displayed or not. |
context | this is the context of the activity requiring this function. | |
baseUrl | URL where to call to fetch renewal or inform the installation of a new request. This URL is provided by the certification authority, like: "https://panel.certisur.com/panel/acme" |
.
Version
String getLibVersion();
This method can be used to determine the library version. This can be useful under certain development conditions. This is a static method of AlisonMobileSDK.
.
Operations
This library is implemented as an general administrator of operation to be performed. Each operation has its own result, which is communicated to the caller throw the corresponding callback.
The function onActivityResult(int requestCode, int resultCode, Intent data) is used as a callback.
Each kind of operation has a specific class, and specific methods to use.
AlisonAuthOperation
This class can be used to generate a signed authentication token. This token is used to determine the certificate used to login into the application.
authOp = new AlisonAuthOperation(String certAlias);
Argument | Description |
---|---|
certAlias | Receives the certificate alias that identify the certificate. If none parameter is provided, then the library select automatically the certificate to be used. |
.
AlisonSignatureOperation
This class can be used to generate a signed authentication token. This token is used to determine the certificate used to login into the application.
authOp = new AlisonAuthOperation(String certAlias);
Argument | Description |
---|---|
.
AlisonImportOperation
This class can be used to generate a signed authentication token. This token is used to determine the certificate used to login into the application.
AlisonAuthOperation authOp = new AlisonAuthOperation(String certAlias);
.
AlisonSignatureOperation
This class can be used to generate a signature of a string.
The signature is CAdES format, without data included into it.
signOp = new AlisonSignatureOperation(String text2sign, String certAlias);
If none certAlias is specified, then the last used certificate is selected for this operation.
If there is more than one certificate that can be used, then the select-certificate windows is displayed.
.
AlisonAuthOperation
Argument | Required | Description |
---|---|---|
urls | ✘ | Array of interfaces to communicate with Alison-Desktop or Alison-Server. The default value is ['https://127.0.0.1:8004', https://127.0.0.1:8005 ]. |
Detect / Enable
Detect if some certificate provider (AlisonDesktop) is installed and enabled into the browser.
These methods allow to check if Alison-Desktop is running, and if it is enabled into the browser used. These method must be used after Alison-Desktop initialization returning an error code 20404
.
If method initialize()
was successful, it's not necessary to call any of these methods.
Available from version 3.0.1+.
isRunning()
Detect if Alison-Desktop is running.
isRunning(): Promise<{ result: boolean }>
isEnabled()
Detect if Alison-Desktop is enabled into the browser used.
isEnabled(): Promise<{ result: boolean }>
enable()
Request AlisonDesktop to ingrate with the browser used.
enable(): Promise<{}>
Note: all these methods depend on security features enabled by browsers, and its accuracy cannot be guaranteed working on any platform and/or browser.
.
Generate CSR
Generates a keyPair and a Certificate Signing Request.
generateCsr({ keyStore: KeyStore options?: { algorithm?: string size?: number signatureAlgorithm?: string } securityPolicy?: SecurityPolicy }): Promise<{ csr: string }>
Argument | Required | Description |
---|---|---|
keyStore | ✔ | AlisonJS SDK#KeyStore where to generate the certificate request. |
options | ✘ | Default values are: { algorithm: 'RSA', size: 2048, csrAlgorithm: 'SHA256WITHRSA' } |
securityPolicy | ✘ | Security requirements to be applied to the keyStore/profile. |
alison.generateCsr({ keyStore: { id: "WIN-ENH" }, options: { size: 2048 }, securityPolicy: { exportable: true } }).then( function({ csr }) { // handle success }, function({ code, detail }) { // handle failure } )
.
Install Certificate
Installs the certificate into the Keystore/profile indicated. Returns AlisonJS SDK#WebCertificate
installPkcs7({ keyStore: KeyStore pkcs7: string securityPolicy?: SecurityPolicy }): Promise<{ certificate: WebCertificate }>
Argument | Required | Description |
---|---|---|
keyStore | ✔ | AlisonJS SDK#KeyStore where the privateKey is stored |
pkcs7 | ✔ | Certificate (X.509) and/or Certificate chain (PKCS#7 structure) to be installed (in base64 format). None PEM header must be included. |
securityPolicy | ✘ | Security requirements to be applied to the keyStore/profile. |
alison.installPkcs7({ keyStore: { id: "WIN-ENH" }, pkcs7: "MIICU5iNXuudGfc=" }).then( function({ certificate }) { // handle success }, function({ code, detail }) { // handle failure } )
.
KeyStore List
Lists ids of available Keystores found in Alison-Desktop.
listKeyStores(): Promise<{ keyStores: { id: string }[] }>
alison.listKeyStores().then( function({ keyStores }) { // handle success }, function({ code, detail }) { // handle failure } )
.
KeyStore Information
Returns information about a specific Keystore.
keyStoreInfo(KeyStore): Promise<{ keyStore: KeyStoreInfo }>
alison.getKeystoreInfo({ id: "CSK" }).then( function({ keyStore }) { // handle success }, function({ code, detail }) { // handle failure } )
.
Certificate List
Lists certificates found in Alison-Desktop. Returns array of AlisonJS SDK#WebCertificate.
certificateList(): Promise<{ certificates: WebCertificate[]; }>;
alison.certificateList().then( function({ certificates }) { // handle success }, function(response) { // handle failure } )
.
Sign
Uses a certificate to sign a string.
sign({ text: string certificate: string keyStore: KeyStore; options?: { algorithm?: string; format?: string; params?: string; } }): Promise<{ signature: string }>;
Argument | Required | Description |
---|---|---|
text | ✔ | Text to be signed in base64 format. |
certificate | ✔ | ThumbPrint of the certificate to use. |
options | ✘ | defaults are { algorithm: 'SHA1withRSA', format: 'CAdES', params: '' } |
keyStore | ✘ | KeyStore where the certificate is located. |
alison.sign({ text: 'A43G3RWG224...', certificate: 'C22E8C20D6042B2BF6A6E054B7378FEC57414765', keyStore: { id: "WIN-ENH" } }).then( function({ signature }) { // handle success }, function(response) { // handle failure } )
.
Structures
The following interfaces are used by this library.
KeyStore
KeyStore { id: string profile?: string }
This structure was extended with more information from AlisonJS version 3.0.1 and Alison-Desktop 3.1.x.
KeyStore { id: string, keyStoreId?: string, keyStoreType?: string, capabilities?: string, friendlyName?: string, status: { resultStatus: int, resultList: [] }, profiles?: string }
Security Policy
A security policy defines behaviour of the keystore or profile, depending each kind of them. Go to this link for a better description of them.
An empty JSON structure must be used to indicate the default one.
{ }
CapiSecurityPolicy { exportable?: boolean; protectionLevel?: number; title?: string; friendlyName?: string; description?: string; } DeviceSecurityPolicy { installDummy?: boolean generateOnBoard?: boolean } PassSecurityPolicy { passMinLength: number passComplexity: number } Pkcs11SecurityPolicy { installDummy?: boolean generateOnBoard?: boolean passMinLength?: number passComplexity?: number } CskSecurityPolicy { id: string passMinLength: number passComplexity: number passLockCount: number passExpiration: number lockTimeout: number idleTimeout: number certExport: number } SecurityPolicy = | CapiSecurityPolicy | CskSecurityPolicy | DeviceSecurityPolicy | PassSecurityPolicy | Pkcs11SecurityPolicy | {}
Web Certificate
WebCertificate { serialNumber: string thumbPrint string subjectDN: string issuerDN: string validity: { from: string left: number until: string total: number isExpired: boolean } }
Example
Generate and Install a certificate.
<script src="./alisonJS.umd.js"></script> const alison = new AlisonJS.Desktop() // Call initialize method with License provided by Certisur alison.initialize({ accessToken: "eyJ2MSI6eyJpZHgiOiI0LUxpY2Vuc2UiLCJ2YWx1ZSI6IlErZ0ErZE1pSXBkN3pYRCtJNWpJY0g3TnhLY1J5ZndUM3ZTWUk2TmNoWE9lUURmL1JMZHltWFRNRXpsbndlcGJIR1lKVEJQQjFwcklnTE16Qlc5cnBiZFNZcEJBV3pvamhEdW9Ra29ZUWc3dENxSUpHbk9KV1ZYUkZFakhid3h2aVBtbEFkZ3Y3ZXdSNldxd0xpaHRNVVArNzlnRmg5TDMvKzBXd3JDbmd0MHhjbnNnRmpvZkhSeUowS21TQi9Ud25KK3ljZ2tod2ZwUkpUTmpYaGZnbmxIWTRyQXY0WkY0WGNtTkdjYUFkQmpIWFpMK1FOUnV3NitBbnFwekxmRkFrdTB0d2NOVVFoL3l1SlBIZlJYSjdZOGtTa0tzWDh2eTVjdW95ZG9kR3d5YndEUmFxUXprcHlyWkIzaFNKRU5RLzc4c1NYbGNwMDNuNWs0bFp0N0lNK0lOQmJMUlZFby9MUEtYTWIyTXFoaTFub3R0RDlEQ1pZRkJkMzU5ZG5Wd3piQUdlOFozTXpBam4wNUZPRkQzcUhtUGJZcFk1QXNwTzR5bE4wUUhGMUprYlRXVmk4MWh2Z244d1l4MEU1Nm9WRXV0UFg0SSs0TktnODVGV0hReGh5dmJDeVovNm1xeE9WVWhUQ3cyS2lvejRMZEpuVTVmRDZqck9rdCtlSU0yWFo5NUF4NEcvUHh2V2lnaWg1VFFhQT09In0sInYyIjp7ImlkeCI6IjItTGljZW5zZSIsInZhbHVlIjoiZXlKaGJHY2lPaUpTVXpJMU5pSjkuZXlKcFlYUWlPakUxTnpjNU56ZzJOemtzSW1WNGNDSTZNVGMwTkRJMU5EQXdNQ3dpWTI5dGNHRnVlVTVoYldVaU9pSkRaWEowYVZOMWNpQlRMa0V1SWl3aVlXeHNiM2RsWkU5eWFXZHBibk1pT2xzaUtpNWpaWEowYVhOMWNpNWpiMjBpTENJcUxtTmxjblJwYzNWeUxtNWxkQ0lzSW1Gc2FYTnZibVJsYzJ0MGIzQXVjR3RwYUc5emRDNWpiMjBpTENKaGJHbHpiMjVrWlhOcmRHOXdMbkJyYVdodmMzUXVZMjl0T2pnd01EVWlMQ0pqYUhKdmJXVXRaWGgwWlc1emFXOXVPaTh2YTNCcWJHRm5aR3B3WVdscGJXNWxZMlJpWkdOdVpHcGphV3B2WVd4aWJHRWlMQ0pzYjJOaGJHaHZjM1E2T0RBd015SXNJbTF2ZWkxbGVIUmxibk5wYjI0Nkx5OWtabUl3WldJM01pMDFOelU0TFRRek4ySXRZVFV3T0MweU9HUmhNVGs0Tm1Wa1ptUWlMQ0pzYjJOaGJHaHZjM1E2T0RBd05DSXNJbXh2WTJGc2FHOXpkRG80TURBMUlpd2liRzlqWVd4b2IzTjBJaXdpYkc5allXeG9iM04wT2pJd01EUWlMQ0pzYjJOaGJHaHZjM1E2TWpBd05TSXNJakV5Tnk0d0xqQXVNU0lzSWpFeU55NHdMakF1TVRvNE1EQTBJaXdpTVRJM0xqQXVNQzR4T2pnd01EVWlYWDAuYXlhY2hfcmxURzd5XzdDcGZ0c09MQ0MzZF80cko1M3NBZVRPeEVfLU43Qzh6QzdlWk9GUDhJNTBYUm03VTJLTTN4ZjBoQi0xdm0tcGQ1d1lfOFhpbUszZ3hVWl94eTRtNmVidmxmdmZudmFIZmxDTHZ4ZkpRellkclRFeXJtZXNBeEFySVUyX0JrTnJkRHAwUXJLRmhEcXpVbC1Sd291TG9hWEE0RVhhbURlcE1waDVsdDRKc2ZQQ0Q4X3JnMHB0d3lMRGprWXY1YkZtNXJaaEJMOGZJS1Zhd255eUhSY2VEekpZZzZnUXU1OTk1V3MyZExlYUVidVFQSWZVNmE5c29WR1o0WG5WX1pGX08tSnlwNkpVcFZTY1UzS0pjTkM1WDlSdG9mOGpMVjRfZ2pCcmhSUXh5UEgwQlpPUC1jZGhKUWlUa1pwYS1wb3RjZTdNUnVKVE1nIn19", }).then(function() { // Generate KeyPair and Certificate Signing Request in MACOS keyStore alison.generateCsr( { keyStore: { id: "MACOS" }, securityPolicy: { installDummy: true } }).then(function({ csr }) { // issue the certificate through an external CA const pkcs7 = requestCertificateFromYourCA(csr) // install issued certificate alison.installPkcs7({ keyStore: { id: "MACOS" }, pkcs7: pkcs7 }).then(function({ certificate }) { // Certificate is currently installed in the MACOS keyStore // In case you want to use or test the certificate we just installed, // You can use the "sign" method alison.sign({ text: 'test signature', certificate: certificate.thumbPrint, keyStore: { id: "MACOS" } }).then(function({ signature }){ // Print signature result console.log(signature) }, printError) }, printError) }, printError) }, printError) function printError({ code, detail }) { console.log(`error ${code}: ${detail}`) }
- No labels