Skip to content

Commit eba52d9

Browse files
jdahmubedjdahmubed
committed
Added comments for javadocs
1 parent 7418d98 commit eba52d9

6 files changed

Lines changed: 387 additions & 10 deletions

File tree

‎lib/src/main/java/com/auth0/jwt/oicmsg/ECKey.java‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,19 @@
1212
import org.slf4j.Logger;
1313
import org.slf4j.LoggerFactory;
1414

15+
/**
16+
* JSON Web key representation of a Elliptic curve key.
17+
According to RFC 7517 a JWK representation of a EC key can look like
18+
this::
19+
{"kty":"EC",
20+
"crv":"P-256",
21+
"x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
22+
"y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
23+
"d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE"
24+
}
25+
26+
Parameters according to https://tools.ietf.org/html/rfc7518#section-6.2
27+
*/
1528
public class ECKey extends Key {
1629

1730
private String crv;
@@ -20,6 +33,7 @@ public class ECKey extends Key {
2033
private Object d;
2134
private Object curve;
2235
final private static Logger logger = LoggerFactory.getLogger(ECKey.class);
36+
//The elliptic curve specific attributes
2337
private static Set<String> longs = new HashSet<String>(Arrays.asList("x", "y", "d"));
2438
protected static Set<String> members = new HashSet<>(Arrays.asList("kty", "alg", "use", "kid", "crv", "x", "y", "d"));
2539
public static Set<String> publicMembers = new HashSet<>(Arrays.asList("kty", "alg", "use", "kid", "crv", "x", "y"));
@@ -50,6 +64,27 @@ public ECKey() {
5064
this("EC", "", "", "", null, "", null, null, null, null, null);
5165
}
5266

67+
/**
68+
* Starting with information gathered from the on-the-wire representation
69+
of an elliptic curve key (a JWK) initiate an
70+
cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey
71+
or EllipticCurvePrivateKey instance. So we have to get from having::
72+
{
73+
"kty":"EC",
74+
"crv":"P-256",
75+
"x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
76+
"y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
77+
"d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE"
78+
}
79+
to having a key that can be used for signing/verifying and/or
80+
encrypting/decrypting.
81+
If 'd' has value then we're dealing with a private key otherwise
82+
a public key. 'x' and 'y' must have values.
83+
If this.key has a value beforehand this will overwrite whatever
84+
was there to begin with.
85+
86+
x, y and d (if present) must be strings or bytes.
87+
*/
5388
public void deserialize() {
5489
try {
5590
if (!(this.x instanceof Number)) {
@@ -88,6 +123,14 @@ public List<Object> getKey(boolean isPrivate) {
88123
}
89124
}
90125

126+
/**
127+
* Go from a
128+
cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
129+
or EllipticCurvePublicKey instance to a JWK representation.
130+
* @param isPrivate: Whether we should include the private parts or not.
131+
* @return A JWK as a hashmap
132+
* @throws SerializationNotPossible
133+
*/
91134
public Object serialize(boolean isPrivate) throws SerializationNotPossible {
92135
if (this.crv == null && this.curve == null) {
93136
throw new SerializationNotPossible();
@@ -105,6 +148,11 @@ public Object serialize(boolean isPrivate) throws SerializationNotPossible {
105148
return args;
106149
}
107150

151+
/**
152+
* Load an Elliptic curve key
153+
* @param key: An elliptic curve key instance
154+
* @return
155+
*/
108156
public ECKey loadKey(Key key) {
109157
this.curve = key;
110158
//how to return multiple objects in Java?
@@ -116,6 +164,7 @@ public List<Object> getDecryptionKey() {
116164
}
117165

118166
public List<Object> getEncryptionKey(boolean isPrivate) {
167+
//both for encryption and decryption.
119168
return this.getKey(isPrivate);
120169
}
121170

‎lib/src/main/java/com/auth0/jwt/oicmsg/Key.java‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
package com.auth0.jwt.oicmsg;
22

3-
import com.auth0.jwt.exceptions.oicmsg_exceptions.HeaderError;
43
import com.google.common.base.Strings;
5-
import com.google.common.primitives.Bytes;
64
import com.google.gson.Gson;
75
import java.util.ArrayList;
86
import java.util.Arrays;
@@ -12,11 +10,16 @@
1210
import java.util.List;
1311
import java.util.Map;
1412
import java.util.Set;
15-
import org.bouncycastle.util.encoders.Base64;
1613
import org.junit.Assert;
1714
import org.slf4j.Logger;
1815
import org.slf4j.LoggerFactory;
1916

17+
/**
18+
* Basic JSON Web key class. Jason Web keys are described in
19+
RFC 7517 (https://tools.ietf.org/html/rfc7517).
20+
The name of parameters used in this class are the same as
21+
specified in RFC 7518 (https://tools.ietf.org/html/rfc7518).
22+
*/
2023
public class Key {
2124

2225
final private static Logger logger = LoggerFactory.getLogger(Key.class);
@@ -120,6 +123,12 @@ public long getInactiveSince() {
120123
return inactiveSince;
121124
}
122125

126+
/**
127+
* A wrapper for to_dict that makes sure that all the private information
128+
as well as extra arguments are included. This method should *not* be
129+
used for exporting information about the key.
130+
* @return
131+
*/
123132
public Map<String, String> toDict() {
124133
Map<String, String> hmap = serialize();
125134
for (String key : args.keySet()) {
@@ -134,6 +143,10 @@ public Key serialize() {
134143
//TODO
135144
}
136145

146+
/**
147+
* Return the set of parameters that are common to all types of keys.
148+
* @return: hashmap
149+
*/
137150
public Map<String, String> common() {
138151
Map<String, String> args = new HashMap<>();
139152
args.put("kty", this.kty);
@@ -154,6 +167,13 @@ public String toString() {
154167
return this.toDict().toString();
155168
}
156169

170+
/**
171+
* Verify that the information gathered from the on-the-wire
172+
representation is of the right type.
173+
This is supposed to run before the info is deserialized.
174+
* @return
175+
* @throws HeaderError
176+
*/
157177
public boolean verify() throws HeaderError {
158178
Object item = null;
159179
for (String key : longs.keySet()) {
@@ -200,6 +220,11 @@ private void base64URLToLong(Object item) {
200220

201221
}
202222

223+
/**
224+
* Compare 2 Key instances to find out if they represent the same key
225+
* @param other: The other Key instance
226+
* @return True if they are the same otherwise False.
227+
*/
203228
@Override
204229
public boolean equals(Object other) {
205230
try {
@@ -223,6 +248,16 @@ public List<String> getKeys() {
223248
return new ArrayList<>(this.toDict().keySet());
224249
}
225250

251+
/**
252+
* Create a thumbprint of the key following the outline in
253+
https://tools.ietf.org/html/draft-jones-jose-jwk-thumbprint-01
254+
* @param hashFunction: A hash function to use for hashing the
255+
information
256+
* @param members: Which attributes of the Key instance should
257+
be included when computing the hash value.
258+
* @return A base64 encode hash over a set of Key attributes
259+
* @throws NoSuchFieldException
260+
*/
226261
public byte[] thumbprint(String hashFunction, List<String> members) throws NoSuchFieldException {
227262
if (members == null || members.isEmpty()) {
228263
members = required;
@@ -260,6 +295,10 @@ public byte[] thumbprint(String hashFunction) {
260295
thumbprint(hashFunction, null);
261296
}
262297

298+
/**
299+
* Construct a Key ID using the thumbprint method and add it to
300+
the key attributes.
301+
*/
263302
public void addKid() {
264303
this.kid = new String(Base64.encode(this.thumbprint("SHA-256")));
265304
}

0 commit comments

Comments
 (0)