195 lines
8.6 KiB
Java
195 lines
8.6 KiB
Java
|
/*
|
||
|
|
* Copyright (C) 2024 The Android Open Source Project
|
||
|
|
*
|
||
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
|
* you may not use this file except in compliance with the License.
|
||
|
|
* You may obtain a copy of the License at
|
||
|
|
*
|
||
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
*
|
||
|
|
* Unless required by applicable law or agreed to in writing, software
|
||
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
|
* See the License for the specific language governing permissions and
|
||
|
|
* limitations under the License.
|
||
|
|
*/
|
||
|
|
|
||
|
|
package android.crypto.hpke;
|
||
|
|
|
||
|
|
import java.security.GeneralSecurityException;
|
||
|
|
import java.security.InvalidKeyException;
|
||
|
|
import java.security.PrivateKey;
|
||
|
|
import java.security.PublicKey;
|
||
|
|
import libcore.util.NonNull;
|
||
|
|
import libcore.util.Nullable;
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Service Provider Interface for HPKE client API classes to communicate with implementations
|
||
|
|
* of HPKE as described in RFC 9180.
|
||
|
|
* <p>
|
||
|
|
* There are no standard Java Cryptography Architecture names or interface classes for HPKE,
|
||
|
|
* but instances of this class can be obtained by calling
|
||
|
|
* {@code Provider.getService("ConscryptHpke", String SuiteName)} where {@code suiteName}
|
||
|
|
* is the name of the HPKE suite, e.g.
|
||
|
|
* {@code "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_128_GCM"}.
|
||
|
|
*/
|
||
|
|
public interface HpkeSpi {
|
||
|
|
/**
|
||
|
|
* Initialises an HPKE SPI in one of the sender modes described in RFC 9180.
|
||
|
|
* <p>
|
||
|
|
* If {@code psk} and {@code psk_id} are supplied then Pre-Shared Key Authentication
|
||
|
|
* will be used.
|
||
|
|
* <p>
|
||
|
|
* If {@code senderKey} is supplied then Asymmetric Key Authentication will be used.
|
||
|
|
* <p>
|
||
|
|
* If neither is supplied then "base" mode (no sender authentication) will be used.
|
||
|
|
* <p>
|
||
|
|
* Note that only base mode is currently supported on Android.
|
||
|
|
* <p>
|
||
|
|
* Public and private keys must be supplied in a format that can be used by the
|
||
|
|
* implementation. An instance of the {@code "XDH"} {@link java.security.KeyFactory} can
|
||
|
|
* be used to translate {@code KeySpecs} or keys from another {@link java.security.Provider}
|
||
|
|
*
|
||
|
|
* @param recipientKey public key of the recipient
|
||
|
|
* @param info application-supplied information, may be null or empty
|
||
|
|
* @param senderKey private key of the sender, for symmetric auth modes only, else null
|
||
|
|
* @param psk pre-shared key, for PSK auth modes only, else null
|
||
|
|
* @param psk_id pre-shared key ID, for PSK auth modes only, else null
|
||
|
|
* @throws InvalidKeyException if recipientKey is null or an unsupported key format
|
||
|
|
* @throws UnsupportedOperationException if mode is not a supported HPKE mode
|
||
|
|
* @throws IllegalStateException if this SPI has already been initialised
|
||
|
|
*/
|
||
|
|
void engineInitSender(
|
||
|
|
@NonNull PublicKey recipientKey,
|
||
|
|
@Nullable byte[] info,
|
||
|
|
@Nullable PrivateKey senderKey,
|
||
|
|
@Nullable byte[] psk,
|
||
|
|
@Nullable byte[] psk_id)
|
||
|
|
throws InvalidKeyException;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Initialises an HPKE SPI in one of the sender modes described in RFC 9180 with
|
||
|
|
* a predefined random seed to allow testing against known test vectors.
|
||
|
|
* <p>
|
||
|
|
* This mode provides absolutely no security and should only be used for testing
|
||
|
|
* purposes.
|
||
|
|
* <p>
|
||
|
|
* If {@code psk} and {@code psk_id} are supplied then Pre-Shared Key Authentication
|
||
|
|
* will be used.
|
||
|
|
* <p>
|
||
|
|
* If {@code senderKey} is supplied then Asymmetric Key Authentication will be used.
|
||
|
|
* <p>
|
||
|
|
* If neither is supplied then "base" mode (no sender authentication) will be used.
|
||
|
|
* <p>
|
||
|
|
* Note that only base mode is currently supported on Android.
|
||
|
|
* <p>
|
||
|
|
* Public and private keys must be supplied in a format that can be used by the
|
||
|
|
* implementation. An instance of the {@code "XDH"} {@link java.security.KeyFactory} can
|
||
|
|
* be used to translate {@code KeySpecs} or keys from another {@link java.security.Provider}
|
||
|
|
*
|
||
|
|
*
|
||
|
|
* @param recipientKey public key of the recipient
|
||
|
|
* @param info application-supplied information, may be null or empty
|
||
|
|
* @param senderKey private key of the sender, for symmetric auth modes only, else null
|
||
|
|
* @param psk pre-shared key, for PSK auth modes only, else null
|
||
|
|
* @param psk_id pre-shared key ID, for PSK auth modes only, else null
|
||
|
|
* @param sKe Predetermined random seed, should only be usesd for validation against
|
||
|
|
* known test vectors
|
||
|
|
* @throws InvalidKeyException if recipientKey is null or an unsupported key format or senderKey
|
||
|
|
* is an unsupported key format
|
||
|
|
* @throws UnsupportedOperationException if mode is not a supported HPKE mode
|
||
|
|
* @throws IllegalStateException if this SPI has already been initialised
|
||
|
|
*/
|
||
|
|
void engineInitSenderWithSeed(
|
||
|
|
@NonNull PublicKey recipientKey,
|
||
|
|
@Nullable byte[] info,
|
||
|
|
@Nullable PrivateKey senderKey,
|
||
|
|
@Nullable byte[] psk,
|
||
|
|
@Nullable byte[] psk_id,
|
||
|
|
@NonNull byte[] sKe)
|
||
|
|
throws InvalidKeyException;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Initialises an HPKE SPI in one of the sender modes described in RFC 9180.
|
||
|
|
* <p>
|
||
|
|
* If {@code psk} and {@code psk_id} are supplied then Pre-Shared Key Authentication
|
||
|
|
* will be used.
|
||
|
|
* <p>
|
||
|
|
* If {@code senderKey} is supplied then Asymmetric Key Authentication will be used.
|
||
|
|
* <p>
|
||
|
|
* If neither is supplied then "base" mode (no sender authentication) will be used.
|
||
|
|
* <p>
|
||
|
|
* Note that only base mode is currently supported on Android.
|
||
|
|
* <p>
|
||
|
|
* Public and private keys must be supplied in a format that can be used by the
|
||
|
|
* implementation. An instance of the {@code "XDH"} {@link java.security.KeyFactory} can
|
||
|
|
* be used to translate {@code KeySpecs} or keys from another {@link java.security.Provider}
|
||
|
|
*
|
||
|
|
* @param encapsulated encapsulated ephemeral key from a sender
|
||
|
|
* @param recipientKey private key of the recipient
|
||
|
|
* @param info application-supplied information, may be null or empty
|
||
|
|
* @param senderKey public key of sender, for asymmetric auth modes only, else null
|
||
|
|
* @param psk pre-shared key, for PSK auth modes only, else null
|
||
|
|
* @param psk_id pre-shared key ID, for PSK auth modes only, else null
|
||
|
|
* @throws InvalidKeyException if recipientKey is null or an unsupported key format or senderKey
|
||
|
|
* is an unsupported key format
|
||
|
|
* @throws UnsupportedOperationException if mode is not a supported HPKE mode
|
||
|
|
* @throws IllegalStateException if this SPI has already been initialised
|
||
|
|
*/
|
||
|
|
void engineInitRecipient(
|
||
|
|
@NonNull byte[] encapsulated,
|
||
|
|
@NonNull PrivateKey recipientKey,
|
||
|
|
@Nullable byte[] info,
|
||
|
|
@Nullable PublicKey senderKey,
|
||
|
|
@Nullable byte[] psk,
|
||
|
|
@Nullable byte[] psk_id)
|
||
|
|
throws InvalidKeyException;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Seals a message, using the internal key schedule maintained by an HPKE sender SPI.
|
||
|
|
*
|
||
|
|
* @param plaintext the plaintext
|
||
|
|
* @param aad optional associated data, may be null or empty
|
||
|
|
* @return the ciphertext
|
||
|
|
* @throws NullPointerException if the plaintext is null
|
||
|
|
* @throws IllegalStateException if this SPI has not been initialised or if it was initialised
|
||
|
|
* as a recipient
|
||
|
|
*/
|
||
|
|
@NonNull byte[] engineSeal(@NonNull byte[] plaintext, @Nullable byte[] aad);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Opens a message, using the internal key schedule maintained by an HPKE recipient SPI.
|
||
|
|
*
|
||
|
|
* @param ciphertext the ciphertext
|
||
|
|
* @param aad optional associated data, may be null or empty
|
||
|
|
* @return the plaintext
|
||
|
|
* @throws IllegalStateException if this SPI has not been initialised or if it was initialised
|
||
|
|
* as a sender
|
||
|
|
* @throws GeneralSecurityException on decryption failures
|
||
|
|
*/
|
||
|
|
@NonNull byte[] engineOpen(@NonNull byte[] ciphertext, @Nullable byte[] aad)
|
||
|
|
throws GeneralSecurityException;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Exports secret key material from this SPI as described in RFC 9180.
|
||
|
|
*
|
||
|
|
* @param length expected output length
|
||
|
|
* @param context optional context string, may be null or empty
|
||
|
|
* @return exported value
|
||
|
|
* @throws IllegalArgumentException if the length is not valid for the KDF in use
|
||
|
|
* @throws IllegalStateException if this SPI has not been initialised
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
@NonNull byte[] engineExport(int length, @Nullable byte[] context);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the encapsulated key material for an HPKE sender.
|
||
|
|
*
|
||
|
|
* @return the key material
|
||
|
|
* @throws IllegalStateException if this SPI has not been initialised or if it was initialised
|
||
|
|
* as a recipient
|
||
|
|
*/
|
||
|
|
@NonNull byte[] getEncapsulated();
|
||
|
|
}
|