com.cosmian.rest.abe

Class KmsClient

java.lang.Object

com.cosmian.rest.abe.KmsClient

public class KmsClient
extends Object

Attribute Based Encryption endpoints

Constructor Summary

Constructors

Constructor and Description
KmsClient(RestClient rest_client) Instantiate a new Kmip client using a RestClient
KmsClient(String server_url, Optional<String> api_key) Instantiate a new KmipClient with DEFAULT_CONNECT_TIMEOUT and DEFAULT_READ_TIMEOUT

Method Summary

Modifier and Type	Method and Description
DecryptedData	coverCryptDecrypt(String userDecryptionKeyUniqueIdentifier, byte[] encryptedData) Decrypt the data in the KMS using the given User Decryption Key The encryptedData should be made of 3 parts: - the length of the encrypted header as a u32 in big endian format (4 bytes) - the header - the AES GCM encrypted content
DecryptedData	coverCryptDecrypt(String userDecryptionKeyUniqueIdentifier, byte[] encryptedData, byte[] authenticationData) Decrypt the data in the KMS using the given User Decryption Key The encryptedData should be made of 3 parts: - the length of the encrypted header as a u32 in big endian format (4 bytes) - the header - the AES GCM encrypted content
byte[]	coverCryptEncrypt(String publicMasterKeyUniqueIdentifier, byte[] plaintext, String encryptionPolicy) Encrypt data in the KMS using the given encryption policy and Public Master Key.
byte[]	coverCryptEncrypt(String publicMasterKeyUniqueIdentifier, byte[] plaintext, String encryptionPolicy, byte[] authenticationData) Encrypt data in the KMS using the given encryption policy and Public Master Key.
byte[]	coverCryptEncrypt(String publicMasterKeyUniqueIdentifier, byte[] plaintext, String encryptionPolicy, byte[] authenticationData, byte[] headerMetaData) Encrypt data in the KMS using the given encryption policy and Public Master Key.
String[]	createCoverCryptMasterKeyPair(Policy policy) Generate inside the KMS, a master private and public key pair for the Policy
String	createCoverCryptUserDecryptionKey(AccessPolicy accessPolicy, String privateMasterKeyUniqueIdentifier) Create a User Decryption Key for the given AccessPolicy in the KMS
String	createCoverCryptUserDecryptionKey(String accessPolicy, String privateMasterKeyUniqueIdentifier) Create a User Decryption Key for the given AccessPolicy expressed as a boolean expression
String	destroyKey(String uniqueIdentifier) Destroy a key in the KMS which makes it unavailable to use in the KMS to perform coverCryptEncrypt(String, byte[], String) or coverCryptDecrypt(String, byte[], Optional) operations.
String	importCoverCryptPrivateMasterKey(String uniqueIdentifier, PrivateKey privateMasterKey, boolean replaceExisting) Import a Private Master Key in the KMS
String	importCoverCryptPublicMasterKey(String uniqueIdentifier, PublicKey publicMasterKey, boolean replaceExisting) Import a Public Master Key in the KMS
String	importCoverCryptUserDecryptionKey(String uniqueIdentifier, PrivateKey userDecryptionKey, boolean replaceExisting) Import a User Decryption Key in the KMS
PrivateKey	retrieveCoverCryptPrivateMasterKey(String privateMasterKeyUniqueIdentifier) Retrieve the Master Private Key from the KMS
PublicKey	retrieveCoverCryptPublicMasterKey(String publicMasterKeyUniqueIdentifier) Retrieve the Master Public Key from the KMS
PrivateKey	retrieveCoverCryptUserDecryptionKey(String userDecryptionKeyUniqueIdentifier) Retrieve a User Decryption Key from the KMS
String	revokeKey(String keyUniqueIdentifier) Revoke a key in the KMS which makes it unavailable to use in the KMS to perform coverCryptEncrypt(String, byte[], String) or coverCryptDecrypt(String, byte[], Optional) operations.
String	rotateCoverCryptAttributes(String privateMasterKeyUniqueIdentifier, String[] policyAttributes) Rotate the given policy attributes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KmsClient

public KmsClient(String server_url,
                 Optional<String> api_key)

Instantiate a new KmipClient with DEFAULT_CONNECT_TIMEOUT and DEFAULT_READ_TIMEOUT

Parameters:

server_url - the REST Server URL e.g. http://localhost:9000

api_key - he optional API Key to use to authenticate

KmsClient

public KmsClient(RestClient rest_client)

Instantiate a new Kmip client using a RestClient

Parameters:

rest_client - the RestClient

Method Detail

createCoverCryptMasterKeyPair

public String[] createCoverCryptMasterKeyPair(Policy policy)
                                       throws CloudproofException

Generate inside the KMS, a master private and public key pair for the Policy

