| Summary || Products || Cryptography || Fusion || KeeeX.Js || Verifier || KeeeX Chain || Digital Identity Management |
The KeeeX.Js library is a JavaScript library that enables developers to perform client-side operations related to the manipulation of keeexed files.
KeeeX tools are designed to allow usage patterns where digital signatures, the cornerstone of authenticity verification, remain under the sole control of their users.
As such, it requires some operations to occur on the client-side.
KeeeX leverages standard technologies, and any compliant software can be used to perform the operations required client-side.
For convenience and to enable fast deployment of solutions built over KeeeX core technology, the KeeeX.Js library is provided to perform the following operations:
The most common use cases include embedding file verification client-side, performing specific actions based on extracted metadata, and computing digital signatures client-side under the exclusive control of an end-user.
This page outlines how to perform these operations.
A more extensive documentation is available upon request.
The library is provided to customers alongside other services that leverage KeeeX technology as two archives containing two variants of the library.
The first one, keeexjs_<version>.min.zip, contains the chunked version of the library.
This variant provides a faster initial loading time and will automatically fetch new bundles as needed.
The second one, keeexjs_<version>.single.zip, is the same library packaged as a single, large file.
It takes longer to load initially but contains every part of the library, allowing it to operate without having to retrieve additional bundles.
Both variants are feature-wise identical, but depending on deployment constraints, one might be more suitable than the other.
The library is distributed through our file-sharing service, available to our customers, which includes notification of updates.
It comes with a full documentation, while this page will only outline the main features.
The library is built with the latest two versions of major common web browser support.
It is compatible with the latest versions of Chrome, Firefox, Safari, and Edge, as well as browsers based on those.
There are no particular requirements to run it, although there is a limitation on the memory footprint of a web browser's JavaScript context, which may limit the maximum size of verified files in the browser.
While there is no definite limit, files up to hundreds of megabytes have been successfully verified in most browsers.
For specific requests, it is also possible to obtain the library as an NPM package.
Please contact us for more information.
To use the KeeeX.Js library as a JavaScript library in web pages, it must first be loaded into the page.
<!-- for the chunked version -->
<script src="js/keeex.min.js"></script>
<!-- for the single file version -->
<script src="js/keeex.single.js"></script>
Note that the chunked version has no specific requirements regarding its location; it should automatically detect its own path and be able to load additional chunks as needed.
The only requirement is that all the chunks are placed in the same directory as the entry point file.
Alternatively, the NPM package can simply be imported as a module as usual.
The library allows you to verify the integrity of files that have been keeexed.
It can be used to check whether a file has not been altered since it was keeexed, as well as retrieving all embedded metadata.
Verifying a file is also a prerequisite for generating a proper digital signature, as described in the KeeeX Fusion page.
Here is a short example of how to verify a file:
// Configure the verifier
const verifier = await KXSDK.KeeexJS.create({
onlineInfo: true,
required: {
signingKeyAddresses: [],
references: [],
},
});
// Actually get a file's metadata
const metadata = await verifier.verify(fileBuffer);
The metadata object will contain almost the exact same output as the verify operation described in the KeeeX Fusion page.
The fileBuffer argument can be an ArrayBuffer, Uint8Array, or a Blob.
Note that, in most browsers, a File can be used as a Blob.
It is possible to customize some aspects of the verification process:
onlineInfo option will trigger the retrieval of online details when available. This can include different properties depending on the file's metadata.required.signingKeyAddresses option will only validate files that have at least one signature from the given list of key addresses.required.references option will require a file to have this reference in its KeeeX metadata.Beyond being used in a browser, the behavior is the same as with our CLI tool Keeex Fusion.
Note that when onlineInfo is false, no data are sent anywhere by the verification process.
When it is true, the following data may be sent:
identityUrl provided in the file itself to retrieve digital identity details from any provider.While no actual content is ever sent, this may pose a security risk as connections would be outbound from the client's device.
Hence, the possibility to disable it.
Note that at no point in time are the file's contents themselves sent anywhere.
Most of the integrity and authenticity checks are also performed offline and do not require a connection to KeeeX's services.
As outlined in the detailed signature process on the KeeeX Fusion page, the following steps are required to perform a digital signature under exclusive control of the end-user:
Using the KeeeX.Js library, the client-side can actually confirm that the content of the file matches with the computed IDX without any third-party intervention.
(This confirmation is usually left to the human end-user, although it is not a requirement.)
Once the file is verified client-side and confirmed to be valid by the end-user, all that is left is to produce a digital signature.
Procuring the private key is not the duty of the KeeeX.Js library; however, KeeeX offers related services for managing user private keys in a secure way, behaving similarly to a custodial wallet without losing exclusive control over the keys.
Once the private key is acquired (for example, a WIF value), using the KeeeX.Js library to import that key and create a digital signature is straightforward:
// Obtain a key instance
const key = await KXSDK.KeysFactory.importKey("bitcoin", {type: "wif", value: "Ky9wu9jNbxJgvreN4aBa22hrMJLB6wt7kj1MMSru8wzeKmeMrEcN"});
// Produce the signature
const signature = await key.sign(metadata.identities[0].signable);
As a side note, it is also possible to generate a new random keypair from the library.
Additionally, the library provides some helper functions to export the private key in various formats (WIF, PEM, etc.).
This documentation will not delve into all the possibilities, but a bare minimum example of generating an identity, saving it securely with a password, and retrieving it would be as follows:
// Create a random keypair
const key = await KXSDK.KeysFactory.generateKey("bitcoin");
// Export an encrypted copy of the keypair
const exportedKey = await key.exportKey(false, {type: "json", password: "<user password>"});
// Later on, retrieve the key instance from the encrypted copy
const importedKey = await KXSDK.KeysFactory.importKey("bitcoin", {type: "json", password: "<user password>", value: exportedKey});
// Key can be used as usual
This is only a short example; a proper implementation would ensure that the user's password is protected, that the exported key is stored securely, and so on.
There are also additional options for handling different key types available in the full documentation.
The KeeeX.Js library allows for retrieving timestamp information related to an IDX.
The same information can also be obtained by verifying a file using the onlineInfo option set to true, but doing a manual check provides two benefits:
The function getTimestampInfo() can be called on the verifier object from an earlier example on this page:
const timestampInfos = await verifier.getTimestampInfo("<idx>", true);
timestampInfos = {
timestampInfo: {
anchors: [
/**
* the number of anchors depends on the license or the asked anchor methods asked during
* timestamp call
*/
{
network: "main",
rollupBtcId: "<btcId>",
rollupUrl: "<url to rollup file>",
timestamp: "<ISO8601 date>",
transactionHash: "<hash on bitcoin blockchain>",
type: "bitcoin"
},
{
certificate: "<CA cert file name>",
idxAsMessage: true, // boolean
ignoreCritical: false, // if true, must pass `-ignore_critical` flag to openssl
timestamp: "<ISO8601 date>",
tsrUrl: "<url to tsr file>",
type: "<one of rfc3161Keeex | rfc3161Certigna>"
},
{
timestamp: "<ISO8601 date>",
transactionHash: "<transaction hash on ethereum like blockchain>",
type: "<one of ethereunKeeex | ethereumClassic>"
},
],
idx: "<idx>",
timestampRequestDate: "<ISO8601 timestamp request date>"
},
decodedTsr: {
"<url to tsr file>": {
/* either */
accuracy: "<accuracy in seconds>",
date: Date, // Tsr date
granted: true, // boolean, if false no other values in the object
source: "<name of the CA timestamp server>"
/* or */
granted: false,
}
}
}
The second parameter is optional and defaults to false.
If present and set to true, the TSR file (assuming one is available for the requested IDX) will be downloaded and decoded, providing human-readable information extracted from it.