com.entrust.toolkit.credentials

Class CapiIdentities

java.lang.Object

java.util.AbstractCollection<CapiIdentity>

com.entrust.toolkit.credentials.CapiIdentities

All Implemented Interfaces:

CapiIdentityFilter, IdentityFilter, java.lang.Iterable<CapiIdentity>, java.util.Collection<CapiIdentity>

public class CapiIdentities
extends java.util.AbstractCollection<CapiIdentity>
implements CapiIdentityFilter

This class stores a set of CapiIdentity objects, and can be used to find digital identities in CAPI. It extends AbstractCollection, but follows the semantics of an unmodifiable collection. This means that any add method will throw an UnsupportedOperationException, and the Iterator returned by a call to iterator() does not support the remove() operation.

An instance of this class should be obtained by calling the static findIdentities() method. This method searches through the "MY" certificate store of the current Windows user, looking for certificates with private keys available. A CapiIdentity is formed by grouping together certificates which belong to the same identity in the Certification Authority. The matching of certificates to an identity is done by private key container name, which have specific naming rules.

This class has convenience methods to find an identity matching a key container name. Other search methods should use the standard method of iterating over a Collection with an Iterator and testing each CapiIdenity.

A CapiCertFilter may be used to filter out Certificates in CAPI that are not acceptable for forming an identity. A custom CapiCertFilter may be defined and passed to the findIdentities(CapiCertFilter), or if more than one filter is required, a CapiSearchFilter containing multiple CapiCertFilter objects may be defined.

It is important to note that it will not necessarily be possible to access all of the identities in the collection. For example, some may have been created with a different security descriptor from the one currently in use that will prevent access to the private key.

Since:

7.0

See Also:

findIdentities(), AbstractCollection

Method Summary

Modifier and Type	Method and Description
static CapiIdentities	findIdentities() Searches the "MY" certificate store of the currently logged in Windows user for certificates that can be used to log in to a User object.
static CapiIdentities	findIdentities(CapiCertFilter filter) Searches the "MY" certificate store of the currently logged in Windows user for certificates that can be used to log in to a User object.
static CapiIdentities	findIdentities(CapiCertFilter filter, CapiIdentityFilter idfilter) Searches the "MY" certificate store of the currently logged in Windows user for certificates that can be used to log in to a User object.
static CapiIdentity	findIdentity(CapiCertFilter filter) This method returns the first CapiIdentity found after searching for identities with the specific filter.
CapiIdentity	findMatchingIdentity(CapiCertificateAndKeyInfo ccaki, CapiIdentityFilter filter) Finds the identity to which the given CapiCertificateAndKeyInfo matches by calling the IdentityFilter.matchIdentity(Identity, CertificateAndKeyInfo) method.
CapiIdentity	findMatchingIdentity(CapiContainerName containerName) Finds the identity to which the given key container name belongs.
static CertStore	getIdentityCertStore(java.lang.String storeName) This method is used to get the CertStore that is used when retrieving identities.
java.util.Iterator<CapiIdentity>	iterator() Returns an Iterator that can be used to iterate through all identities stored in this set.
boolean	matchIdentity(Identity identity, CertificateAndKeyInfo ccaki) Check if the passed in CapiCerticateAndKeyInfo belongs to the specified CapiIdentity.
int	size() Returns the number of identities in this collection.

Methods inherited from class java.util.AbstractCollection

add, addAll, clear, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

equals, hashCode, parallelStream, removeIf, spliterator, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

iterator

public java.util.Iterator<CapiIdentity> iterator()

Returns an Iterator that can be used to iterate through all identities stored in this set. The object returned by calling the next() method of the iterator should be cast to a CapiIdentity.

Specified by:

iterator in interface java.lang.Iterable<CapiIdentity>

Specified by:

iterator in interface java.util.Collection<CapiIdentity>

Specified by:

iterator in class java.util.AbstractCollection<CapiIdentity>

Returns:

an Iterator that can be used to iterate through all identities stored in this set.

size

public int size()

Returns the number of identities in this collection.

Specified by:

size in interface java.util.Collection<CapiIdentity>

Specified by:

size in class java.util.AbstractCollection<CapiIdentity>

Returns:

the number of identities in this collection.

findMatchingIdentity

public CapiIdentity findMatchingIdentity(CapiContainerName containerName)

Finds the identity to which the given key container name belongs.

Parameters:

containerName - The name of the key container for which to find a matching identity

Returns:

The identity matching the container, or null if no matching identity is found.

findMatchingIdentity

public CapiIdentity findMatchingIdentity(CapiCertificateAndKeyInfo ccaki,
                                         CapiIdentityFilter filter)