Parameters:

policy - the Key Policy

Returns:

a tuple containing the master private key UID and the master public key UID

Throws:

CloudproofException - if the creation fails

retrieveCoverCryptPrivateMasterKey

public PrivateKey retrieveCoverCryptPrivateMasterKey(String privateMasterKeyUniqueIdentifier)
                                              throws CloudproofException

Retrieve the Master Private Key from the KMS

Parameters:

privateMasterKeyUniqueIdentifier - the key UID

Returns:

the Private Key

Throws:

CloudproofException - if the retrieval fails

importCoverCryptPrivateMasterKey

public String importCoverCryptPrivateMasterKey(String uniqueIdentifier,
                                               PrivateKey privateMasterKey,
                                               boolean replaceExisting)
                                        throws CloudproofException

Import a Private Master Key in the KMS

Parameters:

uniqueIdentifier - the UID of the key

privateMasterKey - the key

replaceExisting - if a key exists under this UID, replace it

Returns:

the UID of the imported key

Throws:

CloudproofException - if the import fails

retrieveCoverCryptPublicMasterKey

public PublicKey retrieveCoverCryptPublicMasterKey(String publicMasterKeyUniqueIdentifier)
                                            throws CloudproofException

Retrieve the Master Public Key from the KMS

Parameters:

publicMasterKeyUniqueIdentifier - the key UID

Returns:

the Public Key

Throws:

CloudproofException - if the retrieval fails

importCoverCryptPublicMasterKey

public String importCoverCryptPublicMasterKey(String uniqueIdentifier,
                                              PublicKey publicMasterKey,
                                              boolean replaceExisting)
                                       throws CloudproofException

Import a Public Master Key in the KMS

Parameters:

uniqueIdentifier - the UID of the key

publicMasterKey - the key

replaceExisting - if a key exists under this UID, replace it

Returns:

the UID of the imported key

Throws:

CloudproofException - if the import fails

createCoverCryptUserDecryptionKey

public String createCoverCryptUserDecryptionKey(String accessPolicy,
                                                String privateMasterKeyUniqueIdentifier)
                                         throws CloudproofException

Create a User Decryption Key for the given AccessPolicy expressed as a boolean expression

Parameters:

accessPolicy - the AccessPolicy as a string

privateMasterKeyUniqueIdentifier - the UID of the Master Private Key

Returns:

the UID of the newly created key

Throws:

CloudproofException - if the creation fails

createCoverCryptUserDecryptionKey

public String createCoverCryptUserDecryptionKey(AccessPolicy accessPolicy,
                                                String privateMasterKeyUniqueIdentifier)
                                         throws CloudproofException

Create a User Decryption Key for the given AccessPolicy in the KMS

Parameters:

accessPolicy - the AccessPolicy

privateMasterKeyUniqueIdentifier - the UID of the Master Private Key

Returns:

the UID of the newly created key

Throws:

CloudproofException - if the creation fails

retrieveCoverCryptUserDecryptionKey

public PrivateKey retrieveCoverCryptUserDecryptionKey(String userDecryptionKeyUniqueIdentifier)
                                               throws CloudproofException

Retrieve a User Decryption Key from the KMS

Parameters:

userDecryptionKeyUniqueIdentifier - the key UID

Returns:

the User Decryption Key

Throws:

CloudproofException - if the retrieval fails

importCoverCryptUserDecryptionKey

public String importCoverCryptUserDecryptionKey(String uniqueIdentifier,
                                                PrivateKey userDecryptionKey,
                                                boolean replaceExisting)
                                         throws CloudproofException

Import a User Decryption Key in the KMS

Parameters:

uniqueIdentifier - the UID of the key

userDecryptionKey - the key

replaceExisting - if a key exists under this UID, replace it

Returns:

the UID of the imported key

Throws:

CloudproofException - if the import fails

coverCryptEncrypt

public byte[] coverCryptEncrypt(String publicMasterKeyUniqueIdentifier,
                                byte[] plaintext,
                                String encryptionPolicy)
                         throws CloudproofException

Encrypt data in the KMS using the given encryption policy and Public Master Key. The generated cipher text is made of 2 parts: a header containing the encapsulation of the ephemeral symmetric key and the symmetrically encrypted content under that key.

Parameters:

publicMasterKeyUniqueIdentifier - the UID of the Public Key

plaintext - the data to encrypt

encryptionPolicy - the encryption policy as a boolean expression

Returns:

the encrypted data

Throws:

CloudproofException - if the encryption fails

coverCryptEncrypt

public byte[] coverCryptEncrypt(String publicMasterKeyUniqueIdentifier,
                                byte[] plaintext,
                                String encryptionPolicy,
                                byte[] authenticationData)
                         throws CloudproofException

