1 /* 2 * @(#)Key.java 1.54 03/12/19 3 * 4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.security; 9 10 /** 11 * The Key interface is the top-level interface for all keys. It 12 * defines the functionality shared by all key objects. All keys 13 * have three characteristics: 14 * 15 * <UL> 16 * 17 * <LI>An Algorithm 18 * 19 * <P>This is the key algorithm for that key. The key algorithm is usually 20 * an encryption or asymmetric operation algorithm (such as DSA or 21 * RSA), which will work with those algorithms and with related 22 * algorithms (such as MD5 with RSA, SHA-1 with RSA, Raw DSA, etc.) 23 * The name of the algorithm of a key is obtained using the 24 * {@link #getAlgorithm() getAlgorithm} method.<P> 25 * 26 * <LI>An Encoded Form 27 * 28 * <P>This is an external encoded form for the key used when a standard 29 * representation of the key is needed outside the Java Virtual Machine, 30 * as when transmitting the key to some other party. The key 31 * is encoded according to a standard format (such as 32 * X.509 <code>SubjectPublicKeyInfo</code> or PKCS#8), and 33 * is returned using the {@link #getEncoded() getEncoded} method. 34 * Note: The syntax of the ASN.1 type <code>SubjectPublicKeyInfo</code> 35 * is defined as follows: 36 * 37 * <pre> 38 * SubjectPublicKeyInfo ::= SEQUENCE { 39 * algorithm AlgorithmIdentifier, 40 * subjectPublicKey BIT STRING } 41 * 42 * AlgorithmIdentifier ::= SEQUENCE { 43 * algorithm OBJECT IDENTIFIER, 44 * parameters ANY DEFINED BY algorithm OPTIONAL } 45 * </pre> 46 * 47 * For more information, see 48 * <a HREF="http://www.ietf.org/rfc/rfc2459.txt">RFC 2459: 49 * Internet X.509 Public Key Infrastructure Certificate and CRL Profile</a>. 50 * <P> 51 * 52 * <LI>A Format 53 * 54 * <P>This is the name of the format of the encoded key. It is returned 55 * by the {@link #getFormat() getFormat} method.<P> 56 * 57 * </UL> 58 * 59 * Keys are generally obtained through key generators, certificates, 60 * or various Identity classes used to manage keys. 61 * Keys may also be obtained from key specifications (transparent 62 * representations of the underlying key material) through the use of a key 63 * factory (see {@link KeyFactory}). 64 * 65 * <p> A Key should use KeyRep as its serialized representation. 66 * Note that a serialized Key may contain sensitive information 67 * which should not be exposed in untrusted environments. See the 68 * <a HREF="../../../guide/serialization/spec/security.html"> 69 * Security Appendix</a> 70 * of the Serialization Specification for more information. 71 * 72 * @see PublicKey 73 * @see PrivateKey 74 * @see KeyPair 75 * @see KeyPairGenerator 76 * @see KeyFactory 77 * @see KeyRep 78 * @see java.security.spec.KeySpec 79 * @see Identity 80 * @see Signer 81 * 82 * @version 1.54 03/12/19 83 * @author Benjamin Renaud 84 */ 85 86 public interface Key extends java.io.Serializable { 87 88 // Declare serialVersionUID to be compatible with JDK1.1 89 90 /** 91 * The class fingerprint that is set to indicate 92 * serialization compatibility with a previous 93 * version of the class. 94 */ 95 static final long serialVersionUID = 6603384152749567654L; 96 97 /** 98 * Returns the standard algorithm name for this key. For 99 * example, "DSA" would indicate that this key is a DSA key. 100 * See Appendix A in the <a HREF= 101 * "../../../guide/security/CryptoSpec.html#AppA"> 102 * Java Cryptography Architecture API Specification & Reference </a> 103 * for information about standard algorithm names. 104 * 105 * @return the name of the algorithm associated with this key. 106 */ 107 public String getAlgorithm(); 108 109 /** 110 * Returns the name of the primary encoding format of this key, 111 * or null if this key does not support encoding. 112 * The primary encoding format is 113 * named in terms of the appropriate ASN.1 data format, if an 114 * ASN.1 specification for this key exists. 115 * For example, the name of the ASN.1 data format for public 116 * keys is <I>SubjectPublicKeyInfo</I>, as 117 * defined by the X.509 standard; in this case, the returned format is 118 * <code>"X.509"</code>. Similarly, 119 * the name of the ASN.1 data format for private keys is 120 * <I>PrivateKeyInfo</I>, 121 * as defined by the PKCS #8 standard; in this case, the returned format is 122 * <code>"PKCS#8"</code>. 123 * 124 * @return the primary encoding format of the key. 125 */ 126 public String getFormat(); 127 128 /** 129 * Returns the key in its primary encoding format, or null 130 * if this key does not support encoding. 131 * 132 * @return the encoded key, or null if the key does not support 133 * encoding. 134 */ 135 public byte[] getEncoded(); 136 } 137