Payload Encryption (Optional)

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-Payload-Encrypted: true

{
  "encrypted_request": "<JWE_STRING>"
}

{
  "eval_id": "fd2a9785-554c-46be-a36f-e9443eefa380",
  "encrypted_response": "<JWE_STRING>"
}

{
  "docv_previous_reference_id": "fd2a9785-554c-46be-a36f-e9443eefa380",
  "encrypted_response": "<JWE_STRING>"
}

{
  "encrypted_request": "<JWE_STRING>"
}

{
  "eval_id": "<uuid or docv reference>",
  "encrypted_response": "<JWE_STRING>"
}

{
  "eval_id": "123456-abcdef-123456",
  "encrypted_response": "<JWE_String>"
}

{
  "eval_id": "123456-abcdef-123456",
  "error": "Payload encryption is not supported for this api-key"
}

{
  "eval_id": "123456-abcdef-123456",
  "error": "The encrypted payload is verified with success, however, server has internal problems to handle response encryption"
}

import java.security.interfaces.*;
import javax.crypto.*;

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.*;

public class Cipher {

   public String encrypt(String message, RSAPublicKey rsaPublicKey) throws Exception {

       // Assign the default JWE alg and enc.

       JWEAlgorithm alg = JWEAlgorithm.RSA_OAEP_256;
       EncryptionMethod enc = EncryptionMethod.A256GCM;

       // Generate the Content Encryption Key (CEK).

       KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
       keyGenerator.init(enc.cekBitLength());
       SecretKey cek = keyGenerator.generateKey();

       // Encrypt the JWE with the RSA public key + specified AES CEK.
       
       JWEObject jwe = new JWEObject(
               new JWEHeader(alg, enc),
               new Payload(message));
       jwe.encrypt(new RSAEncrypter(rsaPublicKey, cek));
       return jwe.serialize();
   }

   public String decrypt(String jweString, RSAPrivateKey rsaPrivateKey) throws Exception {

       // Decrypt the JWE with the RSA private key.

       JWEObject jwe = JWEObject.parse(jweString);
       jwe.decrypt(new RSADecrypter(rsaPrivateKey));

       return jwe.getPayload().toString();
   }
}

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.RSASSASigner;
import com.nimbusds.jose.crypto.RSASSAVerifier;
import com.nimbusds.jose.jwk.RSAKey;

public class Signature {

   public String sign(String message, RSAKey rsaJWK) throws Exception {

       // Create RSA-signer with the private key

       JWSSigner signer = new RSASSASigner(rsaJWK);

       // Prepare JWS object with simple string as payload

       JWSObject jwsObject = new JWSObject(
               new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(rsaJWK.getKeyID()).build(),
               new Payload(message));

       // Compute the RSA signature

       jwsObject.sign(signer);

       // Serialize to compact form.

       return jwsObject.serialize();
   }

   public boolean verify(String jwsToken, RSAKey rsaPublicKey) throws Exception {

       // To parse the JWS and verify it.

       JWSObject jwsObject = JWSObject.parse(jwsToken);
       JWSVerifier verifier = new RSASSAVerifier(rsaPublicKey);

       return jwsObject.verify(verifier);
   }

}

import com.nimbusds.jose.jwk.RSAKey;

//This class is to simulate customer's actions below:
// 1. Use customer-generated RSA2048 private key to sign;
// 2. Use the Socure-generated RSA2048 public key to wrap AES key.

public class Sender {
   RSAKey rsaKey;
   RSAKey receiverPublicKey;

   public Sender(RSAKey rsaKey, RSAKey receiverPublicKey) {
       this.rsaKey = rsaKey;
       this.receiverPublicKey = receiverPublicKey;
   }


//This function demonstrates how customer will sign and encrypt the payload.

   public String packageMessage(String message) throws Exception {
       System.out.println("Message encryption starts with " + message);

       // Create a signature with a designated RSA2048 key pair.
       
       Signature signature = new Signature();
       String jwsToken = signature.sign(message, rsaKey);

       Cipher cipher = new Cipher();
       String jweToken = cipher.encrypt(jwsToken, receiverPublicKey.toRSAPublicKey());

       System.out.println("Success with encrypted payload: " + jweToken);

       return jweToken;
   }

}

import com.nimbusds.jose.JWSObject;
import com.nimbusds.jose.jwk.RSAKey;

//  This class is to simulate Socure's actions below:
//  1. Use Socure-generated RSA2048 private key to unwrap the AES key;
//  2. Use customer-generated RSA2048 public key to verify the customer's signature.
  
public class Receiver {
   RSAKey rsaKey;
   RSAKey senderPublicKey;

   public Receiver(RSAKey rsaKey, RSAKey senderPublicKey) {
       this.rsaKey = rsaKey;
       this.senderPublicKey = senderPublicKey;
   }

// This function demonstrates how Socure will decrypt the JWE token and verify the signature of customer.

   public String unpackageMessage(String encryptedMessage) throws Exception {
       System.out.println("Message decryption starts with: " + encryptedMessage);

       Signature signature = new Signature();
       Cipher cipher = new Cipher();
       String decryptedJwsToken = cipher.decrypt(encryptedMessage, rsaKey.toRSAPrivateKey());

       if (!signature.verify(decryptedJwsToken, senderPublicKey)) {
           throw new Exception("Error: the JKS token can not be accepted due to sender's signature verification failure.");
       }

       System.out.println("Success: The sender's JKS token is verified with the sender's signature.");
       JWSObject jwsObject = JWSObject.parse(decryptedJwsToken);
       return jwsObject.getPayload().toString();
   }

}