001package com.nimbusds.jose.proc; 002 003 004import java.io.IOException; 005import java.security.Key; 006import java.util.List; 007 008import com.nimbusds.jose.JWEHeader; 009 010 011/** 012 * Interface for selecting key candidates for decrypting a JSON Web Encryption 013 * (JWE) object. Applications should utilise this interface or a similar 014 * framework to determine whether a received JWE object (or encrypted JWT) is 015 * eligible for {@link com.nimbusds.jose.JWEDecrypter decryption} and further 016 * processing. 017 * 018 * <p>The key selection should be based on application specific criteria, such 019 * as recognised header parameters referencing the key (e.g. {@code kid}, 020 * {@code x5t}) and / or the JWE object {@link SecurityContext}. 021 * 022 * <p>See JSON Web Signature (JWE), Appendix D. Notes on Key Selection for 023 * suggestions. 024 * 025 * <p>Possible key types: 026 * 027 * <ul> 028 * <li>{@link javax.crypto.SecretKey} for AES keys. 029 * <li>{@link java.security.interfaces.RSAPrivateKey} private RSA keys. 030 * <li>{@link java.security.interfaces.ECPrivateKey} private EC keys. 031 * </ul> 032 * 033 * @author Vladimir Dzhuvinov 034 * @version 2016-06-15 035 */ 036public interface JWEKeySelector <C extends SecurityContext> { 037 038 039 /** 040 * Selects key candidates for decrypting a JWE object. 041 * 042 * @param header The header of the JWE object. Must not be 043 * {@code null}. 044 * @param context Optional context of the JWE object, {@code null} if 045 * not required. 046 * 047 * @return The key candidates in trial order, empty list if none. 048 * 049 * @throws IOException If an I/0 exception is encountered, e.g. on JWK 050 * retrieval. 051 */ 052 List<? extends Key> selectJWEKeys(final JWEHeader header, final C context) 053 throws IOException; 054}