com.sun.xml.wss
Interface SecurityEnvironment


public interface SecurityEnvironment

The SecurityEnvironment interface links the XWS-Security runtime with the environment/container in which it is running. The SecurityEnvironment interface is invoked by the XWS-Security runtime to perform tasks such as retrieving keys, validating tokens etc.

When using the XWS-Security configuration files with <xwss:JAXRPCSecurity> as the root element, a default implementation of this interface wraps the supplied CallbackHandler. The default implemenation of this interface bundled with XWS-Security invokes the CallbackHandler to implement the methods of this interface.

This interface facilitates usage of XWS-Security in environments which do not necessarily have a natural mapping to the XWS-Security defined callbacks.

There is generally a single SecurityEnvironment instance per-application, which is initialized at application startup.

Note: This interface is evolving and is subject to change in a later release


Method Summary
 boolean authenticateUser(java.util.Map context, java.lang.String username, java.lang.String password)
          Authenticate the user against a list of known username-password pairs.
 boolean authenticateUser(java.util.Map context, java.lang.String username, java.lang.String passwordDigest, java.lang.String nonce, java.lang.String created)
          Authenticate the user given the password digest.
 javax.security.auth.callback.CallbackHandler getCallbackHandler()
           
 java.security.cert.X509Certificate getCertificate(java.util.Map context, java.math.BigInteger serialNumber, java.lang.String issuerName)
           
 java.security.cert.X509Certificate getCertificate(java.util.Map context, byte[] keyIdentifier)
           
 java.security.cert.X509Certificate getCertificate(java.util.Map context, java.security.PublicKey publicKey, boolean forSign)
           
 java.security.cert.X509Certificate getCertificate(java.util.Map context, java.lang.String alias, boolean forSigning)
           
 java.security.cert.X509Certificate getDefaultCertificate(java.util.Map context)
          Retrieves a reasonable default value for the current user's X509Certificate if one exists.
 java.lang.String getPassword(java.util.Map context)
           
 java.security.PrivateKey getPrivateKey(java.util.Map context, java.math.BigInteger serialNumber, java.lang.String issuerName)
           
 java.security.PrivateKey getPrivateKey(java.util.Map context, byte[] keyIdentifier)
           
 java.security.PrivateKey getPrivateKey(java.util.Map context, java.security.PublicKey publicKey, boolean forSign)
           
 java.security.PrivateKey getPrivateKey(java.util.Map context, java.lang.String alias)
           
 java.security.PrivateKey getPrivateKey(java.util.Map context, java.security.cert.X509Certificate cert)
           
 java.security.PublicKey getPublicKey(java.util.Map context, java.math.BigInteger serialNumber, java.lang.String issuerName)
           
 java.security.PublicKey getPublicKey(java.util.Map context, byte[] keyIdentifier)
           
 javax.crypto.SecretKey getSecretKey(java.util.Map context, java.lang.String alias, boolean encryptMode)
           
 javax.security.auth.Subject getSubject()
           
 java.lang.String getUsername(java.util.Map context)
           
 org.w3c.dom.Element locateSAMLAssertion(java.util.Map context, org.w3c.dom.Element binding, java.lang.String assertionId, org.w3c.dom.Document ownerDoc)
          Locate and return a SAML Assertion, given the Authority binding and assertionId
 AuthenticationTokenPolicy.SAMLAssertionBinding populateSAMLPolicy(java.util.Map fpcontext, AuthenticationTokenPolicy.SAMLAssertionBinding policy, DynamicApplicationContext context)
          Locate and update the Policy argument with the SAML Assertion and/or the AuthorityBinding and Assertion ID information.
 void updateOtherPartySubject(javax.security.auth.Subject subject, Assertion assertion)
          Update the public credentials of the subject of the party whose Assertion is given.
 void updateOtherPartySubject(javax.security.auth.Subject subject, java.lang.String username, java.lang.String password)
          Update the public/private credentials of the subject of the party whose username password pair is given.
 void updateOtherPartySubject(javax.security.auth.Subject subject, java.security.cert.X509Certificate cert)
          Update the public credentials of the subject of the party whose certificate is given.
 boolean validateAndCacheNonce(java.lang.String nonce, java.lang.String created, long maxNonceAge)
          Validate the given nonce.
 boolean validateCertificate(java.security.cert.X509Certificate cert)
          Validate an X509Certificate.
 void validateCreationTime(java.util.Map context, java.lang.String creationTime, long maxClockSkew, long timestampFreshnessLimit)
          Validate the creation time.
 void validateSAMLAssertion(java.util.Map context, org.w3c.dom.Element assertion)
          Validate the received SAML Assertion Validations can include validating the Issuer and the Saml User, SAML Version etc.
 void validateTimestamp(java.util.Map context, com.sun.xml.wss.core.Timestamp timestamp, long maxClockSkew, long freshnessLimit)
          Validate the creation time.
 

