Class LinkSession

java.lang.Object
lol.trq.alts.vault.LinkSession

public final class LinkSession extends Object
Owner device linking (AVP SPEC 11.6): how a second owner device gets the OwnerIdentity without the phrase being typed. No host takes part; the request and the grant travel out of band.
  1. The new device calls start() and shows request() and confirmationCode().
  2. The existing owner device reads the request and calls approve(OwnerIdentity, LinkRequest, Predicate), which shows the code it computes and continues only if the owner confirms it matches the one on the new device.
  3. The new device passes the grant to finish(LinkGrant) and has the owner identity.

A session holds an ephemeral private key until it finishes; toString() shows nothing of it.

Since:
1.0.0
  • Method Details

    • start

      public static LinkSession start()
      Starts a session on the new device, with a fresh ephemeral key.
      Returns:
      the session
      Since:
      1.0.0
    • request

      public LinkRequest request()
      The request to carry to the existing owner device.
      Returns:
      the request
      Since:
      1.0.0
    • confirmationCode

      public String confirmationCode()
      The 6-digit code to show on this device; the existing device shows the same one.
      Returns:
      the code
      Since:
      1.0.0
    • finish

      public OwnerIdentity finish(LinkGrant grant)
      Opens the grant with this session's ephemeral key, which is then destroyed. A session finishes once.
      Parameters:
      grant - the grant from the existing owner device
      Returns:
      the owner identity
      Throws:
      AltsException - of kind CRYPTO if the grant was not made for this session's request, and INVALID_INPUT if the session already finished
      Since:
      1.0.0
    • approve

      public static LinkGrant approve(OwnerIdentity owner, LinkRequest request, Predicate<String> confirm)
      The existing owner device's side: hands confirm the code this device computes for the request and, only if it answers true (the owner confirmed it matches the code on the new device), wraps the owner's entropy to the request's key under avp/owner-link/v1.
      Parameters:
      owner - the owner identity on this device
      request - the new device's request
      confirm - shows the code to the owner and answers whether they confirmed the two match
      Returns:
      the grant to carry back
      Throws:
      AltsException - of kind DECLINED if the owner did not confirm; nothing is wrapped. A confirm that throws is not caught: its exception reaches the caller as it is, and nothing is wrapped
      Since:
      1.0.0
    • toString

      public String toString()
      Names the type and the 6-digit confirmationCode(), which this device shows anyway and which is no secret; never the ephemeral private key and never the request.
      Overrides:
      toString in class Object
      Returns:
      a description
      Since:
      1.0.0