java.lang.Object

com.authlete.sd.SDObjectEncoder

public class SDObjectEncoder extends Object

A utility to make elements in a map or a list selectively-disclosable recursively.

Decoy digests are automatically added unless decoy magnification ratio is set to 0.0 through constructors or the setDecoyMagnification(double, double) method.

Some claims such as "iss" and "iat" are retained without being made selectively-disclosable. See the description of the getRetainedClaims() method for details.

 // Original dataset
 //
 //   {
 //     "key-1": "value-1",
 //     "key-2": [
 //       "element-1",
 //       "element-2"
 //     ],
 //     "key-3": {
 //       "sub-key-1": "sub-value-1",
 //       "sub-key-2": "sub-value-2",
 //     },
 //   }
 //
 
 List<String> sublist = List.of(
         "element-1",
         "element-2"
 );

 Map<String, String> submap = Map.of(
         "sub-key-1", "sub-value-1",
         "sub-key-2", "sub-value-2"
 );

 Map<String, Object> originalMap = Map.of(
         "key-1", "value-1",
         "key-2", sublist,
         "key-3", submap
 );

 // Encoder
 SDObjectEncoder encoder = new SDObjectEncoder();

 // Encode
 Map<String, Object> encodedMap = encoder.encode(originalMap);

 // Disclosures yielded as a result of the encoding process.
 List<Disclosure> disclosures = encoder.getDisclosures();

 // Encoded dataset
 //
 //   {
 //     "key-2": [
 //       { "...": "Z_JV6E3FColTFBqUrvfa366V27BFy8cf8fa59NQdavg" },
 //       { "...": "p-vA6nPBgbL-Zgzd5MkVV7RrFPvMCV_f0N9p3CKOLVo" },
 //       { "...": "NVpowlkRQq9aC8aJAS3tz7Gzs3PolUJ7bZLYZiUg5pw" },
 //       { "...": "TfdBAy9CRDAhoyB2O3tcGUWOKnfSzQ1wKDTwJQyuFVU" },
 //       { "...": "Ujg9QqkNQ0tKN_DiPoCQOmHAWGThokrjA5ceve6Xxik" }
 //     ],
 //     "key-3": {
 //       "_sd": [
 //         "JVWbh08VUtBXLWOH16OgPMFZu7qGmKIc7Gt0dxwJin0",
 //         "YJ_T7R1qZsfdDIKoHFQ1ubOToI-DHZHBvZwBU6S1svE",
 //         "Z14X_kICU8SpDGpfDQ2mP1LfWAMtdPPRPJ_434cdKe4",
 //         "r67vz8Rq22eoCw_D-xDVa1bRucngVuRAExSQvWdbrXo"
 //       ]
 //     },
 //     "_sd": [
 //       "--3D5V1QiCzfs7gt4hxlaiFh02bBcUKH6VKCxAcPuGk",
 //       "ON2rSnqtfmLcJTrKKP5_l6swD3AkMbcmjb80hge2eMs",
 //       "wf2OtpIlIqG58GfXN6-jiDX-k1Wt4eJX-nPWbTdfonM"
 //     ],
 //     "_sd_alg": "sha-256"
 //   }
 //
 // Disclosures
 //
 //   | digest                                      | claim name | claim value  |
 //   |---------------------------------------------|------------|--------------|
 //   | ON2rSnqtfmLcJTrKKP5_l6swD3AkMbcmjb80hge2eMs | key-1      | value-1      |
 //   | NVpowlkRQq9aC8aJAS3tz7Gzs3PolUJ7bZLYZiUg5pw | (null)     | element-1    |
 //   | TfdBAy9CRDAhoyB2O3tcGUWOKnfSzQ1wKDTwJQyuFVU | (null)     | element-2    |
 //   | r67vz8Rq22eoCw_D-xDVa1bRucngVuRAExSQvWdbrXo | sub-key-1  | sub-value-1  |
 //   | Z14X_kICU8SpDGpfDQ2mP1LfWAMtdPPRPJ_434cdKe4 | sub-key-2  | sub-value-2  |
 //

Since:: 1.3

Constructor Summary

Constructors

Constructor

Description

SDObjectEncoder()

The default constructor with the default hash algorithm ("sha-256") and the default decoy magnification ratio (min = 0.5, max = 1.5).

SDObjectEncoder(double decoyMagnificationMin, double decoyMagnificationMax)

