001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.keymeta;
019
020import java.io.IOException;
021import java.security.KeyException;
022import java.util.List;
023import org.apache.hadoop.hbase.io.crypto.ManagedKeyData;
024import org.apache.yetus.audience.InterfaceAudience;
025import org.apache.yetus.audience.InterfaceStability;
026
027/**
028 * KeymetaAdmin is an interface for administrative functions related to managed keys. It handles the
029 * following methods:
030 */
031@InterfaceAudience.Public
032@InterfaceStability.Evolving
033public interface KeymetaAdmin {
034  /**
035   * Enables key management for the specified custodian and namespace.
036   * @param keyCust      The key custodian identifier.
037   * @param keyNamespace The namespace for the key management.
038   * @return The list of {@link ManagedKeyData} objects each identifying the key and its current
039   *         status.
040   * @throws IOException if an error occurs while enabling key management.
041   */
042  ManagedKeyData enableKeyManagement(byte[] keyCust, String keyNamespace)
043    throws IOException, KeyException;
044
045  /**
046   * Get the status of all the keys for the specified custodian.
047   * @param keyCust      The key custodian identifier.
048   * @param keyNamespace The namespace for the key management.
049   * @return The list of {@link ManagedKeyData} objects each identifying the key and its current
050   *         status.
051   * @throws IOException if an error occurs while enabling key management.
052   */
053  List<ManagedKeyData> getManagedKeys(byte[] keyCust, String keyNamespace)
054    throws IOException, KeyException;
055
056  /**
057   * Triggers rotation of the System Key (STK) by checking for a new key and propagating it to all
058   * region servers.
059   * @return true if a new STK was found and rotated, false if no change was detected
060   * @throws IOException if an error occurs while rotating the STK
061   */
062  boolean rotateSTK() throws IOException;
063
064  /**
065   * Eject a specific managed key entry from the managed key data cache on all live region servers.
066   * @param keyCustodian the key custodian
067   * @param keyNamespace the key namespace
068   * @param keyMetadata  the key metadata
069   * @throws IOException if an error occurs while ejecting the key
070   */
071  void ejectManagedKeyDataCacheEntry(byte[] keyCustodian, String keyNamespace, String keyMetadata)
072    throws IOException;
073
074  /**
075   * Clear all entries in the managed key data cache on all live region servers.
076   * @throws IOException if an error occurs while clearing the cache
077   */
078  void clearManagedKeyDataCache() throws IOException;
079
080  /**
081   * Disables key management for the specified custodian and namespace. This marks any ACTIVE keys
082   * as INACTIVE and adds a DISABLED state marker such that no new ACTIVE key is retrieved, so the
083   * new data written will not be encrypted.
084   * @param keyCust      The key custodian identifier.
085   * @param keyNamespace The namespace for the key management.
086   * @return The {@link ManagedKeyData} object identifying the previously active key and its current
087   *         state.
088   * @throws IOException  if an error occurs while disabling key management.
089   * @throws KeyException if an error occurs while disabling key management.
090   */
091  ManagedKeyData disableKeyManagement(byte[] keyCust, String keyNamespace)
092    throws IOException, KeyException;
093
094  /**
095   * Disables the specific managed key identified by the specified custodian, namespace, and
096   * metadata hash.
097   * @param keyCust         The key custodian identifier.
098   * @param keyNamespace    The namespace for the key management.
099   * @param keyMetadataHash The key metadata hash.
100   * @return A {@link ManagedKeyData} object identifying the key and its current status.
101   * @throws IOException  if an error occurs while disabling the managed key.
102   * @throws KeyException if an error occurs while disabling the managed key.
103   */
104  ManagedKeyData disableManagedKey(byte[] keyCust, String keyNamespace, byte[] keyMetadataHash)
105    throws IOException, KeyException;
106
107  /**
108   * Attempt a key rotation for the active key of the specified custodian and namespace.
109   * @param keyCust      The key custodian identifier.
110   * @param keyNamespace The namespace for the key management.
111   * @return A {@link ManagedKeyData} object identifying the key and its current status.
112   * @throws IOException  if an error occurs while rotating the managed key.
113   * @throws KeyException if an error occurs while rotating the managed key.
114   */
115  ManagedKeyData rotateManagedKey(byte[] keyCust, String keyNamespace)
116    throws IOException, KeyException;
117
118  /**
119   * Refresh all the keymeta entries for the specified custodian and namespace.
120   * @param keyCust      The key custodian identifier.
121   * @param keyNamespace The namespace for the key management.
122   * @throws IOException  if an error occurs while refreshing managed keys.
123   * @throws KeyException if an error occurs while refreshing managed keys.
124   */
125  void refreshManagedKeys(byte[] keyCust, String keyNamespace) throws IOException, KeyException;
126}