1 /* 2 * Copyright (c) 1996, 2017, 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 * 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}/../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 @SuppressWarnings("serial") // serialVersionUID in an interface is ineffectual 113 static final long serialVersionUID = 6603384152749567654L; 114 115 /** 116 * Returns the standard algorithm name for this key. For 117 * example, "DSA" would indicate that this key is a DSA key. 118 * See the <a href= 119 * "{@docRoot}/../specs/security/standard-names.html"> 120 * Java Security Standard Algorithm Names</a> document 121 * for more information. 122 * 123 * @return the name of the algorithm associated with this key. 124 */ 125 public String getAlgorithm(); 126 127 /** 128 * Returns the name of the primary encoding format of this key, 129 * or null if this key does not support encoding. 130 * The primary encoding format is 131 * named in terms of the appropriate ASN.1 data format, if an 132 * ASN.1 specification for this key exists. 133 * For example, the name of the ASN.1 data format for public 134 * keys is <I>SubjectPublicKeyInfo</I>, as 135 * defined by the X.509 standard; in this case, the returned format is 136 * {@code "X.509"}. Similarly, 137 * the name of the ASN.1 data format for private keys is 138 * <I>PrivateKeyInfo</I>, 139 * as defined by the PKCS #8 standard; in this case, the returned format is 140 * {@code "PKCS#8"}. 141 * 142 * @return the primary encoding format of the key. 143 */ 144 public String getFormat(); 145 146 /** 147 * Returns the key in its primary encoding format, or null 148 * if this key does not support encoding. 149 * 150 * @return the encoded key, or null if the key does not support 151 * encoding. 152 */ 153 public byte[] getEncoded(); 154 }