net.i2p.data

## Class EncryptedLeaseSet

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

- All Implemented Interfaces:
    Serializable, DataStructure

      public class EncryptedLeaseSet
      extends LeaseSet2

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

  EncryptedLeaseSet provides privacy and authentication enhancements over standard LeaseSet2:

  - LeaseSet content is encrypted using authenticated encryption
  - Supports per-client and group-based access control
  - Uses blinded keys for enhanced privacy
  - Requires authentication data for decryption
  - Protects tunnel endpoints from unauthorized discovery

  Key Features:

  - Authentication Types: Supports DH, PSK, and no authentication
  - Blinded Keys: Uses `LeaseSet.getSigningKey()` for the blinded key (revocation key in super)
  - Encryption: Content encrypted with ChaCha20-Poly1305 AEAD
  - Access Control: Fine-grained control over who can decrypt the LeaseSet

  Usage:

  - Services requiring restricted access to tunnel endpoints
  - Private services with authenticated client access
  - Situations where tunnel endpoint discovery must be controlled

  Authentication Methods:

  - `BlindData.AUTH_NONE` - No authentication required
  - `BlindData.AUTH_DH` - Diffie-Hellman key exchange authentication
  - `BlindData.AUTH_PSK` - Pre-shared key authentication

  Implementation Status: PRELIMINARY - Subject to change as the proposal evolves

  See Also:
    Serialized Form

