1 /*
   2  * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.security;
  27 
  28 /**
  29  * The Key interface is the top-level interface for all keys. It
  30  * defines the functionality shared by all key objects. All keys
  31  * have three characteristics:
  32  *
  33  * <UL>
  34  *
  35  * <LI>An Algorithm
  36  *
  37  * <P>This is the key algorithm for that key. The key algorithm is usually
  38  * an encryption or asymmetric operation algorithm (such as DSA or
  39  * RSA), which will work with those algorithms and with related
  40  * algorithms (such as MD5 with RSA, SHA-1 with RSA, Raw DSA, etc.)
  41  * The name of the algorithm of a key is obtained using the
  42  * {@link #getAlgorithm() getAlgorithm} method.<P>
  43  *
  44  * <LI>An Encoded Form
  45  *
  46  * <P>This is an external encoded form for the key used when a standard
  47  * representation of the key is needed outside the Java Virtual Machine,
  48  * as when transmitting the key to some other party. The key
  49  * is encoded according to a standard format (such as
  50  * X.509 <code>SubjectPublicKeyInfo</code> or PKCS#8), and
  51  * is returned using the {@link #getEncoded() getEncoded} method.
  52  * Note: The syntax of the ASN.1 type <code>SubjectPublicKeyInfo</code>
  53  * is defined as follows:
  54  *
  55  * <pre>
  56  * SubjectPublicKeyInfo ::= SEQUENCE {
  57  *   algorithm AlgorithmIdentifier,
  58  *   subjectPublicKey BIT STRING }
  59  *
  60  * AlgorithmIdentifier ::= SEQUENCE {
  61  *   algorithm OBJECT IDENTIFIER,
  62  *   parameters ANY DEFINED BY algorithm OPTIONAL }
  63  * </pre>
  64  *
  65  * For more information, see
  66  * <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280:
  67  * Internet X.509 Public Key Infrastructure Certificate and CRL Profile</a>.
  68  * <P>
  69  *
  70  * <LI>A Format
  71  *
  72  * <P>This is the name of the format of the encoded key. It is returned
  73  * by the {@link #getFormat() getFormat} method.<P>
  74  *
  75  * </UL>
  76  *
  77  * Keys are generally obtained through key generators, certificates,
  78  * or various Identity classes used to manage keys.
  79  * Keys may also be obtained from key specifications (transparent
  80  * representations of the underlying key material) through the use of a key
  81  * factory (see {@link KeyFactory}).
  82  *
  83  * <p> A Key should use KeyRep as its serialized representation.
  84  * Note that a serialized Key may contain sensitive information
  85  * which should not be exposed in untrusted environments.  See the
  86  * <a href="../../../platform/serialization/spec/security.html">
  87  * Security Appendix</a>
  88  * of the Serialization Specification for more information.
  89  *
  90  * @see PublicKey
  91  * @see PrivateKey
  92  * @see KeyPair
  93  * @see KeyPairGenerator
  94  * @see KeyFactory
  95  * @see KeyRep
  96  * @see java.security.spec.KeySpec
  97  * @see Identity
  98  * @see Signer
  99  *
 100  * @author Benjamin Renaud
 101  */
 102 
 103 public interface Key extends java.io.Serializable {
 104 
 105     // Declare serialVersionUID to be compatible with JDK1.1
 106 
 107    /**
 108     * The class fingerprint that is set to indicate
 109     * serialization compatibility with a previous
 110     * version of the class.
 111     */
 112     static final long serialVersionUID = 6603384152749567654L;
 113 
 114     /**
 115      * Returns the standard algorithm name for this key. For
 116      * example, "DSA" would indicate that this key is a DSA key.
 117      * See Appendix A in the <a href=
 118      * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
 119      * Java Cryptography Architecture API Specification &amp; Reference </a>
 120      * for information about standard algorithm names.
 121      *
 122      * @return the name of the algorithm associated with this key.
 123      */
 124     public String getAlgorithm();
 125 
 126     /**
 127      * Returns the name of the primary encoding format of this key,
 128      * or null if this key does not support encoding.
 129      * The primary encoding format is
 130      * named in terms of the appropriate ASN.1 data format, if an
 131      * ASN.1 specification for this key exists.
 132      * For example, the name of the ASN.1 data format for public
 133      * keys is <I>SubjectPublicKeyInfo</I>, as
 134      * defined by the X.509 standard; in this case, the returned format is
 135      * <code>"X.509"</code>. Similarly,
 136      * the name of the ASN.1 data format for private keys is
 137      * <I>PrivateKeyInfo</I>,
 138      * as defined by the PKCS #8 standard; in this case, the returned format is
 139      * <code>"PKCS#8"</code>.
 140      *
 141      * @return the primary encoding format of the key.
 142      */
 143     public String getFormat();
 144 
 145     /**
 146      * Returns the key in its primary encoding format, or null
 147      * if this key does not support encoding.
 148      *
 149      * @return the encoded key, or null if the key does not support
 150      * encoding.
 151      */
 152     public byte[] getEncoded();
 153 }