1 /* 2 * Copyright (c) 1996, 2013, 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. 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} or PKCS#8), and 51 * is returned using the {@link #getEncoded() getEncoded} method. 52 * Note: The syntax of the ASN.1 type {@code SubjectPublicKeyInfo} 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 * 69 * <LI>A Format 70 * 71 * <P>This is the name of the format of the encoded key. It is returned 72 * by the {@link #getFormat() getFormat} method. 73 * 74 * </UL> 75 * 76 * Keys are generally obtained through key generators, certificates, 77 * or various Identity classes used to manage keys. 78 * Keys may also be obtained from key specifications (transparent 79 * representations of the underlying key material) through the use of a key 80 * factory (see {@link KeyFactory}). 81 * 82 * <p> A Key should use KeyRep as its serialized representation. 83 * Note that a serialized Key may contain sensitive information 84 * which should not be exposed in untrusted environments. See the 85 * <a href="{@docRoot}openjdk-redirect.html?v=8&path=/platform/serialization/spec/security.html"> 86 * Security Appendix</a> 87 * of the Serialization Specification for more information. 88 * 89 * @see PublicKey 90 * @see PrivateKey 91 * @see KeyPair 92 * @see KeyPairGenerator 93 * @see KeyFactory 94 * @see KeyRep 95 * @see java.security.spec.KeySpec 96 * @see Identity 97 * @see Signer 98 * 99 * @author Benjamin Renaud 100 */ 101 102 public interface Key extends java.io.Serializable { 103 104 // Declare serialVersionUID to be compatible with JDK1.1 105 106 /** 107 * The class fingerprint that is set to indicate 108 * serialization compatibility with a previous 109 * version of the class. 110 */ 111 static final long serialVersionUID = 6603384152749567654L; 112 113 /** 114 * Returns the standard algorithm name for this key. For 115 * example, "DSA" would indicate that this key is a DSA key. 116 * See Appendix A in the <a href= 117 * "{@docRoot}openjdk-redirect.html?v=8&path=/technotes/guides/security/crypto/CryptoSpec.html#AppA"> 118 * Java Cryptography Architecture API Specification & Reference </a> 119 * for information about standard algorithm names. 120 * 121 * @return the name of the algorithm associated with this key. 122 */ getAlgorithm()123 public String getAlgorithm(); 124 125 /** 126 * Returns the name of the primary encoding format of this key, 127 * or null if this key does not support encoding. 128 * The primary encoding format is 129 * named in terms of the appropriate ASN.1 data format, if an 130 * ASN.1 specification for this key exists. 131 * For example, the name of the ASN.1 data format for public 132 * keys is <I>SubjectPublicKeyInfo</I>, as 133 * defined by the X.509 standard; in this case, the returned format is 134 * {@code "X.509"}. Similarly, 135 * the name of the ASN.1 data format for private keys is 136 * <I>PrivateKeyInfo</I>, 137 * as defined by the PKCS #8 standard; in this case, the returned format is 138 * {@code "PKCS#8"}. 139 * 140 * @return the primary encoding format of the key. 141 */ getFormat()142 public String getFormat(); 143 144 /** 145 * Returns the key in its primary encoding format, or null 146 * if this key does not support encoding. 147 * 148 * @return the encoded key, or null if the key does not support 149 * encoding. 150 */ getEncoded()151 public byte[] getEncoded(); 152 } 153