Method Detail

getDefaultCertificate

java.security.cert.X509Certificate getDefaultCertificate(java.util.Map context)
                                                         throws XWSSecurityException
Retrieves a reasonable default value for the current user's X509Certificate if one exists.

Parameters:
context - a Map of application and integration-layer specific properties
Returns:
the default certificate for the current user
Throws:
XWSSecurityException

getCertificate

java.security.cert.X509Certificate getCertificate(java.util.Map context,
                                                  java.lang.String alias,
                                                  boolean forSigning)
                                                  throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
alias - the alias for identifying the certificate
forSigning - whether this request is for a Sign operation or Encrypt
Returns:
the certificate corresponding to the alias
Throws:
XWSSecurityException - if there was an error while trying to locate the Cerificate

getSecretKey

javax.crypto.SecretKey getSecretKey(java.util.Map context,
                                    java.lang.String alias,
                                    boolean encryptMode)
                                    throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
alias - the alias for identifying the SecretKey
encryptMode - whether this request is for an Encrypt or Decrypt operation
Returns:
the SecretKey corresponding to the alias
Throws:
XWSSecurityException - if there was an error while trying to locate the SecretKey

getPrivateKey

java.security.PrivateKey getPrivateKey(java.util.Map context,
                                       java.lang.String alias)
                                       throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
alias - the alias for identifying the PrivateKey
Returns:
the PrivateKey corresponding to the alias
Throws:
XWSSecurityException - if there was an error while trying to locate the PrivateKey

getPublicKey

java.security.PublicKey getPublicKey(java.util.Map context,
                                     byte[] keyIdentifier)
                                     throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
keyIdentifier - an Opaque identifier indicating the X509 certificate.
Returns:
the PublicKey corresponding to a KeyIdentifier
Throws:
XWSSecurityException - if there was an error while trying to locate the PublicKey

getCertificate

java.security.cert.X509Certificate getCertificate(java.util.Map context,
                                                  byte[] keyIdentifier)
                                                  throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
keyIdentifier - an Opaque identifier indicating the X509 certificate.
Returns:
the X509Certificate corresponding to a KeyIdentifier
Throws:
XWSSecurityException - if there was an error while trying to locate the X509Certificate

getPrivateKey

java.security.PrivateKey getPrivateKey(java.util.Map context,
                                       java.security.cert.X509Certificate cert)
                                       throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
cert - the X509Certificate
Returns:
the PrivateKey corresponding to the X509Certificate
Throws:
XWSSecurityException - if there was an error while trying to locate the PrivateKey

getPrivateKey

java.security.PrivateKey getPrivateKey(java.util.Map context,
                                       java.math.BigInteger serialNumber,
                                       java.lang.String issuerName)
                                       throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
serialNumber - the serialNumber of the certificate
issuerName - the issuerName of the certificate
Returns:
the PrivateKey corresponding to (serialNumber, issuerName)
Throws:
XWSSecurityException - if there was an error while trying to locate the PrivateKey

getCertificate

java.security.cert.X509Certificate getCertificate(java.util.Map context,
                                                  java.security.PublicKey publicKey,
                                                  boolean forSign)
                                                  throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
publicKey - the publicKey
forSign - set to true if the public key is to be used for SignatureVerification
Returns:
the X509Certificate corresponding to a PublicKey
Throws:
XWSSecurityException - if there was an error while trying to locate the PublicKey

getPrivateKey

java.security.PrivateKey getPrivateKey(java.util.Map context,
                                       byte[] keyIdentifier)
                                       throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
