1 /* 2 * Copyright (c) 2000, 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 sun.security.jgss.spi; 27 28 import org.ietf.jgss.*; 29 import java.security.Provider; 30 31 /** 32 * This interface is implemented by the factory class for every 33 * plugin mechanism. The GSSManager locates an implementation of this 34 * interface by querying the security providers installed on the 35 * system. For a provider to support a mechanism defined by Oid x.y.z, 36 * the provider master file would have to contain a mapping from the 37 * property "GssApiMechanism.x.y.z" to an implementation class that serves 38 * as the factory for that mechanism. 39 * <p> 40 * e.g., If a provider master file contained the a mapping from the 41 * property "GssApiMechanism.1.2.840.113554.1.2.2" to the class name 42 * "com.foo.krb5.Krb5GssFactory", then the GSS-API framework would assume 43 * that com.foo.krb5.Krb5GssFactory implements the MechanismFactory 44 * interface and that it can be used to obtain elements required by for 45 * supporting this mechanism. 46 * 47 * @author Mayank Upadhyay 48 */ 49 50 public interface MechanismFactory { 51 52 /** 53 * Returns the Oid of the mechanism that this factory supports. 54 * @return the Oid 55 */ getMechanismOid()56 public Oid getMechanismOid(); 57 58 /** 59 * Returns the provider that this factory came from. 60 * @return the provider 61 */ getProvider()62 public Provider getProvider(); 63 64 /** 65 * Returns the GSS-API nametypes that this mechanism can 66 * support. Having this method helps the GSS-Framework decide quickly 67 * if a certain mechanism can be skipped when importing a name. 68 * @return an array of the Oid's corresponding to the different GSS-API 69 * nametypes supported 70 * @see org.ietf.jgss.GSSName 71 */ getNameTypes()72 public Oid[] getNameTypes() throws GSSException; 73 74 /** 75 * Creates a credential element for this mechanism to be included as 76 * part of a GSSCredential implementation. A GSSCredential is 77 * conceptually a container class of several credential elements from 78 * different mechanisms. A GSS-API credential can be used either for 79 * initiating GSS security contexts or for accepting them. This method 80 * also accepts parameters that indicate what usage is expected and how 81 * long the life of the credential should be. It is not necessary that 82 * the mechanism honor the request for lifetime. An application will 83 * always query an acquired GSSCredential to determine what lifetime it 84 * got back.<p> 85 * 86 * <b>Not all mechanisms support the concept of one credential element 87 * that can be used for both initiating and accepting a context. In the 88 * event that an application requests usage INITIATE_AND_ACCEPT for a 89 * credential from such a mechanism, the GSS framework will need to 90 * obtain two different credential elements from the mechanism, one 91 * that will have usage INITIATE_ONLY and another that will have usage 92 * ACCEPT_ONLY. The mechanism will help the GSS-API realize this by 93 * returning a credential element with usage INITIATE_ONLY or 94 * ACCEPT_ONLY prompting it to make another call to 95 * getCredentialElement, this time with the other usage mode. The 96 * mechanism indicates the missing mode by returning a 0 lifetime for 97 * it.</b> 98 * 99 * @param name the mechanism level name element for the entity whose 100 * credential is desired. A null value indicates that a mechanism 101 * dependent default choice is to be made. 102 * @param initLifetime indicates the lifetime (in seconds) that is 103 * requested for this credential to be used at the context initiator's 104 * end. This value should be ignored if the usage is 105 * ACCEPT_ONLY. Predefined contants are available in the 106 * org.ietf.jgss.GSSCredential interface. 107 * @param acceptLifetime indicates the lifetime (in seconds) that is 108 * requested for this credential to be used at the context acceptor's 109 * end. This value should be ignored if the usage is 110 * INITIATE_ONLY. Predefined contants are available in the 111 * org.ietf.jgss.GSSCredential interface. 112 * @param usage One of the values GSSCredential.INIATE_ONLY, 113 * GSSCredential.ACCEPT_ONLY, and GSSCredential.INITIATE_AND_ACCEPT. 114 * @see org.ietf.jgss.GSSCredential 115 * @throws GSSException if one of the error situations described in RFC 116 * 2743 with the GSS_Acquire_Cred or GSS_Add_Cred calls occurs. 117 */ getCredentialElement(GSSNameSpi name, int initLifetime, int acceptLifetime, int usage)118 public GSSCredentialSpi getCredentialElement(GSSNameSpi name, 119 int initLifetime, int acceptLifetime, int usage) throws GSSException; 120 121 /** 122 * Creates a name element for this mechanism to be included as part of 123 * a GSSName implementation. A GSSName is conceptually a container 124 * class of several name elements from different mechanisms. A GSSName 125 * can be created either with a String or with a sequence of 126 * bytes. This factory method accepts the name in a String. Such a name 127 * can generally be assumed to be printable and may be returned from 128 * the name element's toString() method. 129 * 130 * @param nameStr a string containing the characters describing this 131 * entity to the mechanism 132 * @param nameType an Oid serving as a clue as to how the mechanism should 133 * interpret the nameStr 134 * @throws GSSException if any of the errors described in RFC 2743 for 135 * the GSS_Import_Name or GSS_Canonicalize_Name calls occur. 136 */ getNameElement(String nameStr, Oid nameType)137 public GSSNameSpi getNameElement(String nameStr, Oid nameType) 138 throws GSSException; 139 140 /** 141 * This is a variation of the factory method that accepts a String for 142 * the characters that make up the name. Usually the String characters 143 * are assumed to be printable. The bytes passed in to this method have 144 * to be converted to characters using some encoding of the mechanism's 145 * choice. It is recommended that UTF-8 be used. (Note that UTF-8 146 * preserves the encoding for 7-bit ASCII characters.) 147 * <p> 148 * An exported name will generally be passed in using this method. 149 * 150 * @param name the bytes describing this entity to the mechanism 151 * @param nameType an Oid serving as a clue as to how the mechanism should 152 * interpret the nameStr 153 * @throws GSSException if any of the errors described in RFC 2743 for 154 * the GSS_Import_Name or GSS_Canonicalize_Name calls occur. 155 */ getNameElement(byte[] name, Oid nameType)156 public GSSNameSpi getNameElement(byte[] name, Oid nameType) 157 throws GSSException; 158 159 /** 160 * Creates a security context for this mechanism so that it can be used 161 * on the context initiator's side. 162 * 163 * @param peer the name element from this mechanism that represents the 164 * peer 165 * @param myInitiatorCred a credential element for the context 166 * initiator obtained previously from this mechanism. The identity of 167 * the context initiator can be obtained from this credential. Passing 168 * a value of null here indicates that a default entity of the 169 * mechanism's choice should be assumed to be the context initiator and 170 * that default credentials should be applied. 171 * @param lifetime the requested lifetime (in seconds) for the security 172 * context. Predefined contants are available in the 173 * org.ietf.jgss.GSSContext interface. 174 * @throws GSSException if any of the errors described in RFC 2743 in 175 * the GSS_Init_Sec_Context call occur. 176 */ getMechanismContext(GSSNameSpi peer, GSSCredentialSpi myInitiatorCred, int lifetime)177 public GSSContextSpi getMechanismContext(GSSNameSpi peer, 178 GSSCredentialSpi myInitiatorCred, 179 int lifetime) throws GSSException; 180 181 /** 182 * Creates a security context for this mechanism so thatit can be used 183 * on the context acceptor's side. 184 * 185 * @param myAcceptorCred a credential element for the context acceptor 186 * obtained previously from this mechanism. The identity of the context 187 * acceptor cna be obtained from this credential. Passing a value of 188 * null here indicates that tha default entity of the mechanism's 189 * choice should be assumed to be the context acceptor and default 190 * credentials should be applied. 191 * 192 * @throws GSSException if any of the errors described in RFC 2743 in 193 * the GSS_Accept_Sec_Context call occur. 194 */ getMechanismContext(GSSCredentialSpi myAcceptorCred)195 public GSSContextSpi getMechanismContext(GSSCredentialSpi myAcceptorCred) 196 throws GSSException; 197 198 /** 199 * Creates a security context from a previously exported (serialized) 200 * security context. Note that this is different from Java 201 * serialization and is defined at a mechanism level to interoperate 202 * over the wire with non-Java implementations. Either the initiator or 203 * the acceptor can export and then import a security context. 204 * Implementations of mechanism contexts are not required to implement 205 * exporting and importing. 206 * 207 * @param exportedContext the bytes representing this security context 208 * @throws GSSException is any of the errors described in RFC 2743 in 209 * the GSS_Import_Sec_Context call occur. 210 */ getMechanismContext(byte[] exportedContext)211 public GSSContextSpi getMechanismContext(byte[] exportedContext) 212 throws GSSException; 213 214 } 215