001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2013-2016 ForgeRock AS.
015 */
016
017package org.forgerock.json.jose.jwe.handlers.encryption;
018
019import java.security.Key;
020
021import org.forgerock.json.jose.jwe.JweEncryption;
022
023/**
024 * The interface for EncryptionHandlers for all the different encryption algorithms.
025 * <p>
026 * Provides methods for encrypting plaintexts and decrypting ciphertexts.
027 * @see <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5">
028 *     JWE Encryption and Decryption</a>
029 *
030 * @since 2.0.0
031 */
032public interface EncryptionHandler {
033
034    /**
035     * Creates a Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler
036     * JweAlgorithm.
037     * <p>
038     * See points 1, 2, 3 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
039     *     Section 5.1</a> of the JWE Specification.
040     *
041     * @return The Content Encryption Key or {@literal null} if the shared key should be used directly.
042     */
043    Key getContentEncryptionKey();
044
045    /**
046     * Generates the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler
047     * JweAlgorithm.
048     * <p>
049     * See points 4, 5, 6 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
050     *     Section 5.1</a> of the JWE Specification.
051     *
052     * @param key The key to use to encrypt the Content Encryption Key, if the EncryptionHandler JweAlgorithm requires.
053     * @param contentEncryptionKey The Content Encryption Key (CEK).
054     * @return A byte array of the JWE Encrypted Key.
055     */
056    byte[] generateJWEEncryptedKey(Key key, Key contentEncryptionKey);
057
058    /**
059     * Generates a random JWE Initialisation Vector of the correct size for the encryption algorithm, if the
060     * EncryptionHandler JweAlgorithm does not required an initialisation vector then the initialisation vector will
061     * be an empty octet sequence.
062     * <p>
063     * See points 9 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
064     *     Section 5.1</a> of the JWE Specification.
065     *
066     * @return The Initialisation Vector.
067     */
068    byte[] generateInitialisationVector();
069
070    /**
071     * Encrypts the plaintext with the Content Encryption Key, using the initialisation vector and additional
072     * authenticated data, following the steps defined by the EncryptionHandler JweAlgorithm.
073     * <p>
074     * See points 15, 16 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
075     *     Section 5.1</a> of the JWE Specification.
076     *
077     * @param contentEncryptionKey The Content Encryption Key.
078     * @param initialisationVector The Initialisation Vector.
079     * @param plaintext The plaintext to encrypt.
080     * @param additionalAuthenticatedData An array of bytes representing the additional authenticated data.
081     * @return The JweEncryption object containing the ciphertext and authentication tag.
082     */
083    JweEncryption encryptPlaintext(Key contentEncryptionKey, byte[] initialisationVector, byte[] plaintext,
084            byte[] additionalAuthenticatedData);
085
086    /**
087     * Decrypts the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler
088     * JweAlgorithm.
089     * <p>
090     * See points 9, 10 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.2">
091     *     Section 5.2</a> of the JWE Specification.
092     *
093     * @param key The private key pair to the public key that encrypted the JWT.
094     * @param encryptedContentEncryptionKey The encrypted Content Encryption Key.
095     * @return The decrypted Content Encryption Key.
096     */
097    Key decryptContentEncryptionKey(Key key, byte[] encryptedContentEncryptionKey);
098
099    /**
100     * Decrypts the ciphertext with the Content Encryption Key, using the initialisation vector and additional
101     * authenticated data, following the steps defined by the EncryptionHandler JweAlgorithm.
102     * <p>
103     * See points 14, 15 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.2">
104     *     Section 5.2</a> of the JWE Specification.
105     *
106     * @param contentEncryptionKey The Content Encryption Key.
107     * @param initialisationVector The Initialisation Vector.
108     * @param ciphertext The ciphertext to decrypt.
109     * @param authenticationTag The authentication tag.
110     * @param additionalAuthenticatedData An array of bytes representing the additional authenticated data.
111     * @return An array of bytes representing the decrypted ciphertext.
112     */
113    byte[] decryptCiphertext(Key contentEncryptionKey, byte[] initialisationVector, byte[] ciphertext,
114            byte[] authenticationTag, byte[] additionalAuthenticatedData);
115}