3. MARCO METODOLÓGICO 1 Perspectiva metodológica
3.3. El trabajo de campo: sus etapas y vicisitudes
This release of the Java WSDP includes many example applications that illus- trate how a JAX-RPC or stand-alone SAAJ application developer can use the XML and Web Services Security framework and APIs. The example applica- tions can be found in the <JWSDP_HOME>/xws-security/samples/ <sample_name>/ directory. Before you can run the sample applications, you
must follow the setup instructions inSetting Up To Use XWS-Security With the Sample Applications.
The sample applications print out both the client and server request and response SOAP messages. The output from the server may be viewed in the appropriate container’s log file. The output from the client is sent to stdout or whichever stream is used by the configured log handler. Messages are logged at the INFO
level.
Note: In some of the sample security configuration files, no security is specified for either a request or a response. In this case, the response is a simple JAX-RPC response. When XWS-Security is enabled for an application by providing the - security option to wscompile, and a request or response not containing a
wsse:Security Headeris received, the messageWSS0202: No Security element in the messagewill display in the output to warn that a nonsecure response was received.
In these examples, the server-side code is found in the <JWSDP_HOME>/xws- security/samples/<sample_name>/server/src/<sample_name>/ directory. Client-side code is found in the <JWSDP_HOME>/xws-security/samples/ <sample_name>/client/src/<sample_name>/ directory. The asant (or ant)
targets build objects under the /build/server/ and/build/client/ directo- ries.
These examples can be deployed onto any of the following containers. For the purposes of this tutorial, only deployment to the Sun Java System Application Server Platform Edition 8.1 will be discussed. The README.txt file for each example provides more information on deploying to the other containers. The following containers can be downloaded fromhttp://java.sun.com/webservices/contain- ers/index.html.
• Sun Java System Application Server Platform Edition 8.1 (Application Server)
• Sun Java System Web Server 6.1 (Web Server)
If you are using the Java SDK version 5.0 or higher, download service pack 4 for the Web Server. If you are using version 1.4.2 of the Java SDK, download service pack 2 or 3.
• Tomcat 5 Container for Java WSDP (Tomcat)
These examples use keystore and truststore files that are included in the
keystore and truststore files, read thekeytooldocumentation athttp://java.sun.com/ j2se/1.5.0/docs/tooldocs/solaris/keytool.html. Refer to the application’s README.txtfile if deploying on the Web Server or Tomcat.
The following list provides the name, a short description, and a link to further discussion of each of the sample applications available in this release:
• simple
This sample application lets you plug in different client and server-side configurations describing security settings. This example has support for digital signatures, XML encryption/decryption, and username token veri- fication. This example allows and demonstrates combinations of these basic security mechanisms through configuration files. The sectionSimple Security Configurations Sample Applicationprovides examples and descriptions of configuration files used in the sample application, along with instruc- tions for compiling and running the application.
• api-sample
This sample application shows how to use the XWS-Security 2.0 APIs in a stand-alone mode. This sample defines the XWSSProcessor interface, which is used to insulate the API user from changes that may occur in future releases of the API, and provides an implementation for it. The
Client.javafile uses the XWSSProcessorAPIs to secure a SOAP mes- sage. The section XWS-Security APIs Sample Application provides further description of the sample application, along with instructions for compil- ing and running the application.
• jaas-sample
This sample demonstrates how to plug in a JAASLoginModulefor user- name-password authentication. Read more about JAAS at http:// java.sun.com/products/jaas/. The section JAAS Sample Application provides fur- ther description of the sample application, along with instructions for compiling and running the application.
• swainterop
This sample application demonstrates the Soap Messages with Attachments (SwA) interoperability scenarios. The sectionSoap With Attachments Sample Applica- tion provides further description of the sample application, along with instructions for compiling and running the application.
• samlinterop
This sample application demonstrates support forOASIS WSS Security Asser- tion Markup Language (SAML) Token Profile 1.0in XWS-Security. The section
SAML Sample Applicationprovides further description of the sample applica- tion, along with instructions for compiling and running the application.
• dynamic-policy
This sample application demonstrates how the request and response secu- rity policies can be set at runtime from the SecurityEnvironmen- tHandler callback. The section Dynamic Policy Sample Application provides further description of the sample application, along with instructions for compiling and running the application.
• dynamic-response
This sample application demonstrates using the certificate that arrived in a signed request to encrypt the response back to the requester. The section
Dynamic Response Sample Applicationprovides further description of the sam- ple application, along with instructions for compiling and running the application.
Writing SecurityEnvironmentHandlers
The signing and encryption operations require private-keys and certificates. An application can obtain such information in various ways, such as looking up a keystore with an alias, using the default key-pairs available with the container, looking up a truststore with an alias, etc. Similarly if an application wants to send a username-password in aUsernameToken, it can choose to obtain the user- name-password pair in various ways, such as reading from a file, prompting the user on the console, using a popup window, etc. The authentication of the user- name-password on the receiving application can similarly be done by plugging into existing authentication infrastructure, using a proprietary username-pass- word database, etc.
To support these possibilities, XWS-Security defines a set of CallBackclasses and requires the application to define aCallBackHandlerto handle these call- backs. Thexwss:SecurityEnvironmentHandlerelement is a compulsory child element that needs to be specified. The value of this element is the class name of a Java class that implements thejavax.security.auth.callback.Callback- Handler interface and handles the set of callbacks defined by XWS-Security. There are a set of callbacks that are mandatory and every CallbackHandler
needs to implement them. A few callbacks are optional and can be used to sup- ply some fine-grained property information to the XWS-Security run-time. When using the XWS-Security APIs for securing both JAX-RPC applications and stand-alone applications that make use of SAAJ APIs only for their SOAP
messaging, you have the option of either implementing aCallbackHandleror implementing the com.sun.xml.wss.SecurityEnvironment interface. Once implemented, the appropriate instance of theCallbackHandlerorSecurityEn- vironment interface implementation needs to be set into an instance of
com.sun.xml.wss.ProcessingContext. For example code uses the XWS- Security APIs, refer to XWS-Security APIs Sample Application. TheSecurityEnvi- ronment interface is evolving and is subject to refinement in a later release. Because information such as private keys and certificates for signing and encryp- tion can be obtained in various ways (looking up a keystore with an alias, using the default key-pairs available with the container, looking up a truststore with an alias, etc.), every callback defines a set ofRequestinner classes and a callback can be initialized with any of its request inner classes. A taggingRequestinter- face is also defined within the callback to tag allRequestclasses. For example, the XWS-Security configuration schema defines an xwss:X509Token element containing an optional attributecertificateAlias. When thexwss:X509Token
element embedded inside axwss:Signelement has acertificateAliasattribute specified as shown in the following code snippet, the XWS-Security run-time would invoke theSecurityEnvironmentHandlerof the application with aSig- natureKeyCallback object to obtain the private-key required for the signing operation.
<xwss:Sign>
<xwss:X509Token certificateAlias="xws-security-client"/> </xwss:Sign>
TheSignatureKeyCallbackwill be initialized by XWS-Security run-time with anAliasPrivKeyCertRequest in the following manner:
SignatureKeyCallback sigKeyCallback = new SignatureKeyCallback(new
SignatureKeyCallback.AliasPrivKeyCertRequest(alias));
The application’sSecurityEnvironmentHandlerimplementation then needs to handle the SignatureKeyCallbackand use the alias to locate and set the pri- vate-key and X.509 certificate pair on theAliasPrivKeyCertRequest. The fol- lowing code shows how this callback is handled in the handle() method of
SecurityEnvironmentHandler shipped with thesimple sample.
} else if (callbacks[i] instanceof SignatureKeyCallback) { SignatureKeyCallback cb =
if (cb.getRequest() instanceof SignatureKeyCallback.AliasPrivKeyCertRequest) { SignatureKeyCallback.AliasPrivKeyCertRequest request = (SignatureKeyCallback.AliasPrivKeyCertRequest) cb.getRequest();
String alias = request.getAlias(); if (keyStore == null)
initKeyStore(); try {
X509Certificate cert = (X509Certificate) keyStore.getCertificate(alias);
request.setX509Certificate(cert);
// Assuming key passwords same as the keystore password PrivateKey privKey = (PrivateKey) keyStore.getKey(alias, keyStorePassword.toCharArray()); request.setPrivateKey(privKey); } catch (Exception e) {
throw new IOException(e.getMessage()); }
} else {
throw new
UnsupportedCallbackException(null, "Unsupported Callback Type Encountered");
} }
This handler uses a keystore to locate the private key and certificate pair, and sets it usingAliasPrivKeyCertRequest.
As shown in the sample code, theSecurityEnvironmentHandlershould throw anUnsupportedCallbackExceptionwhenever it cannot handle aCallbackor a particularRequest type of aCallback.
The type ofRequestwith which theCallbackis initialized often depends on the information specified in the security configuration file of the application. For example if the xwss:X509Tokenspecified under anxwss:Signelement did not contain thecertificateAliasattribute, XWS-Security would invoke the appli- cation’s SecurityEnvironmentHandler with SignatureKeyCall- back.DefaultPrivKeyCertRequest to try and obtain the default private-key and certificate pair. If the SecurityEnvironmentHandler does not handle this request and throws an UnsupportedCallbackException, the signature opera- tion would fail.
For more information, read the API documentation for callbacks from the <JWSDP_HOME>/xws-security/docs/api/com/sun/xml/wss/impl/callback/ package-summary.html. This documentation includes the list of mandatory and optional callbacks and the details of theCallbackclasses and supported meth- ods.Table 4–41provides a brief summary of all the mandatoryCallbackclasses and their associatedRequest types.
Table 4–41 Summary ofCallback classes and theirRequest types
Callback Description
Request Inner Classes Defined
Methods in the Request Classes
Signature Key Callback
Used by XWS-Security run- time to obtain the private key to be used for signing the corresponding X.509 certifi- cate. There are two ways in which an application can sup- ply the private-key and certif- icate information.
1. Lookup a keystore using an alias.
2. Obtain the default private- key and certificate from the container/environment in which the application is run- ning.
3. Obtain the private key and certificate given the public key. This kind of request is used in scenarios where the public key appears as aKey- Value under ads:KeyInfo
and needs to be used for sign- ing.
Accordingly, there are three
Request inner classes with which theSignatureKey- Callback can be initialized.
1.AliasPrivKeyC- ertRequest: A
Callback initialized with this request should be handled if the private key to be used for signing is mapped to an alias. 2.Default- PrivKeyCertRe- quest: ACallback
initialized with this request should be han- dled if there's some default private key to be used for signing. 3.PublicKey- BasedPri-
vateKeyCertReque st: A callback initial- ized with this request should be handled if the private key to be used for signing is to be retrieved given the public key.
The following four methods are present in allRequest Classes of thisCallback:
public void setPrivateKey( PrivateKey privateKey) public PrivateKey getPri- vateKey() public void setX509Certificate( X509Certificate certifi- cate) public X509Certificate getX509Certificate()
Signa- ture Verifi- cation Key Callback
Obtains the certificate required for signature verifi- cation. There are currently two situations in which XWS-Security would require this Callback to resolve the certificate:
1. When the signature to be verified references the key using an X.509Subject- KeyIdentifier. For exam- ple, when the sender specifies the attributexwss:keyRef- erenceType="Identi- fier" on the
xwss:X509Token child of thexwss:Sign element. 2. When the signature to be verified references the key using an X.509IssuerSe- rialNumber. For example, when the sender specifies the attributexwss:keyRefer- enceType="IssuerSeri- alNumber" on the
xwss:X509Token child of thexwss:Sign element. 3. When ds:KeyInfo contains a key value, use the public key to obtain the X.509 cer- tificate.
Accordingly, there are three
Request inner classes with which aSignatureVeri- ficationKeyCallbackcan be initialized.
Note: AdditionalRequests
may be defined in a future release. 1. X509SubjectKeyId entifierBase- dRequest: Request for an X.509 certifi- cate whose X.509 SubjectKeyIden- tifier value is given. 2. X509IssuerSerial BasedRequest: Request for an X.509 certificate whose issuer name and serial number values are given.
3.PublicKeyBase- dRequest: Request for an X.509 certifi- cate for a given public key.
The following two methods are present in all theRequest
classes of thisCallback:
public void setX509Certificate( X509Certificate cer- tificate) public X509Certificate getX509Certificate() Table 4–41 Summary ofCallback classes and theirRequest types (Continued)
Callback Description
Request Inner Classes Defined
Methods in the Request Classes
Encryp- tion Key Callback
Obtains the certificate for key-encryption or a symmet- ric-key for data encryption. The three situations for which XWS-Security would require thisCallback for performing encryption: 1. When thexwss:Encrypt
element contains an
xwss:X509Tokenchild with
certificateAlias
attribute set to an alias. The
certificateAlias indi- cates that a random symmet- ric key is used for encryption of the specified message part and the certificate is then used to encrypt the random symmetric-key to be sent along with the message. 2. When thexwss:Encrypt
element contains an
xwss:X509Tokenchild with nocertificateAlias
attribute set on it. XWS- Security tries to obtain a default certificate from the
Callback to be used for encrypting the random sym- metric key.
3. When thexwss:Encrypt
element contains an
xwss:SymmetricKey child specifying thekeyAlias
attribute. This alias indicates that a symmetric key corre- sponding to this alias needs to be located and used for encryption of the specified message part.
4. When an X.509 certificate needs to be obtained for a given public key.
The following are the
Requestinner classes with which an
EncryptionKey- Callback can be ini- tialized.
1.
AliasX509Certifi cateRequest: A
Callback initialized with this request should be handled if the X.509 certificate to be used for encryp- tion is mapped to an alias. 2. DefaultX509Certi ficateRequest: A Callback initialized with this request should be handled if there's a default X.509 certificate to be used for encryption. 3.AliasSymmet- ricKeyRequest: A Callback initialized with this request should be handled if the symmetric key to be used for encryp- tion is mapped to an alias.
4.PublicKeyBase- dRequest: Request for an X.509 certifi- cate for a given public key.
The following two methods are present in the
AliasX509CertificateRequ est and
DefaultX509CertificateRe quest Requestclasses of this
Callback: public void setX509Certificate( X509Certificate cer- tificate) public X509Certificate getX509Certificate()
The following methods are present in theAliasSymmet- ricKeyRequest class of this
Callback:
public void setSymmet- ricKey( javax.crypto.SecretKe y symmetricKey) public javax.crypto.SecretKey getSymmetricKey() Table 4–41 Summary ofCallback classes and theirRequest types (Continued)
Callback Description
Request Inner Classes Defined
Methods in the Request Classes
Decryp- tion Key Callback
Obtains the symmetric key to be used for decrypting the encrypted data or obtaining the private-key for decrypting the encrypted random sym- metric key that was sent with the message (along with the encrypted data).
There are currently four situ- ations in which XWS-Secu- rity will require this
Callback to perform decryption.
1. When theEncryptedKey
references the key (used for encrypting the symmetric key) using an X.509Sub- jectKeyIdentifier. For example, when the sender specifies the attributekey- ReferenceType="Identi- fier" on the
xwss:X509Token child of thexwss:Encrypt element. 2. When theEncrypted- Keyreferences the key (used for encrypting the symmetric key) using an X.509Issu- erSerialNumber. For example, when the sender specifies the attributekey- ReferenceType="Issu- erSerialNumber" on the xwss:x509Token child of xwss:Encrypt element. 1. X509SubjectKeyId entifierBase- dRequest: Request for a private-key when the X.509Subject- KeyIdentifier
value for a corre- sponding X.509 certif- icate is given. 2.
X509IssuerSerial BasedRequest: Request for a private key when the issuer name and serial num- ber values for a corre- sponding X.509 certificate are given. 3.
X509CertificateB asedRequest: Request for a private key when a corre- sponding X.509 certif- icate is given.
The following two methods are present in the X509SubjectKeyIdentifier BasedRequest, X509IssuerSerialBasedReq uest, and X509CertificateBasedRequ est Request classes of this
Callback:
public void setPri- vateKey(
PrivateKey pri- vateKey)
public PrivateKey getPrivateKey() Table 4–41 Summary ofCallback classes and theirRequest types (Continued)
Callback Description
Request Inner Classes Defined
Methods in the Request Classes
Decryp- tion Key Callback (contin- ued)
3. When theEncryptedKey
contains awsse:Directref- erence to the key used for encrypting the symmetric key. This means the X.509 certificate is present as a
wsse:BinarySecurityTo- ken in the message. For example, when the sender specifies the attributekey- Reference-
Type="Direct" on the
xwss:x509Token child of
xwss:Encrypt element. 4. When theEncrypted- Data contains ads:key- Name reference to the symmetric key that was used for encryption. For example, when the sender specifies the
xwss:SymmetricKey child ofxwss:Encrypt and speci- fies thekeyAlias attribute on it.
5. When theEncryptedKey
contains ads:KeyInfowith a key value child.
Accordingly, there are five
Request classes with which aDecryptionKeyCall- back can be initialized.
4.AliasSymmet- ricKeyRequest: A
Callback initialized with this request should be handled if the symmetric key to be used for decryp- tion is mapped to some alias. 5.PublicKey- BasedPrivateKey- Request: Request for a private key given the public key.
The following methods are present in theAliasSymmet- ricKeyRequest class of this
Callback:
public void setSymmet- ricKey( javax.crypto.SecretKe y symmetricKey)