A constructor with the default hash algorithm ("sha-256") and the specified decoy magnification ratio.

SDObjectEncoder(String hashAlgorithm)

A constructor with the specified hash algorithm and the default decoy magnification ratio (min = 0.5, max = 1.5).

SDObjectEncoder(String hashAlgorithm, double decoyMagnificationMin, double decoyMagnificationMax)

A constructor with the specified hash algorithm and decoy magnification ratio.
Method Summary

Modifier and Type

Method

Description

List<Object>

encode(List<?> input)

Encode the content of the given list.

Map<String,Object>

encode(Map<String,Object> input)

Encode the content of the given map.

List<Disclosure>

getDisclosures()

Get the list of Disclosures yielded as a result of the encoding process.

String

getHashAlgorithm()

Get the hash algorithm for digests.

Set<String>

getRetainedClaims()

Get the set of claims that are retained without being made selectively-disclosable when they appear in the top-level map.

boolean

isHashAlgorithmIncluded()

Get the flag indicating whether the "_sd_alg" key (that denotes the hash algorithm for digests) will be included in the encoded map.

SDObjectEncoder

setDecoyMagnification(double min, double max)

Set the decoy magnification ratio.

SDObjectEncoder

setHashAlgorithm(String hashAlgorithm)

Set the hash algorithm for digests.

SDObjectEncoder

setHashAlgorithmIncluded(boolean included)

Set the flag indicating whether the "_sd_alg" key (that denotes the hash algorithm for digests) will be included in the encoded map.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- SDObjectEncoder
  
  public SDObjectEncoder()
  
  The default constructor with the default hash algorithm ("sha-256") and the default decoy magnification ratio (min = 0.5, max = 1.5).
- SDObjectEncoder
  
  public SDObjectEncoder(String hashAlgorithm)
  
  A constructor with the specified hash algorithm and the default decoy magnification ratio (min = 0.5, max = 1.5).
  
  Parameters:
  
  hashAlgorithm - The hash algorithm for digests. If null is given, the default hash algorithm ("sha-256") is used.
- SDObjectEncoder
  public SDObjectEncoder(double decoyMagnificationMin, double decoyMagnificationMax)
  
  A constructor with the default hash algorithm ("sha-256") and the specified decoy magnification ratio.
  The pair of the decoy magnification arguments specifies the range of decoy magnification ratio. The actual ratio is determined randomly between the range for each JSON object and JSON array. The number of inserted decoys is computed by multiplying the ratio to the size of the original JSON object or the length of the original JSON array.
  
  If 0.0 is set to both the decoy magnification arguments, no decoy is inserted.
  
  // Create an encoder that yields no decoy digests. SDObjectEncoder encoder = new SDObjectEncoder(0.0, 0.0);
  
  Parameters:
  
  decoyMagnificationMin - The minimum decoy magnification ratio. If a negative value is given, 0.0 is used instead. If a value greater than 10.0 is given, 10.0 is used instead.
  
  decoyMagnificationMax - The maximum decoy magnification ratio. If a negative value is given, 0.0 is used instead. If a value greater than 10.0 is given, 10.0 is used instead.
- SDObjectEncoder
  public SDObjectEncoder(String hashAlgorithm, double decoyMagnificationMin, double decoyMagnificationMax)
  
  A constructor with the specified hash algorithm and decoy magnification ratio.
  The pair of the decoy magnification arguments specifies the range of decoy magnification ratio. The actual ratio is determined randomly between the range for each JSON object and JSON array. The number of inserted decoys is computed by multiplying the ratio to the size of the original JSON object or the length of the original JSON array.
  
  If 0.0 is set to both the decoy magnification arguments, no decoy is inserted.
  
  // Create an encoder that yields no decoy digests. SDObjectEncoder encoder = new SDObjectEncoder(null, 0.0, 0.0);
  
  Parameters:
  
  hashAlgorithm - The hash algorithm for digests. If null is given, the default hash algorithm ("sha-256") is used.
  
  decoyMagnificationMin - The minimum decoy magnification ratio. If a negative value is given, 0.0 is used instead. If a value greater than 10.0 is given, 10.0 is used instead.
  
  decoyMagnificationMax - The maximum decoy magnification ratio. If a negative value is given, 0.0 is used instead. If a value greater than 10.0 is given, 10.0 is used instead.
