/*******************************************************************************
* Copyright (c) 2005, 2008 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.osgi.service.security;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.security.cert.Certificate;
import org.eclipse.osgi.internal.signedcontent.TrustEngineListener;
/**
* A <code>TrustEngine</code> is used to establish the authenticity of a
* {@link Certificate} chain.
* <p>
* Clients may implement this interface.
* </p>
* @since 3.4
*/
public abstract class TrustEngine {
/**
* Returns the certificate trust anchor contained in the specified chain which
* was used to establish the authenticity of the chain. If no
* trust anchor is found in the chain then <code>null</code> is returned.
* @param chain - a complete or incomplete certificate chain, implementations *MAY* complete chains
* @return - the certificate trust anchor used to establish authenticity
* @throws IOException if there is a problem connecting to the backing store
*/
public abstract Certificate findTrustAnchor(Certificate[] chain) throws IOException;
/**
* Add a trust anchor point to this trust engine. A trust anchor implies that a certificate,
* and any of its children, is to be considered trusted. If <code>null</code> is used
* as the alias then an alias will be generated based on the trust anchor certificate.
* @param anchor - the certificate to add as an anchor point
* @param alias - a unique and human-readable 'friendly name' which can be used to reference the certificate.
* A <code>null</code> value may be used.
* @return the alias used to store the entry
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
* @throws IllegalArgumentException if the alias or anchor already exist in this trust engine
*/
public String addTrustAnchor(Certificate anchor, String alias) throws IOException, GeneralSecurityException {
String storedAlias = doAddTrustAnchor(anchor, alias);
TrustEngineListener listener = TrustEngineListener.getInstance();
if (listener != null)
listener.addedTrustAnchor(anchor);
return storedAlias;
}
/**
* Add a trust anchor point to this trust engine. A trust anchor implies that a certificate,
* and any of its children, is to be considered trusted. If <code>null</code> is used
* as the alias then an alias will be generated based on the trust anchor certificate.
* @param anchor - the certificate to add as an anchor point
* @param alias - a unique and human-readable 'friendly name' which can be used to reference the certificate.
* A <code>null</code> value may be used.
* @return the alias used to store the entry
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
* @throws IllegalArgumentException if the alias or anchor already exist in this trust engine
*/
protected abstract String doAddTrustAnchor(Certificate anchor, String alias) throws IOException, GeneralSecurityException;
/**
* Remove a trust anchor point from the engine, based on the certificate itself.
* @param anchor - the certificate to be removed
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
*/
public final void removeTrustAnchor(Certificate anchor) throws IOException, GeneralSecurityException {
doRemoveTrustAnchor(anchor);
TrustEngineListener listener = TrustEngineListener.getInstance();
if (listener != null)
listener.removedTrustAnchor(anchor);
}
/**
* Remove a trust anchor point from the engine, based on the certificate itself.
* @param anchor - the certificate to be removed
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
*/
protected abstract void doRemoveTrustAnchor(Certificate anchor) throws IOException, GeneralSecurityException;
/**
* Remove a trust anchor point from the engine, based on the human readable "friendly name"
* @param alias - the name of the trust anchor
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
*/
public void removeTrustAnchor(String alias) throws IOException, GeneralSecurityException {
Certificate existing = getTrustAnchor(alias);
doRemoveTrustAnchor(alias);
if (existing != null) {
TrustEngineListener listener = TrustEngineListener.getInstance();
if (listener != null)
listener.removedTrustAnchor(existing);
}
}
/**
* Remove a trust anchor point from the engine, based on the human readable "friendly name"
* @param alias - the name of the trust anchor
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
*/
protected abstract void doRemoveTrustAnchor(String alias) throws IOException, GeneralSecurityException;
/**
* Return the certificate associated with the unique "friendly name" in the engine.
* @param alias - the friendly name
* @return the associated trust anchor
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
*/
public abstract Certificate getTrustAnchor(String alias) throws IOException, GeneralSecurityException;
/**
* Return the list of friendly name aliases for the TrustAnchors installed in the engine.
* @return string[] - the list of friendly name aliases
* @throws IOException if there is a problem connecting to the backing store
* @throws GeneralSecurityException if there is a certificate problem
*/
public abstract String[] getAliases() throws IOException, GeneralSecurityException;
/**
* Return a value indicate whether this trust engine is read-only.
*
* @return true if this trust engine is read-only false otherwise.
*/
public abstract boolean isReadOnly();
/**
* Return a representation string of this trust engine
*
* @return a string
*/
public abstract String getName();
}