IdentityService
Keywords: net.corda.core.node.services.IdentityService interface
Date: 2023-09-18

net.corda.core.node.services

## Interface IdentityService

-     @DoNotImplement
      public IdentityService

  An identity service maintains a directory of parties by their associated distinguished name/public keys and thus supports lookup of a party given its key, or name. The service also manages the certificates linking confidential identities back to the well known identity.

  Well known identities in Corda are the public identity of a party, registered with the network map directory, whereas confidential identities are distributed only on a need to know basis (typically between parties in a transaction being built). See `interface NetworkMapCache` for retrieving well known identities from the network map.

  See Also:
    `interface NetworkMapCache`

- - ### Field Detail

    - #### Companion

          static net.corda.core.node.services.IdentityService.Companion Companion

  - ### Constructor Detail

    - #### IdentityService

          public IdentityService()

  - ### Method Detail

    - #### getTrustRoot

          @NotNull
          java.security.cert.X509Certificate getTrustRoot()

    - #### getTrustAnchor

          @NotNull
          java.security.cert.TrustAnchor getTrustAnchor()

    - #### getCaCertStore

          @NotNull
          java.security.cert.CertStore getCaCertStore()

    - #### verifyAndRegisterIdentity

          @Nullable
          PartyAndCertificate verifyAndRegisterIdentity(@NotNull
                                                                  PartyAndCertificate identity)

      Verify and then store an identity.

      Parameters:
        `identity` - a party and the certificate path linking them to the network trust root.
      Returns:
        the issuing entity, if known.
      Throws:
        `IllegalArgumentException` - if the certificate path is invalid.

    - #### assertOwnership

          void assertOwnership(@NotNull
                               Party party,
                               @NotNull
                               AnonymousParty anonymousParty)

      Asserts that an anonymous party maps to the given full party, by looking up the certificate chain associated with the anonymous party and resolving it back to the given full party.

      Throws:
        `UnknownAnonymousPartyException` - if the anonymous party is not owned by the full party.

    - #### getAllIdentities

          @NotNull
          java.lang.Iterable<net.corda.core.identity.PartyAndCertificate> getAllIdentities()

      Get all identities known to the service. This is expensive, and `partyFromKey` or partyFromX500Name should be used in preference where possible.

      See Also:
        `partyFromKey`, partyFromX500Name

    - #### certificateFromKey

          @Nullable
          PartyAndCertificate certificateFromKey(@NotNull
                                                           java.security.PublicKey owningKey)

      Resolves a public key to the well known identity `class PartyAndCertificate` instance which is owned by the key.

      Parameters:
        `owningKey` - The PublicKey to determine well known identity for.
      Returns:
        the party and certificate, or null if unknown.
      See Also:
        `class PartyAndCertificate`

    - #### partyFromKey

          @Nullable
          Party partyFromKey(@NotNull
                                       java.security.PublicKey key)

      Converts an owning PublicKey to the X500Name extended `class Party` object if the `class Party` has been previously registered with the `interface IdentityService` either as a well known network map identity, or as a part of flows creating and exchanging the identity.

      Parameters:
        `key` - The owning PublicKey of the `class Party`.
      Returns:
        Returns a `class Party` with a matching owningKey if known, else returns null.
      See Also:
        PublicKey, `class Party`, `class Party`, `interface IdentityService`

    - #### wellKnownPartyFromX500Name

          @Nullable
          Party wellKnownPartyFromX500Name(@NotNull
                                                     CordaX500Name name)

      Resolves a party name to the well known identity `class Party` instance for this name. Where possible well known identity lookup from name should be done from the network map (via `interface NetworkMapCache`) instead, as it is the authoritative source of well known identities.

      Parameters:
        `name` - The `class CordaX500Name` to determine well known identity for.
      Returns:
        If known the canonical `class Party` with that name, else null.
      See Also:
        `class Party`, `interface NetworkMapCache`

    - #### wellKnownPartyFromAnonymous

          @Nullable
          Party wellKnownPartyFromAnonymous(@NotNull
                                                      AbstractParty party)

      Resolves a (optionally) confidential identity to the corresponding well known identity `class Party`. It transparently handles returning the well known identity back if a well known identity is passed in.

      Parameters:
        `party` - identity to determine well known identity for.
      Returns:
        well known identity, if found.
      See Also:
        `class Party`

    - #### wellKnownPartyFromAnonymous

          @Nullable
          Party wellKnownPartyFromAnonymous(@NotNull
                                                      PartyAndReference partyRef)

      Resolves a (optionally) confidential identity to the corresponding well known identity `class Party`. Convenience method which unwraps the `class Party` from the `class PartyAndReference` and then resolves the well known identity as normal. It transparently handles returning the well known identity back if a well known identity is passed in.

      Parameters:
        `partyRef` - identity (and reference, which is unused) to determine well known identity for.
      Returns:
        the well known identity, or null if unknown.
      See Also:
        `class Party`, `class Party`, `class PartyAndReference`

    - #### requireWellKnownPartyFromAnonymous

          @NotNull
          Party requireWellKnownPartyFromAnonymous(@NotNull
                                                            AbstractParty party)

      Resolve the well known identity of a party. Throws an exception if the party cannot be identified. If the party passed in is already a well known identity (i.e. a `class Party`) this returns it as-is.

      Returns:
        the well known identity.
      Throws:
        `IllegalArgumentException`
      See Also:
        `class Party`

    - #### partiesFromName

          @NotNull
          java.util.Set<net.corda.core.identity.Party> partiesFromName(@NotNull
                                                                                java.lang.String query,
                                                                                boolean exactMatch)

      Returns a list of candidate matches for a given string, with optional fuzzy(ish) matching. Fuzzy matching may get smarter with time e.g. to correct spelling errors, so you should not hard-code indexes into the results but rather show them via a user interface and let the user pick the one they wanted.

      Parameters:
        `query` - The string to check against the X.500 name components
        `exactMatch` - If true, a case sensitive match is done against each component of each X.500 name.

    - #### registerKey

          void registerKey(@NotNull
                           java.security.PublicKey publicKey,
                           @NotNull
                           Party party,
                           @Nullable
                           java.util.UUID externalId)

      Registers a mapping in the database between the provided PublicKey and `class Party` if one does not already exist. If an entry exists for the supplied PublicKey but the associated `class Party` does not match the one supplied to the method then a warning will be logged and the operation will not be carried out as a key can only ever be registered to one `class Party`.

      This method also optionally adds a mapping from PublicKey to external ID if one is provided. Lastly, the PublicKey is also stored (as well as the PublicKey hash).

      Parameters:
        `publicKey` - The public publicKey that will be registered to the supplied `class Party`
        `party` - The party that the supplied public publicKey will be registered to
        `externalId` - The UUID that the supplied public key can be optionally registered to
      Throws:
        `IllegalArgumentException` - if the public publicKey is already registered to a party that does not match the supplied party
      See Also:
        PublicKey, `class Party`, PublicKey, `class Party`, `class Party`, PublicKey, PublicKey, PublicKey

    - #### externalIdForPublicKey

          @Suspendable
           @Nullable
          java.util.UUID externalIdForPublicKey(@NotNull
                                                                        java.security.PublicKey publicKey)

      This method allows lookups of PublicKeys to an associated "external ID" / UUID. Providing a PublicKey that is unknown by the node or is not mapped to an external ID will return null. Otherwise, if the PublicKey has been mapped to an external ID, then the UUID for that external ID will be returned. The method looks up keys generated by the node as well as keys generated on other nodes and registered with the `interface IdentityService`.

      Parameters:
        `publicKey` - the PublicKey used to perform the lookup to external ID
      See Also:
        PublicKey, UUID, PublicKey, PublicKey, UUID, `interface IdentityService`

    - #### publicKeysForExternalId

          @NotNull
          java.lang.Iterable<java.security.PublicKey> publicKeysForExternalId(@NotNull
                                                                                       java.util.UUID externalId)

      This method returns all the PublicKeys which have been mapped to the supplied external ID.

      Parameters:
        `externalId` - the external ID to lookup PublicKeys for
      See Also:
        PublicKey