Save This Page
Home » openjdk-7 » java » security » [javadoc | source]
    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   }

Save This Page
Home » openjdk-7 » java » security » [javadoc | source]