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="{@docRoot}openjdk-redirect.html?v=8&path=/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 * "{@docRoot}openjdk-redirect.html?v=8&path=/technotes/guides/security/crypto/CryptoSpec.html#AppA"> 119 * Java Cryptography Architecture API Specification & Reference </a> 120 * for information about standard algorithm names. 121 * 122 * @return the name of the algorithm associated with this key. 123 */ getAlgorithm()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 */ getFormat()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 */ getEncoded()152 public byte[] getEncoded(); 153 } 154