1 /* 2 * Copyright (c) 1996, 2019, 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://tools.ietf.org/html/rfc5280">RFC 5280: 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 * key stores or other 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}/../specs/serialization/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 * @since 1.1 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 * @deprecated A {@code serialVersionUID} field in an interface is 113 * ineffectual. Do not use; no replacement. 114 */ 115 @Deprecated 116 @SuppressWarnings("serial") 117 @java.io.Serial 118 static final long serialVersionUID = 6603384152749567654L; 119 120 /** 121 * Returns the standard algorithm name for this key. For 122 * example, "DSA" would indicate that this key is a DSA key. 123 * See the key related sections (KeyFactory, KeyGenerator, 124 * KeyPairGenerator, and SecretKeyFactory) in the <a href= 125 * "{@docRoot}/../specs/security/standard-names.html"> 126 * Java Security Standard Algorithm Names Specification</a> 127 * for information about standard key algorithm names. 128 * 129 * @return the name of the algorithm associated with this key. 130 */ getAlgorithm()131 public String getAlgorithm(); 132 133 /** 134 * Returns the name of the primary encoding format of this key, 135 * or null if this key does not support encoding. 136 * The primary encoding format is 137 * named in terms of the appropriate ASN.1 data format, if an 138 * ASN.1 specification for this key exists. 139 * For example, the name of the ASN.1 data format for public 140 * keys is <I>SubjectPublicKeyInfo</I>, as 141 * defined by the X.509 standard; in this case, the returned format is 142 * {@code "X.509"}. Similarly, 143 * the name of the ASN.1 data format for private keys is 144 * <I>PrivateKeyInfo</I>, 145 * as defined by the PKCS #8 standard; in this case, the returned format is 146 * {@code "PKCS#8"}. 147 * 148 * @return the primary encoding format of the key. 149 */ getFormat()150 public String getFormat(); 151 152 /** 153 * Returns the key in its primary encoding format, or null 154 * if this key does not support encoding. 155 * 156 * @return the encoded key, or null if the key does not support 157 * encoding. 158 */ getEncoded()159 public byte[] getEncoded(); 160 } 161