Package com.sun.xml.wss

Interface SecurityEnvironment

  • All Known Implementing Classes:
    DefaultSecurityEnvironmentImpl, WSITProviderSecurityEnvironment, WssProviderSecurityEnvironment
    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 Detail

      • getDefaultCertificate

        X509Certificate getDefaultCertificate​(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

        X509Certificate getCertificate​(Map context,
                               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

        SecretKey getSecretKey​(Map context,
                       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

        PrivateKey getPrivateKey​(Map context,
                         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

        PublicKey getPublicKey​(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

        X509Certificate getCertificate​(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

      • getCertificate

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

      • getPrivateKey

        PrivateKey getPrivateKey​(Map context,
                         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

        PrivateKey getPrivateKey​(Map context,
                         BigInteger serialNumber,
                         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

        X509Certificate getCertificate​(Map context,
                               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

        PrivateKey getPrivateKey​(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

        PrivateKey getPrivateKey​(Map context,
                         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

        PublicKey getPublicKey​(Map context,
                       BigInteger serialNumber,
                       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

        X509Certificate getCertificate​(Map context,
                               BigInteger serialNumber,
                               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​(Map context,
                         String username,
                         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​(Map context,
                         String username,
                         String passwordDigest,
                         String nonce,
                         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

      • authenticateUser

        String authenticateUser​(Map context,
                        String username)
                 throws XWSSecurityException
        Authenticate the user given the username and context.
        Parameters:
        context - a Map of application and integration-layer specific properties
        username - the username
        Returns:
        password if the username is valid
        Throws:
        XWSSecurityException - if there was an error while trying to authenticate the username

      • getSubject

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

      • validateCreationTime

        void validateCreationTime​(Map context,
                          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​(X509Certificate cert,
                            Map context)
                     throws XWSSecurityException
        Validate an X509Certificate.
        Parameters:
        cert - the X509Certificate to be validated
        cert - the X509Certificate to be validated
        context - Map of application and integration-layer specific properties
        Returns:
        true, if the cert is a valid one, false otherwise.
        Throws:
        XWSSecurityException - if there is some problem during validation. public boolean validateCertificate(X509Certificate cert) throws XWSSecurityException; / /** Validate an X509Certificate.
        XWSSecurityException - if there is some problem during validation.

      • updateOtherPartySubject

        void updateOtherPartySubject​(Subject subject,
                             String username,
                             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​(Subject subject,
                             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​(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

      • updateOtherPartySubject

        void updateOtherPartySubject​(Subject subject,
                             XMLStreamReader 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

      • updateOtherPartySubject

        void updateOtherPartySubject​(Subject subject,
                             Subject bootStrapSubject)
        Update the principal/credentials of the requesting party subject
        Parameters:
        subject - the Subject of the requesting party
        bootStrapSubject - the bootstrap Credentials (during a SecureConversation Bootstrap) of the requesting party

      • validateSAMLAssertion

        void validateSAMLAssertion​(Map context,
                           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

      • validateSAMLAssertion

        void validateSAMLAssertion​(Map context,
                           XMLStreamReader 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 In case HOK SAML Assertion the enveloped signature is removed from this SAML Assertion and verified. (i,e one will not find Signature element under this SAMLAssertion)
        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

        Element locateSAMLAssertion​(Map context,
                            Element binding,
                            String assertionId,
                            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​(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

        String getUsername​(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

        String getPassword​(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​(Map context,
                       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

      • validateAndCacheNonce

        boolean validateAndCacheNonce​(Map context,
                              String nonce,
                              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:
        context - a context containing runtime properties
        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

      • isSelfCertificate

        boolean isSelfCertificate​(X509Certificate cert)
        Returns:
        true if the certificate is a self certificate, false otherwise

      • updateOtherPartySubject

        void updateOtherPartySubject​(Subject subject,
                             GSSName clientCred,
                             GSSCredential gssCred)
        Update the principal/credentials of the requesting party subject
        Parameters:
        subject - the Subject of the requesting party
        clientCred - the GSSName of the requesting party