View Javadoc
1   /*
2    * GordianKnot: Security Suite
3    * Copyright 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  
18  package io.github.tonywasher.joceanus.gordianknot.api.keypair.spec;
19  
20  import io.github.tonywasher.joceanus.gordianknot.api.base.GordianLength;
21  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianLMSSpec.GordianLMSHash;
22  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianLMSSpec.GordianLMSHeight;
23  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianLMSSpec.GordianLMSWidth;
24  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianNTRUPrimeSpec.GordianNTRUPrimeParams;
25  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianNTRUPrimeSpec.GordianNTRUPrimeType;
26  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianXMSSSpec.GordianXMSSDigestType;
27  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianXMSSSpec.GordianXMSSHeight;
28  import io.github.tonywasher.joceanus.gordianknot.api.keypair.spec.GordianXMSSSpec.GordianXMSSMTLayers;
29  
30  import java.util.Arrays;
31  import java.util.List;
32  
33  /**
34   * Asymmetric KeyPair Specification Builder.
35   */
36  public interface GordianKeyPairSpecBuilder {
37      /**
38       * Define keyPairType.
39       *
40       * @param pType the type
41       * @return the Builder
42       */
43      GordianKeyPairSpecBuilder withKeyPairType(GordianKeyPairType pType);
44  
45      /**
46       * Define enum subSpec.
47       *
48       * @param pSubSpec the subSpec
49       * @return the Builder
50       */
51      GordianKeyPairSpecBuilder withEnumSubSpec(Enum<?> pSubSpec);
52  
53      /**
54       * Define xmss subSpec.
55       *
56       * @param pDigestType the digestType
57       * @param pHeight     the height
58       * @return the Builder
59       */
60      GordianKeyPairSpecBuilder withXMSSSubSpec(GordianXMSSDigestType pDigestType,
61                                                GordianXMSSHeight pHeight);
62  
63      /**
64       * Define xmssMT subSpec.
65       *
66       * @param pDigestType the digestType
67       * @param pHeight     the height
68       * @param pLayers     the layers
69       * @return the Builder
70       */
71      GordianKeyPairSpecBuilder withXMSSMTSubSpec(GordianXMSSDigestType pDigestType,
72                                                  GordianXMSSHeight pHeight,
73                                                  GordianXMSSMTLayers pLayers);
74  
75      /**
76       * Define hss subSpec.
77       *
78       * @param pHashType the hashType
79       * @param pHeight   the height
80       * @param pWidth    the width
81       * @param pLength   the length
82       * @param pDepth    the treeDepth
83       * @return the Builder
84       */
85      GordianKeyPairSpecBuilder withLMSSubSpec(GordianLMSHash pHashType,
86                                               GordianLMSHeight pHeight,
87                                               GordianLMSWidth pWidth,
88                                               GordianLength pLength,
89                                               int pDepth);
90  
91      /**
92       * Define ntruPrime subSpec.
93       *
94       * @param pType   the Type
95       * @param pParams the params
96       * @return the Builder
97       */
98      GordianKeyPairSpecBuilder withNTRUPrimeSubSpec(GordianNTRUPrimeType pType,
99                                                     GordianNTRUPrimeParams pParams);
100 
101     /**
102      * Define keyPairSpec list.
103      *
104      * @param pSpecs the specs
105      * @return the builder
106      */
107     GordianKeyPairSpecBuilder withKeyPairSpecs(List<GordianKeyPairSpec> pSpecs);
108 
109     /**
110      * Build the keyPairSpec.
111      *
112      * @return the keyPairSpec
113      */
114     GordianKeyPairSpec build();
115 
116     /**
117      * Create RSAKey.
118      *
119      * @param pSpec the subSpec
120      * @return the KeySpec
121      */
122     default GordianKeyPairSpec rsa(final GordianRSASpec pSpec) {
123         return withKeyPairType(GordianKeyPairType.RSA).withEnumSubSpec(pSpec).build();
124     }
125 
126     /**
127      * Create ECKey.
128      *
129      * @param pCurve the curve
130      * @return the KeySpec
131      */
132     default GordianKeyPairSpec ec(final GordianECSpec pCurve) {
133         return withKeyPairType(GordianKeyPairType.EC).withEnumSubSpec(pCurve).build();
134     }
135 
136     /**
137      * Create SM2Key.
138      *
139      * @param pCurve the curve
140      * @return the KeySpec
141      */
142     default GordianKeyPairSpec sm2(final GordianSM2Spec pCurve) {
143         return withKeyPairType(GordianKeyPairType.SM2).withEnumSubSpec(pCurve).build();
144     }
145 
146     /**
147      * Create DSTU4145Key.
148      *
149      * @param pCurve the curve
150      * @return the KeySpec
151      */
152     default GordianKeyPairSpec dstu4145(final GordianDSTUSpec pCurve) {
153         return withKeyPairType(GordianKeyPairType.DSTU).withEnumSubSpec(pCurve).build();
154     }
155 
156     /**
157      * Create GOST2012Key.
158      *
159      * @param pCurve the curve
160      * @return the KeySpec
161      */
162     default GordianKeyPairSpec gost2012(final GordianGOSTSpec pCurve) {
163         return withKeyPairType(GordianKeyPairType.GOST).withEnumSubSpec(pCurve).build();
164     }
165 
166     /**
167      * Create DSAKey.
168      *
169      * @param pSpec the subSpec
170      * @return the KeySpec
171      */
172     default GordianKeyPairSpec dsa(final GordianDSASpec pSpec) {
173         return withKeyPairType(GordianKeyPairType.DSA).withEnumSubSpec(pSpec).build();
174     }
175 
176     /**
177      * Create DHKey.
178      *
179      * @param pSpec the subSpec
180      * @return the KeySpec
181      */
182     default GordianKeyPairSpec dh(final GordianDHSpec pSpec) {
183         return withKeyPairType(GordianKeyPairType.DH).withEnumSubSpec(pSpec).build();
184     }
185 
186     /**
187      * Create ElGamalKey.
188      *
189      * @param pSpec the spec
190      * @return the KeySpec
191      */
192     default GordianKeyPairSpec elGamal(final GordianDHSpec pSpec) {
193         return withKeyPairType(GordianKeyPairType.ELGAMAL).withEnumSubSpec(pSpec).build();
194     }
195 
196     /**
197      * Create EdDSA25519 Key.
198      *
199      * @return the KeySpec
200      */
201     default GordianKeyPairSpec x25519() {
202         return withKeyPairType(GordianKeyPairType.XDH).withEnumSubSpec(GordianEdwardsSpec.CURVE25519).build();
203     }
204 
205     /**
206      * Create EdX448 Key.
207      *
208      * @return the KeySpec
209      */
210     default GordianKeyPairSpec x448() {
211         return withKeyPairType(GordianKeyPairType.XDH).withEnumSubSpec(GordianEdwardsSpec.CURVE448).build();
212     }
213 
214     /**
215      * Create EdDSA25519 Key.
216      *
217      * @return the KeySpec
218      */
219     default GordianKeyPairSpec ed25519() {
220         return withKeyPairType(GordianKeyPairType.EDDSA).withEnumSubSpec(GordianEdwardsSpec.CURVE25519).build();
221     }
222 
223     /**
224      * Create EdDSA448 Key.
225      *
226      * @return the KeySpec
227      */
228     default GordianKeyPairSpec ed448() {
229         return withKeyPairType(GordianKeyPairType.EDDSA).withEnumSubSpec(GordianEdwardsSpec.CURVE448).build();
230     }
231 
232     /**
233      * Create xmssKey.
234      *
235      * @param pDigestType the xmss digestType
236      * @param pHeight     the height
237      * @return the KeySpec
238      */
239     default GordianKeyPairSpec xmss(final GordianXMSSDigestType pDigestType,
240                                     final GordianXMSSHeight pHeight) {
241         return withKeyPairType(GordianKeyPairType.XMSS).withXMSSSubSpec(pDigestType, pHeight).build();
242     }
243 
244     /**
245      * Create xmssMTKey.
246      *
247      * @param pDigestType the xmss digestType
248      * @param pHeight     the height
249      * @param pLayers     the layers
250      * @return the KeySpec
251      */
252     default GordianKeyPairSpec xmssmt(final GordianXMSSDigestType pDigestType,
253                                       final GordianXMSSHeight pHeight,
254                                       final GordianXMSSMTLayers pLayers) {
255         return withKeyPairType(GordianKeyPairType.XMSS).withXMSSMTSubSpec(pDigestType, pHeight, pLayers).build();
256     }
257 
258     /**
259      * Create lmsKey.
260      *
261      * @param pHashType the hashType
262      * @param pHeight   the height
263      * @param pWidth    the width
264      * @param pLength   the length
265      * @return the KeySpec
266      */
267     default GordianKeyPairSpec lms(final GordianLMSHash pHashType,
268                                    final GordianLMSHeight pHeight,
269                                    final GordianLMSWidth pWidth,
270                                    final GordianLength pLength) {
271         return hss(pHashType, pHeight, pWidth, pLength, 1);
272     }
273 
274     /**
275      * Create hssKey.
276      *
277      * @param pHashType the hashType
278      * @param pHeight   the height
279      * @param pWidth    the width
280      * @param pLength   the length
281      * @param pDepth    the treeDepth
282      * @return the KeySpec
283      */
284     default GordianKeyPairSpec hss(final GordianLMSHash pHashType,
285                                    final GordianLMSHeight pHeight,
286                                    final GordianLMSWidth pWidth,
287                                    final GordianLength pLength,
288                                    final int pDepth) {
289         return withKeyPairType(GordianKeyPairType.LMS).withLMSSubSpec(pHashType, pHeight, pWidth, pLength, pDepth).build();
290     }
291 
292     /**
293      * Create newHopeKey.
294      *
295      * @return the KeySpec
296      */
297     default GordianKeyPairSpec newHope() {
298         return withKeyPairType(GordianKeyPairType.NEWHOPE).build();
299     }
300 
301     /**
302      * Create SLHDSAKey.
303      *
304      * @param pSpec the SLHDSA Spec
305      * @return the KeySpec
306      */
307     default GordianKeyPairSpec slhdsa(final GordianSLHDSASpec pSpec) {
308         return withKeyPairType(GordianKeyPairType.SLHDSA).withEnumSubSpec(pSpec).build();
309     }
310 
311     /**
312      * Create CMCEKey.
313      *
314      * @param pSpec the CMCE Spec
315      * @return the KeySpec
316      */
317     default GordianKeyPairSpec cmce(final GordianCMCESpec pSpec) {
318         return withKeyPairType(GordianKeyPairType.CMCE).withEnumSubSpec(pSpec).build();
319     }
320 
321     /**
322      * Create FRODOKey.
323      *
324      * @param pSpec the FRODO Spec
325      * @return the KeySpec
326      */
327     default GordianKeyPairSpec frodo(final GordianFRODOSpec pSpec) {
328         return withKeyPairType(GordianKeyPairType.FRODO).withEnumSubSpec(pSpec).build();
329     }
330 
331     /**
332      * Create SABERKey.
333      *
334      * @param pSpec the SABER Spec
335      * @return the KeySpec
336      */
337     default GordianKeyPairSpec saber(final GordianSABERSpec pSpec) {
338         return withKeyPairType(GordianKeyPairType.SABER).withEnumSubSpec(pSpec).build();
339     }
340 
341     /**
342      * Create MLKEMKey.
343      *
344      * @param pSpec the MLKEM Spec
345      * @return the KeySpec
346      */
347     default GordianKeyPairSpec mlkem(final GordianMLKEMSpec pSpec) {
348         return withKeyPairType(GordianKeyPairType.MLKEM).withEnumSubSpec(pSpec).build();
349     }
350 
351     /**
352      * Create MLDSAKey.
353      *
354      * @param pSpec the MLDSA Spec
355      * @return the KeySpec
356      */
357     default GordianKeyPairSpec mldsa(final GordianMLDSASpec pSpec) {
358         return withKeyPairType(GordianKeyPairType.MLDSA).withEnumSubSpec(pSpec).build();
359     }
360 
361     /**
362      * Create HQCKey.
363      *
364      * @param pSpec the HQC Spec
365      * @return the KeySpec
366      */
367     default GordianKeyPairSpec hqc(final GordianHQCSpec pSpec) {
368         return withKeyPairType(GordianKeyPairType.HQC).withEnumSubSpec(pSpec).build();
369     }
370 
371     /**
372      * Create BIKEKey.
373      *
374      * @param pSpec the BIKE Spec
375      * @return the KeySpec
376      */
377     default GordianKeyPairSpec bike(final GordianBIKESpec pSpec) {
378         return withKeyPairType(GordianKeyPairType.BIKE).withEnumSubSpec(pSpec).build();
379     }
380 
381     /**
382      * Create NTRUKey.
383      *
384      * @param pSpec the NTRU Spec
385      * @return the KeySpec
386      */
387     default GordianKeyPairSpec ntru(final GordianNTRUSpec pSpec) {
388         return withKeyPairType(GordianKeyPairType.NTRU).withEnumSubSpec(pSpec).build();
389     }
390 
391     /**
392      * Create NTRUPlusKey.
393      *
394      * @param pSpec the NTRUPlus Spec
395      * @return the KeySpec
396      */
397     default GordianKeyPairSpec ntruPlus(final GordianNTRUPlusSpec pSpec) {
398         return withKeyPairType(GordianKeyPairType.NTRUPLUS).withEnumSubSpec(pSpec).build();
399     }
400 
401     /**
402      * Create NTRUPRIMEKey.
403      *
404      * @param pType   the Type
405      * @param pParams the params
406      * @return the KeySpec
407      */
408     default GordianKeyPairSpec ntruprime(final GordianNTRUPrimeType pType,
409                                          final GordianNTRUPrimeParams pParams) {
410         return withKeyPairType(GordianKeyPairType.NTRUPRIME).withNTRUPrimeSubSpec(pType, pParams).build();
411     }
412 
413     /**
414      * Create FalconKey.
415      *
416      * @param pSpec the FALCON Spec
417      * @return the KeySpec
418      */
419     default GordianKeyPairSpec falcon(final GordianFalconSpec pSpec) {
420         return withKeyPairType(GordianKeyPairType.FALCON).withEnumSubSpec(pSpec).build();
421     }
422 
423     /**
424      * Create PicnicKey.
425      *
426      * @param pSpec the Picnic Spec
427      * @return the KeySpec
428      */
429     default GordianKeyPairSpec picnic(final GordianPicnicSpec pSpec) {
430         return withKeyPairType(GordianKeyPairType.PICNIC).withEnumSubSpec(pSpec).build();
431     }
432 
433     /**
434      * Create MayoKey.
435      *
436      * @param pSpec the Mayo Spec
437      * @return the KeySpec
438      */
439     default GordianKeyPairSpec mayo(final GordianMayoSpec pSpec) {
440         return withKeyPairType(GordianKeyPairType.MAYO).withEnumSubSpec(pSpec).build();
441     }
442 
443     /**
444      * Create SnovaKey.
445      *
446      * @param pSpec the Snova Spec
447      * @return the KeySpec
448      */
449     default GordianKeyPairSpec snova(final GordianSnovaSpec pSpec) {
450         return withKeyPairType(GordianKeyPairType.SNOVA).withEnumSubSpec(pSpec).build();
451     }
452 
453     /**
454      * Create CompositeKey.
455      *
456      * @param pSpecs the list of keySpecs
457      * @return the KeySpec
458      */
459     default GordianKeyPairSpec composite(final GordianKeyPairSpec... pSpecs) {
460         return composite(Arrays.asList(pSpecs));
461     }
462 
463     /**
464      * Create CompositeKey.
465      *
466      * @param pSpecs the list of keySpecs
467      * @return the KeySpec
468      */
469     default GordianKeyPairSpec composite(final List<GordianKeyPairSpec> pSpecs) {
470         return withKeyPairType(GordianKeyPairType.COMPOSITE).withKeyPairSpecs(pSpecs).build();
471     }
472 }