001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2016 ForgeRock AS.
015 */
016package org.forgerock.opendj.security;
017
018import org.forgerock.opendj.ldap.ByteSequence;
019
020/**
021 * A service provider interface for externalizing the strategy used for wrapping individual private/secret keys.
022 * Applications can configure an LDAP keystore to delegate key wrapping responsibilities by setting the
023 * {@link KeyStoreParameters#EXTERNAL_KEY_WRAPPING_STRATEGY} option.
024 */
025public interface ExternalKeyWrappingStrategy {
026    /**
027     * Wraps the provided encoded key.
028     *
029     * @param unwrappedKey
030     *         The non-{@code null} key to be wrapped. The format of the unwrapped key is unspecified.
031     * @return The non-{@code null} protected key. The format of the returned wrapped key is implementation defined.
032     * @throws LocalizedKeyStoreException
033     *         If an unexpected problem occurred when wrapping the key.
034     */
035    ByteSequence wrapKey(ByteSequence unwrappedKey) throws LocalizedKeyStoreException;
036
037    /**
038     * Unwraps the provided {@link #wrapKey(ByteSequence) wrapped} key.
039     *
040     * @param wrappedKey
041     *         The non-{@code null} key to be unwrapped. The format of the wrapped key is implementation
042     *         defined and must have been produced via a call to {@link #wrapKey(ByteSequence)}.
043     * @return The non-{@code null} unwrapped key which must contain exactly the same content passed to {@link
044     * #wrapKey(ByteSequence)}.
045     * @throws LocalizedKeyStoreException
046     *         If an unexpected problem occurred when unwrapping the key.
047     */
048    ByteSequence unwrapKey(ByteSequence wrappedKey) throws LocalizedKeyStoreException;
049}