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