Securebox v2 provides a simple interface to perform encryptions by using any of the following * credential types: * *
Note that {@code header} will be authenticated (but not encrypted) together with {@code * payload}, and the same {@code header} has to be provided for {@link #decrypt}. * * @param theirPublicKey the recipient's public key, or null if the payload is to be encrypted * only with the shared secret * @param sharedSecret the secret shared between the sender and the recipient, or null if the * payload is to be encrypted only with the recipient's public key * @param header the data that will be authenticated with {@code payload} but not encrypted, or * null if the data is empty * @param payload the data to be encrypted, or null if the data is empty * @return the encrypted payload * @throws NoSuchAlgorithmException if any underlying crypto algorithm is not supported * @throws InvalidKeyException if the provided key is invalid for underlying crypto algorithms * @hide */ public static byte[] encrypt( @Nullable PublicKey theirPublicKey, @Nullable byte[] sharedSecret, @Nullable byte[] header, @Nullable byte[] payload) throws NoSuchAlgorithmException, InvalidKeyException { sharedSecret = emptyByteArrayIfNull(sharedSecret); if (theirPublicKey == null && sharedSecret.length == 0) { throw new IllegalArgumentException("Both the public key and shared secret are empty"); } header = emptyByteArrayIfNull(header); payload = emptyByteArrayIfNull(payload); KeyPair senderKeyPair; byte[] dhSecret; byte[] hkdfInfo; if (theirPublicKey == null) { senderKeyPair = null; dhSecret = EMPTY_BYTE_ARRAY; hkdfInfo = HKDF_INFO_WITHOUT_PUBLIC_KEY; } else { senderKeyPair = genKeyPair(); dhSecret = dhComputeSecret(senderKeyPair.getPrivate(), theirPublicKey); hkdfInfo = HKDF_INFO_WITH_PUBLIC_KEY; } byte[] randNonce = genRandomNonce(); byte[] keyingMaterial = ArrayUtils.concat(dhSecret, sharedSecret); SecretKey encryptionKey = hkdfDeriveKey(keyingMaterial, HKDF_SALT, hkdfInfo); byte[] ciphertext = aesGcmEncrypt(encryptionKey, randNonce, payload, header); if (senderKeyPair == null) { return ArrayUtils.concat(VERSION, randNonce, ciphertext); } else { return ArrayUtils.concat( VERSION, encodePublicKey(senderKeyPair.getPublic()), randNonce, ciphertext); } } /** * Decrypts {@code encryptedPayload} by using {@code ourPrivateKey} and/or {@code sharedSecret}. * At least one of {@code ourPrivateKey} and {@code sharedSecret} must be non-null, and an empty * {@code sharedSecret} is equivalent to null. * *
Note that {@code header} should be the same data used for {@link #encrypt}, which is * authenticated (but not encrypted) together with {@code payload}; otherwise, an {@code * AEADBadTagException} will be thrown. * * @param ourPrivateKey the recipient's private key, or null if the payload was encrypted only * with the shared secret * @param sharedSecret the secret shared between the sender and the recipient, or null if the * payload was encrypted only with the recipient's public key * @param header the data that was authenticated with the original payload but not encrypted, or * null if the data is empty * @param encryptedPayload the data to be decrypted * @return the original payload that was encrypted * @throws NoSuchAlgorithmException if any underlying crypto algorithm is not supported * @throws InvalidKeyException if the provided key is invalid for underlying crypto algorithms * @throws AEADBadTagException if the authentication tag contained in {@code encryptedPayload} * cannot be validated, or if the payload is not a valid SecureBox V2 payload. * @hide */ public static byte[] decrypt( @Nullable PrivateKey ourPrivateKey, @Nullable byte[] sharedSecret, @Nullable byte[] header, byte[] encryptedPayload) throws NoSuchAlgorithmException, InvalidKeyException, AEADBadTagException { sharedSecret = emptyByteArrayIfNull(sharedSecret); if (ourPrivateKey == null && sharedSecret.length == 0) { throw new IllegalArgumentException("Both the private key and shared secret are empty"); } header = emptyByteArrayIfNull(header); if (encryptedPayload == null) { throw new NullPointerException("Encrypted payload must not be null."); } ByteBuffer ciphertextBuffer = ByteBuffer.wrap(encryptedPayload); byte[] version = readEncryptedPayload(ciphertextBuffer, VERSION.length); if (!Arrays.equals(version, VERSION)) { throw new AEADBadTagException("The payload was not encrypted by SecureBox v2"); } byte[] senderPublicKeyBytes; byte[] dhSecret; byte[] hkdfInfo; if (ourPrivateKey == null) { dhSecret = EMPTY_BYTE_ARRAY; hkdfInfo = HKDF_INFO_WITHOUT_PUBLIC_KEY; } else { senderPublicKeyBytes = readEncryptedPayload(ciphertextBuffer, EC_PUBLIC_KEY_LEN_BYTES); dhSecret = dhComputeSecret(ourPrivateKey, decodePublicKey(senderPublicKeyBytes)); hkdfInfo = HKDF_INFO_WITH_PUBLIC_KEY; } byte[] randNonce = readEncryptedPayload(ciphertextBuffer, GCM_NONCE_LEN_BYTES); byte[] ciphertext = readEncryptedPayload(ciphertextBuffer, ciphertextBuffer.remaining()); byte[] keyingMaterial = ArrayUtils.concat(dhSecret, sharedSecret); SecretKey decryptionKey = hkdfDeriveKey(keyingMaterial, HKDF_SALT, hkdfInfo); return aesGcmDecrypt(decryptionKey, randNonce, ciphertext, header); } private static byte[] readEncryptedPayload(ByteBuffer buffer, int length) throws AEADBadTagException { byte[] output = new byte[length]; try { buffer.get(output); } catch (BufferUnderflowException ex) { throw new AEADBadTagException("The encrypted payload is too short"); } return output; } private static byte[] dhComputeSecret(PrivateKey ourPrivateKey, PublicKey theirPublicKey) throws NoSuchAlgorithmException, InvalidKeyException { KeyAgreement agreement = KeyAgreement.getInstance(KA_ALG); try { agreement.init(ourPrivateKey); } catch (RuntimeException ex) { // Rethrow the RuntimeException as InvalidKeyException throw new InvalidKeyException(ex); } agreement.doPhase(theirPublicKey, /*lastPhase=*/ true); return agreement.generateSecret(); } /** Derives a 128-bit AES key. */ private static SecretKey hkdfDeriveKey(byte[] secret, byte[] salt, byte[] info) throws NoSuchAlgorithmException { Mac mac = Mac.getInstance(MAC_ALG); try { mac.init(new SecretKeySpec(salt, MAC_ALG)); } catch (InvalidKeyException ex) { // This should never happen throw new RuntimeException(ex); } byte[] pseudorandomKey = mac.doFinal(secret); try { mac.init(new SecretKeySpec(pseudorandomKey, MAC_ALG)); } catch (InvalidKeyException ex) { // This should never happen throw new RuntimeException(ex); } mac.update(info); // Hashing just one block will yield 256 bits, which is enough to construct the AES key byte[] hkdfOutput = mac.doFinal(CONSTANT_01); return new SecretKeySpec(Arrays.copyOf(hkdfOutput, GCM_KEY_LEN_BYTES), CIPHER_ALG); } private static byte[] aesGcmEncrypt(SecretKey key, byte[] nonce, byte[] plaintext, byte[] aad) throws NoSuchAlgorithmException, InvalidKeyException { try { return aesGcmInternal(AesGcmOperation.ENCRYPT, key, nonce, plaintext, aad); } catch (AEADBadTagException ex) { // This should never happen throw new RuntimeException(ex); } } private static byte[] aesGcmDecrypt(SecretKey key, byte[] nonce, byte[] ciphertext, byte[] aad) throws NoSuchAlgorithmException, InvalidKeyException, AEADBadTagException { return aesGcmInternal(AesGcmOperation.DECRYPT, key, nonce, ciphertext, aad); } private static byte[] aesGcmInternal( AesGcmOperation operation, SecretKey key, byte[] nonce, byte[] text, byte[] aad) throws NoSuchAlgorithmException, InvalidKeyException, AEADBadTagException { Cipher cipher; try { cipher = Cipher.getInstance(ENC_ALG); } catch (NoSuchPaddingException ex) { // This should never happen because AES-GCM doesn't use padding throw new RuntimeException(ex); } GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LEN_BYTES * 8, nonce); try { if (operation == AesGcmOperation.DECRYPT) { cipher.init(Cipher.DECRYPT_MODE, key, spec); } else { cipher.init(Cipher.ENCRYPT_MODE, key, spec); } } catch (InvalidAlgorithmParameterException ex) { // This should never happen throw new RuntimeException(ex); } try { cipher.updateAAD(aad); return cipher.doFinal(text); } catch (AEADBadTagException ex) { // Catch and rethrow AEADBadTagException first because it's a subclass of // BadPaddingException throw ex; } catch (IllegalBlockSizeException | BadPaddingException ex) { // This should never happen because AES-GCM can handle inputs of any length without // padding throw new RuntimeException(ex); } } /** * Encodes public key in format expected by the secure hardware module. This is used as part * of the vault params. * * @param publicKey The public key. * @return The key packed into a 65-byte array. */ public static byte[] encodePublicKey(PublicKey publicKey) { ECPoint point = ((ECPublicKey) publicKey).getW(); byte[] x = point.getAffineX().toByteArray(); byte[] y = point.getAffineY().toByteArray(); byte[] output = new byte[EC_PUBLIC_KEY_LEN_BYTES]; // The order of arraycopy() is important, because the coordinates may have a one-byte // leading 0 for the sign bit of two's complement form System.arraycopy(y, 0, output, EC_PUBLIC_KEY_LEN_BYTES - y.length, y.length); System.arraycopy(x, 0, output, 1 + EC_COORDINATE_LEN_BYTES - x.length, x.length); output[0] = EC_PUBLIC_KEY_PREFIX; return output; } /** * Decodes byte[] encoded public key. * * @param keyBytes encoded public key * @return the public key */ public static PublicKey decodePublicKey(byte[] keyBytes) throws NoSuchAlgorithmException, InvalidKeyException { BigInteger x = new BigInteger( /*signum=*/ 1, Arrays.copyOfRange(keyBytes, 1, 1 + EC_COORDINATE_LEN_BYTES)); BigInteger y = new BigInteger( /*signum=*/ 1, Arrays.copyOfRange( keyBytes, 1 + EC_COORDINATE_LEN_BYTES, EC_PUBLIC_KEY_LEN_BYTES)); // Checks if the point is indeed on the P-256 curve for security considerations validateEcPoint(x, y); KeyFactory keyFactory = KeyFactory.getInstance(EC_ALG); try { return keyFactory.generatePublic(new ECPublicKeySpec(new ECPoint(x, y), EC_PARAM_SPEC)); } catch (InvalidKeySpecException ex) { // This should never happen throw new RuntimeException(ex); } } private static void validateEcPoint(BigInteger x, BigInteger y) throws InvalidKeyException { if (x.compareTo(EC_PARAM_P) >= 0 || y.compareTo(EC_PARAM_P) >= 0 || x.signum() == -1 || y.signum() == -1) { throw new InvalidKeyException("Point lies outside of the expected curve"); } // Points on the curve satisfy y^2 = x^3 + ax + b (mod p) BigInteger lhs = y.modPow(BIG_INT_02, EC_PARAM_P); BigInteger rhs = x.modPow(BIG_INT_02, EC_PARAM_P) // x^2 .add(EC_PARAM_A) // x^2 + a .mod(EC_PARAM_P) // This will speed up the next multiplication .multiply(x) // (x^2 + a) * x = x^3 + ax .add(EC_PARAM_B) // x^3 + ax + b .mod(EC_PARAM_P); if (!lhs.equals(rhs)) { throw new InvalidKeyException("Point lies outside of the expected curve"); } } private static byte[] genRandomNonce() throws NoSuchAlgorithmException { byte[] nonce = new byte[GCM_NONCE_LEN_BYTES]; new SecureRandom().nextBytes(nonce); return nonce; } private static byte[] emptyByteArrayIfNull(@Nullable byte[] input) { return input == null ? EMPTY_BYTE_ARRAY : input; } }