Service Programming Interfaces (SPI)

The Web Services Security service programming interface (WSS SPI) provides programming interfaces for securing Web Services Security.

The Web Services Security specification provides a flexible framework for building secure web services to implement message content integrity and confidentiality. The specification does not define specific token formats, but instead associates separate profile documents that define various security token formats and semantics for using those tokens. The Web Services Security service programming model supports the flexible framework by providing extension points to integrate with new token formats, and with methods to obtains keys needed for message protection. Web Services Security uses this programming model to implement support for the standard X.509 token profile, the Username token profile, and the Kerberos token profiles. The programming model is also used to implement support for the LTPA security token, and for new security token types.

The Web Service Security run time token generation and token consuming Service Programming Interfaces (SPI) have been redesigned so that the same security token interface and JAAS Login Module implementation can be used for both the WSS API and the SPI. The WSS SPI for the service provider extends the security token types and provides keys and deriving keys for signing, signature verification, encryption and decryption.

The Web Services Security service programming model provides mechanisms to process custom security tokens, to use custom token in signing and encryption, and to retrieve encryption and signing keys. The Web Services Security service programming interfaces for the JAX-RPC run time, and for the JAX-WS run time, are similar, but not identical.

JAX-RPC run time

The plug-in programming interfaces for the JAX-RPC run time consist of the TokenGenerator, KeyLocator, and JAAS CallbackHandler for outbound message processing, and the TokenConsumer, KeyLocator, and JAAS LoginModule for inbound message processing.

Token Generator, KeyLocator, and Callback Handler

The TokenGenerator class is responsible for formatting the security token to the XML element. This class calls the CallbackHandler class specified in the TokenGeneratorConfig object, which obtains the security token input data, and then stores the resulting security token in the Subject object private credentials.

Token Consumer, KeyLocator and JAAS LoginModule

The KeyLocator class is responsible for obtaining the required key for signing and encrypting SOAP message elements from a key store specified by the KeyStoreConfig and the KeyLocatorConfig configuration. The TokenConsumer class extracts the token data from the XML security token representation, and stores it in the JAAS Subject using a JAAS LoginModule. The specified KeyLocator class is invoked to find the required key for verifying the digital signature and decrypting the SOAP message elements.

JAX-WS run time

The plug-in programming interfaces for the JAX-WS run time are based on the JAAS programming model for both inbound and outbound SOAP message processing. The JAAS LoginModule and CallbackHandler are responsible for processing the security tokens in SOAP messages. The Login Module and Callback Handler both retrieve and generate tokens, and store the SecurityToken objects in the run time. They replace the functionality of the TokenGenerator, TokenConsumer, and KeyLocator interfaces.

Due to the differences in the programming models, any WebSphere Application Server or custom SPI implementation from the Web Services Security Version 6.1 run time is not supported to run on the Web Services Security run time with the Version 6.1 Feature Pack for Web Services, or the Version 7.0 and later Web Services Security runtime. However, the Web Services Security Version 6.1 run time is supported simultaneously with the Version 6.1 Feature Pack for Web Services, meaning the Version 6.1 SPI implementations are still supported through the original run time. Before using the new Web Services Security run time, a code migration is required to reprogram the Version 6.1 DOM-based SPIs to the AXIOM-based SPIs in the Feature Pack for Web Services, before the SPI can be used.

Related concepts

Web Services Security API programming model

Web Services Security APIs