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 import io.github.tonywasher.joceanus.gordianknot.api.keyset.spec.GordianKeySetSpec;
25
26 import java.security.spec.X509EncodedKeySpec;
27
28 /**
29 * keySet API.
30 */
31 public interface GordianKeySet {
32 /**
33 * Obtain the keySetSpec.
34 *
35 * @return the keySetSpec
36 */
37 GordianKeySetSpec getKeySetSpec();
38
39 /**
40 * Create a keySetCipher.
41 *
42 * @return the keySetCipher
43 * @throws GordianException on error
44 */
45 GordianKeySetCipher createCipher() throws GordianException;
46
47 /**
48 * Encrypt bytes.
49 *
50 * @param pBytesToEncrypt the bytes to encrypt
51 * @return the encrypted bytes
52 * @throws GordianException on error
53 */
54 byte[] encryptBytes(byte[] pBytesToEncrypt) throws GordianException;
55
56 /**
57 * Decrypt bytes.
58 *
59 * @param pBytesToDecrypt the bytes to decrypt
60 * @return the decrypted bytes
61 * @throws GordianException on error
62 */
63 byte[] decryptBytes(byte[] pBytesToDecrypt) throws GordianException;
64
65 /**
66 * Create a keySetAADCipher.
67 *
68 * @return the keySetCipher
69 * @throws GordianException on error
70 */
71 GordianKeySetAADCipher createAADCipher() throws GordianException;
72
73 /**
74 * Encrypt AAD bytes.
75 *
76 * @param pBytesToEncrypt the bytes to encrypt
77 * @return the encrypted bytes
78 * @throws GordianException on error
79 */
80 default byte[] encryptAADBytes(final byte[] pBytesToEncrypt) throws GordianException {
81 return encryptAADBytes(pBytesToEncrypt, null);
82 }
83
84 /**
85 * Encrypt AAD bytes.
86 *
87 * @param pBytesToEncrypt the bytes to encrypt
88 * @param pAAD the AAD data
89 * @return the encrypted bytes
90 * @throws GordianException on error
91 */
92 byte[] encryptAADBytes(byte[] pBytesToEncrypt,
93 byte[] pAAD) throws GordianException;
94
95 /**
96 * Decrypt AAD bytes.
97 *
98 * @param pBytesToDecrypt the bytes to decrypt
99 * @return the decrypted bytes
100 * @throws GordianException on error
101 */
102 default byte[] decryptAADBytes(final byte[] pBytesToDecrypt) throws GordianException {
103 return decryptAADBytes(pBytesToDecrypt, null);
104 }
105
106 /**
107 * Decrypt AAD bytes.
108 *
109 * @param pBytesToDecrypt the bytes to decrypt
110 * @param pAAD the AAD data
111 * @return the decrypted bytes
112 * @throws GordianException on error
113 */
114 byte[] decryptAADBytes(byte[] pBytesToDecrypt,
115 byte[] pAAD) throws GordianException;
116
117 /**
118 * secure KeySet.
119 *
120 * @param pKeySetToSecure the keySet to secure
121 * @return the encryptedKeySet
122 * @throws GordianException on error
123 */
124 byte[] secureKeySet(GordianKeySet pKeySetToSecure) throws GordianException;
125
126 /**
127 * derive KeySet.
128 *
129 * @param pSecuredKeySet the secured keySet
130 * @return the decrypted keySet
131 * @throws GordianException on error
132 */
133 GordianKeySet deriveKeySet(byte[] pSecuredKeySet) throws GordianException;
134
135 /**
136 * secure bytes.
137 *
138 * @param pBytesToSecure the bytes to secure
139 * @return the securedBytes
140 * @throws GordianException on error
141 */
142 byte[] secureBytes(byte[] pBytesToSecure) throws GordianException;
143
144 /**
145 * derive bytes.
146 *
147 * @param pSecuredBytes the secured bytes
148 * @return the derivedBytes
149 * @throws GordianException on error
150 */
151 byte[] deriveBytes(byte[] pSecuredBytes) throws GordianException;
152
153 /**
154 * secure Key.
155 *
156 * @param pKeyToSecure the key to secure
157 * @return the securedKey
158 * @throws GordianException on error
159 */
160 byte[] secureKey(GordianKey<?> pKeyToSecure) throws GordianException;
161
162 /**
163 * derive Key.
164 *
165 * @param <T> the keyType class
166 * @param pSecuredKey the secured key
167 * @param pKeyType the key type
168 * @return the derived key
169 * @throws GordianException on error
170 */
171 <T extends GordianKeySpec> GordianKey<T> deriveKey(byte[] pSecuredKey,
172 T pKeyType) throws GordianException;
173
174 /**
175 * secure privateKey.
176 *
177 * @param pKeyPair the keyPair to secure
178 * @return the securedPrivateKey
179 * @throws GordianException on error
180 */
181 byte[] securePrivateKey(GordianKeyPair pKeyPair) throws GordianException;
182
183 /**
184 * derive keyPair.
185 *
186 * @param pPublicKeySpec the publicKeySpec
187 * @param pSecuredPrivateKey the secured privateKey
188 * @return the keyPair
189 * @throws GordianException on error
190 */
191 GordianKeyPair deriveKeyPair(X509EncodedKeySpec pPublicKeySpec,
192 byte[] pSecuredPrivateKey) throws GordianException;
193
194 /**
195 * Obtain wrapped size of a key.
196 *
197 * @param pKeyLen the keyLength
198 * @return the wrapped length
199 */
200 int getKeyWrapLength(GordianLength pKeyLen);
201
202 /**
203 * Obtain wrapped size of the privateKey of a keyPair.
204 *
205 * @param pKeyPair the keyPair
206 * @return the wrapped length
207 * @throws GordianException on error
208 */
209 int getPrivateKeyWrapLength(GordianKeyPair pKeyPair) throws GordianException;
210
211 /**
212 * Obtain the keySet wrap length.
213 *
214 * @return the length
215 */
216 int getKeySetWrapLength();
217
218 /**
219 * Clone the keySet.
220 *
221 * @return the cloned keySet
222 * @throws GordianException on error
223 */
224 GordianKeySet cloneIt() throws GordianException;
225 }