net.i2p.data

## Class LeaseSet2

- java.lang.Object
- - net.i2p.data.DataStructureImpl
  - - net.i2p.data.DatabaseEntry
    - - net.i2p.data.LeaseSet
      - - net.i2p.data.LeaseSet2

- All Implemented Interfaces:
    Serializable, DataStructure
  Direct Known Subclasses:
    EncryptedLeaseSet, MetaLeaseSet

      public class LeaseSet2
      extends LeaseSet

  Implementation of LeaseSet2 as specified in Proposal 123: New NetDb Entries.

  LeaseSet2 provides several enhancements over the original LeaseSet format:

  - Support for multiple encryption keys with server preference ordering
  - Offline signature support for reduced router load
  - Published and expiration timestamps independent of lease times
  - Options and statistics support
  - Blinded and encrypted LeaseSet support

  Key differences from LeaseSet:

  - Uses `getPublished()` for version comparison instead of lease dates
  - Supports multiple encryption keys via `getEncryptionKeys()`
  - Includes offline signing capabilities via `setOfflineSignature(long, SigningPublicKey, Signature)`
  - Has separate published and expires timestamps
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `_expires`
    `protected int` | `_flags`
    `protected Signature` | `_offlineSignature`
    `protected Properties` | `_options`
    `protected long` | `_published`
    `protected long` | `_transientExpires`
    `protected SigningPublicKey` | `_transientSigningPublicKey`

    - ### Fields inherited from class net.i2p.data.LeaseSet

      `_byteified, _checked, _destination, _encryptionKey, _lastExpiration, _leases, _signingKey, MAX_LEASES`

    - ### Fields inherited from class net.i2p.data.DatabaseEntry

      `_signature, KEY_TYPE_ENCRYPTED_LS2, KEY_TYPE_LEASESET, KEY_TYPE_LS2, KEY_TYPE_META_LS2, KEY_TYPE_ROUTERINFO, KEY_TYPE_SERVICE_LIST, KEY_TYPE_SERVICE_RECORD`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LeaseSet2()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addEncryptionKey(PublicKey key)` Add an encryption key.
    `void` | `addLease(Lease lease)` Adds a lease to this leaseset.
    `void` | `encrypt(SessionKey key)` Encrypt the gateway and tunnel ID of each lease, leaving the expire dates unchanged.
    `boolean` | `equals(Object object)`
    `Hash` | `getBlindedHash()` The orignal blinded hash, where this came from.
    `protected byte[]` | `getBytes()` without sig!
    `PublicKey` | `getEncryptionKey()` If more than one key, return the first supported one.
    `PublicKey` | `getEncryptionKey(Set<EncType> supported)` If more than one key, return the first supported one.
    `List<PublicKey>` | `getEncryptionKeys()` This returns all the keys.
    `long` | `getExpires()` Published expiration, as received.
    `String` | `getOption(String opt)`
    `Properties` | `getOptions()` Gets the leaseset options.
    `long` | `getPublished()` Published timestamp, as received.
    `boolean` | `getReceivedAsPublished()` If true, we received this LeaseSet by a remote peer publishing it to us, AND the unpublished flag is not set.
    `long` | `getTransientExpiration()` Absolute time, not time from now.
    `SigningPublicKey` | `getTransientSigningKey()` Gets the transient public key for offline signing.
    `int` | `getType()` Get the type of the data structure.
    `int` | `hashCode()` the destination has enough randomness in it to use it by itself for speed
    `boolean` | `isBlindedWhenPublished()` Set if the unencrypted LS, when published, will be blinded/encrypted
    `boolean` | `isCurrent(long fudge)` Determine whether the leaseset is currently valid, at least within a given fudge factor.
    `boolean` | `isOffline()` Checks if this leaseset uses offline keys.
    `boolean` | `isUnpublished()`
    `static Signature` | `offlineSign(long expires, SigningPublicKey transientSPK, SigningPrivateKey priv)` Generate a Signature to pass to setOfflineSignature()
    `void` | `readBytes(InputStream in)` This does NOT validate the signature
    `protected void` | `readHeader(InputStream in)`
    `protected void` | `readOfflineBytes(InputStream in)`
    `void` | `setBlindedHash(Hash bh)` Set this on creation if known
    `void` | `setBlindedWhenPublished()` Set if the unencrypted LS, when published, will be blinded/encrypted
    `boolean` | `setOfflineSignature(long expires, SigningPublicKey transientSPK, Signature offlineSig)` Destination must be previously set.
    `void` | `setOptions(Properties options)` Configure a set of options or statistics that the router can expose.
    `void` | `setPublished(long now)` Set published timestamp.
    `void` | `setSigningKey(SigningPublicKey key)` The revocation key.
    `void` | `setUnpublished()` Marks this leaseset as unpublished.
    `void` | `sign(SigningPrivateKey key)` Sign the structure using the supplied signing key.
    `int` | `size()` Number of bytes, NOT including signature
    `String` | `toString()`
    `boolean` | `verifyOfflineSignature()`
    `protected boolean` | `verifyOfflineSignature(SigningPublicKey spk)`
    `boolean` | `verifySignature()` Verify with the SPK in the dest for online sigs.
    `protected void` | `writeBody(OutputStream out)` Without sig.
    `void` | `writeBytes(OutputStream out)` Including sig.
    `protected void` | `writeBytesWithoutSig(OutputStream out)` Without sig.
    `protected void` | `writeHeader(OutputStream out)`
    `protected void` | `writeOfflineBytes(OutputStream out)`

    - ### Methods inherited from class net.i2p.data.LeaseSet

      `getDate, getDestination, getEarliestLeaseDate, getKeysAndCert, getLatestLeaseDate, getLease, getLeaseCount, getSigningKey, setDestination, setEncryptionKey, setReceivedBy`

    - ### Methods inherited from class net.i2p.data.DatabaseEntry

      `getHash, getReceivedAsReply, getReceivedBy, getRoutingKey, getSignature, getSigningPublicKey, isLeaseSet, isLeaseSet, isRouterInfo, setReceivedAsPublished, setReceivedAsReply, setSignature, validateRoutingKey`

    - ### Methods inherited from class net.i2p.data.DataStructureImpl

      `calculateHash, fromBase64, fromByteArray, read, toBase64, toByteArray`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### _expires

          protected long _expires

    - #### _flags

          protected int _flags

    - #### _offlineSignature

          protected Signature _offlineSignature

    - #### _options

          protected Properties _options

    - #### _published

          protected long _published

    - #### _transientExpires

          protected long _transientExpires

    - #### _transientSigningPublicKey

          protected SigningPublicKey _transientSigningPublicKey

  - ### Constructor Detail

    - #### LeaseSet2

          public LeaseSet2()

  - ### Method Detail

    - #### addEncryptionKey

          public void addEncryptionKey(PublicKey key)

      Add an encryption key. Encryption keys should be added in order of server preference, most-preferred first.

    - #### addLease

          public void addLease(Lease lease)

      Description copied from class: `LeaseSet`
      Adds a lease to this leaseset.
      Overrides:
        `addLease` in class `LeaseSet`
      Parameters:
        `lease` - must be a Lease2
      Throws:
        `IllegalArgumentException` - if not a Lease2

    - #### encrypt

          public void encrypt(SessionKey key)

      Description copied from class: `LeaseSet`
      Encrypt the gateway and tunnel ID of each lease, leaving the expire dates unchanged. This adds an extra dummy lease, because AES data must be padded to 16 bytes. The fact that it is encrypted is not stored anywhere. Must be called after all the leases are in place, but before sign().
      Overrides:
        `encrypt` in class `LeaseSet`

    - #### equals

          public boolean equals(Object object)

      Overrides:
        `equals` in class `LeaseSet`

    - #### getBlindedHash

          public Hash getBlindedHash()

      The orignal blinded hash, where this came from.
      Returns:
        null if unknown or not previously blinded

    - #### getBytes

          protected byte[] getBytes()

      without sig!
      Overrides:
        `getBytes` in class `LeaseSet`
      Returns:
        the raw payload data, or null on error (for example, if this is a RouterInfo, a DataFormatException is thrown instead)

    - #### getEncryptionKey

          public PublicKey getEncryptionKey()

      If more than one key, return the first supported one. If none supported, return the first one.
      Overrides:
        `getEncryptionKey` in class `LeaseSet`

    - #### getEncryptionKey

          public PublicKey getEncryptionKey(Set<EncType> supported)

      If more than one key, return the first supported one. If none supported, return null.
      Overrides:
        `getEncryptionKey` in class `LeaseSet`
      Parameters:
        `supported` - what return types are allowed
      Returns:
        first supported key or null

    - #### getEncryptionKeys

          public List<PublicKey> getEncryptionKeys()

      This returns all the keys. getEncryptionKey() returns the first one. Encryption keys should be in order of server preference, most-preferred first. Client behavior should be to select the first key with a supported encryption type. Clients may use other selection algorithms based on encryption support, relative performance, and other factors.
      Returns:
        not a copy, do not modify, null if none

    - #### getExpires

          public long getExpires()

      Published expiration, as received. May be different than getLatestLeaseDate(), which is the latest lease expiration.
      Returns:
        in ms, with 1 second resolution

    - #### getOption

          public String getOption(String opt)

    - #### getOptions

          public Properties getOptions()

      Gets the leaseset options.
      Returns:
        not a copy, do not modify, or null

    - #### getPublished

          public long getPublished()

      Published timestamp, as received. Different than getDate() or getEarliestLeaseDate(), which are the earliest lease expiration. Use this for LS2 version comparison, NOT getEarliestLeaseDate(), because that will return -1 for EncryptedLS and MetaLS.
      Returns:
        in ms, with 1 second resolution

    - #### getReceivedAsPublished

          public boolean getReceivedAsPublished()

      If true, we received this LeaseSet by a remote peer publishing it to us, AND the unpublished flag is not set. Default false.
      Overrides:
        `getReceivedAsPublished` in class `DatabaseEntry`

    - #### getTransientExpiration

          public long getTransientExpiration()

      Absolute time, not time from now.
      Returns:
        transient expiration time or 0 if not offline signed

    - #### getTransientSigningKey

          public SigningPublicKey getTransientSigningKey()

      Gets the transient public key for offline signing.
      Returns:
        transient public key or null if not offline signed

    - #### getType

          public int getType()

      Description copied from class: `DatabaseEntry`
      Get the type of the data structure. This should be faster than instanceof.
      Overrides:
        `getType` in class `LeaseSet`
      Returns:
        KEY_TYPE_ROUTERINFO or KEY_TYPE_LEASESET or LS2 types

    - #### hashCode

          public int hashCode()

      the destination has enough randomness in it to use it by itself for speed
      Overrides:
        `hashCode` in class `LeaseSet`

    - #### isBlindedWhenPublished

          public boolean isBlindedWhenPublished()

      Set if the unencrypted LS, when published, will be blinded/encrypted

    - #### isCurrent

          public boolean isCurrent(long fudge)

      Determine whether the leaseset is currently valid, at least within a given fudge factor. Overridden to use the expiration time instead of the last expiration.
      Overrides:
        `isCurrent` in class `LeaseSet`
      Parameters:
        `fudge` - milliseconds fudge factor to allow between the current time
      Returns:
        true if there are current leases, false otherwise

    - #### isOffline

          public boolean isOffline()

      Checks if this leaseset uses offline keys.

    - #### isUnpublished

          public boolean isUnpublished()

    - #### offlineSign

          public static Signature offlineSign(long expires,
                                              SigningPublicKey transientSPK,
                                              SigningPrivateKey priv)

      Generate a Signature to pass to setOfflineSignature()
      Parameters:
        `expires` - absolute ms
        `transientSPK` - the key that will sign the leaseset
        `priv` - the private signing key for the destination
      Returns:
        null on error

    - #### readBytes

          public void readBytes(InputStream in)
                         throws DataFormatException,
                                IOException

      This does NOT validate the signature
      Specified by:
        `readBytes` in interface `DataStructure`
      Overrides:
        `readBytes` in class `LeaseSet`
      Parameters:
        `in` - stream to read from
      Throws:
        `IllegalStateException` - if called more than once or Destination already set
        `DataFormatException` - if the data is improperly formatted
        `IOException` - if there was a problem reading the stream

    - #### readHeader

          protected void readHeader(InputStream in)
                             throws DataFormatException,
                                    IOException

      Throws:
        `DataFormatException`
        `IOException`

    - #### readOfflineBytes

          protected void readOfflineBytes(InputStream in)
                                   throws DataFormatException,
                                          IOException

      Throws:
        `DataFormatException`
        `IOException`

    - #### setBlindedHash

          public void setBlindedHash(Hash bh)

      Set this on creation if known

    - #### setBlindedWhenPublished

          public void setBlindedWhenPublished()

      Set if the unencrypted LS, when published, will be blinded/encrypted
      Throws:
        `IllegalStateException` - if already signed

    - #### setOfflineSignature

          public boolean setOfflineSignature(long expires,
                                             SigningPublicKey transientSPK,
                                             Signature offlineSig)

      Destination must be previously set.
      Parameters:
        `expires` - absolute ms
        `transientSPK` - the key that will sign the leaseset
        `offlineSig` - the signature by the spk in the destination
      Returns:
        success, false if verify failed or expired
      Throws:
        `IllegalStateException` - if already signed

    - #### setOptions

          public void setOptions(Properties options)

      Configure a set of options or statistics that the router can expose. Makes a copy.
      Parameters:
        `options` - if null, clears current options
      Throws:
        `IllegalStateException` - if LeaseSet2 is already signed

    - #### setPublished

          public void setPublished(long now)

      Set published timestamp. Will be rounded to nearest second. If not called, will be set on write.

    - #### setSigningKey

          public void setSigningKey(SigningPublicKey key)

      The revocation key. Overridden to do nothing, as we're using the _signingKey field for the blinded key in Enc LS2.
      Overrides:
        `setSigningKey` in class `LeaseSet`

    - #### setUnpublished

          public void setUnpublished()

      Marks this leaseset as unpublished.
      Throws:
        `IllegalStateException` - if already signed

    - #### sign

          public void sign(SigningPrivateKey key)
                    throws DataFormatException

      Sign the structure using the supplied signing key. Overridden because LS2 sigs cover the type byte.
      Overrides:
        `sign` in class `DatabaseEntry`
      Throws:
        `IllegalStateException` - if already signed
        `DataFormatException`

    - #### size

          public int size()

      Number of bytes, NOT including signature
      Overrides:
        `size` in class `LeaseSet`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `LeaseSet`

    - #### verifyOfflineSignature

          public boolean verifyOfflineSignature()

    - #### verifyOfflineSignature

          protected boolean verifyOfflineSignature(SigningPublicKey spk)

    - #### verifySignature

          public boolean verifySignature()

      Verify with the SPK in the dest for online sigs. Verify with the SPK in the offline sig section for offline sigs.
      Overrides:
        `verifySignature` in class `LeaseSet`
      Returns:
        valid

    - #### writeBody

          protected void writeBody(OutputStream out)
                            throws DataFormatException,
                                   IOException

      Without sig. This does NOT validate the signature
      Throws:
        `DataFormatException`
        `IOException`

    - #### writeBytes

          public void writeBytes(OutputStream out)
                          throws DataFormatException,
                                 IOException

      Including sig. This does NOT validate the signature
      Specified by:
        `writeBytes` in interface `DataStructure`
      Overrides:
        `writeBytes` in class `LeaseSet`
      Parameters:
        `out` - stream to write to
      Throws:
        `DataFormatException` - if the data was incomplete or not yet ready to be written
        `IOException` - if there was a problem writing to the stream

    - #### writeBytesWithoutSig

          protected void writeBytesWithoutSig(OutputStream out)
                                       throws DataFormatException,
                                              IOException

      Without sig. This does NOT validate the signature
      Throws:
        `DataFormatException`
        `IOException`

    - #### writeHeader

          protected void writeHeader(OutputStream out)
                              throws DataFormatException,
                                     IOException

      Throws:
        `DataFormatException`
        `IOException`

    - #### writeOfflineBytes

          protected void writeOfflineBytes(OutputStream out)
                                    throws DataFormatException,
                                           IOException

      Throws:
        `DataFormatException`
        `IOException`