keyIdentifier - an Opaque identifier indicating the X509 certificate.
Returns:
the PrivateKey corresponding to a KeyIdentifier
Throws:
XWSSecurityException - if there was an error while trying to locate the PrivateKey

getPrivateKey

java.security.PrivateKey getPrivateKey(java.util.Map context,
                                       java.security.PublicKey publicKey,
                                       boolean forSign)
                                       throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
publicKey - the publicKey
forSign - set to true if the purpose is Signature
Returns:
the PrivateKey corresponding to a PublicKey
Throws:
XWSSecurityException - if there was an error while trying to locate the PrivateKey

getPublicKey

java.security.PublicKey getPublicKey(java.util.Map context,
                                     java.math.BigInteger serialNumber,
                                     java.lang.String issuerName)
                                     throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
serialNumber - the serialNumber of the certificate
issuerName - the issuerName of the certificate
Returns:
the PublicKey corresponding to (serialNumber, issuerName)
Throws:
XWSSecurityException - if there was an error while trying to locate the PublicKey

getCertificate

java.security.cert.X509Certificate getCertificate(java.util.Map context,
                                                  java.math.BigInteger serialNumber,
                                                  java.lang.String issuerName)
                                                  throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
serialNumber - the serialNumber of the certificate
issuerName - the issuerName of the certificate
Returns:
the X509Certificate corresponding to (serialNumber, issuerName)
Throws:
XWSSecurityException - if there was an error while trying to locate the X509Certificate

authenticateUser

boolean authenticateUser(java.util.Map context,
                         java.lang.String username,
                         java.lang.String password)
                         throws XWSSecurityException
Authenticate the user against a list of known username-password pairs.

Parameters:
context - a Map of application and integration-layer specific properties
username - the username
password - the password
Returns:
true if the username-password pair is valid, false otherwise
Throws:
XWSSecurityException - if there was an error while trying to authenticate the username

authenticateUser

boolean authenticateUser(java.util.Map context,
                         java.lang.String username,
                         java.lang.String passwordDigest,
                         java.lang.String nonce,
                         java.lang.String created)
                         throws XWSSecurityException
Authenticate the user given the password digest.

Parameters:
context - a Map of application and integration-layer specific properties
username - the username
passwordDigest - the digested password
nonce - the nonce which was part of the digest
created - the creation time which was part of the digest
Returns:
true if the password digest is valid, false otherwise
Throws:
XWSSecurityException - if there was an error while trying to authenticate the username

getSubject

javax.security.auth.Subject getSubject()
Returns:
the host/sender Subject, null if subject is not available/initialized

validateCreationTime

void validateCreationTime(java.util.Map context,
                          java.lang.String creationTime,
                          long maxClockSkew,
                          long timestampFreshnessLimit)
                          throws XWSSecurityException
Validate the creation time. It is an error if the creation time is older than current local time minus TIMESTAMP_FRESHNESS_LIMIT minus MAX_CLOCK_SKEW

Parameters:
context - a Map of application and integration-layer specific properties
creationTime - the creation-time value
maxClockSkew - (in milliseconds) the maximum clockskew
timestampFreshnessLimit - (in milliseconds) the limit for which timestamps are considered fresh
Throws:
XWSSecurityException - if there was an error while trying to validate the creationTime

validateCertificate

boolean validateCertificate(java.security.cert.X509Certificate cert)
                            throws XWSSecurityException
Validate an X509Certificate.

Parameters:
cert - the X509Certificate to be validated
Returns:
true, if the cert is a valid one, false otherwise.
Throws:
XWSSecurityException - if there is some problem during validation.

updateOtherPartySubject

void updateOtherPartySubject(javax.security.auth.Subject subject,
                             java.lang.String username,
                             java.lang.String password)
Update the public/private credentials of the subject of the party whose username password pair is given.

Parameters:
subject - the Subject of the requesting party
username - the username of the requesting party
password - the password of the requesting party

updateOtherPartySubject

void updateOtherPartySubject(javax.security.auth.Subject subject,
                             java.security.cert.X509Certificate cert)
Update the public credentials of the subject of the party whose certificate is given.

Parameters:
subject - the Subject of the requesting party
cert - the X509Certificate of the requesting party

updateOtherPartySubject

void updateOtherPartySubject(javax.security.auth.Subject subject,
                             Assertion assertion)
