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.cipher;
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.key.GordianKey;
22 import io.github.tonywasher.joceanus.gordianknot.api.keypair.GordianKeyPair;
23
24 import java.security.spec.X509EncodedKeySpec;
25
26 /**
27 * GordianKnot base for Wrap Cipher.
28 */
29 public interface GordianWrapper {
30 /**
31 * Obtain the keyType.
32 *
33 * @return the keyType
34 */
35 GordianSymKeySpec getKeySpec();
36
37 /**
38 * Secure key.
39 *
40 * @param pKeyToSecure the key to secure
41 * @return the securedKey
42 * @throws GordianException on error
43 */
44 byte[] secureKey(GordianKey<?> pKeyToSecure) throws GordianException;
45
46 /**
47 * Derive key from bytes.
48 *
49 * @param <T> type of key to be derived
50 * @param pSecuredKey the securedKey
51 * @param pKeyType the type of key to be derived
52 * @return the derived key
53 * @throws GordianException on error
54 */
55 <T extends GordianKeySpec> GordianKey<T> deriveKey(byte[] pSecuredKey,
56 T pKeyType) throws GordianException;
57
58 /**
59 * Secure privateKey.
60 *
61 * @param pKeyPair the keyPair to secure
62 * @return the securedPrivateKey
63 * @throws GordianException on error
64 */
65 byte[] securePrivateKey(GordianKeyPair pKeyPair) throws GordianException;
66
67 /**
68 * Derive the keyPair from the PKCS8/X509 encodings.
69 *
70 * @param pPublicKeySpec the publicKeySpec
71 * @param pSecuredPrivateKey the secured privateKey
72 * @return the derived keyPair
73 * @throws GordianException on error
74 */
75 GordianKeyPair deriveKeyPair(X509EncodedKeySpec pPublicKeySpec,
76 byte[] pSecuredPrivateKey) throws GordianException;
77
78 /**
79 * secure bytes.
80 *
81 * @param pBytesToSecure the bytes to secure
82 * @return the securedBytes
83 * @throws GordianException on error
84 */
85 byte[] secureBytes(byte[] pBytesToSecure) throws GordianException;
86
87 /**
88 * derive bytes.
89 *
90 * @param pSecuredBytes the secured bytes
91 * @return the derivedBytes
92 * @throws GordianException on error
93 */
94 default byte[] deriveBytes(final byte[] pSecuredBytes) throws GordianException {
95 return deriveBytes(pSecuredBytes, 0);
96 }
97
98 /**
99 * derive bytes.
100 *
101 * @param pSecuredBytes the secured bytes
102 * @param pOffset the offset within the secured bytes
103 * @return the derivedBytes
104 * @throws GordianException on error
105 */
106 byte[] deriveBytes(byte[] pSecuredBytes,
107 int pOffset) throws GordianException;
108
109 /**
110 * Obtain wrapped size of a key.
111 *
112 * @param pKey the keyToWrap
113 * @return the wrapped length
114 */
115 int getKeyWrapLength(GordianKey<?> pKey);
116
117 /**
118 * Obtain wrapped size of a byte array of the given length.
119 *
120 * @param pDataLength the length of the byte array
121 * @return the wrapped length
122 */
123 int getDataWrapLength(int pDataLength);
124
125 /**
126 * Obtain wrapped size of the privateKey of a keyPair.
127 *
128 * @param pKeyPair the keyPair
129 * @return the wrapped length
130 * @throws GordianException on error
131 */
132 int getPrivateKeyWrapLength(GordianKeyPair pKeyPair) throws GordianException;
133 }