http://github.com/google/tink: Tink is a small cryptographic library that provides a safe, simple, agile and fast way to accomplish some common cryptographic tasks. 
// Copyright 2017 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////

package com.google.crypto.tink;

import com.google.crypto.tink.proto.KeyData;
import com.google.protobuf.ByteString;
import com.google.protobuf.MessageLite;
import java.security.GeneralSecurityException;


A KeyManager "understands" keys of a specific key type: it can generate keys of the supported
type and create primitives for supported keys.

A key type is identified by the global name of the protocol buffer that holds the corresponding key material, and is given by typeUrl-field of KeyData-protocol buffer. 
The template parameter P denotes the primitive corresponding to the keys handled by this manager. 
Since:1.0.0
/**
 * A KeyManager "understands" keys of a specific key type: it can generate keys of the supported
 * type and create primitives for supported keys.
 *
 * <p>A key type is identified by the global name of the protocol buffer that holds the
 * corresponding key material, and is given by {@code typeUrl}-field of {@link KeyData}-protocol
 * buffer.
 *
 * <p>The template parameter {@code P} denotes the primitive corresponding to the keys handled by
 * this manager.
 *
 * @since 1.0.0
 */
public interface KeyManager<P> {
  // APIs for primitive development

  
Constructs an instance of P for the key given in serializedKey, which must be a serialized key protocol buffer handled by this manager. 
Throws:
Returns:the new constructed P
/**
   * Constructs an instance of P for the key given in {@code serializedKey}, which must be a
   * serialized key protocol buffer handled by this manager.
   *
   * @return the new constructed P
   * @throws GeneralSecurityException if the key given in {@code serializedKey} is corrupted or not
   *     supported
   */
  P getPrimitive(ByteString serializedKey) throws GeneralSecurityException;

  
Constructs an instance of P for the key given in key. 
Throws:
Returns:the new constructed P
/**
   * Constructs an instance of P for the key given in {@code key}.
   *
   * @return the new constructed P
   * @throws GeneralSecurityException if the key given in {@code key} is corrupted or not supported
   */
  P getPrimitive(MessageLite key) throws GeneralSecurityException;

  
Generates a new key according to specification in serializedKeyFormat, which must be a serialized key format protocol buffer handled by this manager. 
Throws:
Returns:the new generated key
/**
   * Generates a new key according to specification in {@code serializedKeyFormat}, which must be a
   * serialized key format protocol buffer handled by this manager.
   *
   * @return the new generated key
   * @throws GeneralSecurityException if the specified format is wrong or not supported
   */
  MessageLite newKey(ByteString serializedKeyFormat) throws GeneralSecurityException;

  
Generates a new key according to specification in keyFormat. 
Throws:
Returns:the new generated key
/**
   * Generates a new key according to specification in {@code keyFormat}.
   *
   * @return the new generated key
   * @throws GeneralSecurityException if the specified format is wrong or not supported
   */
  MessageLite newKey(MessageLite keyFormat) throws GeneralSecurityException;

  
Returns:true iff this KeyManager supports key type identified by typeUrl.
/** @return true iff this KeyManager supports key type identified by {@code typeUrl}. */
  boolean doesSupport(String typeUrl);

  
Returns:the type URL that identifies the key type of keys managed by this KeyManager.
/** @return the type URL that identifies the key type of keys managed by this KeyManager. */
  String getKeyType();

  
Returns:the version number of this KeyManager.
/** @return the version number of this KeyManager. */
  int getVersion();

  
Returns the primitive class object of the P. Should be implemented as return P.class; when implementing a key manager for primitive {$code P}. 
Returns:P.class
/**
   * Returns the primitive class object of the P. Should be implemented as {@code return P.class;}
   * when implementing a key manager for primitive {$code P}.
   *
   * @return {@code P.class}
   */
  Class<P> getPrimitiveClass();

  // APIs for Key Management

  
Generates a new KeyData according to specification in serializedkeyFormat. 
This should be used solely by KeysetManager. 
Throws:
Returns:the new generated key
/**
   * Generates a new {@code KeyData} according to specification in {@code serializedkeyFormat}.
   *
   * <p>This should be used solely by {@link KeysetManager}.
   *
   * @return the new generated key
   * @throws GeneralSecurityException if the specified format is wrong or not supported
   */
  KeyData newKeyData(ByteString serializedKeyFormat) throws GeneralSecurityException;
}