Finds the identity to which the given CapiCertificateAndKeyInfo matches by calling the IdentityFilter.matchIdentity(Identity, CertificateAndKeyInfo) method.

Parameters:

ccaki - The CapiCertificateAndKeyInfo which will be used to find certificates and key that belong to this identity.

filter - The CapiIdentityFilter used to find the certificates and keys that belong to this identity.

Returns:

The identity matching the container, or null if no matching identity is found.

matchIdentity

public boolean matchIdentity(Identity identity,
                             CertificateAndKeyInfo ccaki)

Check if the passed in CapiCerticateAndKeyInfo belongs to the specified CapiIdentity.

In an Entrust Identity, there can be multiple certificates and keys. For example, encryption, verification and non-repudiation. When these certificates are stored in CAPI using Entrust, the CapiContainerName is used to find other certificates that may be associated with that identity. However, if the Entrust certificates were added into CAPI using a third-party mechanism, such as a P11 driver, or an export from P12, then the Entrust container format will not be used. Therefore, this identity will be considered an unknown identity and the toolkit will use the SubjectDN and IssuerDN of the certificates in CAPI to find the certificates that belong to the same identity.

Note: Because the Entrust CAPI container format was not used when writing the certificates into CAPI, this identity will not be able to be managed by the toolkit. Attempting to manage such an identity may result in undefined behaviour, and is not supported by the toolkit.

Specified by:

matchIdentity in interface IdentityFilter

Parameters:

identity - The CapiIdentity

ccaki - The CapiCertificateAndKeyInfo

Returns:

true if the CapiCertificateAndKeyInfo belong to the CapiIdentity, false if CapiCertificateAndKeyInfo do not belong.

findIdentities

public static CapiIdentities findIdentities()
                                     throws CapiException

Searches the "MY" certificate store of the currently logged in Windows user for certificates that can be used to log in to a User object. To be acceptable, a certificate must:

• have a matching private key available
• have a chain to a root certificate available

Returns:

a collection of CapiIdentity objects that may be used to construct a CapiCredentialReader to log in to a User

Throws:

CapiException - if any non-recoverable error occurs searching for certificates, such as not being able to open the "MY" certificate store.

findIdentity

public static CapiIdentity findIdentity(CapiCertFilter filter)
                                 throws CapiException

This method returns the first CapiIdentity found after searching for identities with the specific filter. This is useful when using a filter that should only return 1 identity such as the CertIdentityCertFilter.

Parameters:

filter - The CapiCertFilter used to filter out acceptable certificates used to find identities

Returns:

The first CapiIdentity in the list of identities returned, or none if no identites are returned

Throws:

CapiException - if an error occurs

See Also:

CapiCertFilter

findIdentities

public static CapiIdentities findIdentities(CapiCertFilter filter)
                                     throws CapiException

Searches the "MY" certificate store of the currently logged in Windows user for certificates that can be used to log in to a User object.

The CapiCertFilter is used to filter out certificates that should not be considered for use when searching for identities

Parameters:

filter - The CapiCertFilter used to filter out certificates which should be considered acceptable.

Returns:

a collection of CapiIdentity objects that may be used to construct a CapiCredentialReader to log in to a User

Throws:

CapiException - if any non-recoverable error occurs searching for certificates, such as not being able to open the "MY" certificate store.

See Also:

CapiCertFilter, UnverifiedCertFilter, CapiSearchFilter

findIdentities

public static CapiIdentities findIdentities(CapiCertFilter filter,
                                            CapiIdentityFilter idfilter)
                                     throws CapiException

Searches the "MY" certificate store of the currently logged in Windows user for certificates that can be used to log in to a User object.

The CapiCertFilter is used to filter out certificates that should not be considered for use when searching for identities

The CapiIdentityFilter is used to identify certificates which should belong to the same identity. Null may be specified to indicate the default matchIdentity(Identity, CertificateAndKeyInfo) filter will be used.

Parameters:

filter - The CapiCertFilter used to filter out certificates which should not be considered acceptable.

idfilter - The CapiIdentityFilter used to match the certificates and keys that belong to the same identity.

Returns:

a collection of CapiIdentity objects that may be used to construct a CapiCredentialReader to log in to a User

Throws:

CapiException - if any non-recoverable error occurs searching for certificates, such as not being able to open the "MY" certificate store.

See Also:

CapiCertFilter, UnverifiedCertFilter, CapiSearchFilter

getIdentityCertStore

public static CertStore getIdentityCertStore(java.lang.String storeName)
                                      throws CapiException

This method is used to get the CertStore that is used when retrieving identities. It is static and can be used by any class in the package

Parameters:

storeName - The store name

Throws:

CapiException