└── README.md


/README.md:
--------------------------------------------------------------------------------
 1 | # Specification for integrating CFRG algorithms in Java/JCE
 2 | This specification proposal is based on the following IETF RFCs and Drafts:
 3 | - https://tools.ietf.org/html/rfc7748
 4 | - https://tools.ietf.org/html/rfc8032
 5 | - https://tools.ietf.org/html/draft-ietf-curdle-pkix-04
 6 | - https://tools.ietf.org/html/draft-ietf-cose-msg-24
 7 | - https://tools.ietf.org/html/rfc8037
 8 | 
 9 | The core issue is if CFRG algorithms should reuse the current EC classes or not.  *This specification is based
10 | on the idea that the CFRG algorithms differ too much from EC to be conveniently
11 | and logically mapped into the current EC classes and interfaces.*
12 | 
13 | Rationale: None of the existing external representations of CFRG keys specify parameters like `ECPoint`, `coFactor`, or `ECField`.
14 | The PKIX draft does not reuse the ASN.1 EC definitions for named curves either.
15 | 
16 | Although probably not applicable to the existing CFRG algorithms, RFC 8037 states: *Do not assume that there is an underlying elliptic curve,
17 |    despite the existence of the "crv" and "x" parameters.  (For
18 |    instance, this key type could be extended to represent Diffie-Hellman
19 |    (DH) algorithms based on hyperelliptic surfaces.)*
20 | 
21 | Note: If provider implementations *internally* reuse EC structures is something else which does not have to exposed in "application-level" APIs.
22 | 
23 | The remaining question would then be what to call this new key type.
24 | Since both RFC 8037 and the COSE draft use the name "OKP" (Octet Key Pair), it seems reasonable adopting this name here as well.
25 | 
26 | Below is a very condensed version of the propoposal:
27 | 
28 | ```java
29 | public interface OPKKey {
30 |     public String getCurve();                // Algorithm | RFC 8037 "crv"
31 | 
32 |     public int USAGE_SIGNATURE = 1;          // For usage with "isPermitted()"
33 |     public int USAGE_DH = 2;                 // For usage with "isPermitted()"
34 |     public boolean isPermitted(int usages);  // According to specs a key is either Signature or DH
35 | }
36 | ```
37 | 
38 | ```java
39 | public interface OKPPublicKey extends PublicKey, OKPKey {
40 |     public byte[] getX();  // Public key value | RFC 8037 "x"
41 | }
42 | ```
43 | 
44 | ```java
45 | public interface OKPPrivateKey extends PrivateKey, OKPKey {
46 |     public byte[] getD();  // Private key value | RFC 8037 "d"
47 | }
48 | ```
49 | 
50 | ```java
51 | String curve;  // Algorithm name
52 | byte[] x;      // Public key value
53 | byte[] d;      // Private key value
54 | ```
55 | 
56 | ```java
57 | KeyFactory.getInstance("OKP").generatePrivate(new OKPPrivateKeySpec(d, curve));
58 | ```
59 | 
60 | ```java
61 | KeyFactory.getInstance("OKP").generatePublic(new OKPPublicKeySpec(x, curve));
62 | ```
63 | 
64 | ```java
65 | AlgorithmParameterSpec keySpec = new OKPGenParameterSpec(curve);
66 | KeyPairGenerator kpg = KeyPairGenerator.getInstance("OKP");
67 | kpg.initialize(keySpec);
68 | ```
69 | 
70 | ```java
71 | PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(pkcs8PrivateKeyBlob);
72 | KeyFactory.getInstance("OKP").generatePrivate(keySpec);
73 | ```
74 | 
75 | ```java
76 | Signature signature = Signature.getInstance("EdDSA");
77 | ```
78 | 
79 | The only place where it sort of breaks down is `KeyAgreement`, I would play it safe by inventing new name:
80 | `KeyAgreement.getInstance("MoDH")` 
81 | to not run into possible conflicts (_crashes_) with existing code and providers.  The additional test required to cope with "ECDH" and "MoDH" (for _Montgomery_ in analogy with _Edwards_) seems bearable:
82 | ```java
83 | KeyAgreement.getInstance(publicKey instanceof ECKey ? "ECDH" : "MoDH");
84 | ```
85 | 
86 |  The CFRG key algorithm/curve identifiers include:
87 |   ```
88 |   X25519
89 |   X448
90 |   Ed25519
91 |   Ed448
92 | ```
93 | <table>
94 | <tr><td><i>It would IMO be a pity if Oracle, Bouncycastle, and Google(Android) took different routes for CFRG support</i></td></tr>
95 | </table>
96 | 
97 | ## PKCS \#11 and .NET
98 | Ideally other cryptographic APIs should also adopt OKP keys.
99 | 


--------------------------------------------------------------------------------