1 /*
2 * The contents of this file are subject to the terms of the Common Development and
3 * Distribution License (the License). You may not use this file except in compliance with the
4 * License.
5 *
6 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
7 * specific language governing permission and limitations under the License.
8 *
9 * When distributing Covered Software, include this CDDL Header Notice in each file and include
10 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
11 * Header, with the fields enclosed by brackets [] replaced by your own identifying
12 * information: "Portions copyright [year] [name of copyright owner]".
13 *
14 * Copyright 2013-2016 ForgeRock AS.
15 */
16
17 package org.forgerock.json.jose.jwe.handlers.encryption;
18
19 import java.security.Key;
20
21 import org.forgerock.json.jose.jwe.JweEncryption;
22
23 /**
24 * The interface for EncryptionHandlers for all the different encryption algorithms.
25 * <p>
26 * Provides methods for encrypting plaintexts and decrypting ciphertexts.
27 * @see <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5">
28 * JWE Encryption and Decryption</a>
29 *
30 * @since 2.0.0
31 */
32 public interface EncryptionHandler {
33
34 /**
35 * Creates a Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler
36 * JweAlgorithm.
37 * <p>
38 * See points 1, 2, 3 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
39 * Section 5.1</a> of the JWE Specification.
40 *
41 * @return The Content Encryption Key or {@literal null} if the shared key should be used directly.
42 */
43 Key getContentEncryptionKey();
44
45 /**
46 * Generates the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler
47 * JweAlgorithm.
48 * <p>
49 * See points 4, 5, 6 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
50 * Section 5.1</a> of the JWE Specification.
51 *
52 * @param key The key to use to encrypt the Content Encryption Key, if the EncryptionHandler JweAlgorithm requires.
53 * @param contentEncryptionKey The Content Encryption Key (CEK).
54 * @return A byte array of the JWE Encrypted Key.
55 */
56 byte[] generateJWEEncryptedKey(Key key, Key contentEncryptionKey);
57
58 /**
59 * Generates a random JWE Initialisation Vector of the correct size for the encryption algorithm, if the
60 * EncryptionHandler JweAlgorithm does not required an initialisation vector then the initialisation vector will
61 * be an empty octet sequence.
62 * <p>
63 * See points 9 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
64 * Section 5.1</a> of the JWE Specification.
65 *
66 * @return The Initialisation Vector.
67 */
68 byte[] generateInitialisationVector();
69
70 /**
71 * Encrypts the plaintext with the Content Encryption Key, using the initialisation vector and additional
72 * authenticated data, following the steps defined by the EncryptionHandler JweAlgorithm.
73 * <p>
74 * See points 15, 16 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.1">
75 * Section 5.1</a> of the JWE Specification.
76 *
77 * @param contentEncryptionKey The Content Encryption Key.
78 * @param initialisationVector The Initialisation Vector.
79 * @param plaintext The plaintext to encrypt.
80 * @param additionalAuthenticatedData An array of bytes representing the additional authenticated data.
81 * @return The JweEncryption object containing the ciphertext and authentication tag.
82 */
83 JweEncryption encryptPlaintext(Key contentEncryptionKey, byte[] initialisationVector, byte[] plaintext,
84 byte[] additionalAuthenticatedData);
85
86 /**
87 * Decrypts the Content Encryption Key (CEK) following the appropriate steps defined by the EncryptionHandler
88 * JweAlgorithm.
89 * <p>
90 * See points 9, 10 in <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11#section-5.2">
91 * Section 5.2</a> of the JWE Specification.
92 *
93 * @param key The private key pair to the public key that encrypted the JWT.
94 * @param encryptedContentEncryptionKey The encrypted Content Encryption Key.
95 * @return The decrypted Content Encryption Key.
96 */
97 Key decryptContentEncryptionKey(Key key, byte[] encryptedContentEncryptionKey);
98
99 /**
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 }