- - ### Field Summary

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

      `_expires, _flags, _offlineSignature, _options, _published, _transientExpires, _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
    `EncryptedLeaseSet()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `encrypt(int authType, List<? extends SimpleDataStructure> clientKeys)` Throws IllegalStateException if not initialized.
    `void` | `encrypt(SessionKey skey)` Throws IllegalStateException if not initialized.
    `boolean` | `equals(Object object)`
    `LeaseSet2` | `getDecryptedLeaseSet()`
    `PublicKey` | `getEncryptionKey(Set<EncType> supported)` If more than one key, return the first supported one.
    `List<PublicKey>` | `getEncryptionKeys()` This returns all the keys.
    `Hash` | `getHash()` This must be used instead of getDestination().getHash().
    `Lease` | `getLease(int index)`
    `int` | `getLeaseCount()` Gets the number of leases in this leaseset.
    `protected SigningPublicKey` | `getSigningPublicKey()` Overridden to return the blinded key so super.verifySignature() will work.
    `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
    `void` | `readBytes(InputStream in)` This does NOT validate the signature
    `protected void` | `readHeader(InputStream in)` Overridden because we have a blinded key, not a dest
    `protected void` | `readOfflineBytes(InputStream in)` Overridden because we have a blinded key, not a dest
    `void` | `setClientPrivateKey(PrivateKey privKey)` Must be set before verify for per-client auth.
    `void` | `setDestination(Destination dest)` Overridden to set the blinded key.
    `void` | `setSecret(String secret)` Must be set before sign or verify.
    `void` | `setSigningKey(SigningPublicKey spk)` Overridden to set the blinded key.
    `void` | `sign(SigningPrivateKey key)` Sign the structure using the supplied signing key.
    `void` | `sign(SigningPrivateKey key, int authType, List<? extends SimpleDataStructure> clientKeys)` Sign the structure using the supplied signing key.
    `int` | `size()` Number of bytes, NOT including signature
    `String` | `toString()`
    `boolean` | `verifyOfflineSignature()` Overridden because we have a blinded key, not a dest
    `boolean` | `verifySignature()` Overridden to decrypt if possible, and verify inner sig also.
    `boolean` | `verifySignature(PrivateKey clientKey)` Decrypt if possible, and verify inner sig also.
    `protected void` | `writeBytesWithoutSig(OutputStream out)` Before encrypt() is called, the inner leaseset.
    `protected void` | `writeHeader(OutputStream out)` Overridden because we have a blinded key, not a dest
    `protected void` | `writeOfflineBytes(OutputStream out)` Overridden because we have a blinded key, not a dest

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

      `addEncryptionKey, addLease, getBlindedHash, getBytes, getEncryptionKey, getExpires, getOption, getOptions, getPublished, getReceivedAsPublished, getTransientExpiration, getTransientSigningKey, isBlindedWhenPublished, isCurrent, isOffline, isUnpublished, offlineSign, setBlindedHash, setBlindedWhenPublished, setOfflineSignature, setOptions, setPublished, setUnpublished, verifyOfflineSignature, writeBody, writeBytes`

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

      `getDate, getDestination, getEarliestLeaseDate, getKeysAndCert, getLatestLeaseDate, getSigningKey, setEncryptionKey, setReceivedBy`

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

      `getReceivedAsReply, getReceivedBy, getRoutingKey, getSignature, 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`

- - ### Constructor Detail

    - #### EncryptedLeaseSet

          public EncryptedLeaseSet()

  - ### Method Detail

    - #### encrypt

          public void encrypt(int authType,
                              List<? extends SimpleDataStructure> clientKeys)

      Throws IllegalStateException if not initialized. Ref: proposal 123
      Parameters:
        `authType` - 0, 1, or 3, see BlindData
        `clientKeys` - The client's X25519 public or private keys, null if unused
      Throws:
        `IllegalStateException`

    - #### encrypt

          public void encrypt(SessionKey skey)

      Throws IllegalStateException if not initialized.
      Overrides:
        `encrypt` in class `LeaseSet2`
      Parameters:
        `skey` - ignored
      Throws:
        `IllegalStateException`

    - #### equals

          public boolean equals(Object object)

      Overrides:
        `equals` in class `LeaseSet2`

    - #### getDecryptedLeaseSet

          public LeaseSet2 getDecryptedLeaseSet()

      Returns:
        leaseset or null if not decrypted.

    - #### 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 `LeaseSet2`
      Parameters:
        `supported` - what return types are allowed
      Returns:
        first supported key or null

    - #### getEncryptionKeys

          public List<PublicKey> getEncryptionKeys()

      Description copied from class: `LeaseSet2`
      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.
      Overrides:
        `getEncryptionKeys` in class `LeaseSet2`
      Returns:
        null if not decrypted.

    - #### getHash

          public Hash getHash()

      This must be used instead of getDestination().getHash(). Overridden because we have a blinded key, not a dest. This is the hash of the signing public key type and the signing public key. Throws IllegalStateException if not initialized.
      Overrides:
        `getHash` in class `DatabaseEntry`
      Returns:
        Hash or null
      Throws:
        `IllegalStateException`

    - #### getLease

          public Lease getLease(int index)

      Overrides:
        `getLease` in class `LeaseSet`
      Returns:
        null if not decrypted.

    - #### getLeaseCount

          public int getLeaseCount()

      Description copied from class: `LeaseSet`
      Gets the number of leases in this leaseset.
      Overrides:
        `getLeaseCount` in class `LeaseSet`
      Returns:
        0-16, or 0 if not decrypted.

    - #### getSigningPublicKey

          protected SigningPublicKey getSigningPublicKey()

      Overridden to return the blinded key so super.verifySignature() will work.
      Overrides:
        `getSigningPublicKey` in class `DatabaseEntry`
      Returns:
        SPK or null

    - #### 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 `LeaseSet2`
      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 `LeaseSet2`

    - #### 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 `LeaseSet2`
      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

      Overridden because we have a blinded key, not a dest
      Overrides:
        `readHeader` in class `LeaseSet2`
      Throws:
        `DataFormatException`
        `IOException`

    - #### readOfflineBytes

          protected void readOfflineBytes(InputStream in)
                                   throws DataFormatException,
                                          IOException

      Overridden because we have a blinded key, not a dest
      Overrides:
        `readOfflineBytes` in class `LeaseSet2`
      Throws:
        `DataFormatException`
        `IOException`

    - #### setClientPrivateKey

          public void setClientPrivateKey(PrivateKey privKey)

      Must be set before verify for per-client auth.
      Parameters:
        `privKey` - non-null

    - #### setDestination

          public void setDestination(Destination dest)

      Overridden to set the blinded key. setSecret() MUST be called before this for non-null secret, or alpha will be wrong.
      Overrides:
        `setDestination` in class `LeaseSet`
      Parameters:
        `dest` - non-null, must be EdDSA_SHA512_Ed25519 or RedDSA_SHA512_Ed25519
      Throws:
        `IllegalStateException` - if already signed
        `IllegalArgumentException` - if not EdDSA

    - #### setSecret

          public void setSecret(String secret)

      Must be set before sign or verify. Must be called before setDestination() or setSigningKey(), or alpha will be wrong.
      Parameters:
        `secret` - null or "" for none (default)

    - #### setSigningKey

          public void setSigningKey(SigningPublicKey spk)

      Overridden to set the blinded key. setSecret() MUST be called before this for non-null secret, or alpha will be wrong.
      Overrides:
        `setSigningKey` in class `LeaseSet2`
      Parameters:
        `spk` - unblinded key non-null, must be EdDSA_SHA512_Ed25519 or RedDSA_SHA512_Ed25519
      Throws:
        `IllegalStateException` - if already signed
        `IllegalArgumentException` - if not EdDSA

    - #### sign

          public void sign(SigningPrivateKey key)
                    throws DataFormatException

      Sign the structure using the supplied signing key. Overridden because we sign the inner, then blind and encrypt and sign the outer.
      Overrides:
        `sign` in class `LeaseSet2`
      Throws:
        `IllegalStateException` - if already signed
        `DataFormatException`

    - #### sign

          public void sign(SigningPrivateKey key,
                           int authType,
                           List<? extends SimpleDataStructure> clientKeys)
                    throws DataFormatException

      Sign the structure using the supplied signing key. Overridden because we sign the inner, then blind and encrypt and sign the outer.
      Parameters:
        `authType` - 0, 1, or 3, see BlindData
        `clientKeys` - X25519 public keys for DH, private keys for PSK
      Throws:
        `IllegalStateException` - if already signed
        `DataFormatException`

    - #### size

          public int size()

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

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `LeaseSet2`

    - #### verifyOfflineSignature

          public boolean verifyOfflineSignature()

      Overridden because we have a blinded key, not a dest
      Overrides:
        `verifyOfflineSignature` in class `LeaseSet2`

    - #### verifySignature

          public boolean verifySignature()

      Overridden to decrypt if possible, and verify inner sig also. Must call setDestination() prior to this if attempting decryption. Must call setClientKey() prior to this if attempting decryption.
      Overrides:
        `verifySignature` in class `LeaseSet2`
      Returns:
        valid

    - #### verifySignature

          public boolean verifySignature(PrivateKey clientKey)

      Decrypt if possible, and verify inner sig also. Must call setDestination() prior to this if attempting decryption.
      Parameters:
        `clientKey` - PrivateKey for DH or PSK, or null if none
      Returns:
        valid

    - #### writeBytesWithoutSig

          protected void writeBytesWithoutSig(OutputStream out)
                                       throws DataFormatException,
                                              IOException

      Before encrypt() is called, the inner leaseset. After encrypt() is called, the encrypted data. Without sig. This does NOT validate the signature
      Overrides:
        `writeBytesWithoutSig` in class `LeaseSet2`
      Throws:
        `DataFormatException`
        `IOException`

    - #### writeHeader

          protected void writeHeader(OutputStream out)
                              throws DataFormatException,
                                     IOException

      Overridden because we have a blinded key, not a dest
      Overrides:
        `writeHeader` in class `LeaseSet2`
      Throws:
        `DataFormatException`
        `IOException`

    - #### writeOfflineBytes

          protected void writeOfflineBytes(OutputStream out)
                                    throws DataFormatException,
                                           IOException

      Overridden because we have a blinded key, not a dest
      Overrides:
        `writeOfflineBytes` in class `LeaseSet2`
      Throws:
        `DataFormatException`
        `IOException`