Update the public credentials of the subject of the party whose Assertion is given.

Parameters:
subject - the Subject of the requesting party
assertion - the SAML Assertion of the requesting party

validateSAMLAssertion

void validateSAMLAssertion(java.util.Map context,
                           org.w3c.dom.Element assertion)
                           throws XWSSecurityException
Validate the received SAML Assertion Validations can include validating the Issuer and the Saml User, SAML Version etc. Note: The SAML Condition (notBefore, notOnOrAfter) is validated by the XWS runtime

Parameters:
context - a Map of application and integration-layer specific properties
assertion - the Assertion to be validated
Throws:
XWSSecurityException - if there was an error while validating the SAML Assertion

locateSAMLAssertion

org.w3c.dom.Element locateSAMLAssertion(java.util.Map context,
                                        org.w3c.dom.Element binding,
                                        java.lang.String assertionId,
                                        org.w3c.dom.Document ownerDoc)
                                        throws XWSSecurityException
Locate and return a SAML Assertion, given the Authority binding and assertionId

Parameters:
context - a Map of application and integration-layer specific properties
binding - an org.w3c.dom.Element representing the SAML AuthorityBinding
assertionId - the Assertion ID of the SAML Assertion
ownerDoc - the owner document into which the returned SAML Assertion should be imported to
Throws:
XWSSecurityException - if there was an error while trying to locate the SAML Assertion

populateSAMLPolicy

AuthenticationTokenPolicy.SAMLAssertionBinding populateSAMLPolicy(java.util.Map fpcontext,
                                                                  AuthenticationTokenPolicy.SAMLAssertionBinding policy,
                                                                  DynamicApplicationContext context)
                                                                  throws XWSSecurityException
Locate and update the Policy argument with the SAML Assertion and/or the AuthorityBinding and Assertion ID information. The DynamicApplicationContext may contain information to be used by the implementation to make its runtime decisions on how to obtaim the SAML Assertion

Parameters:
fpcontext - a Map of application and integration-layer specific properties
policy - the SAML Assertion Policy to be populated
context - the DynamicApplicationContext
Returns:
populated SAML Assertion policy
Throws:
XWSSecurityException - if there was an error while trying to populate the SAML Assertion Policy

getUsername

java.lang.String getUsername(java.util.Map context)
                             throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
Returns:
the username using UsernameCallback
Throws:
XWSSecurityException - if there was an error while trying obtain the username

getPassword

java.lang.String getPassword(java.util.Map context)
                             throws XWSSecurityException
Parameters:
context - a Map of application and integration-layer specific properties
Returns:
the password using PasswordCallback
Throws:
XWSSecurityException - if there was an error while trying obtain the password

validateTimestamp

void validateTimestamp(java.util.Map context,
                       com.sun.xml.wss.core.Timestamp timestamp,
                       long maxClockSkew,
                       long freshnessLimit)
                       throws XWSSecurityException
Validate the creation time. It is an error if the creation time is older than current local time minus TIMESTAMP_FRESHNESS_LIMIT minus MAX_CLOCK_SKEW

Parameters:
context - a Map of application and integration-layer specific properties
timestamp - the Timestamp element
maxClockSkew - (in milliseconds) the maximum clockskew
freshnessLimit - (in milliseconds) the limit for which timestamps are considered fresh
Throws:
XWSSecurityException - if there was an error while trying validate the Timestamp

getCallbackHandler

javax.security.auth.callback.CallbackHandler getCallbackHandler()
                                                                throws XWSSecurityException
Returns:
any Callback Handler associated with this Environment, null otherwise
Throws:
XWSSecurityException - if there was an error while trying retrieve the CallbackHandler

validateAndCacheNonce

boolean validateAndCacheNonce(java.lang.String nonce,
                              java.lang.String created,
                              long maxNonceAge)
                              throws XWSSecurityException
Validate the given nonce. It is an error if the nonce matches any stored nonce values on the server if there is no error then the nonce is Cached.

Parameters:
nonce - the encoded nonce value
created - the creation time value
maxNonceAge - the time in milliseconds for which this nonce will be stored on the receiver.
Returns:
true if this nonce is valid
Throws:
XWSSecurityException - if there was an error while trying to validate the Nonce


Copyright ? 2005 Sun Microsystems, Inc. All Rights Reserved.