Encrypt data in the KMS using the given encryption policy and Public Master Key. The generated cipher text is made of 2 parts: a header containing the encapsulation of the ephemeral symmetric key and the symmetrically encrypted content under that key.

Parameters:

publicMasterKeyUniqueIdentifier - the UID of the Public Key

plaintext - the data to encrypt

encryptionPolicy - the encryption policy as a boolean expression

authenticationData - the authentication data used in the AEAD of the symmetric scheme

Returns:

the encrypted data

Throws:

CloudproofException - if the encryption fails

coverCryptEncrypt

public byte[] coverCryptEncrypt(String publicMasterKeyUniqueIdentifier,
                                byte[] plaintext,
                                String encryptionPolicy,
                                byte[] authenticationData,
                                byte[] headerMetaData)
                         throws CloudproofException

Encrypt data in the KMS using the given encryption policy and Public Master Key. The generated cipher text is made of 2 parts: a header containing the encapsulation of the ephemeral symmetric key and the symmetrically encrypted content under that key.

Parameters:

publicMasterKeyUniqueIdentifier - the UID of the Public Key

plaintext - the data to encrypt

encryptionPolicy - the encryption policy as a boolean expression

authenticationData - the authentication data used in the AEAD of the symmetric scheme

headerMetaData - Metadata to encrypt within the header

Returns:

the encrypted data

Throws:

CloudproofException - if the encryption fails

coverCryptDecrypt

public DecryptedData coverCryptDecrypt(String userDecryptionKeyUniqueIdentifier,
                                       byte[] encryptedData)
                                throws CloudproofException

Decrypt the data in the KMS using the given User Decryption Key The encryptedData should be made of 3 parts: - the length of the encrypted header as a u32 in big endian format (4 bytes) - the header - the AES GCM encrypted content

Parameters:

userDecryptionKeyUniqueIdentifier - the key UID

encryptedData - the cipher text

Returns:

the clear text data

Throws:

CloudproofException - if the decryption fails

coverCryptDecrypt

public DecryptedData coverCryptDecrypt(String userDecryptionKeyUniqueIdentifier,
                                       byte[] encryptedData,
                                       byte[] authenticationData)
                                throws CloudproofException

Decrypt the data in the KMS using the given User Decryption Key The encryptedData should be made of 3 parts: - the length of the encrypted header as a u32 in big endian format (4 bytes) - the header - the AES GCM encrypted content

Parameters:

userDecryptionKeyUniqueIdentifier - the key UID

encryptedData - the cipher text

authenticationData - the data to use in the authentication of the symmetric scheme

Returns:

the clear text data

Throws:

CloudproofException - if the decryption fails

rotateCoverCryptAttributes

public String rotateCoverCryptAttributes(String privateMasterKeyUniqueIdentifier,
                                         String[] policyAttributes)
                                  throws CloudproofException

Rotate the given policy attributes. This will rekey in the KMS:

• the Master Keys
• all User Decryption Keys that contain one of these attributes in their policy and are not rotated.

Non Rekeyed User Decryption Keys cannot decrypt ata encrypted with the rekeyed Master Public Key and the given attributes.
Rekeyed User Decryption Keys however will be able to decrypt data encrypted by the previous Master Public Key and the rekeyed one.
Note: there is a limit on the number of revocations that can be performed which is set in the Policy when Master Keys are created

Parameters:

privateMasterKeyUniqueIdentifier - the UID of the private master key

policyAttributes - the array of CoverCrypt attributes

Returns:

the Master Public Key UID

Throws:

CloudproofException - if the revocation fails

revokeKey

public String revokeKey(String keyUniqueIdentifier)
                 throws CloudproofException

Revoke a key in the KMS which makes it unavailable to use in the KMS to perform coverCryptEncrypt(String, byte[], String) or coverCryptDecrypt(String, byte[], Optional) operations.

If this key is a User Decryption Key, it will not be rekeyed in case of attribute revocation.

Note: this revokes the key **inside** the KMS: it does not prevent an user who has a local copy of a User Decryption Key to perform decryption operations.

Parameters:

keyUniqueIdentifier - the UID of the key to revoke

Returns:

the UID of the revoked key

Throws:

CloudproofException - if the revocation fails

destroyKey

public String destroyKey(String uniqueIdentifier)
                  throws CloudproofException

Destroy a key in the KMS which makes it unavailable to use in the KMS to perform coverCryptEncrypt(String, byte[], String) or coverCryptDecrypt(String, byte[], Optional) operations.

Note: this destroy the key **inside** the KMS: it does not prevent an user who has a local copy of a User Decryption Key to perform decryption operations.

Parameters:

uniqueIdentifier - the UID of the key to revoke

Returns:

the UID of the destroyed key

Throws:

CloudproofException - if the destruction fails