GJWT
diff --git a/‎lib/src/main/java/com/auth0/jwt/oicmsg/ECKey.java‎
Lines changed: 49 additions & 0 deletions b/‎lib/src/main/java/com/auth0/jwt/oicmsg/ECKey.java‎
Lines changed: 49 additions & 0 deletions
diff --git a/‎lib/src/main/java/com/auth0/jwt/oicmsg/Key.java‎
Lines changed: 42 additions & 3 deletions b/‎lib/src/main/java/com/auth0/jwt/oicmsg/Key.java‎
Lines changed: 42 additions & 3 deletions
@@ -12,6 +12,19 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ *     JSON Web key representation of a Elliptic curve key.
+ According to RFC 7517 a JWK representation of a EC key can look like
+ this::
+ {"kty":"EC",
+ "crv":"P-256",
+ "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
+ "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
+ "d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE"
+ }
+
+ Parameters according to https://tools.ietf.org/html/rfc7518#section-6.2
+ */
 public class ECKey extends Key {
 
     private String crv;
@@ -20,6 +33,7 @@ public class ECKey extends Key {
     private Object d;
     private Object curve;
     final private static Logger logger = LoggerFactory.getLogger(ECKey.class);
+    //The elliptic curve specific attributes
     private static Set<String> longs = new HashSet<String>(Arrays.asList("x", "y", "d"));
     protected static Set<String> members = new HashSet<>(Arrays.asList("kty", "alg", "use", "kid", "crv", "x", "y", "d"));
     public static Set<String> publicMembers = new HashSet<>(Arrays.asList("kty", "alg", "use", "kid", "crv", "x", "y"));
@@ -50,6 +64,27 @@ public ECKey() {
         this("EC", "", "", "", null, "", null, null, null, null, null);
     }
 
+    /**
+     *   Starting with information gathered from the on-the-wire representation
+         of an elliptic curve key (a JWK) initiate an
+         cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey
+         or EllipticCurvePrivateKey instance. So we have to get from having::
+         {
+         "kty":"EC",
+         "crv":"P-256",
+         "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
+         "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
+         "d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE"
+         }
+         to having a key that can be used for signing/verifying and/or
+         encrypting/decrypting.
+         If 'd' has value then we're dealing with a private key otherwise
+         a public key. 'x' and 'y' must have values.
+         If this.key has a value beforehand this will overwrite whatever
+         was there to begin with.
+
+         x, y and d (if present) must be strings or bytes.
+     */
     public void deserialize() {
         try {
             if (!(this.x instanceof Number)) {
@@ -88,6 +123,14 @@ public List<Object> getKey(boolean isPrivate) {
         }
     }
 
+    /**
+     * Go from a
+       cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
+       or EllipticCurvePublicKey instance to a JWK representation.
+     * @param isPrivate: Whether we should include the private parts or not.
+     * @return A JWK as a hashmap
+     * @throws SerializationNotPossible
+     */
     public Object serialize(boolean isPrivate) throws SerializationNotPossible {
         if (this.crv == null && this.curve == null) {
             throw new SerializationNotPossible();
@@ -105,6 +148,11 @@ public Object serialize(boolean isPrivate) throws SerializationNotPossible {
         return args;
     }
 
+    /**
+     * Load an Elliptic curve key
+     * @param key: An elliptic curve key instance
+     * @return
+     */
     public ECKey loadKey(Key key) {
         this.curve = key;
         //how to return multiple objects in Java?
@@ -116,6 +164,7 @@ public List<Object> getDecryptionKey() {
     }
 
     public List<Object> getEncryptionKey(boolean isPrivate) {
+        //both for encryption and decryption.
         return this.getKey(isPrivate);
     }
 
 
@@ -1,8 +1,6 @@
 package com.auth0.jwt.oicmsg;
 
-import com.auth0.jwt.exceptions.oicmsg_exceptions.HeaderError;
 import com.google.common.base.Strings;
-import com.google.common.primitives.Bytes;
 import com.google.gson.Gson;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -12,11 +10,16 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
-import org.bouncycastle.util.encoders.Base64;
 import org.junit.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ *     Basic JSON Web key class. Jason Web keys are described in
+ RFC 7517 (https://tools.ietf.org/html/rfc7517).
+ The name of parameters used in this class are the same as
+ specified in RFC 7518 (https://tools.ietf.org/html/rfc7518).
+ */
 public class Key {
 
     final private static Logger logger = LoggerFactory.getLogger(Key.class);
@@ -120,6 +123,12 @@ public long getInactiveSince() {
         return inactiveSince;
     }
 
+    /**
+     * A wrapper for to_dict that makes sure that all the private information
+     as well as extra arguments are included. This method should *not* be
+     used for exporting information about the key.
+     * @return
+     */
     public Map<String, String> toDict() {
         Map<String, String> hmap = serialize();
         for (String key : args.keySet()) {
@@ -134,6 +143,10 @@ public Key serialize() {
         //TODO
     }
 
+    /**
+     * Return the set of parameters that are common to all types of keys.
+     * @return: hashmap
+     */
     public Map<String, String> common() {
         Map<String, String> args = new HashMap<>();
         args.put("kty", this.kty);
@@ -154,6 +167,13 @@ public String toString() {
         return this.toDict().toString();
     }
 
+    /**
+     * Verify that the information gathered from the on-the-wire
+     representation is of the right type.
+     This is supposed to run before the info is deserialized.
+     * @return
+     * @throws HeaderError
+     */
     public boolean verify() throws HeaderError {
         Object item = null;
         for (String key : longs.keySet()) {
@@ -200,6 +220,11 @@ private void base64URLToLong(Object item) {
 
     }
 
+    /**
+     * Compare 2 Key instances to find out if they represent the same key
+     * @param other: The other Key instance
+     * @return True if they are the same otherwise False.
+     */
     @Override
     public boolean equals(Object other) {
         try {
@@ -223,6 +248,16 @@ public List<String> getKeys() {
         return new ArrayList<>(this.toDict().keySet());
     }
 
+    /**
+     * Create a thumbprint of the key following the outline in
+     https://tools.ietf.org/html/draft-jones-jose-jwk-thumbprint-01
+     * @param hashFunction: A hash function to use for hashing the
+                            information
+     * @param members: Which attributes of the Key instance should
+                        be included when computing the hash value.
+     * @return A base64 encode hash over a set of Key attributes
+     * @throws NoSuchFieldException
+     */
     public byte[] thumbprint(String hashFunction, List<String> members) throws NoSuchFieldException {
         if (members == null || members.isEmpty()) {
             members = required;
@@ -260,6 +295,10 @@ public byte[] thumbprint(String hashFunction) {
         thumbprint(hashFunction, null);
     }
 
+    /**
+     *  Construct a Key ID using the thumbprint method and add it to
+        the key attributes.
+     */
     public void addKid() {
         this.kid = new String(Base64.encode(this.thumbprint("SHA-256")));
     }