SignEncrypt operations

The methods described below are provided to perform SignEncrypt operations such as signature, encryption, verification and decryption.

static SCWS.createCertificate(certData)

Creates a SCWS.Certificate() object from a X.509 certificate. The SCWS.Certificate() object lifetime corresponds to the lifetime of the environnement. It is not imported into the token or added to the certificate store.

Arguments:

  • certData – A Blob containing the binary data of the X509 certificate to create. The data can be either in raw binary (DER-encoded) form, or encoded in PEM form.

Returns:

A Promise resolving to the SCWS.Certificate() object corresponding to the input data.

static SCWS.matchIssuerAndSerialsWithCerts(issuerAndSerials, certificates)

Matches IssuerAndSerialNumbers with certificates.

Arguments:

  • issuerAndSerials – An ArrayBuffer object, or a list of such objects, corresponding to the list of IssuersAndSerialNumbers to match with certificates.

  • certificates – A SCWS.Certificate() object, or a list of such objects, corresponding to the list of certificates to match with IssuerAndSerialNumbers

Returns:

A Promise resolving to a list of handles of SCWS.Certificate() objects, corresponding to a subset of certificates given as input, for which a correspondance has been found with one of given IssuerAndSerialNumbers.

static SCWS.signDocument(documentToSign, privateKey, certificate, options)

Signs a document.

The sign options are provided by the options parameter. It must be a JavaScript object with the following fields:

  • format: Format to use for signature, given as a string. It can take following values: CADES_ATTACHED, CADES_DETACHED, PADES or XADES_DETACHED.

  • hashAlgorithm: Hash algorithm to use, given as a string. It can take the following values: sha1, sha256, sha384, sha512.

  • fileName: (optional) Name of the file to sign, given as a string. Should be given if signature format is XADES_DETACHED. This parameter will be used to fill the URI field of XADES signature.

Note that this parameter may evolve in the future to handle more options.

Arguments:

  • documentToSign – The document to sign, given as a Blob object.

  • privateKey – A SCWS.Key(), with private attribute, which will be used to sign the document.

  • certificate – A SCWS.Certificate() object corresponding to a certificate linked to the private key, with correct signature usages.

  • options – A JavaScript object as described above.

Returns:

A Promise resolving to the signed document, as a Blob object.

static SCWS.encryptDocument(documentToEncrypt, certificateList)

Encrypts a document.

Arguments:

  • documentToEncrypt – The document to encrypt, given as a Blob object.

  • certificateList – A SCWS.Certificate() object, or a list of such objects, corresponding to the list of recipients of document to encrypt. The certificates can come from the token, the store, or outside.

Returns:

A Promise resolving to the encrypted document, as a Blob object.

static SCWS.signEncryptDocument(documentToSignEncrypt, privateKey, signCertificate, encryptCertificates, options)

Signs and encrypts a document.

The sign options are provided by the options parameter. It must be a JavaScript object with the following fields:

  • hashAlgorithm: Hash algorithm to use, given as a string. It can take the following values: sha1, sha256, sha384, sha512.

Note that this parameter may evolve in the future to handle more options.

Arguments:

  • documentToSignEncrypt – The document to sign and encrypt, given as a Blob object.

  • privateKey – A SCWS.Key(), with private attribute, which will be used to sign the document.

  • signCertificate – A SCWS.Certificate() object corresponding to a certificate linked to the private key, with correct signature usages.

  • encryptCertificates – A SCWS.Certificate() object, or a list of such objects, corresponding to the list of recipients of document to encrypt. The certificates can come from the token, the store, or outside.

  • options – Hash algorithm to use, given as a string. It can take the following values: sha1, sha256, sha384, sha512

Returns:

A Promise resolving to the signed and encrypted document, as a Blob object.

static SCWS.verifyDocument(signature, options, originalDocument, originalDocumentCallback)

Verifies the validity of a signature.

The verify options are provided by the options parameter. It must be a JavaScript object with the following fields:

  • format: Format to use for verification, given as a string. It can take following values: CADES_ATTACHED, CADES_DETACHED, PKCS7 (corrresponding to CMS attached), PADES or XADES_DETACHED.

Note that this parameter may evolve in the future to handle more options.

If the signature format is CADES_DETACHED, PADES or XADES_DETACHED, there is no need to recover an original file, so this entry point will only return the verification result as described below. However, if the format is CADES_ATTACHED or PKCS7, SCWS.verifyDocument() will also recover the original file. For performance reasons, data received and sent is processed using streams: it thus involves that recovering and sending back of original document will start before the result of verification is known. This will be achieved using a callback given as a parameter of SCWS.verifyDocument(), which will be called on the output of recovering process. This callback function should take as input a Blob object corresponding to the original document recovered.

Whatever the format given as parameter is, the verification result will be returned as output, as a JavaScript object will the following fields:

  • globalSignatureValidity: a global boolean set to true if, for each signatory: the signature is valid, the certificate is valid, and the signature is CADES BES compliant (this condition is not checked if format is PKCS7). This boolean is set to false if one of these conditons is not met.

  • signatories: a list of verification results for each signatory, given as JavaScript objects will the following fields:

    • certificate: the signatory’s certificate, given as a SCWS.Certificate() object.

    • signatureValidity: a boolean specifying the validity of the signature.

    • signerTrust: a boolean specifying if the certificate is trusted or not.

    • cadesBESCompliance: a boolean specifying if the signature has CADES BES level or not. Always false in case of PKCS7 format.

Arguments:

  • signature – The signed document to verify, given as a Blob object.

  • options – A JavaScript object as described above.

  • originalDocument – (optional) The original document, if signature was made detached. Should be given only if format is CADES_DETACHED or XADES_DETACHED, undefined otherwise.

  • originalDocumentCallback – (optional) Callback to be called on recovered original document, as described above. Should be given only if format is CADES_ATTACHED or PKCS7, undefined otherwise.

Returns:

A Promise resolving to the verification result, as described above.

static SCWS.decryptDocument(encryptedDocument, getPrivKeyCallback)

Decrypts an encrypted document.

The SCWS.decryptDocument() function lets the calling application choose the certificate and private key to use to decrypt the document, using a callback given as a parameter of the function. This callback must take as input a list of ArrayBuffer corresponding to IssuerSerialNumbers, that SCWS.decryptDocument() will find in the encrypted document, and a function. This function takes two parameters :

  • privateKey: a SCWS.Key() object, with private attribute, corresponding to the private key to use for decryption.

  • certificate: a SCWS.Certificate() object, corresponding to the certificate to use for decryption.

The callback must use the given list of IssuerSerialNumbers to retrieve the private key and the certificate to use for decryption, and then call the function given as a second parameter of the callback with chosen private key and certificate to process the decryption.

Arguments:

  • encryptedDocument – The encrypted document to decrypt, given as a Blob object.

  • getPrivKeyCallback – A callback function, as described above.

Returns:

A Promise resolving to the decrypted document, as a Blob object.

static SCWS.decryptVerifyDocument(documentToDecryptVerify, getPrivKeyCallback, originalDocumentCallback)

Decrypts an encrypted document and verifies its signature.

Arguments:

  • documentToDecryptVerify – The document to decrypt and verify, given as a Blob object.

  • getPrivKeyCallback – The callback used to return the private key and certificate to use for decryption, as decribed for SCWS.decryptDocument() function.

  • originalDocumentCallback – The callback to be called on original recovered document, as described for SCWS.verifyDocument() function.

Returns:

A Promise resolving to the verification result, as described for SCWS.verifyDocument() function.