| /******************************************************************************* |
| * 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(); |
| } |