1 /*
2 * GordianKnot: Security Suite
3 * Copyright 2012-2026. Tony Washer
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
6 * use this file except in compliance with the License. You may obtain a copy
7 * of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14 * License for the specific language governing permissions and limitations under
15 * the License.
16 */
17 package io.github.tonywasher.joceanus.gordianknot.api.keyset;
18
19 import io.github.tonywasher.joceanus.gordianknot.api.base.GordianException;
20 import io.github.tonywasher.joceanus.gordianknot.api.base.GordianKeySpec;
21 import io.github.tonywasher.joceanus.gordianknot.api.base.GordianLength;
22 import io.github.tonywasher.joceanus.gordianknot.api.key.GordianKey;
23 import io.github.tonywasher.joceanus.gordianknot.api.keypair.GordianKeyPair;
24
25 import java.security.spec.X509EncodedKeySpec;
26
27 /**
28 * keySet API.
29 */
30 public interface GordianKeySet {
31 /**
32 * Obtain the keySetSpec.
33 *
34 * @return the keySetSpec
35 */
36 GordianKeySetSpec getKeySetSpec();
37
38 /**
39 * Create a keySetCipher.
40 *
41 * @return the keySetCipher
42 * @throws GordianException on error
43 */
44 GordianKeySetCipher createCipher() throws GordianException;
45
46 /**
47 * Encrypt bytes.
48 *
49 * @param pBytesToEncrypt the bytes to encrypt
50 * @return the encrypted bytes
51 * @throws GordianException on error
52 */
53 byte[] encryptBytes(byte[] pBytesToEncrypt) throws GordianException;
54
55 /**
56 * Decrypt bytes.
57 *
58 * @param pBytesToDecrypt the bytes to decrypt
59 * @return the decrypted bytes
60 * @throws GordianException on error
61 */
62 byte[] decryptBytes(byte[] pBytesToDecrypt) throws GordianException;
63
64 /**
65 * Create a keySetAADCipher.
66 *
67 * @return the keySetCipher
68 * @throws GordianException on error
69 */
70 GordianKeySetAADCipher createAADCipher() throws GordianException;
71
72 /**
73 * Encrypt AAD bytes.
74 *
75 * @param pBytesToEncrypt the bytes to encrypt
76 * @return the encrypted bytes
77 * @throws GordianException on error
78 */
79 default byte[] encryptAADBytes(final byte[] pBytesToEncrypt) throws GordianException {
80 return encryptAADBytes(pBytesToEncrypt, null);
81 }
82
83 /**
84 * Encrypt AAD bytes.
85 *
86 * @param pBytesToEncrypt the bytes to encrypt
87 * @param pAAD the AAD data
88 * @return the encrypted bytes
89 * @throws GordianException on error
90 */
91 byte[] encryptAADBytes(byte[] pBytesToEncrypt,
92 byte[] pAAD) throws GordianException;
93
94 /**
95 * Decrypt AAD bytes.
96 *
97 * @param pBytesToDecrypt the bytes to decrypt
98 * @return the decrypted bytes
99 * @throws GordianException on error
100 */
101 default byte[] decryptAADBytes(final byte[] pBytesToDecrypt) throws GordianException {
102 return decryptAADBytes(pBytesToDecrypt, null);
103 }
104
105 /**
106 * Decrypt AAD bytes.
107 *
108 * @param pBytesToDecrypt the bytes to decrypt
109 * @param pAAD the AAD data
110 * @return the decrypted bytes
111 * @throws GordianException on error
112 */
113 byte[] decryptAADBytes(byte[] pBytesToDecrypt,
114 byte[] pAAD) throws GordianException;
115
116 /**
117 * secure KeySet.
118 *
119 * @param pKeySetToSecure the keySet to secure
120 * @return the encryptedKeySet
121 * @throws GordianException on error
122 */
123 byte[] secureKeySet(GordianKeySet pKeySetToSecure) throws GordianException;
124
125 /**
126 * derive KeySet.
127 *
128 * @param pSecuredKeySet the secured keySet
129 * @return the decrypted keySet
130 * @throws GordianException on error
131 */
132 GordianKeySet deriveKeySet(byte[] pSecuredKeySet) throws GordianException;
133
134 /**
135 * secure bytes.
136 *
137 * @param pBytesToSecure the bytes to secure
138 * @return the securedBytes
139 * @throws GordianException on error
140 */
141 byte[] secureBytes(byte[] pBytesToSecure) throws GordianException;
142
143 /**
144 * derive bytes.
145 *
146 * @param pSecuredBytes the secured bytes
147 * @return the derivedBytes
148 * @throws GordianException on error
149 */
150 byte[] deriveBytes(byte[] pSecuredBytes) throws GordianException;
151
152 /**
153 * secure Key.
154 *
155 * @param pKeyToSecure the key to secure
156 * @return the securedKey
157 * @throws GordianException on error
158 */
159 byte[] secureKey(GordianKey<?> pKeyToSecure) throws GordianException;
160
161 /**
162 * derive Key.
163 *
164 * @param <T> the keyType class
165 * @param pSecuredKey the secured key
166 * @param pKeyType the key type
167 * @return the derived key
168 * @throws GordianException on error
169 */
170 <T extends GordianKeySpec> GordianKey<T> deriveKey(byte[] pSecuredKey,
171 T pKeyType) throws GordianException;
172
173 /**
174 * secure privateKey.
175 *
176 * @param pKeyPair the keyPair to secure
177 * @return the securedPrivateKey
178 * @throws GordianException on error
179 */
180 byte[] securePrivateKey(GordianKeyPair pKeyPair) throws GordianException;
181
182 /**
183 * derive keyPair.
184 *
185 * @param pPublicKeySpec the publicKeySpec
186 * @param pSecuredPrivateKey the secured privateKey
187 * @return the keyPair
188 * @throws GordianException on error
189 */
190 GordianKeyPair deriveKeyPair(X509EncodedKeySpec pPublicKeySpec,
191 byte[] pSecuredPrivateKey) throws GordianException;
192
193 /**
194 * Obtain wrapped size of a key.
195 *
196 * @param pKeyLen the keyLength
197 * @return the wrapped length
198 */
199 int getKeyWrapLength(GordianLength pKeyLen);
200
201 /**
202 * Obtain wrapped size of the privateKey of a keyPair.
203 *
204 * @param pKeyPair the keyPair
205 * @return the wrapped length
206 * @throws GordianException on error
207 */
208 int getPrivateKeyWrapLength(GordianKeyPair pKeyPair) throws GordianException;
209
210 /**
211 * Obtain the keySet wrap length.
212 *
213 * @return the length
214 */
215 int getKeySetWrapLength();
216
217 /**
218 * Clone the keySet.
219 *
220 * @return the cloned keySet
221 * @throws GordianException on error
222 */
223 GordianKeySet cloneIt() throws GordianException;
224 }