001: /*
002:
003: * $Id: SecurityEnvironment.java,v 1.11 2007/09/13 12:42:20 kumarjayanti Exp $
004: */
005:
006: /*
007: * The contents of this file are subject to the terms
008: * of the Common Development and Distribution License
009: * (the License). You may not use this file except in
010: * compliance with the License.
011: *
012: * You can obtain a copy of the license at
013: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
014: * See the License for the specific language governing
015: * permissions and limitations under the License.
016: *
017: * When distributing Covered Code, include this CDDL
018: * Header Notice in each file and include the License file
019: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
020: * If applicable, add the following below the CDDL Header,
021: * with the fields enclosed by brackets [] replaced by
022: * you own identifying information:
023: * "Portions Copyrighted [year] [name of copyright owner]"
024: *
025: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
026: */
027:
028: package com.sun.xml.wss;
029:
030: import java.math.BigInteger;
031: import java.security.PrivateKey;
032: import java.security.PublicKey;
033: import java.security.cert.X509Certificate;
034:
035: import javax.security.auth.Subject;
036: import javax.security.auth.callback.CallbackHandler;
037:
038: import javax.crypto.SecretKey;
039:
040: import com.sun.xml.wss.core.Timestamp;
041: import com.sun.xml.wss.saml.Assertion;
042:
043: import com.sun.xml.wss.impl.policy.mls.AuthenticationTokenPolicy;
044: import com.sun.xml.wss.impl.configuration.DynamicApplicationContext;
045: import javax.xml.stream.XMLStreamReader;
046:
047: import org.w3c.dom.Element;
048: import org.w3c.dom.Document;
049:
050: import java.util.Map;
051:
052: /**
053: * The SecurityEnvironment interface links the XWS-Security runtime with the
054: * environment/container in which it is running. The SecurityEnvironment interface
055: * is invoked by the XWS-Security runtime to perform tasks such as retrieving keys,
056: * validating tokens etc.
057: *<P>
058: * When using the XWS-Security configuration files with <xwss:JAXRPCSecurity> as
059: * the root element, a default implementation of this interface wraps the supplied CallbackHandler.
060: * The default implemenation of this interface bundled with XWS-Security invokes the CallbackHandler
061: * to implement the methods of this interface.
062: *<P>
063: * This interface facilitates usage of XWS-Security in environments which do not necessarily have a
064: * natural mapping to the XWS-Security defined callbacks.
065: *<P>
066: * There is generally a single SecurityEnvironment instance per-application, which is initialized at application startup.
067: *<P>
068: *Note: This interface is evolving and is subject to change in a later release
069: */
070: public interface SecurityEnvironment {
071:
072: /**
073: * Retrieves a reasonable default value for the current user's
074: * X509Certificate if one exists.
075: * @param context a Map of application and integration-layer specific properties
076: * @return the default certificate for the current user
077: * @throws XWSSecurityException
078: */
079: public X509Certificate getDefaultCertificate(Map context)
080: throws XWSSecurityException;
081:
082: /**
083: * @return the certificate corresponding to the alias
084: *
085: * @param context a Map of application and integration-layer specific properties
086: * @param alias the alias for identifying the certificate
087: * @param forSigning whether this request is for a Sign operation or Encrypt
088: * @exception XWSSecurityException if there was an error while trying to locate the Cerificate
089: */
090: public X509Certificate getCertificate(Map context, String alias,
091: boolean forSigning) throws XWSSecurityException;
092:
093: /**
094: *@return the SecretKey corresponding to the alias
095: *@param context a Map of application and integration-layer specific properties
096: *@param alias the alias for identifying the SecretKey
097: *@param encryptMode whether this request is for an Encrypt or Decrypt operation
098: *@exception XWSSecurityException if there was an error while trying to locate the SecretKey
099: */
100: public SecretKey getSecretKey(Map context, String alias,
101: boolean encryptMode) throws XWSSecurityException;
102:
103: /**
104: *@return the PrivateKey corresponding to the alias
105: *@param context a Map of application and integration-layer specific properties
106: *@param alias the alias for identifying the PrivateKey
107: *@exception XWSSecurityException if there was an error while trying to locate the PrivateKey
108: */
109: public PrivateKey getPrivateKey(Map context, String alias)
110: throws XWSSecurityException;
111:
112: /**
113: * @return the PublicKey corresponding to a KeyIdentifier
114: * @param context a Map of application and integration-layer specific properties
115: * @param keyIdentifier an Opaque identifier indicating
116: * the X509 certificate.
117: * @exception XWSSecurityException if there was an error while trying to locate the PublicKey
118: */
119: public PublicKey getPublicKey(Map context, byte[] keyIdentifier)
120: throws XWSSecurityException;
121:
122: public PublicKey getPublicKey(Map context, byte[] keyIdentifier,
123: String valueType) throws XWSSecurityException;
124:
125: /**
126: * @return the X509Certificate corresponding to a KeyIdentifier
127: * @param context a Map of application and integration-layer specific properties
128: * @param keyIdentifier an Opaque identifier indicating
129: * the X509 certificate.
130: * @exception XWSSecurityException if there was an error while trying to locate the X509Certificate
131: */
132: public X509Certificate getCertificate(Map context,
133: byte[] keyIdentifier) throws XWSSecurityException;
134:
135: /**
136: * @return the X509Certificate corresponding to a KeyIdentifier
137: * @param context a Map of application and integration-layer specific properties
138: * @param identifier an Opaque identifier indicating the X509 certificate.
139: * @param valueType
140: * @exception XWSSecurityException if there was an error while trying to locate the X509Certificate
141: */
142: public X509Certificate getCertificate(Map context,
143: byte[] identifier, String valueType)
144: throws XWSSecurityException;
145:
146: /**
147: * @return the PrivateKey corresponding to the X509Certificate
148: * @param context a Map of application and integration-layer specific properties
149: * @param cert the X509Certificate
150: * @throws XWSSecurityException if there was an error while trying to locate the PrivateKey
151: */
152: public PrivateKey getPrivateKey(Map context, X509Certificate cert)
153: throws XWSSecurityException;
154:
155: /**
156: * @return the PrivateKey corresponding to (serialNumber, issuerName)
157: *
158: * @param context a Map of application and integration-layer specific properties
159: * @param serialNumber the serialNumber of the certificate
160: * @param issuerName the issuerName of the certificate
161: * @throws XWSSecurityException if there was an error while trying to locate the PrivateKey
162: */
163: public PrivateKey getPrivateKey(Map context,
164: BigInteger serialNumber, String issuerName)
165: throws XWSSecurityException;
166:
167: /**
168: * @return the X509Certificate corresponding to a PublicKey
169: *
170: * @param context a Map of application and integration-layer specific properties
171: * @param publicKey the publicKey
172: * @param forSign set to true if the public key is to be used for SignatureVerification
173: * @throws XWSSecurityException if there was an error while trying to locate the PublicKey
174: */
175: public X509Certificate getCertificate(Map context,
176: PublicKey publicKey, boolean forSign)
177: throws XWSSecurityException;
178:
179: /**
180: * @return the PrivateKey corresponding to a KeyIdentifier
181: *
182: * @param context a Map of application and integration-layer specific properties
183: * @param keyIdentifier an Opaque identifier indicating
184: * the X509 certificate.
185: * @throws XWSSecurityException if there was an error while trying to locate the PrivateKey
186: */
187: public PrivateKey getPrivateKey(Map context, byte[] keyIdentifier)
188: throws XWSSecurityException;
189:
190: public PrivateKey getPrivateKey(Map context, byte[] keyIdentifier,
191: String valueType) throws XWSSecurityException;
192:
193: /**
194: * @return the PrivateKey corresponding to a PublicKey
195: *
196: * @param context a Map of application and integration-layer specific properties
197: * @param publicKey the publicKey
198: * @param forSign set to true if the purpose is Signature
199: * @throws XWSSecurityException if there was an error while trying to locate the PrivateKey
200: */
201: public PrivateKey getPrivateKey(Map context, PublicKey publicKey,
202: boolean forSign) throws XWSSecurityException;
203:
204: /**
205: * @return the PublicKey corresponding to (serialNumber, issuerName)
206: *
207: * @param context a Map of application and integration-layer specific properties
208: * @param serialNumber the serialNumber of the certificate
209: * @param issuerName the issuerName of the certificate
210: * @throws XWSSecurityException if there was an error while trying to locate the PublicKey
211: */
212: public PublicKey getPublicKey(Map context, BigInteger serialNumber,
213: String issuerName) throws XWSSecurityException;
214:
215: /**
216: * @return the X509Certificate corresponding to (serialNumber, issuerName)
217: *
218: * @param context a Map of application and integration-layer specific properties
219: * @param serialNumber the serialNumber of the certificate
220: * @param issuerName the issuerName of the certificate
221: * @throws XWSSecurityException if there was an error while trying to locate the X509Certificate
222: */
223: public X509Certificate getCertificate(Map context,
224: BigInteger serialNumber, String issuerName)
225: throws XWSSecurityException;
226:
227: /**
228: * Authenticate the user against a list of known username-password
229: * pairs.
230: *
231: * @param context a Map of application and integration-layer specific properties
232: * @param username the username
233: * @param password the password
234: * @return true if the username-password pair is valid, false otherwise
235: * @throws XWSSecurityException if there was an error while trying to authenticate the username
236: */
237: public boolean authenticateUser(Map context, String username,
238: String password) throws XWSSecurityException;
239:
240: /**
241: * Authenticate the user given the password digest.
242: *
243: * @param context a Map of application and integration-layer specific properties
244: * @param username the username
245: * @param passwordDigest the digested password
246: * @param nonce the nonce which was part of the digest
247: * @param created the creation time which was part of the digest
248: * @return true if the password digest is valid, false otherwise
249: * @throws XWSSecurityException if there was an error while trying to authenticate the username
250: */
251: public boolean authenticateUser(Map context, String username,
252: String passwordDigest, String nonce, String created)
253: throws XWSSecurityException;
254:
255: /**
256: * @return the host/sender Subject,
257: * null if subject is not available/initialized
258: */
259: public Subject getSubject();
260:
261: /**
262: * Validate the creation time. It is an error if the
263: * creation time is older than current local time minus
264: * TIMESTAMP_FRESHNESS_LIMIT minus MAX_CLOCK_SKEW
265: *
266: * @param context a Map of application and integration-layer specific properties
267: * @param creationTime the creation-time value
268: * @param maxClockSkew (in milliseconds) the maximum clockskew
269: * @param timestampFreshnessLimit (in milliseconds) the limit for which timestamps
270: * are considered fresh
271: * @throws XWSSecurityException if there was an error while trying to validate the creationTime
272: */
273: public void validateCreationTime(Map context, String creationTime,
274: long maxClockSkew, long timestampFreshnessLimit)
275: throws XWSSecurityException;
276:
277: /**
278: * Validate the expiration time (wsu:Expires). It is an error if the
279: * expiration time is older than current local time minus MAX_CLOCK_SKEW
280: * @return true if this expiration time is valid
281: * @param expirationTime the expiration-time value
282: * @param maxClockSkew (in milliseconds) the maximum clockskew
283: * @param timestampFreshnessLimit (in milliseconds) the limit for which timestamps
284: * are considered fresh
285: * @throws XWSSecurityException if there was an error while trying to validate the expirationTime
286: */
287: /*public boolean validateExpirationTime(
288: String expirationTime, long maxClockSkew, long timestampFreshnessLimit)
289: throws XWSSecurityException;*/
290:
291: /**
292: * Validate an X509Certificate.
293: * @return true, if the cert is a valid one, false otherwise.
294: * @param cert the X509Certificate to be validated
295: * @throws XWSSecurityException
296: * if there is some problem during validation.
297: */
298: public boolean validateCertificate(X509Certificate cert)
299: throws XWSSecurityException;
300:
301: /**
302: * Update the public/private credentials of the subject of the party
303: * whose username password pair is given.
304: * @param subject the Subject of the requesting party
305: * @param username the username of the requesting party
306: * @param password the password of the requesting party
307: */
308: public void updateOtherPartySubject(Subject subject,
309: String username, String password);
310:
311: /**
312: * Update the public credentials of the subject of the party
313: * whose certificate is given.
314: * @param subject the Subject of the requesting party
315: * @param cert the X509Certificate of the requesting party
316: */
317: public void updateOtherPartySubject(Subject subject,
318: X509Certificate cert);
319:
320: /**
321: * Update the public credentials of the subject of the party
322: * whose Assertion is given.
323: * @param subject the Subject of the requesting party
324: * @param assertion the SAML Assertion of the requesting party
325: */
326:
327: public void updateOtherPartySubject(Subject subject,
328: Assertion assertion);
329:
330: /**
331: * Update the public credentials of the subject of the party
332: * whose Assertion is given.
333: * @param subject the Subject of the requesting party
334: * @param assertion the SAML Assertion of the requesting party
335: */
336:
337: public void updateOtherPartySubject(Subject subject,
338: XMLStreamReader assertion);
339:
340: /**
341: * Update the principal/credentials of the requesting party subject
342: * @param subject the Subject of the requesting party
343: * @param bootStrapSubject the bootstrap Credentials (during a SecureConversation Bootstrap) of the requesting party
344: */
345: public void updateOtherPartySubject(Subject subject,
346: Subject bootStrapSubject);
347:
348: /* The three methods below are required to insulate integrating environments
349: * such as JSR 196 etc from XWS Policies and Dynamic Policy Callback
350: * Also the SAML infrastructure would be different in different containers
351: * The default implementation in JWSDP will make a DP callback, but
352: * the notion of DP callbacks does not apply for JSR 196
353: */
354:
355: /**
356: * Validate the received SAML Assertion
357: * Validations can include validating the Issuer and the Saml User, SAML Version etc.
358: * Note: The SAML Condition (notBefore, notOnOrAfter) is validated by the XWS runtime
359: *
360: * @param context a Map of application and integration-layer specific properties
361: * @param assertion the Assertion to be validated
362: * @throws XWSSecurityException if there was an error while validating the SAML Assertion
363: */
364: public void validateSAMLAssertion(Map context, Element assertion)
365: throws XWSSecurityException;
366:
367: /**
368: * Validate the received SAML Assertion
369: * Validations can include validating the Issuer and the Saml User, SAML Version etc.
370: * Note: The SAML Condition (notBefore, notOnOrAfter) is validated by the XWS runtime
371: *
372: * In case HOK SAML Assertion the enveloped signature is removed from this SAML Assertion and verified.
373: * (i,e one will not find Signature element under this SAMLAssertion)
374: * @param context a Map of application and integration-layer specific properties
375: * @param assertion the Assertion to be validated
376: * @throws XWSSecurityException if there was an error while validating the SAML Assertion
377: */
378: public void validateSAMLAssertion(Map context,
379: XMLStreamReader assertion) throws XWSSecurityException;
380:
381: /**
382: * Locate and return a SAML Assertion, given the Authority binding and assertionId
383: *
384: * @param context a Map of application and integration-layer specific properties
385: * @param binding an org.w3c.dom.Element representing the SAML AuthorityBinding
386: * @param assertionId the Assertion ID of the SAML Assertion
387: * @param ownerDoc the owner document into which the returned SAML Assertion should be imported to
388: * @throws XWSSecurityException if there was an error while trying to locate the SAML Assertion
389: */
390: public Element locateSAMLAssertion(Map context, Element binding,
391: String assertionId, Document ownerDoc)
392: throws XWSSecurityException;
393:
394: /**
395: * Locate and update the Policy argument with the SAML Assertion and/or the AuthorityBinding
396: * and Assertion ID information.
397: * The DynamicApplicationContext may contain information to be used by the implementation to make
398: * its runtime decisions on how to obtaim the SAML Assertion
399: *
400: * @param fpcontext a Map of application and integration-layer specific properties
401: * @param policy the SAML Assertion Policy to be populated
402: * @param context the DynamicApplicationContext
403: * @return populated SAML Assertion policy
404: * @throws XWSSecurityException if there was an error while trying to populate the SAML Assertion Policy
405: */
406: public AuthenticationTokenPolicy.SAMLAssertionBinding populateSAMLPolicy(
407: Map fpcontext,
408: AuthenticationTokenPolicy.SAMLAssertionBinding policy,
409: DynamicApplicationContext context)
410: throws XWSSecurityException;
411:
412: /**
413: *
414: * @param context a Map of application and integration-layer specific properties
415: * @return the username using UsernameCallback
416: * @throws XWSSecurityException if there was an error while trying obtain the username
417: */
418: public String getUsername(Map context) throws XWSSecurityException;
419:
420: /**
421: *
422: * @param context a Map of application and integration-layer specific properties
423: * @return the password using PasswordCallback
424: * @throws XWSSecurityException if there was an error while trying obtain the password
425: */
426: public String getPassword(Map context) throws XWSSecurityException;
427:
428: /**
429: * Validate the creation time. It is an error if the
430: * creation time is older than current local time minus
431: * TIMESTAMP_FRESHNESS_LIMIT minus MAX_CLOCK_SKEW
432: *
433: * @param context a Map of application and integration-layer specific properties
434: * @param timestamp the Timestamp element
435: * @param maxClockSkew (in milliseconds) the maximum clockskew
436: * @param freshnessLimit (in milliseconds) the limit for which timestamps
437: * are considered fresh
438: * @throws XWSSecurityException if there was an error while trying validate the Timestamp
439: */
440: public void validateTimestamp(Map context, Timestamp timestamp,
441: long maxClockSkew, long freshnessLimit)
442: throws XWSSecurityException;
443:
444: public void validateTimestamp(Map context, String created,
445: String expires, long maxClockSkew, long freshnessLimit)
446: throws XWSSecurityException;
447:
448: /**
449: * @return any Callback Handler associated with this Environment, null otherwise
450: * @throws XWSSecurityException if there was an error while trying retrieve the CallbackHandler
451: */
452: public CallbackHandler getCallbackHandler()
453: throws XWSSecurityException;
454:
455: /**
456: * Validate the given nonce. It is an error if the nonce matches any
457: * stored nonce values on the server
458: * if there is no error then the nonce is Cached.
459: * @return true if this nonce is valid
460: * @param nonce the encoded nonce value
461: * @param created the creation time value
462: * @param maxNonceAge the time in milliseconds for which this nonce
463: * will be stored on the receiver.
464: * @throws XWSSecurityException if there was an error while trying to validate the Nonce
465: */
466: public boolean validateAndCacheNonce(String nonce, String created,
467: long maxNonceAge) throws XWSSecurityException;
468:
469: /**
470: *@return true if the certificate is a self certificate, false otherwise
471: */
472: public boolean isSelfCertificate(X509Certificate cert);
473:
474: }
|