Package io.github.hapjava.server

Interface HomekitAuthInfo

  • public interface HomekitAuthInfo
    Authentication info that must be provided when constructing a new HomekitServer. You will need to implement this interface yourself to provide the necessary callbacks to a persistent storage mechanism. All values provided must be constant across invocations or the accessories will require re-pairing within iOS.
    Author:
    Andy Lintner

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void createUser​(java.lang.String username, byte[] publicKey)
      Deprecated method to add a user, assuming all users are admins.
      default void createUser​(java.lang.String username, byte[] publicKey, boolean isAdmin)
      Called during the pairing process, you should store the user and public key in a manner that the public key can later be retrieved using getUserPublicKey(String).
      java.lang.String getMac()
      A unique MAC address to be advertised with the HomeKit information.
      java.lang.String getPin()
      A pin code used for pairing the device.
      byte[] getPrivateKey()
      The private key used by the server during pairing and message encryption.
      java.math.BigInteger getSalt()
      The Salt that will be used when hashing the pin code to send to the client.
      default java.lang.String getSetupId()
      A setup Id used for pairing the device using QR Code.
      byte[] getUserPublicKey​(java.lang.String username)
      Called when an already paired iOS device is re-connecting.
      default boolean hasUser()
      Called to check if a user has been created.
      default java.util.Collection<java.lang.String> listUsers()
      List all users which have been authenticated.
      void removeUser​(java.lang.String username)
      Called when an iOS device needs to remove an existing pairing.
      default boolean userIsAdmin​(java.lang.String username)
      Determine if the specified user is an admin.

    • Method Detail

      • getPin

        java.lang.String getPin()
        A pin code used for pairing the device. This pin will be required within iOS in order to complete pairing. The numbers cannot be sequential and should not have a repeating pattern.
        Returns:
        the pin code, in the form ###-##-###

      • getSetupId

        default java.lang.String getSetupId()
        A setup Id used for pairing the device using QR Code. It can be any alphanumeric combination of the length of 4.
        Returns:
        setup id

      • getMac

        java.lang.String getMac()
        A unique MAC address to be advertised with the HomeKit information. This does not have to be the MAC address of the network interface. You can generate this using HomekitServer.generateMac().
        Returns:
        the unique MAC address.

      • getSalt

        java.math.BigInteger getSalt()
        The Salt that will be used when hashing the pin code to send to the client. You should generate this using HomekitServer.generateSalt().
        Returns:
        the Salt.

      • getPrivateKey

        byte[] getPrivateKey()
        The private key used by the server during pairing and message encryption. You should generate this using HomekitServer.generateKey()
        Returns:
        the private key.

      • createUser

        default void createUser​(java.lang.String username,
                        byte[] publicKey,
                        boolean isAdmin)
        Called during the pairing process, you should store the user and public key in a manner that the public key can later be retrieved using getUserPublicKey(String). This must be stored in a persistent store as pairing will need to be reset if the information is lost.
        Parameters:
        username - the iOS device's username. The value will not be meaningful to anything but iOS.
        publicKey - the iOS device's public key.
        isAdmin - if the user is an admin, authorized to and/remove other users

      • createUser

        default void createUser​(java.lang.String username,
                        byte[] publicKey)
        Deprecated method to add a user, assuming all users are admins.

        At least one of the createUser methods must be implemented.

        Parameters:
        username - the iOS device's username.
        publicKey - the iOS device's public key.

      • removeUser

        void removeUser​(java.lang.String username)
        Called when an iOS device needs to remove an existing pairing. Subsequent calls to getUserPublicKey(String) for this username return null.
        Parameters:
        username - the username to delete from the persistent store.

      • listUsers

        default java.util.Collection<java.lang.String> listUsers()
        List all users which have been authenticated.
        Returns:
        the previously stored list of users.

      • getUserPublicKey

        byte[] getUserPublicKey​(java.lang.String username)
        Called when an already paired iOS device is re-connecting. The public key returned by this method will be compared with the signature of the pair verification request to validate the device.
        Parameters:
        username - the username of the iOS device to retrieve the public key for.
        Returns:
        the previously stored public key for this user.

      • userIsAdmin

        default boolean userIsAdmin​(java.lang.String username)
        Determine if the specified user is an admin.
        Parameters:
        username - the username of the iOS device to retrieve permissions for.
        Returns:
        the previously stored permissions.

      • hasUser

        default boolean hasUser()
        Called to check if a user has been created. The homekit accessory advertises whether the accessory has already been paired. At this time, it's unclear whether multiple users can be created, however it is known that advertising as unpaired will break in iOS 9. The default value has been provided to maintain API compatibility for implementations targeting iOS 8.
        Returns:
        whether a user has been created and stored