Software Development Kit (SDK)
Last updated
Last updated
ℹ️ This page describes how to use the Confidencial SDK, which lets developers perform Confidencial actions such as decryption within their applications. Please if you would like to get access to it.
ℹ️ The SDK is currently available in JavaScript and consists of one function, which supports the decryption of files. Support for encryption and other languages is coming soon. Have a language you’d like to see supported? .
ℹ️ While the SDK does not currently support encryption, the Confidencial can be used to encrypt files and can be invoked from JavaScript code running in a Node environment (using the module)
To use the Confidencial SDK in your JavaScript code, include a reference to the main SDK file, c11-sdk-js.min.js. For example, if the SDK is being used within a web page, include the following line within the <head> element of the HTML
where sdk-location is the path to the main SDK file.
All SDK functions are contained within the C11 namespace (e.g. C11.removeEncryption)
To use decryption functions within the SDK, valid private (decryption) keys are required for all files to be decrypted. Private keys for individual users can be obtained by following the instructions in . Private keys for groups are stored within a Confidencial Key Server and are never exposed. Instead of decrypting client-side, decryption for groups is done within the key server. The removeEncryption function described below is used for both individual-user and group decryption.
privateKeyPemMap, keyServerAccessToken, keyServerUrlOrigin, groupNames })`
Removes encryption from (decrypts) a file
options object:
The keys in this dictionary object are strings that represent the hashes of public keys
The values in this dictionary object are strings that represent the corresponding private keys in PEM format
See the partial code example below for how a private key map can be assembled once public key hashes and private key PEMs are obtained
keyServerAccessToken is a string value representing a JSON Web Token (JWT) that can be used to access the key server utilized by your enterprise (this may be hosted by your enterprise or by Confidencial)
The key server utilized by your enterprise will be configured to validate JWTs based on a JSON Web Key Set (JWKS) file, which contain the public key(s) corresponding to the private key(s) used to sign valid JWTs
keyServerUrlOrigin is a string representing the URL of the key server utilized by your enterprise
groupNamesis a string array (string[]) representing the list of groups from which decryptions should be attempted. For each group listed, the key server will check that the user specified in the provided JWT is a member of the group, and if so, attempt to use private keys belonging to the group to decrypt content in the provided document.
remotely-stored, group key
The example below contains a complete HTML page that allows a user to decrypt a file. The HTML page contains file inputs for the user to upload a file to be decrypted and a file representing the private (decryption) key in PEM format. The page also contains inputs for the user to supply other parameters required for individual-user and group decryption.
⚠️ To avoid CORS errors, the HTML page below should be accessed through a web server (running either locally or in the cloud). Viewing this page directly in a web browser will not work if your browser is enforcing CORS restrictions (as most browsers do by default).
ℹ️ NOTE: The script below assumes the main SDK file, `c11-sdk-js.min.js`, is being served by a local web server running on port 8080. Adjust the `` line in the code below accordingly if you are hosting the SDK file in a different location. </aside> <aside> ⚠️ To avoid invalid character errors, make sure the web server serving the SDK file is sending the appropriate content type header (`Content-Type: application/javascript; charset=UTF-8`) </aside> <!DOCTYPE html> <html> <head> <title>C11-SDK-Encryption-Removal</title> <script src="http://127.0.0.1:8080/c11-sdk-js.min.js"></script> <script> async function removeEncryption() { console.log("removeEncryption started"); const option1 = document.getElementById('privateKeyEncryption'); const option2 = document.getElementById('groupEncryption'); const option3 = document.getElementById('bothEncryption'); const isPrivateKeyEncryption = option1.checked || option3.checked; const isGroupEncryption = option2.checked || option3.checked; const publicKeyHashElement = document.getElementById("PublicKeyHash"); if (publicKeyHashElement?.value?.length === 0 && isPrivateKeyEncryption) { alert("Please enter your Public Key Hash"); return; } const privateKeyfileElement = document.getElementById("privateKey"); if (privateKeyfileElement?.files?.length === 0 && isPrivateKeyEncryption) { alert("Please upload your private Key"); return; } const encryptedPdfFileElement = document.getElementById("encryptedPdfFile"); if (encryptedPdfFileElement.files.length === 0) { alert("Please upload encrypted Pdf File"); return; } const opkssAccessTokenElement = document.getElementById("opkssAccessToken"); if (opkssAccessTokenElement?.value?.length === 0 && isGroupEncryption) { alert("Please enter your OPKSS/keyServer Access Token"); return; } const keyServerUrlOriginElement = document.getElementById("keyServerUrlOrigin"); if (keyServerUrlOriginElement?.value?.length === 0 && isGroupEncryption) { alert("Please enter your OPKSS/keyServer Origin URL"); return; } const encryptedPdfFile = encryptedPdfFileElement.files[0]; let privateKeyMap = {}; if (isPrivateKeyEncryption) { const privateKeyFile = privateKeyfileElement.files[0]; const publicKeyHash = publicKeyHashElement.value; privateKeyMap[publicKeyHash] = await privateKeyFile.text(); } let opkssAccessTokenValue; let keyServerUrlOriginValue; let remoteGroupNamesValue = []; if (isGroupEncryption) { opkssAccessTokenValue = opkssAccessTokenElement.value; keyServerUrlOriginValue = keyServerUrlOriginElement.value; if (document.getElementById("remoteGroupNames")?.value?.length > 0) remoteGroupNamesValue = document.getElementById("remoteGroupNames")?.value?.split(","); } const decryptedFile = await C11.removeEncryption(encryptedPdfFile, { privateKeyPemMap: privateKeyMap, keyServerAccessToken: opkssAccessTokenValue, keyServerUrlOrigin: keyServerUrlOriginValue, groupNames: remoteGroupNamesValue }); if (window.navigator.msSaveOrOpenBlob) // IE10+ window.navigator.msSaveOrOpenBlob(decryptedFile, filename); else { // Others var a = document.createElement("a"), url = URL.createObjectURL(decryptedFile); a.href = url; a.download = encryptedPdfFile.name; document.body.appendChild(a); a.click(); setTimeout(function () { document.body.removeChild(a); window.URL.revokeObjectURL(url); }, 0); } } document.addEventListener('DOMContentLoaded', function () { const option1 = document.getElementById('privateKeyEncryption'); const option2 = document.getElementById('groupEncryption'); const option3 = document.getElementById('bothEncryption'); const input1 = document.getElementById('privateKeyDiv'); const input2 = document.getElementById('groupDiv'); // Function to toggle visibility of inputs based on radio button selection function toggleInputs() { if (option1.checked) { input1.classList.remove('hidden'); input2.classList.add('hidden'); } else if (option2.checked) { input1.classList.add('hidden'); input2.classList.remove('hidden'); } else if (option3.checked) { input1.classList.remove('hidden'); input2.classList.remove('hidden'); } } // Initial toggle on page load toggleInputs(); // Event listener for radio button change option1.addEventListener('change', toggleInputs); option2.addEventListener('change', toggleInputs); option3.addEventListener('change', toggleInputs); }); </script> <style> form { margin: 20px auto; max-width: 600px; padding: 20px; border: 1px solid #ccc; border-radius: 5px; } label { display: block; margin-bottom: 10px; font-weight: bold; } input[type="text"], input[type="file"] { display: block; margin-bottom: 20px; width: 100%; padding: 10px; border-radius: 5px; border: 1px solid #ccc; box-sizing: border-box; } input[type="button"] { background-color: #08329d; color: white; padding: 10px 20px; border: none; border-radius: 5px; cursor: pointer; } input[type="button"]:hover { background-color: #3e558e; } .hidden { display: none; } </style> </head> <body> <form> <input style="display: inline;" type="radio" id="privateKeyEncryption" name="encryptionMethod" checked="checked" value="privateKeyEncryption"> <label style="display: inline;" for="privateKeyEncryption"> Decrypt using Private Key</label> <input style="display: inline;" type="radio" id="groupEncryption" name="encryptionMethod" value="groupEncryption"> <label style="display: inline;" for="groupEncryption"> Decrypt using groups</label> <input style="display: inline;" type="radio" id="bothEncryption" name="encryptionMethod" value="bothEncryption"> <label style="display: inline;" for="bothEncryption"> Decrypt using both</label></br></br></br> <div id="privateKeyDiv" class="hidden"> <label for="PublicKeyHash">Your Public Key Hash:</label> <input type="text" id="PublicKeyHash" name="PublicKeyHash" placeholder="Enter Your Public Key Hash" /> <label for="privateKey">Your Private Key:</label> <input type="file" accept=".key" id="privateKey" name="privateKey" /> </div> <label for="encryptedPdfFile">Encrypted Pdf File:</label> <input type="file" accept=".pdf" id="encryptedPdfFile" name="encryptedPdfFile" /> <div id="groupDiv" class="hidden"> <label for="opkssAccessToken">Your OPKSS/keyServer Access Token:</label> <input type="text" id="opkssAccessToken" name="opkssAccessToken" placeholder="Enter Your OPKSS/keyServer Access Token" /> <label for="keyServerUrlOrigin">Your OPKSS/keyServer Origin URL:</label> <input type="text" id="keyServerUrlOrigin" name="keyServerUrlOrigin" placeholder="Enter Your OPKSS/keyServer Origin URL" /> <label for="remoteGroupNames">Your Groups names:</label> <input type="text" id="remoteGroupNames" name="remoteGroupNames" placeholder="Enter group names to decrypt for. [optional] e.g. group1, group2" /> </div> <input type="button" value="Decrypt" onclick="removeEncryption()" /> </form> </body> </html>
file is a object referencing the file to be decrypted
privateKeyPemMap is a dictionary object that maps public key hashes (stored as string) to private keys in (also stored as string)
Both public key hashes and private key PEMs can be obtained using the Confidencial or ; see
Upon success removeEncryption returns a object representing the decrypted file
The example below assumes privateKeyfileElement and encryptedPdfFileElement are HTML inputs and publicKeyHashElement is an HTML input.