Method Details
- getHashAlgorithm
  
  public String getHashAlgorithm()
  
  Get the hash algorithm for digests.
  
  Returns:
  
  The hash algorithm.
- setHashAlgorithm
  
  public SDObjectEncoder setHashAlgorithm(String hashAlgorithm)
  
  Set the hash algorithm for digests.
  
  Parameters:
  
  hashAlgorithm - The hash algorithm. If null is given, the default hash algorithm ("sha-256") is used.
  
  Returns:
  
  this object.
- setDecoyMagnification
  public SDObjectEncoder setDecoyMagnification(double min, double max)
  
  Set the decoy magnification ratio.
  The pair of the arguments specifies the range of decoy magnification ratio. The actual ratio is determined randomly between the range for each JSON object and SON array. The number of inserted decoys is computed by multiplying the ratio to the size of the original JSON object or the length of the original JSON array.
  
  If 0.0 is set to both the arguments, no decoy is inserted.
  
  // Yield no decoy digests. encoder.setDecoyMagnification(0.0, 0.0);
  
  Parameters:
  
  min - The minimum decoy magnification ratio. If a negative value is given, 0.0 is used instead. If a value greater than 10.0 is given, 10.0 is used instead.
  
  max - The maximum decoy magnification ratio. If a negative value is given, 0.0 is used instead. If a value greater than 10.0 is given, 10.0 is used instead.
  
  Returns:
  
  this object.
- isHashAlgorithmIncluded
  
  public boolean isHashAlgorithmIncluded()
  
  Get the flag indicating whether the "_sd_alg" key (that denotes the hash algorithm for digests) will be included in the encoded map.
  
  Returns:
  
  true if the "_sd_alg" key will be included in the encoded map.
- setHashAlgorithmIncluded
  
  public SDObjectEncoder setHashAlgorithmIncluded(boolean included)
  
  Set the flag indicating whether the "_sd_alg" key (that denotes the hash algorithm for digests) will be included in the encoded map.
  
  Parameters:
  
  included - true to include the "_sd_alg" key in the encoded map. false not to include the key.
  
  Returns:
  
  this object.
- getRetainedClaims
  public Set<String> getRetainedClaims()
  
  Get the set of claims that are retained without being made selectively-disclosable when they appear in the top-level map.
  By default, the following claims are registered as ones to retain.
  
  iss
  iat
  nbf
  exp
  cnf
  vct
  status
  
  By modifying the Set object returned from this method, the behavior of this encoder can be changed. For instance, the example below makes the encoder retain the "sub" claim.
  
  encoder.getRetainedClaims().add("sub");
  
  Returns:
  
  The set of claims to retain.
- getDisclosures
  
  public List<Disclosure> getDisclosures()
  
  Get the list of Disclosures yielded as a result of the encoding process.
  On every call of either the encode(Map) method or the encode(List) method, the disclosure list is reset. The "reset" here means that a new List instance is created and assigned, and the previous one (if any) is detached.
  
  Returns:
  
  The list of Disclosures.
- encode
  
  public Map<String,Object> encode(Map<String,Object> input)
  
  Encode the content of the given map.
  On the entry of this method, the disclosure list returned from the getDisclosures() method is reset. The "reset" here means that a new List instance is created and assigned, and the previous one (if any) is detached.
  
  Some claims such as "iss" and "iat" are retained without being made selectively-disclosable when they appear in the top-level map. See the description of the getRetainedClaims() method for details.
  
  The encoded map will contain the "_sd_alg" key that denotes the hash algorithm for digests. If the key should not be included, call setHashAlgorithmIncluded(false) before calling this method.
  
  Parameters:
  
  input - The input map. If null is given, null is returned.
  
  Returns:
  
  The encoded map.
- encode
  
  public List<Object> encode(List<?> input)
  
  Encode the content of the given list.
  On the entry of this method, the disclosure list returned from the getDisclosures() method is reset. The "reset" here means that a new List instance is created and assigned, and the previous one (if any) is detached.
  
  Parameters:
  
  input - The input list. If null is given, null is returned.
  
  Returns:
  
  The encoded list.

Class SDObjectEncoder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

SDObjectEncoder

SDObjectEncoder

SDObjectEncoder

SDObjectEncoder

Method Details

getHashAlgorithm

setHashAlgorithm

setDecoyMagnification

isHashAlgorithmIncluded

setHashAlgorithmIncluded

getRetainedClaims

getDisclosures

encode

encode