PK HAoa,mimetypeapplication/epub+zipPK HA META-INF/PK HAOEBPS/PK HA OEBPS/images/PK HAOEBPS/imagesdb/PK HAhhMETA-INF/container.xml PK HAއ;OEBPS/Auth-AuthCreds.html Authenticating Received Credentials

Authenticating Received Credentials

Overview

On the server side, you can verify that received credentials are authentic by registering a callback handler with the Fuse Services Framework runtime. You can either write your own custom code to perform credentials verification or you can implement a callback handler that integrates with a third-party enterprise security system (for example, an LDAP server).

Configuring a server callback handler in Spring XML

To configure a server callback handler that verifies UsernameToken credentials received from clients, set the ws-security.callback-handler property in the server's Spring XML configuration, as follows:

<beans ... >
    <jaxws:endpoint 
       id="UserNameOverTransport"
       address="https://localhost:9001/UserNameOverTransport" 
       serviceName="interop:PingService10"
       endpointName="interop:UserNameOverTransport_IPingService"
       implementor="interop.server.UserNameOverTransport"
       depends-on="tls-settings">
        
       <jaxws:properties>
            <entry key="ws-security.username" value="Alice"/>
            <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
        </jaxws:properties> 
     
    </jaxws:endpoint> 
    ...
</beans>

In the preceding example, the callback handler is implemented by the UTPasswordCallback class.

Implementing the callback handler to check passwords

To implement a callback handler for checking passwords on the server side, implement the javax.security.auth.callback.CallbackHandler interface. The general approach to implementing the CallbackHandler interface for a server is similar to implementing a CallbackHandler for a client. The interpretation given to the returned password on the server side is different, however: the password from the callback handler is compared against the received client password in order to verify the client's credentials.

For example, you could use the sample implementation shown in Example 7.2 to obtain passwords on the server side. On the server side, the WSS4J runtime would compare the password obtained from the callback with the password in the received client credentials. If the two passwords match, the credentials are successfully verified.

A more realistic implementation of a server callback handler would involve writing an integration with a third-party database that is used to store security data (for example, integration with an LDAP server).

PK HARj33OEBPS/Auth-ClientCreds.html Providing Client Credentials

Providing Client Credentials

Overview

There are essentially two approaches to providing UsernameToken client credentials: you can either set both the username and the password directly in the client's Spring XML configuration; or you can set the username in the client's configuration and implement a callback handler to provide passwords programmatically. The latter approach (by programming) has the advantage that passwords are easier to hide from view.

Client credentials properties

Table 7.1 shows the properties you can use to specify WS-Security username/password credentials on a client's request context in Spring XML.

Table 7.1. Client Credentials Properties

PropertiesDescription
ws-security.usernameSpecifies the username for UsernameToken policy assertions.
ws-security.passwordSpecifies the password for UsernameToken policy assertions. If not specified, the password is obtained by calling the callback handler.
ws-security.callback-handler

Specifies the class name of the WSS4J callback handler that retrieves passwords for UsernameToken policy assertions. Note that the callback handler can also handle other kinds of security events.

Configuring client credentials in Spring XML

To configure username/password credentials in a client's request context in Spring XML, set the ws-security.username and ws-security.password properties as follows:

<beans ... >
    <jaxws:client name="{NamespaceName}LocalPortName"
                  createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.username" value="Alice"/>
            <entry key="ws-security.password" value="abcd!1234"/>
        </jaxws:properties>
    </jaxws:client>
    ...
</beans>

If you prefer not to store the password directly in Spring XML (which might potentially be a security hazard), you can provide passwords using a callback handler instead.

Programming a callback handler for passwords

If you want to use a callback handler to provide passwords for the UsernameToken header, you must first modify the client configuration in Spring XML, replacing the ws-security.password setting by a ws-security.callback-handler setting, as follows:

<beans ... >
    <jaxws:client name="{NamespaceName}LocalPortName"
                  createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.username" value="Alice"/>
            <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
        </jaxws:properties>
    </jaxws:client>
    ...
</beans>

In the preceding example, the callback handler is implemented by the UTPasswordCallback class. You can write a callback handler by implementing the javax.security.auth.callback.CallbackHandler interface, as shown in Example 7.2.

Example 7.2. Callback Handler for UsernameToken Passwords

package interop.client;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;

import org.apache.ws.security.WSPasswordCallback;

public class UTPasswordCallback implements CallbackHandler {
    
    private Map<String, String> passwords = 
        new HashMap<String, String>();
    
    public UTPasswordCallback() {
        passwords.put("Alice", "ecilA");
        passwords.put("Frank", "invalid-password");
        //for MS clients
        passwords.put("abcd", "dcba");
    }

    public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
        for (int i = 0; i < callbacks.length; i++) {
            WSPasswordCallback pc = (WSPasswordCallback)callbacks[i];

            String pass = passwords.get(pc.getIdentifier());
            if (pass != null) {
                pc.setPassword(pass);
                return;
            }
        }
        
        throw new IOException();
    }
    
    // Add an alias/password pair to the callback mechanism.
    public void setAliasPassword(String alias, String password) {
        passwords.put(alias, password);
    }
}

The callback functionality is implemented by the CallbackHandler.handle() method. In this example, it assumed that the callback objects passed to the handle() method are all of org.apache.ws.security.WSPasswordCallback type (in a more realistic example, you would check the type of the callback objects).

A more realistic implementation of a client callback handler would probably consist of prompting the user to enter their password.

WSPasswordCallback class

When a CallbackHandler is called in a Fuse Services Framework client for the purpose of setting a UsernameToken password, the corresponding WSPasswordCallback object has the USERNAME_TOKEN usage code.

For more details about the WSPasswordCallback class, see org.apache.ws.security.WSPasswordCallback.

The WSPasswordCallback class defines several different usage codes, as follows:

USERNAME_TOKEN

Obtain the password for UsernameToken credentials. This usage code is used both on the client side (to obtain a password to send to the server) and on the server side (to obtain a password in order to compare it with the password received from the client).

On the server side, this code is set in the following cases:

  • Digest password—if the UsernameToken contains a digest password, the callback must return the corresponding password for the given user name (given by WSPasswordCallback.getIdentifier()). Verification of the password (by comparing with the digest password) is done by the WSS4J runtime.

  • Plaintext password—implemented the same way as the digest password case (since Fuse Services Framework 2.4.0).

  • Custom password type—if getHandleCustomPasswordTypes() is true on org.apache.ws.security.WSSConfig, this case is implemented the same way as the digest password case (since Fuse Services Framework 2.4.0). Otherwise, an exception is thrown.

If no Password element is included in a received UsernameToken on the server side, the callback handler is not called (since Fuse Services Framework 2.4.0).

DECRYPT

Need a password to retrieve a private key from a Java keystore, where WSPasswordCallback.getIdentifier() gives the alias of the keystore entry. WSS4J uses this private key to decrypt the session (symmetric) key.

SIGNATURE

Need a password to retrieve a private key from a Java keystore, where WSPasswordCallback.getIdentifier() gives the alias of the keystore entry. WSS4J uses this private key to produce a signature.

SECRET_KEY

Need a secret key for encryption or signature on the outbound side, or for decryption or verification on the inbound side. The callback handler must set the key using the setKey(byte[]) method.

SECURITY_CONTEXT_TOKEN

Need the key for a wsc:SecurityContextToken, which you provide by calling the setKey(byte[]) method.

CUSTOM_TOKEN

Need a token as a DOM element. For example, this is used for the case of a reference to a SAML Assertion or SecurityContextToken that is not in the message. The callback handler must set the token using the setCustomToken(Element) method.

KEY_NAME

(Obsolete) Since Fuse Services Framework 2.4.0, this usage code is obsolete.

USERNAME_TOKEN_UNKNOWN

(Obsolete) Since Fuse Services Framework 2.4.0, this usage code is obsolete.

UNKNOWN

Not used by WSS4J.

PK HAl OEBPS/Auth-Intro.html Introduction to Authentication

Introduction to Authentication

Overview

In Fuse Services Framework, an application can be set up to use authentication through a combination of policy assertions in the WSDL contract and configuration settings in Spring XML.

[Note]Note

Remember, you can also use the HTTPS protocol as the basis for authentication and, in some cases, this might be easier to configure. See Authentication Alternatives.

Steps to set up authentication

In outline, you need to perform the following steps to set up an application to use authentication:

  1. Add a supporting tokens policy to an endpoint in the WSDL contract. This has the effect of requiring the endpoint to include a particular type of token (client credentials) in its request messages.

  2. On the client side, provide credentials to send by configuring the relevant endpoint in Spring XML.

  3. (Optional) On the client side, if you decide to provide passwords using a callback handler, implement the callback handler in Java.

  4. On the server side, associate a callback handler class with the endpoint in Spring XML. The callback handler is then responsible for authenticating the credentials received from remote clients.

PK HA\=^^OEBPS/Auth-Policy.html Specifying an Authentication Policy

Specifying an Authentication Policy

Overview

If you want an endpoint to support authentication, associate a supporting tokens policy assertion with the relevant endpoint binding. There are several different kinds of supporting tokens policy assertions, whose elements all have names of the form *SupportingTokens (for example, SupportingTokens, SignedSupportingTokens, and so on). For a complete list, see SupportingTokens assertions.

Associating a supporting tokens assertion with an endpoint has the following effects:

  • Messages to or from the endpoint are required to include the specified token type (where the token's direction is specified by the sp:IncludeToken attribute).

  • Depending on the particular type of supporting tokens element you use, the endpoint might be required to sign and/or encrypt the token.

The supporting tokens assertion implies that the runtime will check that these requirements are satisified. But the WS-SecurityPolicy policies do not define the mechanism for providing credentials to the runtime. You must use Spring XML configuration to specify the credentials (see Providing Client Credentials).

Syntax

The *SupportingTokens elements (that is, all elements with the SupportingTokens suffix—see SupportingTokens assertions) have the following syntax:

<sp:SupportingTokensElement xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
    [Token Assertion]+
    <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite> ?
    (
      <sp:SignedParts ... > ... </sp:SignedParts> |
      <sp:SignedElements ... > ... </sp:SignedElements> |
      <sp:EncryptedParts ... > ... </sp:EncryptedParts> |
      <sp:EncryptedElements ... > ... </sp:EncryptedElements> |
    ) *
    ...
  </wsp:Policy>
  ...
</sp:SupportingTokensElement>

Where SupportingTokensElement stands for one of the supporting token elements, *SupportingTokens.Typically, if you simply want to include a token (or tokens) in the security header, you would include one or more token assertions, [Token Assertion], in the policy. In particular, this is all that is required for authentication.

If the token is of an appropriate type (for example, an X.509 certificate or a symmetric key), you could theoretically also use it to sign or encrypt specific parts of the current message using the sp:AlgorithmSuite, sp:SignedParts, sp:SignedElements, sp:EncryptedParts, and sp:EncryptedElements elements. This functionality is currently not supported by Fuse Services Framework, however.

Sample policy

Example 7.1 shows an example of a policy that requires a WS-Security UsernameToken token (which contains username/password credentials) to be included in the security header. In addition, because the token is specified inside an sp:SignedSupportingTokens element, the policy requires that the token is signed. This example uses a transport binding, so it is the underlying transport that is responsible for signing the message.

For example, if the underlying transport is HTTPS, the SSL/TLS protocol (configured with an appropriate algorithm suite) is responsible for signing the entire message, including the security header that contains the specified token. This is sufficient to satisfy the requirement that the supporting token is signed.

Example 7.1. Example of a Supporting Tokens Policy

<wsp:Policy wsu:Id="UserNameOverTransport_IPingService_policy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:TransportBinding> ... </sp:TransportBinding>
      <sp:SignedSupportingTokens
          xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:UsernameToken
              sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
            <wsp:Policy>
              <sp:WssUsernameToken10/>
            </wsp:Policy>
          </sp:UsernameToken>
        </wsp:Policy>
      </sp:SignedSupportingTokens>
      ...
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

Where the presence of the sp:WssUsernameToken10 sub-element indicates that the UsernameToken header should conform to version 1.0 of the WS-Security UsernameToken specification.

Token types

In principle, you can specify any of the WS-SecurityPolicy token types in a supporting tokens assertion. For SOAP-level authentication, however, only the sp:UsernameToken token type is relevant.

sp:UsernameToken

In the context of a supporting tokens assertion, this element specifies that a WS-Security UsernameToken is to be included in the security SOAP header. Essentially, a WS-Security UsernameToken is used to send username/password credentials in the WS-Security SOAP header. The sp:UsernameToken element has the following syntax:

<sp:UsernameToken sp:IncludeToken="xs:anyURI"? xmlns:sp="..." ... >
  (
    <sp:Issuer>wsa:EndpointReferenceType</sp:Issuer> |
    <sp:IssuerName>xs:anyURI</sp:IssuerName>
  ) ?
  <wst:Claims Dialect="..."> ... </wst:Claims> ?
  <wsp:Policy xmlns:wsp="...">
    (
      <sp:NoPassword ... /> |
      <sp:HashPassword ... />
    ) ?
    (
      <sp:RequireDerivedKeys /> |
      <sp:RequireImpliedDerivedKeys ... /> |
      <sp:RequireExplicitDerivedKeys ... />
    ) ?
    (
      <sp:WssUsernameToken10 ... /> |
      <sp:WssUsernameToken11 ... />
    ) ?
    ...
  </wsp:Policy>
  ...
</sp:UsernameToken>

The sub-elements of sp:UsernameToken are all optional and are not needed for ordinary authentication. Normally, the only part of this syntax that is relevant is the sp:IncludeToken attribute.

[Note]Note

Currently, in the sp:UsernameToken syntax, only the sp:WssUsernameToken10 sub-element is supported in Fuse Services Framework.

sp:IncludeToken attribute

The value of the sp:IncludeToken must match the WS-SecurityPolicy version from the enclosing policy. The current version is 1.2, but legacy WSDL might use version 1.1. Valid values of the sp:IncludeToken attribute are as follows:

Never

The token MUST NOT be included in any messages sent between the initiator and the recipient; rather, an external reference to the token should be used. Valid URI values are:

1.2

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/Never

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Never

Once

The token MUST be included in only one message sent from the initiator to the recipient. References to the token MAY use an internal reference mechanism. Subsequent related messages sent between the recipient and the initiator may refer to the token using an external reference mechanism. Valid URI values are:

1.2

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/Once

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Once

AlwaysToRecipient

The token MUST be included in all messages sent from initiator to the recipient. The token MUST NOT be included in messages sent from the recipient to the initiator. Valid URI values are:

1.2

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/AlwaysToRecipient

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/AlwaysToRecipient

AlwaysToInitiator

The token MUST be included in all messages sent from the recipient to the initiator. The token MUST NOT be included in messages sent from the initiator to the recipient. Valid URI values are:

1.2

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/AlwaysToInitiator

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/AlwaysToInitiator

Always

The token MUST be included in all messages sent between the initiator and the recipient. This is the default behavior. Valid URI values are:

1.2

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/Always

1.1

http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Always

SupportingTokens assertions

The following kinds of supporting tokens assertions are supported:

sp:SupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. No additional requirements are imposed.

[Warning]Warning

This policy does not explicitly require the tokens to be signed or encrypted. It is normally essential, however, to protect tokens by signing and encryption.

sp:SignedSupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. In addition, this policy requires that the token is signed, in order to guarantee token integrity.

[Warning]Warning

This policy does not explicitly require the tokens to be encrypted. It is normally essential, however, to protect tokens both by signing and encryption.

sp:EncryptedSupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. In addition, this policy requires that the token is encrypted, in order to guarantee token confidentiality.

[Warning]Warning

This policy does not explicitly require the tokens to be signed. It is normally essential, however, to protect tokens both by signing and encryption.

sp:SignedEncryptedSupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. In addition, this policy requires that the token is both signed and encrypted, in order to guarantee token integrity and confidentiality.

sp:EndorsingSupportingTokens

An endorsing supporting token is used to sign the message signature (primary signature). This signature is known as an endorsing signature or secondary signature. Hence, by applying an endorsing supporting tokens policy, you can have a chain of signatures: the primary signature, which signs the message itself, and the secondary signature, which signs the primary signature.

[Note]Note

If you are using a transport binding (for example, HTTPS), the message signature is not actually part of the SOAP message, so it is not possible to sign the message signature in this case. If you specify this policy with a transport binding, the endorsing token signs the timestamp instead.

[Warning]Warning

This policy does not explicitly require the tokens to be signed or encrypted. It is normally essential, however, to protect tokens by signing and encryption.

sp:SignedEndorsingSupportingTokens

This policy is the same as the endorsing supporting tokens policy, except that the tokens are required to be signed, in order to guarantee token integrity.

[Warning]Warning

This policy does not explicitly require the tokens to be encrypted. It is normally essential, however, to protect tokens both by signing and encryption.

sp:EndorsingEncryptedSupportingTokens

This policy is the same as the endorsing supporting tokens policy, except that the tokens are required to be encrypted, in order to guarantee token confidentiality.

[Warning]Warning

This policy does not explicitly require the tokens to be signed. It is normally essential, however, to protect tokens both by signing and encryption.

sp:SignedEndorsingEncryptedSupportingTokens

This policy is the same as the endorsing supporting tokens policy, except that the tokens are required to be signed and encrypted, in order to guarantee token integrity and confidentiality.

PK HAOOEBPS/Auth.html Chapter 7. Authentication

Chapter 7. Authentication

This chapter describes how to use policies to configure authentication in a Fuse Services Framework application. Currently, the only credentials type supported in the SOAP layer is the WS-Security UsernameToken.

Introduction to Authentication
Specifying an Authentication Policy
Providing Client Credentials
Authenticating Received Credentials
PK HA;OEBPS/CiphersJava.html Chapter 4. Configuring HTTPS Cipher Suites

Chapter 4. Configuring HTTPS Cipher Suites

This chapter explains how to specify the list of cipher suites that are made available to clients and servers for the purpose of establishing HTTPS connections. During a security handshake, the client chooses a cipher suite that matches one of the cipher suites available to the server.

Supported Cipher Suites
Cipher Suite Filters
SSL/TLS Protocol Version
PK HAY+OEBPS/ConfigTLS.html Chapter 3. Configuring HTTPS

Chapter 3. Configuring HTTPS

This chapter describes how to configure HTTPS endpoints.

Authentication Alternatives
Target-Only Authentication
Mutual Authentication
Specifying Trusted CA Certificates
When to Deploy Trusted CA Certificates
Specifying Trusted CA Certificates for HTTPS
Specifying an Application’s Own Certificate
Deploying Own Certificate for HTTPS
PK HApv OEBPS/DN.html Appendix A. ASN.1 and Distinguished Names

Appendix A. ASN.1 and Distinguished Names

The OSI Abstract Syntax Notation One (ASN.1) and X.500 Distinguished Names play an important role in the security standards that define X.509 certificates and LDAP directories.

ASN.1
Distinguished Names
PK HALnf1x1xOEBPS/HTTPCompatible.html Chapter 1. Security for HTTP-Compatible Bindings

Chapter 1. Security for HTTP-Compatible Bindings

This chapter describes the security features supported by the Fuse Services Framework HTTP transport. These security features are available to any Fuse Services Framework binding that can be layered on top of the HTTP transport.

Overview

This section describes how to configure the HTTP transport to use SSL/TLS security, a combination usually referred to as HTTPS. In Fuse Services Framework, HTTPS security is configured by specifying settings in XML configuration files.

The following topics are discussed in this chapter:

Generating X.509 certificates

A basic prerequisite for using SSL/TLS security is to have a collection of X.509 certificates available to identify your server applications and, optionally, to identify your client applications. You can generate X.509 certificates in one of the following ways:

[Note]Note

The HTTPS protocol mandates a URL integrity check, which requires a certificate’s identity to match the hostname on which the server is deployed. See Special Requirements on HTTPS Certificates for details.

Certificate format

In the Java runtime, you must deploy X.509 certificate chains and trusted CA certificates in the form of Java keystores. See Configuring HTTPS for details.

Enabling HTTPS

A prerequisite for enabling HTTPS on a WSDL endpoint is that the endpoint address must be specified as a HTTPS URL. There are two different locations where the endpoint address is set and both must be modified to use a HTTPS URL:

HTTPS client with no certificate

For example, consider the configuration for a secure HTTPS client with no certificate, as shown in Example 1.3.

Example 1.3. Sample HTTPS Client with No Certificate

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:sec="http://cxf.apache.org/configuration/security"
       xmlns:http="http://cxf.apache.org/transports/http/configuration"
       xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
       xsi:schemaLocation="...">
                    
    <http:conduit name="{http://apache.org/hello_world_soap_http}SoapPort.http-conduit"> 1
      <http:tlsClientParameters> 2
        <sec:trustManagers> 3
          <sec:keyStore type="JKS" password="password"
                        file="certs/truststore.jks"/>
        </sec:trustManagers>
        <sec:cipherSuitesFilter> 4
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
    </http:tlsClientParameters>
  </http:conduit>
  
</beans>

The preceding client configuration is described as follows:

1

The TLS security settings are defined on a specific WSDL port. In this example, the WSDL port being configured has the QName, {http://apache.org/hello_world_soap_http}SoapPort.

2

The http:tlsClientParameters element contains all of the client’s TLS configuration details.

3

The sec:trustManagers element is used to specify a list of trusted CA certificates (the client uses this list to decide whether or not to trust certificates received from the server side).

The file attribute of the sec:keyStore element specifies a Java keystore file, truststore.jks, containing one or more trusted CA certificates. The password attribute specifies the password required to access the keystore, truststore.jks. See Specifying Trusted CA Certificates for HTTPS.

[Note]Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute (where the keystore file is provided on the classpath) or the url attribute. In particular, the resource attribute must be used with applications that are deployed into an OSGi container. You must be extremely careful not to load the truststore from an untrustworthy source.

4

The sec:cipherSuitesFilter element can be used to narrow the choice of cipher suites that the client is willing to use for a TLS connection. See Configuring HTTPS Cipher Suites for details.

HTTPS client with certificate

Consider a secure HTTPS client that is configured to have its own certificate. Example 1.4 shows how to configure such a sample client.

Example 1.4. Sample HTTPS Client with Certificate

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:sec="http://cxf.apache.org/configuration/security"
 xmlns:http="http://cxf.apache.org/transports/http/configuration"
 xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
 xsi:schemaLocation="...">

  <http:conduit name="{http://apache.org/hello_world_soap_http}SoapPort.http-conduit">
    <http:tlsClientParameters>
      <sec:trustManagers>
          <sec:keyStore type="JKS" password="password"
               file="certs/truststore.jks"/>
      </sec:trustManagers>
      <sec:keyManagers keyPassword="password"> 1
           <sec:keyStore type="JKS" password="password" 2
                file="certs/wibble.jks"/>
      </sec:keyManagers>
      <sec:cipherSuitesFilter>
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
    </http:tlsClientParameters>
   </http:conduit>
  
    <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl"/>
</beans>

The preceding client configuration is described as follows:

1

The sec:keyManagers element is used to attach an X.509 certificate and a private key to the client. The password specified by the keyPasswod attribute is used to decrypt the certificate’s private key.

2

The sec:keyStore element is used to specify an X.509 certificate and a private key that are stored in a Java keystore. This sample declares that the keystore is in Java Keystore format (JKS).

The file attribute specifies the location of the keystore file, wibble.jks, that contains the client’s X.509 certificate chain and private key in a key entry. The password attribute specifies the keystore password which is required to access the contents of the keystore.

It is expected that the keystore file contains just one key entry, so it is not necessary to specify a key alias to identify the entry. If you are deploying a keystore file with multiple key entries, however, it is possible to specify the key in this case by adding the sec:certAlias element as a child of the http:tlsClientParameters element, as follows:

<http:tlsClientParameters>
    ...
    <sec:certAlias>CertAlias</sec:certAlias>
    ...
</http:tlsClientParameters>

For details of how to create a keystore file, see Use the CA to Create Signed Certificates in a Java Keystore.

[Note]Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute (where the keystore file is provided on the classpath) or the url attribute. In particular, the resource attribute must be used with applications that are deployed into an OSGi container. You must be extremely careful not to load the truststore from an untrustworthy source.

HTTPS server configuration

Consider a secure HTTPS server that requires clients to present an X.509 certificate. Example 1.5 shows how to configure such a server.

Example 1.5. Sample HTTPS Server Configuration

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sec="http://cxf.apache.org/configuration/security"
xmlns:http="http://cxf.apache.org/transports/http/configuration"
xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
xsi:schemaLocation="...">

  <httpj:engine-factory bus="cxf"> 1
   <httpj:engine port="9001"> 2
    <httpj:tlsServerParameters> 3
      <sec:keyManagers keyPassword="password"> 4
           <sec:keyStore type="JKS" password="password" 5
                file="certs/cherry.jks"/>
      </sec:keyManagers>
      <sec:trustManagers> 6
          <sec:keyStore type="JKS" password="password"
               file="certs/truststore.jks"/>
      </sec:trustManagers>
      <sec:cipherSuitesFilter> 7
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
      <sec:clientAuthentication want="true" required="true"/> 8
    </httpj:tlsServerParameters>
   </httpj:engine>
  </httpj:engine-factory>
  
</beans>

The preceding server configuration is described as follows:

1

The bus attribute references the relevant CXF Bus instance. By default, a CXF Bus instance with the ID, cxf, is automatically created by the Fuse Services Framework runtime.

2

On the server side, TLS is not configured for each WSDL port. Instead of configuring each WSDL port, the TLS security settings are applied to a specific IP port, which is 9001 in this example. All of the WSDL ports that share this IP port are therefore configured with the same TLS security settings.

3

The http:tlsServerParameters element contains all of the server’s TLS configuration details.

4

The sec:keyManagers element is used to attach an X.509 certificate and a private key to the server. The password specified by the keyPasswod attribute is used to decrypt the certificate’s private key.

5

The sec:keyStore element is used to specify an X.509 certificate and a private key that are stored in a Java keystore. This sample declares that the keystore is in Java Keystore format (JKS).

The file attribute specifies the location of the keystore file, cherry.jks, that contains the client’s X.509 certificate chain and private key in a key entry. The password attribute specifies the keystore password, which is needed to access the contents of the keystore.

It is expected that the keystore file contains just one key entry, so it is not necessary to specify a key alias to identify the entry. If you are deploying a keystore file with multiple key entries, however, it is possible to specify the key in this case by adding the sec:certAlias element as a child of the http:tlsClientParameters element, as follows:

<http:tlsClientParameters>
    ...
    <sec:certAlias>CertAlias</sec:certAlias>
    ...
</http:tlsClientParameters>
[Note]Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute or the url attribute. You must be extremely careful not to load the truststore from an untrustworthy source.

For details of how to create such a keystore file, see Use the CA to Create Signed Certificates in a Java Keystore.

6

The sec:trustManagers element is used to specify a list of trusted CA certificates (the server uses this list to decide whether or not to trust certificates presented by clients).

The file attribute of the sec:keyStore element specifies a Java keystore file, truststore.jks, containing one or more trusted CA certificates. The password attribute specifies the password required to access the keystore, truststore.jks. See Specifying Trusted CA Certificates for HTTPS.

[Note]Note

Instead of the file attribute, you can specify the location of the keystore using either the resource attribute or the url attribute.

7

The sec:cipherSuitesFilter element can be used to narrow the choice of cipher suites that the server is willing to use for a TLS connection. See Configuring HTTPS Cipher Suites for details.

8

The sec:clientAuthentication element determines the server’s disposition towards the presentation of client certificates. The element has the following attributes:

  • want attribute—If true (the default), the server requests the client to present an X.509 certificate during the TLS handshake; if false, the server does not request the client to present an X.509 certificate.

  • required attribute—If true, the server raises an exception if a client fails to present an X.509 certificate during the TLS handshake; if false (the default), the server does not raise an exception if the client fails to present an X.509 certificate.

PK HA_ OEBPS/ManageCerts.html Chapter 2. Managing Certificates

Chapter 2. Managing Certificates

TLS authentication uses X.509 certificates—a common, secure and reliable method of authenticating your application objects. This chapter explains how to create X.509 certificates that identify your Fuse Services Framework applications.

What is an X.509 Certificate?
Certification Authorities
Choice of CAs
Commercial Certification Authorities
Private Certification Authorities
Certificate Chaining
Special Requirements on HTTPS Certificates
Creating Your Own Certificates
Prerequisites
Set Up Your Own CA
Use the CA to Create Signed Certificates in a Java Keystore
Use the CA to Create Signed PKCS#12 Certificates
PK HAge{H{H+OEBPS/MsgProtect-SOAP-AsymmetricPolicy.html Specifying an AsymmetricBinding Policy

Specifying an AsymmetricBinding Policy

Overview

The asymmetric binding policy implements SOAP message protection using asymmetric key algorithms (public/private key combinations) and does so at the SOAP layer. The encryption and signing algorithms used by the asymmetric binding are similar to the encryption and signing algorithms used by SSL/TLS. A crucial difference, however, is that SOAP message protection enables you to select particular parts of a message to protect (for example, individual headers, body, or attachments), whereas transport layer security can operate only on the whole message.

Policy subject

An asymmetric binding policy must be applied to an endpoint policy subject (see Endpoint policy subject). For example, given the asymmetric binding policy with ID, MutualCertificate10SignEncrypt_IPingService_policy, you could apply the policy to an endpoint binding as follows:

<wsdl:binding name="MutualCertificate10SignEncrypt_IPingService" type="i0:IPingService">
  <wsp:PolicyReference URI="#MutualCertificate10SignEncrypt_IPingService_policy"/>
  ...
</wsdl:binding>

Syntax

The AsymmetricBinding element has the following syntax:

<sp:AsymmetricBinding xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
  (
   <sp:InitiatorToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:InitiatorToken>
  ) | (
   <sp:InitiatorSignatureToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:InitiatorSignatureToken>
   <sp:InitiatorEncryptionToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:InitiatorEncryptionToken>
  )
  (
   <sp:RecipientToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:RecipientToken>
  ) | (
   <sp:RecipientSignatureToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:RecipientSignatureToken>
   <sp:RecipientEncryptionToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:RecipientEncryptionToken>
  )
   <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite>
   <sp:Layout ... > ... </sp:Layout> ?
   <sp:IncludeTimestamp ... /> ?
   <sp:EncryptBeforeSigning ... /> ?
   <sp:EncryptSignature ... /> ?
   <sp:ProtectTokens ... /> ?
   <sp:OnlySignEntireHeadersAndBody ... /> ?
   ...
  </wsp:Policy>
  ...
</sp:AsymmetricBinding>

Sample policy

Example 6.4 shows an example of an asymmetric binding that supports message protection with signatures and encryption, where the signing and encryption is done using pairs of public/private keys (that is, using asymmetric cryptography). This example does not specify which parts of the message should be signed and encrypted, however. For details of how to do that, see Specifying Parts of Message to Encrypt and Sign.

Example 6.4. Example of an Asymmetric Binding

<wsp:Policy wsu:Id="MutualCertificate10SignEncrypt_IPingService_policy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:AsymmetricBinding
          xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:InitiatorToken>
            <wsp:Policy>
              <sp:X509Token
                  sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
                <wsp:Policy>
                  <sp:WssX509V3Token10/>
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:InitiatorToken>
          <sp:RecipientToken>
            <wsp:Policy>
              <sp:X509Token
                  sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token10/>
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:RecipientToken>
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic256/>
            </wsp:Policy>
          </sp:AlgorithmSuite>
          <sp:Layout>
            <wsp:Policy>
              <sp:Lax/>
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp/>
          <sp:EncryptSignature/>
          <sp:OnlySignEntireHeadersAndBody/>
        </wsp:Policy>
      </sp:AsymmetricBinding>
      <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:MustSupportRefKeyIdentifier/>
          <sp:MustSupportRefIssuerSerial/>
        </wsp:Policy>
      </sp:Wss10>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

sp:InitiatorToken

The initiator token refers to the public/private key-pair owned by the initiator. This token is used as follows:

Confusingly, this token is used both by the initiator and by the recipient. However, only the initiator has access to the private key so, in this sense, the token can be said to belong to the initiator. In Basic Signing and Encryption Scenario, the initiator token is the certificate, Alice.

This element should contain a nested wsp:Policy element and sp:X509Token element as shown. The sp:IncludeToken attribute is set to AlwaysToRecipient, which instructs the runtime to include Alice's public key with every message sent to the recipient. This option is useful, in case the recipient wants to use the initiator's certificate to perform authentication. The most deeply nested element, WssX509V3Token10 is optional. It specifies what specification version the X.509 certificate should conform to. The following alternatives (or none) can be specified here:

sp:WssX509V3Token10

This optional element is a policy assertion that indicates that an X509 Version 3 token should be used.

sp:WssX509Pkcs7Token10

This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used.

sp:WssX509PkiPathV1Token10

This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used.

sp:WssX509V1Token11

This optional element is a policy assertion that indicates that an X509 Version 1 token should be used.

sp:WssX509V3Token11

This optional element is a policy assertion that indicates that an X509 Version 3 token should be used.

sp:WssX509Pkcs7Token11

This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used.

sp:WssX509PkiPathV1Token11

This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used.

sp:RecipientToken

The recipient token refers to the public/private key-pair owned by the recipient. This token is used as follows:

Confusingly, this token is used both by the recipient and by the initiator. However, only the recipient has access to the private key so, in this sense, the token can be said to belong to the recipient. In Basic Signing and Encryption Scenario, the recipient token is the certificate, Bob.

This element should contain a nested wsp:Policy element and sp:X509Token element as shown. The sp:IncludeToken attribute is set to Never, because there is no need to include Bob's public key in the reply messages.

[Note]Note

In Fuse Services Framework, there is never a need to send Bob's or Alice's token in a message, because both Bob's certificate and Alice's certificate are provided at both ends of the connection—see Providing Encryption Keys and Signing Keys.

sp:AlgorithmSuite

This element specifies the suite of cryptographic algorithms to use for signing and encryption. For details of the available algorithm suites, see Specifying the Algorithm Suite.

sp:Layout

This element specifies whether to impose any conditions on the order in which security headers are added to the SOAP message. The sp:Lax element specifies that no conditions are imposed on the order of security headers. The alternatives to sp:Lax are sp:Strict, sp:LaxTimestampFirst, or sp:LaxTimestampLast.

sp:IncludeTimestamp

If this element is included in the policy, the runtime adds a wsu:Timestamp element to the wsse:Security header. By default, the timestamp is not included.

sp:EncryptBeforeSigning

If a message part is subject to both encryption and signing, it is necessary to specify the order in which these operations are performed. The default order is to sign before encrypting. But if you include this element in your asymmetric policy, the order is changed to encrypt before signing.

[Note]Note

Implicitly, this element also affects the order of the decryption and signature verification operations. For example, if the sender of a message signs before encrypting, the receiver of the message must decrypt before verifying the signature.

sp:EncryptSignature

This element specifies that the message signature must be encrypted (by the encryption token, specified as described in Providing Encryption Keys and Signing Keys). Default is false.

[Note]Note

The message signature is the signature obtained directly by signing various parts of the message, such as message body, message headers, or individual elements (see Specifying Parts of Message to Encrypt and Sign). Sometimes the message signature is referred to as the primary signature, because the WS-SecurityPolicy specification also supports the concept of an endorsing supporting token, which is used to sign the primary signature. Hence, if an sp:EndorsingSupportingTokens element is applied to an endpoint, you can have a chain of signatures: the primary signature, which signs the message itself, and the secondary signature, which signs the primary signature.

For more details about the various kinds of endorsing supporting token, see SupportingTokens assertions.

sp:ProtectTokens

This element specifies that signatures must cover the token used to generate that signature. Default is false.

sp:OnlySignEntireHeadersAndBody

This element specifies that signatures can be applied only to an entire body or to entire headers, not to sub-elements of the body or sub-elements of a header. When this option is enabled, you are effectively prevented from using the sp:SignedElements assertion (see Specifying Parts of Message to Encrypt and Sign).

PK HA!!)OEBPS/MsgProtect-SOAP-EncryptAndSign.html Specifying Parts of Message to Encrypt and Sign

Specifying Parts of Message to Encrypt and Sign

Overview

Encryption and signing provide two kinds of protection: confidentiality and integrity, respectively. The WS-SecurityPolicy protection assertions are used to specify which parts of a message are subject to protection. Details of the protection mechanisms, on the other hand, are specified separately in the relevant binding policy (see xSpecifying an AsymmetricBinding Policy, Specifying a SymmetricBinding Policy, and Transport Layer Message Protection).

The protection assertions described here are really intended to be used in combination with SOAP security, because they apply to features of a SOAP message. Nonetheless, these policies can also be satisfied by a transport binding (such as HTTPS), which applies protection to the entire message, rather than to specific parts.

Policy subject

A protection assertion must be applied to a message policy subject (see Message policy subject). In other words, it must be placed inside a wsdl:input, wsdl:output, or wsdl:fault element in a WSDL binding. For example, given the protection policy with ID, MutualCertificate10SignEncrypt_IPingService_header_Input_policy, you could apply the policy to a wsdl:input message part as follows:

<wsdl:operation name="header">
  <soap:operation soapAction="http://InteropBaseAddress/interop/header" style="document"/>
  <wsdl:input name="headerRequest">
    <wsp:PolicyReference
        URI="#MutualCertificate10SignEncrypt_IPingService_header_Input_policy"/>
      <soap:header message="i0:headerRequest_Headers" part="CustomHeader" use="literal"/>
      <soap:body use="literal"/>
    </wsdl:input>
    ...
</wsdl:operation>

Protection assertions

The following WS-SecurityPolicy protection assertions are currently supported by Fuse Services Framework:

The following WS-SecurityPolicy protection assertions are not supported by Fuse Services Framework:

Syntax

The SignedParts element has the following syntax:

<sp:SignedParts xmlns:sp="..." ... >
  <sp:Body />?
  <sp:Header Name="xs:NCName"? Namespace="xs:anyURI" ... />*
  <sp:Attachments />?
  ...
</sp:SignedParts>

The EncryptedParts element has the following syntax:

<sp:EncryptedParts xmlns:sp="..." ... >
  <sp:Body/>? 
  <sp:Header Name="xs:NCName"? Namespace="xs:anyURI" ... />* 
  <sp:Attachments />? 
  ... 
</sp:EncryptedParts>

Sample policy

Example 6.6 shows a policy that combines two protection assertions: a signed parts assertion and an encrypted parts assertion. When this policy is applied to a message part, the affected message bodies are signed and encrypted. In addition, the message header named CustomHeader is signed.

Example 6.6. Integrity and Encryption Policy Assertions

<wsp:Policy wsu:Id="MutualCertificate10SignEncrypt_IPingService_header_Input_policy">
    <wsp:ExactlyOne>
        <wsp:All>
            <sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
                <sp:Body/>
                <sp:Header Name="CustomHeader" Namespace="http://InteropBaseAddress/interop"/>
            </sp:SignedParts>
            <sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
                <sp:Body/>
            </sp:EncryptedParts>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

sp:Body

This element specifies that protection (encryption or signing) is applied to the body of the message. The protection is applied to the entire message body: that is, the soap:Body element, its attributes, and its content.

sp:Header

This element specifies that protection is applied to the SOAP header specified by the header's local name, using the Name attribute, and namespace, using the Namespace attribute. The protection is applied to the entire message header, including its attributes and its content.

sp:Attachments

This element specifies that all SOAP with Attachments (SwA) attachments are protected.

PK HA_0Iss OEBPS/MsgProtect-SOAP-Intro.html Introduction to SOAP Message Protection

Introduction to SOAP Message Protection

Overview

By applying message protection at the SOAP encoding layer, instead of at the transport layer, you have access to a more flexible range of protection policies. In particular, because the SOAP layer is aware of the message structure, you can apply protection at a finer level of granularity—for example, by encrypting and signing only those headers that actually require protection. This feature enables you to support more sophisticated multi-tier architectures. For example, one plaintext header might be aimed at an intermediate tier (located within a secure intranet), while an encrypted header might be aimed at the final destination (reached through an insecure public network).

Security bindings

As described in the WS-SecurityPolicy specification, one of the following binding types can be used to protect SOAP messages:

Message protection

The following qualities of protection can be applied to part or all of a message:

These qualities of protection can be arbitrarily combined in a single message. Thus, some parts of a message can be just encrypted, while other parts of the message are just signed, and other parts of the message can be both signed and encrypted. It is also possible to leave parts of the message unprotected.

The most flexible options for applying message protection are available at the SOAP layer (sp:AsymmetricBinding or sp:SymmetricBinding). The transport layer (sp:TransportBinding) only gives you the option of applying protection to the whole message.

Specifying parts of the message to protect

Currently, Fuse Services Framework enables you to sign or encrypt the following parts of a SOAP message:

The WS-SecurityPolicy specification also defines policies for applying protection to individual XML elements, but this is currently not supported in Fuse Services Framework.

Role of configuration

Not all of the details required for message protection are specified using policies. The policies are primarily intended to provide a way of specifying the quality of protection required for a service. Supporting details, such as security tokens, passwords, and so on, must be provided using a separate, product-specific mechanism. In practice, this means that in Fuse Services Framework, some supporting configuration details must be provided in Spring XML configuration files. For details, see Providing Encryption Keys and Signing Keys.

PK HAj)eReR&OEBPS/MsgProtect-SOAP-ProvideKeys.html Providing Encryption Keys and Signing Keys

Providing Encryption Keys and Signing Keys

Overview

The standard WS-SecurityPolicy policies are designed to specify security requirements in some detail: for example, security protocols, security algorithms, token types, authentication requirements, and so on, are all described. But the standard policy assertions do not provide any mechanism for specifying associated security data, such as keys and credentials. WS-SecurityPolicy expects that the requisite security data is provided through a proprietary mechanism. In Fuse Services Framework, the associated security data is provided through Spring XML configuration.

Configuring encryption keys and signing keys

You can specify an application's encryption keys and signing keys by setting properties on a client's request context or on an endpoint context (see Add encryption and signing properties to Spring configuration). The properties you can set are shown in Table 6.1.

Table 6.1. Encryption and Signing Properties

PropertyDescription
ws-security.signature.propertiesThe WSS4J properties file/object that contains the WSS4J properties for configuring the signature keystore (which is also used for decrypting) and Crypto objects.
ws-security.signature.username(Optional) The username or alias of the key in the signature keystore to use. If not specified, the alias set in the properties file is used. If that is also not set, and the keystore only contains a single key, that key will be used.
ws-security.encryption.propertiesThe WSS4J properties file/object that contains the WSS4J properties for configuring the encryption keystore (which is also used for validating signatures) and Crypto objects.
ws-security.encryption.username(Optional) The username or alias of the key in the encryption keystore to use. If not specified, the alias set in the properties file is used. If that is also not set, and the keystore only contains a single key, that key will be used.
[Tip]Tip

The names of the preceding properties are not so well chosen, because they do not accurately reflect what they are used for. The key specified by ws-security.signature.properties is actually used both for signing and decrypting. The key specified by ws-security.encryption.properties is actually used both for encrypting and for validating signatures.

Add encryption and signing properties to Spring configuration

Before you can use any WS-Policy policies in a Fuse Services Framework application, you must add the policies feature to the default CXF bus. Add the p:policies element to the CXF bus, as shown in the following Spring configuration fragment:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xmlns:cxf="http://cxf.apache.org/core"
       xmlns:p="http://cxf.apache.org/policy" ... >

    <cxf:bus>
        <cxf:features>
            <p:policies/>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>
    ...
</beans>

The following example shows how to add signature and encryption properties to proxies of the specified service type (where the service name is specified by the name attribute of the jaxws:client element). The properties are stored in WSS4J property files, where alice.properties contains the properties for the signature key and bob.properties contains the properties for the encryption key.

<beans ... >
    <jaxws:client name="{http://InteropBaseAddress/interop}MutualCertificate10SignEncrypt_IPingService"
                  createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.signature.properties" value="etc/alice.properties"/>
            <entry key="ws-security.encryption.properties" value="etc/bob.properties"/>
        </jaxws:properties>
    </jaxws:client>
    ...
</beans>

In fact, although it is not obvious from the property names, each of these keys is used for two distinct purposes on the client side:

If you find this confusing, see Basic Signing and Encryption Scenario for a more detailed explanation.

The following example shows how to add signature and encryption properties to a JAX-WS endpoint. The properties file, bob.properties, contains the properties for the signature key and the properties file, alice.properties, contains the properties for the encryption key (this is the inverse of the client configuration).

<beans ... >
    <jaxws:endpoint 
       name="{http://InteropBaseAddress/interop}MutualCertificate10SignEncrypt_IPingService"
       id="MutualCertificate10SignEncrypt"
       address="http://localhost:9002/MutualCertificate10SignEncrypt" 
       serviceName="interop:PingService10"
       endpointName="interop:MutualCertificate10SignEncrypt_IPingService"
       implementor="interop.server.MutualCertificate10SignEncrypt">
        
        <jaxws:properties>
            <entry key="ws-security.signature.properties" value="etc/bob.properties"/>
            <entry key="ws-security.encryption.properties" value="etc/alice.properties"/>
        </jaxws:properties> 

    </jaxws:endpoint> 
    ...
</beans>

Each of these keys is used for two distinct purposes on the server side:

  • bob.properties (that is, the key specified by ws-security.signature.properties) is used on the server side as follows:

    • For signing outgoing messages.

    • For decrypting incoming messages.

  • alice.properties (that is, the key specified by ws-security.encryption.properties) is used on the server side as follows:

    • For encrypting outgoing messages.

    • For verifying signatures on incoming messages.

Define the WSS4J property files

Fuse Services Framework uses WSS4J property files to load the public keys and the private keys needed for encryption and signing. Table 6.2 describes the properties that you can set in these files.

Table 6.2. WSS4J Keystore Properties

PropertyDescription

org.apache.ws.security. crypto.provider

Specifies an implementation of the Crypto interface (see WSS4J Crypto interface). Normally, you specify the default WSS4J implementation of Crypto, org.apache.ws.security.components.crypto.Merlin.

The rest of the properties in this table are specific to the Merlin implementation of the Crypto interface.

org.apache.ws.security. crypto.merlin.keystore.provider

(Optional) The name of the JSSE keystore provider to use. The default keystore provider is Bouncy Castle. You can switch provider to Sun's JSSE keystore provider by setting this property to SunJSSE.

org.apache.ws.security. crypto.merlin.keystore.type

The Bouncy Castle keystore provider supports the following types of keystore: JKS and PKCS12. In addition, Bouncy Castle supports the following proprietary keystore types: BKS and UBER.

org.apache.ws.security. crypto.merlin.keystore.file

Specifies the location of the keystore file to load, where the location is specified relative to the Classpath.

org.apache.ws.security. crypto.merlin.keystore.alias

(Optional) If the keystore type is JKS (Java keystore), you can select a specific key from the keystore by specifying its alias. If the keystore contains only one key, there is no need to specify an alias.

org.apache.ws.security. crypto.merlin.keystore.password

The password specified by this property is used for two purposes: to unlock the keystore (keystore password) and to decrypt a private key that is stored in the keystore (private key password). Hence, the keystore password must be same as the private key password.

For example, the etc/alice.properties file contains property settings to load the PKCS#12 file, certs/alice.pfx, as follows:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin

org.apache.ws.security.crypto.merlin.keystore.type=PKCS12
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.file=certs/alice.pfx

The etc/bob.properties file contains property settings to load the PKCS#12 file, certs/bob.pfx, as follows:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin

org.apache.ws.security.crypto.merlin.keystore.password=password

# for some reason, bouncycastle has issues with bob.pfx
org.apache.ws.security.crypto.merlin.keystore.provider=SunJSSE
org.apache.ws.security.crypto.merlin.keystore.type=PKCS12
org.apache.ws.security.crypto.merlin.keystore.file=certs/bob.pfx

Programming encryption keys and signing keys

An alternative approach to loading encryption keys and signing keys is to use the properties shown in Table 6.3 to specify Crypto objects that load the relevant keys. This requires you to provide your own implementation of the WSS4J Crypto interface, org.apache.ws.security.components.crypto.Crypto.

Table 6.3. Properties for Specifying Crypto Objects

PropertyDescription
ws-security.signature.cryptoSpecifies an instance of a Crypto object that is responsible for loading the keys for signing and decrypting messages.
ws-security.encryption.cryptoSpecifies an instance of a Crypto object that is responsible for loading the keys for encrypting messages and verifying signatures.

WSS4J Crypto interface

Example 6.7 shows the definition of the Crypto interface that you can implement, if you want to provide encryption keys and signing keys by programming. For more information, see the WSS4J home page.

Example 6.7. WSS4J Crypto Interface

// Java
package org.apache.ws.security.components.crypto;

import org.apache.ws.security.WSSecurityException;

import java.io.InputStream;
import java.math.BigInteger;
import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.cert.Certificate;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;

public interface Crypto {
    X509Certificate loadCertificate(InputStream in)
    throws WSSecurityException;

    X509Certificate[] getX509Certificates(byte[] data, boolean reverse)
    throws WSSecurityException;

    byte[] getCertificateData(boolean reverse, X509Certificate[] certs)
    throws WSSecurityException;

    public PrivateKey getPrivateKey(String alias, String password)
    throws Exception;

    public X509Certificate[] getCertificates(String alias)
    throws WSSecurityException;

    public String getAliasForX509Cert(Certificate cert)
    throws WSSecurityException;

    public String getAliasForX509Cert(String issuer)
    throws WSSecurityException;

    public String getAliasForX509Cert(String issuer, BigInteger serialNumber)
    throws WSSecurityException;

    public String getAliasForX509Cert(byte[] skiBytes)
    throws WSSecurityException;

    public String getDefaultX509Alias();

    public byte[] getSKIBytesFromCert(X509Certificate cert)
    throws WSSecurityException;
 
    public String getAliasForX509CertThumb(byte[] thumb)
    throws WSSecurityException;
 
    public KeyStore getKeyStore();

    public CertificateFactory getCertificateFactory()
    throws WSSecurityException;

    public boolean validateCertPath(X509Certificate[] certs)
    throws WSSecurityException;

    public String[] getAliasesForDN(String subjectDN)
    throws WSSecurityException;
}
PK HAf00.OEBPS/MsgProtect-SOAP-SignEncryptScenario.html Basic Signing and Encryption Scenario

Basic Signing and Encryption Scenario

Overview

The scenario described here is a client-server application, where an asymmetric binding policy is set up to encrypt and sign the SOAP body of messages that pass back and forth between the client and the server.

Example scenario

Figure 6.1 shows an overview of the basic signing and encryption scenario, which is specified by associating an asymmetric binding policy with an endpoint in the WSDL contract.

Figure 6.1. Basic Signing and Encryption Scenario

Basic Signing and Encryption Scenario

Scenario steps

When the client in Figure 6.1 invokes a synchronous operation on the recipient's endpoint, the request and reply message are processed as follows:

  1. As the outgoing request message passes through the WS-SecurityPolicy handler, the handler processes the message in accordance with the policies specified in the client’s asymmetric binding policy. In this example, the handler performs the following processing:

    1. Encrypt the SOAP body of the message using Bob’s public key.

    2. Sign the encrypted SOAP body using Alice’s private key.

  2. As the incoming request message passes through the server's WS-SecurityPolicy handler, the handler processes the message in accordance with the policies specified in the server’s asymmetric binding policy. In this example, the handler performs the following processing:

    1. Verify the signature using Alice’s public key.

    2. Decrypt the SOAP body using Bob’s private key.

  3. As the outgoing reply message passes back through the server's WS-SecurityPolicy handler, the handler performs the following processing:

    1. Encrypt the SOAP body of the message using Alice’s public key.

    2. Sign the encrypted SOAP body using Bob’s private key.

  4. As the incoming reply message passes back through the client's WS-SecurityPolicy handler, the handler performs the following processing:

    1. Verify the signature using Bob’s public key.

    2. Decrypt the SOAP body using Alice’s private key.

PK HA5R5R0OEBPS/MsgProtect-SOAP-SpecifyAlgorithmSuite.html Specifying the Algorithm Suite

Specifying the Algorithm Suite

Overview

An algorithm suite is a coherent collection of cryptographic algorithms for performing operations such as signing, encryption, generating message digests, and so on.

For reference purposes, this section describes the algorithm suites defined by the WS-SecurityPolicy specification. Whether or not a particular algorithm suite is available, however, depends on the underlying security provider. Fuse Services Framework security is based on the pluggable Java Cryptography Extension (JCE) and Java Secure Socket Extension (JSSE) layers. By default, Fuse Services Framework is configured with Sun's JSSE provider, which supports the cipher suites described in Appendix A of Sun's JSSE Reference Guide.

Syntax

The AlgorithmSuite element has the following syntax:

<sp:AlgorithmSuite xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
   (<sp:Basic256 ... /> |
    <sp:Basic192 ... /> |
    <sp:Basic128 ... /> |
    <sp:TripleDes ... /> |
    <sp:Basic256Rsa15 ... /> |
    <sp:Basic192Rsa15 ... /> |
    <sp:Basic128Rsa15 ... /> |
    <sp:TripleDesRsa15 ... /> |
    <sp:Basic256Sha256 ... /> |
    <sp:Basic192Sha256 ... /> |
    <sp:Basic128Sha256 ... /> |
    <sp:TripleDesSha256 ... /> |
    <sp:Basic256Sha256Rsa15 ... /> |
    <sp:Basic192Sha256Rsa15 ... /> |
    <sp:Basic128Sha256Rsa15 ... /> |
    <sp:TripleDesSha256Rsa15 ... /> |
    ...)
    <sp:InclusiveC14N ... /> ?
    <sp:SOAPNormalization10 ... /> ?
    <sp:STRTransform10 ... /> ?
   (<sp:XPath10 ... /> |
    <sp:XPathFilter20 ... /> |
    <sp:AbsXPath ... /> |
    ...)?
    ...
  </wsp:Policy>
  ...
</sp:AlgorithmSuite>

The algorithm suite assertion supports a large number of alternative algorithms (for example, Basic256). For a detailed description of the algorithm suite alternatives, see Table 6.4.

Algorithm suites

Table 6.4 provides a summary of the algorithm suites supported by WS-SecurityPolicy. The column headings refer to different types of cryptographic algorithm, as follows: [Dig] is the digest algorithm; [Enc] is the encryption algorithm; [Sym KW] is the symmetric key-wrap algorithm; [Asym KW] is the asymmetric key-wrap algorithm; [Enc KD] is the encryption key derivation algorithm; [Sig KD] is the signature key derivation algorithm.

Table 6.4. Algorithm Suites

Algorithm Suite[Dig][Enc][Sym KW][Asym KW][Enc KD][Sig KD]
Basic256Sha1Aes256KwAes256KwRsaOaepPSha1L256PSha1L192
Basic192Sha1Aes192KwAes192KwRsaOaepPSha1L192PSha1L192
Basic128Sha1Aes128KwAes128KwRsaOaepPSha1L128PSha1L128
TripleDesSha1TripleDesKwTripleDesKwRsaOaepPSha1L192PSha1L192
Basic256Rsa15Sha1Aes256KwAes256KwRsa15PSha1L256PSha1L192
Basic192Rsa15Sha1Aes192KwAes192KwRsa15PSha1L192PSha1L192
Basic128Rsa15Sha1Aes128KwAes128KwRsa15PSha1L128PSha1L128
TripleDesRsa15Sha1TripleDesKwTripleDesKwRsa15PSha1L192PSha1L192
Basic256Sha256Sha256Aes256KwAes256KwRsaOaepPSha1L256PSha1L192
Basic192Sha256Sha256Aes192KwAes192KwRsaOaepPSha1L192PSha1L192
Basic128Sha256Sha256Aes128KwAes128KwRsaOaepPSha1L128PSha1L128
TripleDesSha256Sha256TripleDesKwTripleDesKwRsaOaepPSha1L192PSha1L192
Basic256Sha256Rsa15Sha256Aes256KwAes256KwRsa15PSha1L256PSha1L192
Basic192Sha256Rsa15Sha256Aes192KwAes192KwRsa15PSha1L192PSha1L192
Basic128Sha256Rsa15Sha256Aes128KwAes128KwRsa15PSha1L128PSha1L128
TripleDesSha256Rsa15Sha256TripleDesKwTripleDesKwRsa15PSha1L192PSha1L192

Types of cryptographic algorithm

The following types of cryptographic algorithm are supported by WS-SecurityPolicy:

Symmetric key signature

The symmetric key signature property, [Sym Sig], specifies the algorithm for generating a signature using a symmetric key. WS-SecurityPolicy specifies that the HmacSha1 algorithm is always used.

The HmacSha1 algorithm is identified by the following URI:

http://www.w3.org/2000/09/xmldsig#hmac-sha1

Asymmetric key signature

The asymmetric key signature property, [Asym Sig], specifies the algorithm for generating a signature using an asymmetric key. WS-SecurityPolicy specifies that the RsaSha1 algorithm is always used.

The RsaSha1 algorithm is identified by the following URI:

http://www.w3.org/2000/09/xmldsig#rsa-sha1

Digest

The digest property, [Dig], specifies the algorithm used for generating a message digest value. WS-SecurityPolicy supports two alternative digest algorithms: Sha1 and Sha256.

The Sha1 algorithm is identified by the following URI:

http://www.w3.org/2000/09/xmldsig#sha1

The Sha256 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#sha256

Encryption

The encryption property, [Enc], specifies the algorithm used for encrypting data. WS-SecurityPolicy supports the following encryption algorithms: Aes256, Aes192, Aes128, TripleDes.

The Aes256 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#aes256-cbc

The Aes192 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#aes192-cbc

The Aes128 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#aes128-cbc

The TripleDes algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#tripledes-cbc

Symmetric key wrap

The symmetric key wrap property, [Sym KW], specifies the algorithm used for signing and encrypting symmetric keys. WS-SecurityPolicy supports the following symmetric key wrap algorithms: KwAes256, KwAes192, KwAes128, KwTripleDes.

The KwAes256 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#kw-aes256

The KwAes192 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#kw-aes192

The KwAes128 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#kw-aes128

The KwTripleDes algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#tripledes-cbc

Asymmetric key wrap

The asymmetric key wrap property, [Asym KW], specifies the algorithm used for signing and encrypting asymmetric keys. WS-SecurityPolicy supports the following asymmetric key wrap algorithms: KwRsaOaep, KwRsa15.

The KwRsaOaep algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

The KwRsa15 algorithm is identified by the following URI:

http://www.w3.org/2001/04/xmlenc#rsa-1_5

Computed key

The computed key property, [Comp Key], specifies the algorithm used to compute a derived key. When secure parties communicate with the aid of a shared secret key (for example, when using WS-SecureConversation), it is recommended that a derived key is used instead of the original shared key, in order to avoid exposing too much data for analysis by hostile third parties. WS-SecurityPolicy specifies that the PSha1 algorithm is always used.

The PSha1 algorithm is identified by the following URI:

http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/dk/p_sha1

Encryption key derivation

The encryption key derivation property, [Enc KD], specifies the algorithm used to compute a derived encryption key. WS-SecurityPolicy supports the following encryption key derivation algorithms: PSha1L256, PSha1L192, PSha1L128.

The PSha1 algorithm is identified by the following URI (the same algorithm is used for PSha1L256, PSha1L192, and PSha1L128; just the key lengths differ):

http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/dk/p_sha1

Signature key derivation

The signature key derivation property, [Sig KD], specifies the algorithm used to compute a derived signature key. WS-SecurityPolicy supports the following signature key derivation algorithms: PSha1L192, PSha1L128.

Key length properties

Table 6.5 shows the minimum and maximum key lengths supported in WS-SecurityPolicy.

Table 6.5. Key Length Properties

PropertyKey Length
Minimum symmetric key length [Min SKL]128, 192, 256
Maximum symmetric key length [Max SKL]256
Minimum asymmetric key length [Min AKL]1024
Maximum asymmetric key length [Max AKL]4096

The value of the minimum symmetric key length, [Min SKL], depends on which algorithm suite is selected.

PK HA"Ծ--*OEBPS/MsgProtect-SOAP-SymmetricPolicy.html Specifying a SymmetricBinding Policy

Specifying a SymmetricBinding Policy

Overview

The symmetric binding policy implements SOAP message protection using symmetric key algorithms (shared secret key) and does so at the SOAP layer. Examples of a symmetric binding are the Kerberos protocol and the WS-SecureConversation protocol.

[Note]Note

Currently, Fuse Services Framework supports only WS-SecureConversation tokens in a symmetric binding.

Policy subject

A symmetric binding policy must be applied to an endpoint policy subject (see Endpoint policy subject). For example, given the symmetric binding policy with ID, SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy, you could apply the policy to an endpoint binding as follows:

<wsdl:binding name="SecureConversation_MutualCertificate10SignEncrypt_IPingService" type="i0:IPingService">
  <wsp:PolicyReference URI="#SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy"/>
  ...
</wsdl:binding>

Syntax

The SymmetricBinding element has the following syntax:

<sp:SymmetricBinding xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
  (
   <sp:EncryptionToken ... >
     <wsp:Policy> ... </wsp:Policy>
   </sp:EncryptionToken>
   <sp:SignatureToken ... >
     <wsp:Policy> ... </wsp:Policy>
   </sp:SignatureToken>
  ) | (
   <sp:ProtectionToken ... >
     <wsp:Policy> ... </wsp:Policy>
   </sp:ProtectionToken>
  )
   <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite>
   <sp:Layout ... > ... </sp:Layout> ?
   <sp:IncludeTimestamp ... /> ?
   <sp:EncryptBeforeSigning ... /> ?
   <sp:EncryptSignature ... /> ?
   <sp:ProtectTokens ... /> ?
   <sp:OnlySignEntireHeadersAndBody ... /> ?
   ...
  </wsp:Policy>
  ...
</sp:SymmetricBinding>

Sample policy

Example 6.5 shows an example of a symmetric binding that supports message protection with signatures and encryption, where the signing and encryption is done using a single symmetric key (that is, using symmetric cryptography). This example does not specify which parts of the message should be signed and encrypted, however. For details of how to do that, see Specifying Parts of Message to Encrypt and Sign.

Example 6.5. Example of a Symmetric Binding

<wsp:Policy wsu:Id="SecureConversation_MutualCertificate10SignEncrypt_IPingService_policy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:SymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:ProtectionToken>
            <wsp:Policy>
              <sp:SecureConversationToken>
                ...
              </sp:SecureConversationToken>
            </wsp:Policy>
          </sp:ProtectionToken>
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic256/>
            </wsp:Policy>
          </sp:AlgorithmSuite>
          <sp:Layout>
            <wsp:Policy>
              <sp:Lax/>
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp/>
          <sp:EncryptSignature/>
          <sp:OnlySignEntireHeadersAndBody/>
        </wsp:Policy>
      </sp:SymmetricBinding>
      <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:MustSupportRefKeyIdentifier/>
          <sp:MustSupportRefIssuerSerial/>
        </wsp:Policy>
      </sp:Wss10>
      ...
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

sp:ProtectionToken

This element specifies a symmetric token to use for both signing and encrypting messages. For example, you could specify a WS-SecureConversation token here.

If you want to use distinct tokens for signing and encrypting operations, use the sp:SignatureToken element and the sp:EncryptionToken element in place of this element.

sp:SignatureToken

This element specifies a symmetric token to use for signing messages. It should be used in combination with the sp:EncryptionToken element.

sp:EncryptionToken

This element specifies a symmetric token to use for encrypting messages. It should be used in combination with the sp:SignatureToken element.

sp:AlgorithmSuite

This element specifies the suite of cryptographic algorithms to use for signing and encryption. For details of the available algorithm suites, see Specifying the Algorithm Suite.

sp:Layout

This element specifies whether to impose any conditions on the order in which security headers are added to the SOAP message. The sp:Lax element specifies that no conditions are imposed on the order of security headers. The alternatives to sp:Lax are sp:Strict, sp:LaxTimestampFirst, or sp:LaxTimestampLast.

sp:IncludeTimestamp

If this element is included in the policy, the runtime adds a wsu:Timestamp element to the wsse:Security header. By default, the timestamp is not included.

sp:EncryptBeforeSigning

When a message part is subject to both encryption and signing, it is necessary to specify the order in which these operations are performed. The default order is to sign before encrypting. But if you include this element in your symmetric policy, the order is changed to encrypt before signing.

[Note]Note

Implicitly, this element also affects the order of the decryption and signature verification operations. For example, if the sender of a message signs before encrypting, the receiver of the message must decrypt before verifying the signature.

sp:EncryptSignature

This element specifies that the message signature must be encrypted. Default is false.

sp:ProtectTokens

This element specifies that signatures must cover the token used to generate that signature. Default is false.

sp:OnlySignEntireHeadersAndBody

This element specifies that signatures can be applied only to an entire body or to entire headers, not to sub-elements of the body or sub-elements of a header. When this option is enabled, you are effectively prevented from using the sp:SignedElements assertion (see Specifying Parts of Message to Encrypt and Sign).

PK HAKbMMOEBPS/MsgProtect-SOAP.html SOAP Message Protection

SOAP Message Protection

Introduction to SOAP Message Protection
Basic Signing and Encryption Scenario
Specifying an AsymmetricBinding Policy
Specifying a SymmetricBinding Policy
Specifying Parts of Message to Encrypt and Sign
Providing Encryption Keys and Signing Keys
Specifying the Algorithm Suite
PK HAv00OEBPS/MsgProtect-Transport.html Transport Layer Message Protection

Transport Layer Message Protection

Overview

Transport layer message protection refers to the message protection (encryption and signing) that is provided by the transport layer. For example, HTTPS provides encryption and message signing features using SSL/TLS. In fact, WS-SecurityPolicy does not add much to the HTTPS feature set, because HTTPS is already fully configurable using Spring XML configuration (see Configuring HTTPS). An advantage of specifying a transport binding policy for HTTPS, however, is that it enables you to embed security requirements in the WSDL contract. Hence, any client that obtains a copy of the WSDL contract can discover what the transport layer security requirements are for the endpoints in the WSDL contract.

Prerequisites

If you use WS-SecurityPolicy to configure the HTTPS transport, you must also configure HTTPS security appropriately in the Spring configuration.

Example 6.1 shows how to configure a client to use the HTTPS transport protocol. The sec:keyManagers element specifies the client's own certificate, alice.pfx, and the sec:trustManagers element specifies the trusted CA list. Note how the http:conduit element's name attribute uses wildcards to match the endpoint address. For details of how to configure HTTPS on the client side, see Configuring HTTPS.

Example 6.1. Client HTTPS Configuration in Spring

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:http="http://cxf.apache.org/transports/http/configuration"
       xmlns:sec="http://cxf.apache.org/configuration/security" ... >

  <http:conduit name="https://.*/UserNameOverTransport.*">
    <http:tlsClientParameters disableCNCheck="true">
      <sec:keyManagers keyPassword="password">
        <sec:keyStore type="pkcs12" password="password" resource="certs/alice.pfx"/>
      </sec:keyManagers>
      <sec:trustManagers>
        <sec:keyStore type="pkcs12" password="password" resource="certs/bob.pfx"/>
      </sec:trustManagers>
    </http:tlsClientParameters>
  </http:conduit>
  ...
</beans>

Example 6.2 shows how to configure a server to use the HTTPS transport protocol. The sec:keyManagers element specifies the server's own certificate, bob.pfx, and the sec:trustManagers element specifies the trusted CA list. For details of how to configure HTTPS on the server side, see Configuring HTTPS.

Example 6.2. Server HTTPS Configuration in Spring

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:http="http://cxf.apache.org/transports/http/configuration"
       xmlns:sec="http://cxf.apache.org/configuration/security" ... >

  <httpj:engine-factory id="tls-settings">
    <httpj:engine port="9001">
      <httpj:tlsServerParameters>
        <sec:keyManagers keyPassword="password">
          <sec:keyStore type="pkcs12" password="password" resource="certs/bob.pfx"/>
        </sec:keyManagers>
        <sec:trustManagers>
          <sec:keyStore type="pkcs12" password="password" resource="certs/alice.pfx"/>
        </sec:trustManagers> 
      </httpj:tlsServerParameters>
    </httpj:engine>
  </httpj:engine-factory>
  ...
</beans>

Policy subject

A transport binding policy must be applied to an endpoint policy subject (see Endpoint policy subject). For example, given the transport binding policy with ID, UserNameOverTransport_IPingService_policy, you could apply the policy to an endpoint binding as follows:

<wsdl:binding name="UserNameOverTransport_IPingService" type="i0:IPingService">
  <wsp:PolicyReference URI="#UserNameOverTransport_IPingService_policy"/>
  ...
</wsdl:binding>

Syntax

The TransportBinding element has the following syntax:

<sp:TransportBinding xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
    <sp:TransportToken ... >
      <wsp:Policy> ... </wsp:Policy>
      ...
    </sp:TransportToken>
    <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite>
    <sp:Layout ... > ... </sp:Layout> ?
    <sp:IncludeTimestamp ... /> ?
      ...
  </wsp:Policy>
  ...
</sp:TransportBinding>

Sample policy

Example 6.3 shows an example of a transport binding that requires confidentiality and integrity using the HTTPS transport (specified by the sp:HttpsToken element) and a 256-bit algorithm suite (specified by the sp:Basic256 element).

Example 6.3. Example of a Transport Binding

<wsp:Policy wsu:Id="UserNameOverTransport_IPingService_policy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:TransportBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:TransportToken>
            <wsp:Policy>
              <sp:HttpsToken RequireClientCertificate="false"/>
            </wsp:Policy>
          </sp:TransportToken>
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic256/>
            </wsp:Policy>
          </sp:AlgorithmSuite>
          <sp:Layout>
            <wsp:Policy>
              <sp:Lax/>
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp/>
        </wsp:Policy>
      </sp:TransportBinding>
      ...
      <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:MustSupportRefKeyIdentifier/>
          <sp:MustSupportRefIssuerSerial/>
        </wsp:Policy>
      </sp:Wss10>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

sp:TransportToken

This element has a two-fold effect: it requires a particular type of security token and it indicates how the transport is secured. For example, by specifying the sp:HttpsToken, you indicate that the connection is secured by the HTTPS protocol and the security tokens are X.509 certificates.

sp:AlgorithmSuite

This element specifies the suite of cryptographic algorithms to use for signing and encryption. For details of the available algorithm suites, see Specifying the Algorithm Suite.

sp:Layout

This element specifies whether to impose any conditions on the order in which security headers are added to the SOAP message. The sp:Lax element specifies that no conditions are imposed on the order of security headers. The alternatives to sp:Lax are sp:Strict, sp:LaxTimestampFirst, or sp:LaxTimestampLast.

sp:IncludeTimestamp

If this element is included in the policy, the runtime adds a wsu:Timestamp element to the wsse:Security header. By default, the timestamp is not included.

sp:MustSupportRefKeyIdentifier

This element specifies that the security runtime must be able to process Key Identifier token references, as specified in the WS-Security 1.0 specification. A key identifier is a mechanism for identifying a key token, which may be used inside signature or encryption elements. Fuse Services Framework requires this feature.

sp:MustSupportRefIssuerSerial

This element specifies that the security runtime must be able to process Issuer and Serial Number token references, as specified in the WS-Security 1.0 specification. An issuer and serial number is a mechanism for identifying a key token, which may be used inside signature or encryption elements. Fuse Services Framework requires this feature.

PK HAø@ @ OEBPS/MsgProtect.html Chapter 6. Message Protection

Chapter 6. Message Protection

The following message protection mechanisms are described in this chapter: protection against eavesdropping (by employing encryption algorithms) and protection against message tampering (by employing message digest algorithms). The protection can be applied at various levels of granularity and to different protocol layers. At the transport layer, you have the option of applying protection to the entire contents of the message; while at the SOAP layer, you have the option of applying protection to various parts of the message (bodies, headers, or attachments).

Transport Layer Message Protection
SOAP Message Protection
Introduction to SOAP Message Protection
Basic Signing and Encryption Scenario
Specifying an AsymmetricBinding Policy
Specifying a SymmetricBinding Policy
Specifying Parts of Message to Encrypt and Sign
Providing Encryption Keys and Signing Keys
Specifying the Algorithm Suite
PK HAI.//OEBPS/STS-AppliesTo.html Enabling AppliesTo in the STS

Enabling AppliesTo in the STS

Overview

When you specify an IssuedToken policy, you can replace both of the TokenType and KeyType elements by a single AppliesTo element, which specifies the identity of the server that the client wants to communicate with. The idea behind this approach is that the STS already knows what type of token the server wants and what kind of single sign-on scenario the server supports. In other words, this information is centralized in the STS (and the STS must be configured with this information).

Figure 9.10 shows an overview of the steps that the STS follows to process the AppliesTo policy.

Figure 9.10. Processing the AppliesTo Policy

Processing the AppliesTo Policy

Steps to process the AppliesTo policy

When the IssuedToken policy includes the AppliesTo policy, the STS processes the client's issue token request as follows:

  1. The trigger that enables the AppliesTo policy is when the client encounters an IssuedToken policy with a RequestSecurityTokenTemplate that contains the AppliesTo policy element. In this case, the STSClient constructs a RequestSecurityToken request message containing the specified AppliesTo element and uses this message to invoke the Issue operation on the STS.

    In the example shown in Figure 9.10, the AppliesTo element references the FooAddress endpoint URL, which is the URL of the WS endpoint in the server that the client wants to invoke.

  2. After detecting the presence of the AppliesTo element in the incoming request, the TokenIssueOperation instance iterates over the list of registered StaticService objects, trying to find a regular expression that matches the target address, FooAddress, that was specified by the AppliesTo element.

    If a match is found, the TokenIssueOperation checks whether the tokenType and keyType properties are set on the StaticService object. If these properties are set, they override the values (if any) that were specified in the incoming request.

    If a match is not found, the TokenIssueOperation raises an error.

    [Note]Note

    If a list of services is registered with the TokenIssueOperation instance, one of the registered services must match the address specified by AppliesTo.

  3. Now that the requested token type and key type have been determined, the TokenIssueOperation object proceeds as usual to issue the requested token (for example, see Customizing the Issue Operation).

  4. The STS returns the issued token to the client.

  5. The client can now send a secure invocation to the FooAddress endpoint on the server, including the issued token in the SOAP security header.

IssuedToken policy without AppliesTo enabled

Before looking at how to enable the AppliesTo policy, it is worth reminding ourselves what a typical IssuedToken policy looks like without the AppliesTo policy enabled. For example, the following IssuedToken policy requests a SAML 2.0 token that embeds a key of type public key (an X.509 certificate) for the purpose of identifying the client (Holder-of-Key scenario):

<sp:IssuedToken
      sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
    <sp:RequestSecurityTokenTemplate>
        <t:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</t:TokenType>
        <t:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey</t:KeyType>
    </sp:RequestSecurityTokenTemplate>
    <wsp:Policy>
        <sp:RequireInternalReference />
    </wsp:Policy>
    <sp:Issuer>
        <wsaw:Address>http://localhost:8080/SecurityTokenService/</wsaw:Address>
    </sp:Issuer>
</sp:IssuedToken>

In the ordinary case, without AppliesTo enabled, the IssuedToken policy specifies the required token type and key type explicitly.

IssuedToken policy with AppliesTo enabled

When the AppliesTo policy is enabled, it is no longer necessary to specify the required token type and key type in the message that is sent to the STS. You use the AppliesTo policy to specify which target endpoint the issued token is needed for and the STS looks up the target endpoint to discover the policies that apply to the issued token.

Therefore, in the RequestSecurityTokenTemplate element in the IssuedToken policy, you need only specify the AppliesTo element, as shown in the following example:

<sp:IssuedToken
      sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
    <sp:RequestSecurityTokenTemplate>
        <wsp:AppliesTo>
            <wsa:EndpointReference>
                <wsa:Address>http://localhost:9001/SoapContext/SoapPort</wsa:Address>
            </wsa:EndpointReference>
        </wsp:AppliesTo>
    </sp:RequestSecurityTokenTemplate>
    <wsp:Policy>
        <sp:RequireInternalReference />
    </wsp:Policy>
    <sp:Issuer>
        <wsaw:Address>http://localhost:8080/SecurityTokenService/</wsaw:Address>
    </sp:Issuer>
</sp:IssuedToken>

In this example, the AppliesTo policy specifies that the token is issued for the server endpoint, http://localhost:9001/SoapContext/SoapPort.

Configuring the list of services

When using the AppliesTo policy, you must configure the STS to recognize the relevant target endpoint and provide the appropriate policies for issuing tokens (in particular, the TokenType and KeyType policies).

The following sample STS configuration shows how to configure the TokenIssueOperation with a list of services (in this example, the list is just a singleton).

<beans ... >
    <bean id="utIssueDelegate" class="org.apache.cxf.sts.operation.TokenIssueOperation">
        <property name="tokenProviders" ref="utTokenProviders" />
        <property name="services" ref="utService" />
        <property name="stsProperties" ref="utSTSProperties" />
    </bean>
    ...
    <bean id="utService"
        class="org.apache.cxf.sts.service.StaticService">
        <property name="endpoints" ref="utEndpoints"/>
        <property name="tokenType"
            value="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"/>
        <property name="keyType"
            value="http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey"/>
    </bean>
    
    <util:list id="utEndpoints">
        <value>http://localhost:(\d)*/SoapContext/SoapPort</value>
    </util:list>
    ...
</beans>

Services are represented by one or more StaticService instances. Each StaticService instance holds a list of regular expressions, which are matched against the AppliesTo address URL. If a match is found, the specified properties of the StaticService instance are then used for issuing the token.

PK HAsxOEBPS/STS-Arch-Cancel.html Customizing the Cancel Operation

Customizing the Cancel Operation

TokenCancelOperation

Figure 9.4 shows an overview of the components that are involved in the Cancel operation.

Figure 9.4. Configuring TokenCancelOperation

Configuring TokenCancelOperation

Plug-in framework

The following property can be set on the TokenCancelOperation class:

tokencancellers

Specifies a list of token cancellers, where each token canceller is capable of canceling tokens of a particular type. Currently, the only token canceller implementation provided is the SCTCanceller, for canceling WS-SecureConversation tokens.

SCTCanceller

The SCTCanceller token canceller is used in the context of WS-SecureConversation to cancel security context tokens.

A registered SCTCanceller instance is triggered to cancel a token, if the token namespace specified by the requesting STS client is one of the following:

Namespaces handled by the SCTCanceller
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512
http://schemas.xmlsoap.org/ws/2005/02/sc

You can optionally set the following property on an SCTCanceller instance:

verifyProofOfPossession

When the verifyProofOfPossession flag is enabled, only the owner of the security context token is allowed to cancel the token. To prove possession of the token, the client must demonstrate that it knows the secret key associated with the security context token. The client demonstrates knowledge of the key by signing some part of the SOAP message using the secret key.

Default is true.

Sample configuration of SCTCanceller

Example 9.3 shows an example of how to configure the STS Cancel operation. In this example, the TokenCancelOperation class is configured to use an SCTCanceller token canceller.

Example 9.3. Configuring the STS Cancel Operation

<beans ... >
    ...
    <bean id="utSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="cancelOperation" ref="utCancelDelegate"/>
        ...
    </bean>    

    <bean id="utCancelDelegate"
        class="org.apache.cxf.sts.operation.TokenCancelOperation">
        <property name="tokencancellers" ref="utSctCanceller"/>
        ...
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    ...    
    <bean id="utSctCanceller"
        class="org.apache.cxf.sts.token.canceller.SCTCanceller">
        <property name="verifyProofOfPossession" value="false"/>
    </bean>
    ...    
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="keys/stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...    
</beans>
PK HAu.5:5:OEBPS/STS-Arch-Issue.html Customizing the Issue Operation

Customizing the Issue Operation

TokenIssueOperation

For the Issue operation, the TokenIssueOperation class provides the overall coordination of the token issuing process. There are some important aspects of a TokenIssueOperation instance that can be customized. In particular, because the TokenIssueOperation instance delegates token generation to token providers—where each token provider is capable of generating a particular kind of token—the token provider beans play a particularly important role in issuing tokens.

Figure 9.2 shows an overview of the major components that are involved in token issuing.

Figure 9.2. Configuring TokenIssueOperation

Configuring TokenIssueOperation

Plug-in framework

The implementation of TokenIssueOperation has a modular structure. You can inject various plug-ins into the TokenIssueOperation instance in order to customize the behavior of the Issue operation. The following properties can be set on the TokenIssueOperation class:

tokenProviders

Specifies a list of token providers, where each token provider is capable of generating tokens of a specific type. Whenever an STS client asks the Issue operation to issue a token of a specific type, the TokenIssueOperation class iterates over all of the token providers specified by this property, asking each of them whether they can handle the required token type (by invoking the canHandle() method on each token provider).

The available token providers are described in Token providers.

stsProperties

References a bean that encapsulates generic configuration properties for the STS (normally an instance of StaticSTSProperties). This configuration data mainly consists of the details needed to access a signing certificate and an encrypting certificate.

services

Specifies a list of known services and their corresponding token requirements. This property must be set, if you want to support the AppliesTo policy in a token request. For details, see Enabling AppliesTo in the STS.

encryptIssuedToken

Specifies whether or not to encrypt an issued token. Default is false.

If you enable this option, you must also associate an encryption key with the TokenIssueOperation, through the properties defined on the StaticSTSProperties instance—see Encrypting key

Token providers

The Fuse Services Framework STS currently provides the following token provider implementations:

SAMLTokenProvider

The SAMLTokenProvider token provider is used to generate SAML tokens. This is the most commonly used token provider.

A registered SAMLTokenProvider instance is triggered to issue a token, if the token type specified by the requesting STS client is one of the following:

Token Type URIs handled by the SAMLTokenProvider
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
urn:oasis:names:tc:SAML:1.0:assertion
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
urn:oasis:names:tc:SAML:2.0:assertion

The SAMLTokenProvider class comes pre-configured with sensible default behaviors, so it is normally acceptable to instantiate it without setting any of its properties. If you want to customize its behavior, however, you can set some or all of the following properties:

attributeStatementProviders

You can optionally use this property to add attribute statement providers, if you want to define your own custom attribute statements in the generated SAML token. If this property is not set, the DefaultAttributeStatementProvider class is automatically invoked, which generates the following attribute statements:

authenticationStatementProviders

You can optionally add authentication statement providers, if you want to define your own custom authentication statements in the generated SAML token. No authentication statements are added by default.

authDecisionStatementProviders

You can optionally add authorization decision statement providers, if you want to define your own custom authorization decision statements in the generated SAML token. No authorization decision statements are added by default.

subjectProvider

You can optionally set this property to define a custom SAML subject provider.

If this property is not set, the DefaultSubjectProvider class is automatically invoked. The default implementation automatically populates the SAML subject with all of the fields needed to support the standard scenarios: Holder-of-Key with SymmetricKey; Holder-of-Key with PublicKey algorithm; and Bearer.

conditionsProvider

You can optionally set this property to define a custom conditions provider.

If this property is not set, the DefaultConditionsProvider class is automatically invoked. The default implementation applies a default lifetime of five minutes to the token and sets the audience restriction URI to the value of the received AppliesTo address (if any).

signToken

Specifies whether or not to sign the SAML token. Default is true.

realmMap

Specifies a map that associates realm names with SAMLRealm objects. Only required, if you want to enable support for realms. For details, see Enabling Realms in the STS.

SCTProvider

The SCTProvider token provider is used to generate security context tokens, which you only need if you are using the WS-SecureConversation protocol.

A registered SCTProvider instance is triggered to issue a token, if the token type specified by the requesting STS client is one of the following:

Token Type URIs handled by the SCTProvider
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/sct
http://schemas.xmlsoap.org/ws/2005/02/sc/sct

You can optionally set the following properties on an SCTProvider instance:

lifetime

Specifies the lifetime of the generated security context token. Default is five minutes.

returnEntropy

Specifies whether to return entropy to the STS client. Default is true.

Sample configuration of SAMLTokenProvider

Example 9.1 shows an example of how to configure the STS Issue operation. In this example, the TokenIssueOperation class is configured to use a SAMLTokenProvider token provider.

Example 9.1. Configuring the STS Issue Operation

<beans ... >
    ...
    <bean id="utSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="issueOperation" ref="utIssueDelegate"/>
        ...
    </bean>    

    <bean id="utIssueDelegate"
        class="org.apache.cxf.sts.operation.TokenIssueOperation">
        <property name="tokenProviders" ref="utSamlTokenProvider"/>
        ...
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    ...    
    <bean id="utSamlTokenProvider"
        class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
    </bean>
    ...    
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="keys/stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...    
</beans>
PK HAQbM+M+OEBPS/STS-Arch-Overview.html Overview of the STS

Overview of the STS

Architecture

The Fuse Services Framework STS has a modular architecture, with many components that are configurable or replaceable. Many of the optional features are enabled by implementing and configuring plug-ins that are injected into the STS runtime. Figure 9.1 gives a broad overview of the core components and optional components of the STS.

Figure 9.1. STS Architecture

STS Architecture

STS WSDL

The STS is accessed through a standard WSDL contract. As with any WSDL contract, you can think of the STS WSDL as consisting of two main parts, as follows:

STS operations

The STS WSDL defines the following standard operations (from the WS-Trust specification):

STS policies

When a secure application connects to the STS, this connection is also subject to security policies. For example, the STS might require STS clients to authenticate themselves using a WS-Security UsernameToken or by presenting an X.509 certificate, and so on.

For more details, see Choosing policies.

Abstract STS provider framework

The Fuse Services Framework implementation of the STS is designed as a pluggable framework. The core class in this framework is the SecurityTokenServiceProvider class from the org.apache.cxf.ws.security.sts.provider package, which provides the Java implementation of the STS WSDL interface.

For each of the standard STS operations, the STS provider defines the following abstract interfaces:

By implementing each of these interfaces and injecting the corresponding instances into the SecurityTokenServiceProvider instance, you can customize the implementation of each STS operation.

In practice, however, you would normally use the default implementations of these operations which are, as follows:

TokenIssueOperation class

The TokenIssueOperation class from the org.apache.cxf.ws.security.sts.operation package is the default implementation of the Issue operation.

To configure a TokenIssueOperation instance, you would normally just provide it with a reference to a SAMLTokenProvider instance (which enables it to issue SAML tokens). For details, see Customizing the Issue Operation.

TokenValidateOperation class

The TokenValidateOperation class from the org.apache.cxf.ws.security.sts.operation package is the default implementation of the Validate operation.

To configure a TokenValidateOperation instance, you need to provide it with a list of token validators. For details, see Customizing the Validate Operation.

TokenCancelOperation class

The TokenCancelOperation class from the org.apache.cxf.ws.security.sts.operation package is the default implementation of the Cancel operation.

To configure a TokenCancelOperation instance, you need to provide it with a list of cancellers. At the moment, only the SCTCanceller canceller is available, which is used for cancelling Security Context Tokens in the context of secure conversations (WS-SecureConversation specification). For details, see Customizing the Validate Operation.

PK HA11!OEBPS/STS-Arch-STSProperties.html Configuring STS Properties

Configuring STS Properties

Overview

The STS properties are a general collection of properties, used for various purposes in the STS. In particular, some of the properties are used to load resources for the STS, such as a signing key and an encryption key.

The STS properties are encapsulated in a StaticSTSProperties instance (which implements the STSPropertiesMBean interface) and can be injected into the various operation implementations (TokenIssueOperation, TokenValidateOperation, and so on).

What you can configure with STS properties

You can use the STS properties to configure the following aspects of the STS:

Issuer

The issuer is a string that uniquely identifies the issuing STS. The issuer string is normally embedded in issued tokens and, when validating tokens, the STS normally checks the issuer string value. Consequently, it is important to use the issuer string in a consistent way, so that the STS can recognize the tokens that it has issued.

The issuer string is also important in the context of using realms. See Enabling Realms in the STS.

For example, you can set the issuer string as follows:

<beans ... >
    ...
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        ...
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...    
</beans>

Callback handler

The callback handler is a Java class that implements the javax.security.auth.callback.CallbackHandler interface. The purpose of the callback handler is to provide any passwords required by the STS. In particular, the callback handler is normally used to provide the password to access the STS signing key.

For an example of an STS callback handler implementation, see STS callback handler .

<beans ... >
    ...
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        ...
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        ...
    </bean>
    ...    
</beans>

Signing key

The must important use of the STS signing key is for signing SAML tokens, so that WS servers can establish trust in the issued SAML token. There are several properties available for specifying the signing key, which allow you to specify the signing key in a variety of different ways and to customize the signing algorithm. The properties are as follows:

signatureCrypto

Specifies the signing key directly as an org.apache.ws.security.components.crypto.Crypto instance. This is the most flexible way of configuring the signing key, but also the most complicated. The signaturePropertiesFile property offers an easier alternative for specifying the signing key.

signaturePropertiesFile

Specifies the location of a file containing WSS4J keystore properties, that provide access to the signing key in a Java keystore file. For details of the WSS4J keystore properties that you can set in this file, see Table 6.2.

signatureUsername

Specifies the alias of the signing key in the specified Java keystore.

signatureProperties

(Optional) By injecting an org.apache.cxf.sts.SignatureProperties instance into this property, you can fine-tune the signing algorithm used by the STS.

For example, the following example shows how to specify the signing key using the signaturePropertiesFile property, where the private key with the alias, mystskey, is selected from the specified Java keystore.

<beans ... >
    ...
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="keys/stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        ...
    </bean>
    ...    
</beans>

The stsKeystore.properties file typically contains WSS4J keystore properties like the following:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=stsspass
org.apache.ws.security.crypto.merlin.keystore.file=keys/stsstore.jks

Where the signing key is stored in the stsstore.jks Java keystore file and the stsspass password unlocks the keystore file.

Encrypting key

The encrypting key is (optionally) used for encrypting issued tokens. It is only necessary to configure the encrypting key, if the encryptIssuedToken option is set to true on the TokenIssueOperation instance—see Customizing the Issue Operation.

There are several properties available for specifying the encrypting key, which allow you to specify the encrypting key in a variety of different ways and to customize the encryption algorithm. The properties are as follows:

encryptionCrypto

Specifies the encryption key directly as an org.apache.ws.security.components.crypto.Crypto instance. This is the most flexible way of configuring the encryption key, but also the most complicated. The encryptionPropertiesFile property offers an easier alternative for specifying the encryption key.

encryptionPropertiesFile

Specifies the location of a file containing WSS4J keystore properties, that provide access to the encryption key in a Java keystore file. For details of the WSS4J keystore properties that you can set in this file, see Table 6.2.

encryptionUsername

Specifies the alias of the encryption key in the specified Java keystore.

encryptionProperties

(Optional) By injecting an org.apache.cxf.sts.service.EncryptionProperties instance into this property, you can fine-tune the encryption algorithm used by the STS.

Realm settings

The following properties are relevant only when realm support is enabled in the STS (as described in Enabling Realms in the STS)L

realmParser

(Optional) In the context of enabling realms in the STS, you would inject an org.apache.cxf.sts.RealmParser instance into this property, to give STS the ability to decide which realm the current token should be issued in. For more details, see Issuing Tokens in Multiple Realms.

identityMapper

(Optional) In the context of token transformation in the STS, you would inject an org.apache.cxf.sts.IdentityMapper instance into this property, which has the capability to map a principal in the context of one realm to the corresponding principal in the context of another realm. For more details, see Token Transformation across Realms.

PK HA}՛pPpPOEBPS/STS-Arch-Validate.html Customizing the Validate Operation

Customizing the Validate Operation

TokenValidateOperation

For the Validate operation, the TokenValidateOperation class provides the overall coordination of the token validation process. The TokenValidateOperation instance delegates token validation to token validators—where each token validator is capable of validating a particular kind of token.

The TokenValidateOperation class can also support token transformation and this capability is discussed in detail in the context of realms, Token Transformation across Realms.

Figure 9.3 shows an overview of the major components that are involved in token validation.

Figure 9.3. Configuring TokenValidateOperation

Configuring TokenValidateOperation

Plug-in framework

You can inject various plug-ins into the TokenValidateOperation instance in order to customize the behavior of the Validate operation. The following properties can be set on the TokenValidateOperation class:

tokenValidators

Specifies a list of token validators, where each token validator is capable of validating tokens of a specific type. Whenever an STS client asks the Validate operation to validate a token of a specific type, the TokenValidateOperation class iterates over all of the token validators specified by this property, asking each of them whether they can handle the required token type (by invoking the canHandle() method on each token validator).

The available token validators are described in Token validators.

stsProperties

References a bean that encapsulates generic configuration properties for the STS (normally an instance of StaticSTSProperties). This configuration data mainly consists of the details needed to access a signing certificate and an encrypting certificate.

services

(Only relevant, if token transformation is requested) Specifies a list of known services and their corresponding token requirements. This property must be set, if you want to support the AppliesTo policy in a token request. For details, see Enabling AppliesTo in the STS.

tokenProviders

(Only relevant, if token transformation is requested) Specifies a list of token providers, where each token provider is capable of generating tokens of a specific type.

For details of token transformation, see Token Transformation across Realms.

Token validators

The Fuse Services Framework STS currently provides the following token validator implementations:

SAMLTokenValidator

A registered SAMLTokenValidator instance is triggered to validate a token, if the received token is a SAML assertion and its token type is one of the following:

Token Type URIs handled by the SAMLTokenValidator
urn:oasis:names:tc:SAML:1.0:assertion
urn:oasis:names:tc:SAML:2.0:assertion

Validating a SAML token consists, essentially, of verifying the signature on the SAML token and checking that the signer is trusted (the SAML token must be signed, otherwise it cannot be validated). In outline, a typical signed SAML 2.0 token has a structure like the following:

<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                 ID="_181835fb981efecaf71d80ecd5fc3c74"
                 IssueInstant="2011-05-09T09:36:37.359Z" Version="2.0">
    <saml2:Issuer> ... </saml2:Issuer>
    <saml2:Subject> ... </saml2:Subject>
    <saml2:Conditions NotBefore=" ... " NotOnOrAfter=" ... "/>
    ...
    <Signature:Signature xmlns:Signature="http://www.w3.org/2000/09/xmldsig#"
                         xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <!-- Details of the signing algorithm used -->
        </SignedInfo>
        <SignatureValue>
            <!-- The signature value -->
        </SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509SubjectName> ... </X509SubjectName>
                <X509Certificate>
                    <!-- The certificate that can decrypt the signature value -->
                </X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature:Signature>
</saml2:Assertion>

The SAMLTokenValidator class uses the following algorithm to validate the received SAML token:

  1. The SAML assertion is first checked, to ensure that it is well-formed.

  2. If the assertion is not signed, it is rejected.

  3. The signature is checked, using the X.509 certificate embedded in the assertion's signature. If the signature is verified, this proves that whoever signed the SAML token is in possession of the private key corresponding to the embedded X.509 certificate.

  4. The embedded X.509 certificate is checked to make sure that it is trusted. The validator looks up the trusted certificates stored in the STS properties signature trust store (as configured by the signaturePropertiesFile property or the signatureCrypto property on the StaticSTSProperties object—see Configuring STS Properties) and checks that the certificate is either present in the trust store or is signed by a private key corresponding to one of the certificates in the trust store (certificate chaining).

  5. If the subjectConstraints property is set on the SAMLTokenValidator instance, the validator checks that the Subject DN string from the embedded X.509 certificate matches one of the specified regular expressions. If there is no match, the SAML assertion is rejected.

    This optional feature gives you more fine-grained control over which signing certificates to trust.

One of the most important configuration settings for SAMLTokenValidator is made indirectly, by specifying the signature trust store for the parent TokenValidateOperation instance. The signature trust store is usually configured by setting the signaturePropertiesFile property on the StaticSTSProperties bean, and then injecting the StaticSTSProperties bean into the TokenValidateOperation instance. For example, see Example 9.2.

To configure and customize the SAMLTokenValidator class, you can set some or all of the following properties:

subjectConstraints

Specifies a list of regular expression strings. If this property is set, the subject DN extracted from the X.509 embedded in the SAML assertion must match one of the specified regular expressions. If this property is not set, no test is applied to the subject DN.

validator

You can optionally set this property to customize the step that checks whether or not the embedded X.509 certificate is trusted or not. By default, the WSS4J SignatureTrustValidator class is used.

samlRealmCodec

If you want to use realms with SAML tokens, you must implement the SAMLRealmCodec interface and inject an instance into this property. The purpose of the SAML realm codec is to assign a realm to the SAML token, based on the contents of the SAML assertion. No SAML realm codec is set by default.

For more details about using realms with the STS, see Enabling Realms in the STS.

UsernameTokenValidator

A registered UsernameTokenValidator instance is triggered to validate a token, if the received token can be parsed as a UsernameToken.

Validating a WSS UsernameToken consists, essentially, of checking that the client has supplied the correct password for the username. This implies that the STS server must be configured with a database of usernames and passwords, so that it can check the UsernameToken credentials.

The WSS4J library provides two alternative validator implementations for validating UsernameToken credentials, as follows:

UsernameTokenValidator

(Default) This WSS4J validator implementation uses a CallbackHandler object to look up passwords, where the callback handler, is specified by setting the callbackHandler property on the StaticSTSProperties object—see Configuring STS Properties.

To use this validator, you must provide your own CallbackHandler implementation. For example, see STS callback handler

JAASUsernameTokenValidator

This WSS4J validator implementation integrates password lookup with JAAS, so that the UsernameToken credentials are checked using a JAAS login module. In particular, by configuring an appropriate JAAS login module, you could integrate the UsernameToken validator with an LDAP database.

To use this token validator, create an instance of JAASUsernameTokenValidator and inject it into the validator property of the UsernameTokenValidator bean.

It is also possible to add support for realms, by implementing the UsernameTokenRealmCodec interface and registering it with the UsernameTokenValidator bean—for details, see Enabling Realms in the STS.

X509TokenValidator

A registered X509TokenValidator instance is triggered to validate a token, if the received token can be parsed as a BinarySecurityToken type.

Validating an X.509 token (encoded as a BinarySecurityToken in Base-64 encoding) consists of checking that the received certificate is trusted.

The default validator used by the X509TokenValidator class is the WSS4J SignatureTrustValidator, which checks that the X.509 certificate is either present in the trust store or is signed by a private key corresponding to one of the certificates in the trust store (certificate chaining). The trust store that is used for this purpose is the signature trust store on the StaticSTSProperties object—see Configuring STS Properties.

SCTValidator

A registered SCTValidator instance is triggered to validate a token, if the received token can be parsed as a SecurityContextToken type and belongs to one of the following namespaces:

Namespaces handled by SCTValidator
http://schemas.xmlsoap.org/ws/2005/02/sc
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512

The SCTValidator is used to validate security context tokens in the context of WS-SecureConversation sessions, which is currently not covered by this documentation.

Sample configuration

Example 9.2 shows an example of how to configure the STS Validate operation. In this example, the TokenValidateOperation class is configured to use a SAMLTokenValidator token validator.

Example 9.2. Configuring the STS Validate Operation

<beans ... >
    ...
    <bean id="utSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        ...
        <property name="validateOperation" ref="utValidateDelegate"/>
    </bean>    
    ...    
    <bean id="utValidateDelegate"
        class="org.apache.cxf.sts.operation.TokenValidateOperation">
        <property name="tokenValidators" ref="utSamlTokenValidator"/>
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    ...    
    <bean id="utSamlTokenValidator"
        class="org.apache.cxf.sts.token.validator.SAMLTokenValidator">
    </bean>
    ...    
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="keys/stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...
</beans>
PK HA8HHOEBPS/STS-Arch-WSDL.html Customizing the STS WSDL

Customizing the STS WSDL

Overview

The STS itself is a Web service and thus, like any Web service, it has a WSDL contract that defines how other applications and processes can interact with it. Although some core features of the STS WSDL are fixed by the WS-Trust specification (for example, the core data types and the WSDL port type), there are several important aspects of the STS WSDL contract that can be customized.

In particular, the following aspects of the STS WSDL can be customized:

WSDL types and portType

The WSDL types and WSDL port type for the STS are defined exactly by the WS-Trust specification. In outline, the WSDL port type is defined as follows:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
        targetNamespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:wstrust="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata">
    >

  <wsdl:types>
    ...
  </wsdl:types>
  ...
  <!-- This portType is an example of an STS supporting full protocol -->
  <wsdl:portType name="STS">
    <wsdl:operation name="Cancel">
      <wsdl:input
        wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Cancel"
        message="tns:RequestSecurityTokenMsg"/>
      <wsdl:output
        wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/CancelFinal"
        message="tns:RequestSecurityTokenResponseMsg"/>
    </wsdl:operation>
    <wsdl:operation name="Issue"> ... </wsdl:operation>
    <wsdl:operation name="Renew"> ... </wsdl:operation>
    <wsdl:operation name="Validate"> ... </wsdl:operation>
    <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
    <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>

For each of the STS operations, the following message types are sent or received:

For a full listing of the STS WSDL port type and WSDL types, see the sample WS-Trust 1.4 WSDL file in the Fuse Services Framework samples:

CXFInstallDir/samples/sts/wsdl/ws-trust-1.4-service.wsdl

Choosing a WSDL binding

Because the STS is accessed through a standard WSDL contract, you can customize the WSDL binding just the same way as you can for any other Web service. You should use a SOAP binding, but you can in principle use a transport other than HTTP. The main choices are:

In practice, however, SOAP/HTTP is the normal use case.

SOAP/HTTP binding

The following extract from the STS WSDL shows the physical part of the WSDL contract, consisting of a SOAP/HTTP binding (defined by the wsdl:binding element) and a HTTP port (defined by the wsdl:service element):

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
  <wsdl:binding name="UT_Binding" type="wstrust:STS">
      ...
      <soap:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
      <wsdl:operation name="Issue"> ... </wsdl:operation>
      <wsdl:operation name="Validate"> ... </wsdl:operation>
      <wsdl:operation name="Cancel"> ... </wsdl:operation>
      <wsdl:operation name="Renew"> ... </wsdl:operation>
      <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
      <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:binding>
  
  <wsdl:service name="SecurityTokenService">
      <wsdl:port name="UT_Port" binding="tns:UT_Binding">
         <soap:address location="http://localhost:8080/SecurityTokenService/UT" />
      </wsdl:port>
  </wsdl:service>
  ...
</wsdl:definitions>

The soap:binding element is used to specify that this is a SOAP binding and the transport attribute identifies the transport type as HTTP. Inside the wsdl:port element, the location attribute of the soap:address element specifies the URL that is used to access the STS.

In a real deployment of the STS, you would edit the location URL to specify the host and IP port where the STS is actually running.

Choosing policies

Access to the STS itself must be made secure. Hence, you must apply WS-Security policies to the STS endpoint to define the relevant security policies. Although the requisite policy definitions themselves are fairly complex, it really boils down to a choice between three main alternatives, as follows:

Inserting policy references

After defining a policy for connecting to the STS, you must then apply it to the STS endpoints. The easiest way to apply a policy is to use the wsp:PolicyReference element, which references the relevant WS policy (see Policies and policy references). The following extract from the STS WSDL shows how to apply policies to the SOAP/HTTP binding:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
  <wsdl:binding name="UT_Binding" type="wstrust:STS">
    <wsp:PolicyReference URI="#UT_policy" />
      <soap:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
      <wsdl:operation name="Issue">
          <soap:operation
              soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" />
          <wsdl:input>
              <wsp:PolicyReference URI="#Input_policy" />
              <soap:body use="literal" />
          </wsdl:input>
          <wsdl:output>
              <wsp:PolicyReference URI="#Output_policy" />
              <soap:body use="literal" />
          </wsdl:output>
      </wsdl:operation>
      <wsdl:operation name="Validate"> ... </wsdl:operation>
      <wsdl:operation name="Cancel"> ... </wsdl:operation>
      <wsdl:operation name="Renew"> ... </wsdl:operation>
      <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
      <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:binding>
  ...
</wsdl:definitions>

The first wsp:PolicyReference element applies the UT_Policy policy (in the sample/sts demonstration, this is a symmetric binding policy) to the SOAP binding. This implies that the policy applies to all endpoints that use this SOAP binding.

The second wsp:PolicyReference element applies the Input_policy policy to the Issue operation's request message, and the third wsp:PolicyReference element applies the Output_policy policy to the Issue operation's response message. The Input_policy policy and the Output_policy policy are used to specify which parts of the SOAP messages to protect (see Specifying Parts of Message to Encrypt and Sign).

Example of SymmetricBinding and UsernameToken policy

For example, the following sample policy is used to specify that clients must connect to the STS using the symmetric key binding and the clients must also include UsernameToken credentials, to authenticate themselves to the STS:

  <wsp:Policy wsu:Id="UT_policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsap10:UsingAddressing/>
            <sp:SymmetricBinding
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:ProtectionToken>
                     <wsp:Policy>
                        <sp:X509Token
                           sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                           <wsp:Policy>
                              <sp:RequireDerivedKeys />
                              <sp:RequireThumbprintReference />
                              <sp:WssX509V3Token10 />
                           </wsp:Policy>
                        </sp:X509Token>
                     </wsp:Policy>
                  </sp:ProtectionToken>
                  <sp:AlgorithmSuite>
                     <wsp:Policy>
                        <sp:Basic128 />
                     </wsp:Policy>
                  </sp:AlgorithmSuite>
                  <sp:Layout>
                     <wsp:Policy>
                        <sp:Lax />
                     </wsp:Policy>
                  </sp:Layout>
                  <sp:IncludeTimestamp />
                  <sp:EncryptSignature />
                  <sp:OnlySignEntireHeadersAndBody />
               </wsp:Policy>
            </sp:SymmetricBinding>
            <sp:SignedSupportingTokens
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:UsernameToken
                     sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                     <wsp:Policy>
                        <sp:WssUsernameToken10 />
                     </wsp:Policy>
                  </sp:UsernameToken>
               </wsp:Policy>
            </sp:SignedSupportingTokens>
            <sp:Wss11
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportRefKeyIdentifier />
                  <sp:MustSupportRefIssuerSerial />
                  <sp:MustSupportRefThumbprint />
                  <sp:MustSupportRefEncryptedKey />
               </wsp:Policy>
            </sp:Wss11>
            <sp:Trust13
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportIssuedTokens />
                  <sp:RequireClientEntropy />
                  <sp:RequireServerEntropy />
               </wsp:Policy>
            </sp:Trust13>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>
PK HAzCOEBPS/STS-Arch.html STS Architecture

STS Architecture

Overview of the STS
Customizing the STS WSDL
Customizing the Issue Operation
Customizing the Validate Operation
Customizing the Cancel Operation
Configuring STS Properties
PK HA)ZOEBPS/STS-Claims.html Enabling Claims in the STS

Enabling Claims in the STS

Demonstration location

The sample code in this section is taken from an STS system test. If you download and install the source distribution of Fuse Services Framework, you can find the system test Java code under the following directory:

CXFInstallDir/services/sts/systests/advanced/src/test/java/org/apache/cxf/systest/sts

And the system test resource files under the following directory:

CXFInstallDir/services/sts/systests/advanced/src/test/resources/org/apache/cxf/systest/sts

What is a claim?

A claim is an additional piece of data (for example, e-mail address, telephone number, and so on) about a principal, which can be included in a token along with the basic token data. Because this additional data is subject to signing, verification, and authentication, along with the rest of the token, the recipient can be confident that this data is true and accurate.

Requesting claims in an IssuedToken policy

If you want to issue a token with claims embedded, you can add a WS-Trust Claims element to the RequestSecurityTokenTemplate part of the issued token policy, as follows:

<sp:IssuedToken
      sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
    <sp:RequestSecurityTokenTemplate>
        <t:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1</t:TokenType>
        <t:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey</t:KeyType>
        <t:Claims Dialect="http://schemas.xmlsoap.org/ws/2005/05/identity"
                  xmlns:ic="http://schemas.xmlsoap.org/ws/2005/05/identity">
            <ic:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email"/>
            <ic:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"/>
            <ic:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/phone"
                          Optional="true"/>
        </t:Claims>
    </sp:RequestSecurityTokenTemplate>
    <wsp:Policy>
        <sp:RequireInternalReference />
    </wsp:Policy>
    <sp:Issuer>
        <wsaw:Address>http://localhost:8080/SecurityTokenService/UT</wsaw:Address>
    </sp:Issuer>
</sp:IssuedToken>

By adding the Claims element to the RequestSecurityTokenTemplate element, you ensure that the STS client includes the specified claims in the token issue request that is sent to the STS. The STS responds to this request by retrieving the relevant claim data for the principal and embedding it into the issued token.

Processing claims

Figure 9.9 shows an overview of the steps that the STS performs to process claims received in an issue token request.

Figure 9.9. Processing Claims

Processing Claims

Steps to process claims

The STS processes claims as follows:

  1. One of the first things the TokenIssueOperation must do is to prepare for parsing the incoming request message.

    If a ClaimsManager object is registered with the TokenIssueOperation, the TokenIssueOperation invokes getClaimsParsers on the ClaimsManager instance, to obtain the list of available claims parsers.

  2. The TokenIssueOperation initiates parsing of the request message by invoking the parseRequest method on the RequestParser object, passing the list of ClaimsParser objects as one of the arguments to parseRequest. This ensures that the RequestParser is capable of parsing any Claims elements that might appear in the request message.

  3. If no claims parsers are configured on the claims manager (so that list of claims parsers is null), the RequestParser tries the IdentityClaimsParser claims parser by default. But the IdentityClaimsParser is applied to the Claims element, only if the Dialect attribute of the Claims element is equal to the identity claims dialect URI.

  4. After parsing the request message, the TokenIssueOperation tries to find the appropriate token provider, by calling canHandleToken on each of the registered token providers.

  5. In the current scenario, we assume that the client has requested the STS to issue a SAML token, so that the SAMLTokenProvider is selected to issue the token. The TokenIssueOperation invokes createToken on the SAMLTokenProvider.

  6. Before proceeding to issue the token, the SAMLTokenProvider checks whether handlers are available to process all of the non-optional claims. If the required claim handlers are not available, an exception is raised and the SAML token is not issued.

    For example, in the identity claims dialect, a claim can be tagged as non-optional by setting the Optional attribute to false on a ClaimsType element in the IssuedToken policy, as follows:

    <t:Claims Dialect="http://schemas.xmlsoap.org/ws/2005/05/identity"
          xmlns:ic="http://schemas.xmlsoap.org/ws/2005/05/identity">
    <ic:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email"
                  Optional="false"/>
    ...
</t:Claims>
    [Important]Important

    In the identity claims dialect, all claims are required (that is, non-optional) by default.

  7. When specifying the list of SAML attribute statement providers explicitly, it is good practice to include the DefaultAttributeStatementProvider instance in the list, so that the default token issuing behavior of the SAMLTokenProvider is preserved.

  8. In this example, the CustomAttributeStatementProvider encapsulates the code that embeds the requisite claim values into the issued SAML token. The SAMLTokenProvider invokes the getStatement method to obtain the SAML attribute statements containing the required claim values.

  9. The CustomAttributeStatementProvider obtains the claim values for the current principal, by invoking the retrieveClaimValues method on the ClaimsManager object.

    For example, if the request message included claims for the principal's e-mail address and phone number, it is at this point that the STS actually retrieves the principal's e-mail address and phone number.

  10. The ClaimsManager retrieves the claim values by iterating over all of the claims handlers, where each claims handler returns data for as many claims as it can.

    A claims handler implementation is effectively an intermediate layer between the ClaimsManager and a database. The database stores secure data about each user—such as, address, e-mail, telephone number, department, and so on—which can be used to populate claim values. For example, the database could be an LDAP server and Fuse Services Framework provides an LdapClaimsHandler class for this scenario—see The LdapClaimsHandler.

  11. After retrieving all of the claim values, the CustomAttributeStatementProvider proceeds to repackage the claim values as attribute statements, so that they can be embedded in the issued SAML token.

Claim dialects

In order to be as extensible and flexible as possible, the WS-Trust claims mechanism is designed to be pluggable and does not define the syntax of claims. That is, the contents of a WS-Trust Claims element is left unspecified by WS-Trust.

The detailed syntax of claims can be defined in third-party specifications, by defining a claim dialect. The Claim element allows you to specify the claim dialect in the Dialect attribute, as follows:

<t:Claims Dialect="DialectURI" xmlns:DialectPrefix="DialectURI">
    ...
</t:Claims>

You can then use the specified dialect to specify claims inside the Claims element.

For example, some of the claim dialects defined by the Oasis open standards foundation are as follows:

  • Identity claim dialect—defines the kind of data that is typically associated with a user account (for example, address, e-mail, telephone number) and is specified by the Identity Metasystem Interoperability Specification.

  • Common claim dialect—(not supported) defines data that is used in WS-Federation and is specified by the WS-Federation Specification. Fuse Services Framework does not provide an implementation of this claims dialect, but you could plug in a custom implementation to the STS, if you wish.

  • XSPA claim dialect—(not supported) defines a claim dialect that is used in Cross-Enterprise Security and Privacy Authorization XSPA Specification, which is a security standard used in the context of healthcare organizations. Fuse Services Framework does not provide an implementation of this claims dialect, but you could plug in a custom implementation to the STS, if you wish.

Identity claim dialect

The identity claim dialect is supported by default in Fuse Services Framework. It enables you to request the kind of data fields that are typically stored under a user's LDAP account—for example, address details, telephone number, department, role, and so on. The identity claim dialect is associated with the following dialect URI:

http://schemas.xmlsoap.org/ws/2005/05/identity

You can specify identity claims using the following syntax:

<t:Claims Dialect="http://schemas.xmlsoap.org/ws/2005/05/identity"
          xmlns:ic="http://schemas.xmlsoap.org/ws/2005/05/identity">
    <ic:ClaimType Uri="ClaimTypeURI" Optional="[true|false]"/>
    ...
</t:Claims>

The identity claim dialect defines a single element, ic:ClaimType, which has the following attributes:

Uri

Specifies the type of claim value that you want to include in the issued token. For example, the ClaimTypeURI might identify an e-mail address claim value, a phone number claim value, and so on.

Optional

Specifies whether or not this particular claim is optional or not. Setting to true means that the STS must be capable of populating the issued token with the claim value for the principal, otherwise the token cannot be issued. Default is true.

Claim type URIs for the identity claim dialect

The identity claim dialect supports the following claim type URIs:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

The subject's first name.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

The subject's surname.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

The subject's e-mail address.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress

The subject's street address.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/locality

The subject's locality, which could be a city, county, or other geographic region.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/stateorprovince

The subject's state or province.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/postalcode

The subject's postal code.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country

The subject's country.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/homephone

The subject's home phone number.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone

The subject's secondary phone number (for example, at work).

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone

The subject's mobile phone number.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth

The subject's date of birth.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender

The subject's gender.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier

The subject's Private Personal Identifier (PPID). The PPID is described in detail in the Identity Metasystem Interoperability Oasis standard.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage

The subject's Web page.

Claims parsers

Because WS-Trust claims have a pluggable architecture, you need a pluggable architecture for parsing claims. The STS allows you to configure a list of claims parsers to customize support for claims. Typically, you register a claims parser for each claim dialect you want to support.

The IdentityClaimsParser

By default, the STS provides a single claims parser implementation: the identity claims parser, org.apache.cxf.sts.claims.IdentityClaimsParser, which can parse the identity claim dialect.

You can optionally configure the identity claims parser explicitly, by registering it with the ClaimsManager instance. But this is not strictly necessary, because the request parser automatically defaults to the identity claims parser, even if you have not explicitly configured it.

Implementing a custom claims parser

You can extend the claims parsing capability of the STS by implementing a custom claims parser. For this, you would define a custom Java class that implements the following Java interface:

// Java
package org.apache.cxf.sts.claims;

import org.w3c.dom.Element;

public interface ClaimsParser {

    /**
     * @param claim Element to parse claim request from
     * @return RequestClaim parsed from claim
     */
    RequestClaim parse(Element claim);

    /**
     * This method indicates the claims dialect this Parser can handle.
     * 
     * @return Name of supported Dialect
     */
    String getSupportedDialect();

}

Claims handlers

The purpose of a claims handler is to retrieve the requested claim values for the specified principal. Typically, a claims handler is an intermediate layer that looks up claim values in persistent storage.

For example, suppose that an incoming request includes claims for an e-mail address and a phone number (the request claims). When the STS is ready to start populating the issued token with claim values, it calls on the registered claims handlers to retrieve the required claim values for the specified principal. If the principal is the user, Alice, for example, the claims handler would contact a database to retrieve Alice's e-mail address and phone number.

The LdapClaimsHandler

Fuse Services Framework provides the claims handler, org.apache.cxf.sts.claims.LdapClaimsHandler, which is capable of retrieving claim values from an LDAP server.

Implementing a custom claims handler

You can provide a custom claims handler by defining a class that implements the following Java interface:

// Java
package org.apache.cxf.sts.claims;

import java.net.URI;
import java.security.Principal;
import java.util.List;

import javax.xml.ws.WebServiceContext;

/**
 * This interface provides a pluggable way to handle Claims.
 */
public interface ClaimsHandler {

    List<URI> getSupportedClaimTypes();

    ClaimCollection retrieveClaimValues(
            RequestClaimCollection claims,
            ClaimsParameters parameters);

    @Deprecated
    ClaimCollection retrieveClaimValues(
            Principal principal,
            RequestClaimCollection claims,
            WebServiceContext context,
            String realm);
}

Configuring the ClaimsManager

The ClaimsManager class encapsulates most of the functionality required to support claims and you must configure it if you want to support claims in the STS. In particular, the claims manager encapsulates a list of claims parsers and a list of claims handlers. In practice, if you are using just the identity claims dialect, there is no need to configure the list of claims parsers explicitly; it is sufficient to configure just the list of claims handlers.

For example, the following Spring XML fragment shows how to register a ClaimsManager instance with the TokenIssueOperation bean, where the claims manager is initialized with a claims handler list containing one claims handler, CustomClaimsHandler.

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:cxf="http://cxf.apache.org/core"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://cxf.apache.org/configuration/security"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  xmlns:util="http://www.springframework.org/schema/util"
  xsi:schemaLocation="
            http://cxf.apache.org/core
            http://cxf.apache.org/schemas/core.xsd
            http://cxf.apache.org/configuration/security
            http://cxf.apache.org/schemas/configuration/security.xsd
            http://cxf.apache.org/jaxws
            http://cxf.apache.org/schemas/jaxws.xsd
            http://cxf.apache.org/transports/http/configuration
            http://cxf.apache.org/schemas/configuration/http-conf.xsd
            http://cxf.apache.org/transports/http-jetty/configuration
            http://cxf.apache.org/schemas/configuration/http-jetty.xsd
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans.xsd
            http://www.springframework.org/schema/util
            http://www.springframework.org/schema/util/spring-util-2.0.xsd">
    ...
    <bean id="transportSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="issueOperation" ref="transportIssueDelegate" />
        <property name="validateOperation" ref="transportValidateDelegate" />
    </bean>

    <bean id="transportIssueDelegate" class="org.apache.cxf.sts.operation.TokenIssueOperation">
        ...
        <property name="claimsManager" ref="claimsManager" />
        ...
    </bean>
    ...
    <bean id="claimsManager" class="org.apache.cxf.sts.claims.ClaimsManager">
        <property name="claimHandlers" ref="claimHandlerList" />
    </bean>

    <util:list id="claimHandlerList">
        <ref bean="customClaimsHandler" />
    </util:list>

    <bean id="customClaimsHandler"
        class="org.apache.cxf.systest.sts.deployment.CustomClaimsHandler">
    </bean>
    ...   
</beans>

The CustomClaimsHandler class is a trivial implementation of a claims handler that appears in one of the STS system tests. For the purposes of the test, it returns a few fixed claim values for a couple of different principals.

Embedding claim values in a SAML token

The key step in processing claims is the point where the STS attempts to issue the token. Whichever token provider is selected to issue the token, it must be capable of inserting the retrieved claim values into the issued token. The token provider must therefore be customized or extended, so that it is capable of embedding the claims in the issued token.

In the case of issuing SAML tokens, the appropriate mechanism for embedding claim values is to generate SAML attribute statements containing the claim values. The appropriate way to extend the SAML token provider, therefore, is to implement a custom AttributeStatementProvider class and to register this class with the SAMLTokenProvider instance (see SAMLTokenProvider).

Sample AttributeStatementProvider

Example 9.4 shows a sample implementation of an AttributeStatementProvider class, which is capable of embedding claim values in a SAML token. This sample implementation, CustomAttributeStatementProvider, is taken from the STS system tests, but it is generally quite useful as a starting point for a custom attribute statement provider implementation.

Example 9.4. The CustomAttributeStatementProvider Class

package org.apache.cxf.systest.sts.deployment;

import java.net.URI;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;

import org.apache.cxf.sts.claims.Claim;
import org.apache.cxf.sts.claims.ClaimCollection;
import org.apache.cxf.sts.claims.ClaimsManager;
import org.apache.cxf.sts.claims.ClaimsParameters;
import org.apache.cxf.sts.token.provider.AttributeStatementProvider;
import org.apache.cxf.sts.token.provider.TokenProviderParameters;
import org.apache.ws.security.WSConstants;
import org.apache.ws.security.saml.ext.bean.AttributeBean;
import org.apache.ws.security.saml.ext.bean.AttributeStatementBean;

public class CustomAttributeStatementProvider implements AttributeStatementProvider {

    public AttributeStatementBean getStatement(TokenProviderParameters providerParameters) {

        // Handle Claims
        ClaimsManager claimsManager = providerParameters.getClaimsManager();
        ClaimCollection retrievedClaims = new ClaimCollection();
        if (claimsManager != null) {
            ClaimsParameters params = new ClaimsParameters(); 1
            params.setAdditionalProperties(providerParameters.getAdditionalProperties());
            params.setAppliesToAddress(providerParameters.getAppliesToAddress());
            params.setEncryptionProperties(providerParameters.getEncryptionProperties());
            params.setKeyRequirements(providerParameters.getKeyRequirements());
            params.setPrincipal(providerParameters.getPrincipal());
            params.setRealm(providerParameters.getRealm());
            params.setStsProperties(providerParameters.getStsProperties());
            params.setTokenRequirements(providerParameters.getTokenRequirements());
            params.setTokenStore(providerParameters.getTokenStore());
            params.setWebServiceContext(providerParameters.getWebServiceContext());
            retrievedClaims = 
                claimsManager.retrieveClaimValues( 2
                    providerParameters.getRequestedClaims(),
                    params
                );
        }
        if (retrievedClaims == null) {
            return null;
        }
        
        Iterator<Claim> claimIterator = retrievedClaims.iterator();
        if (!claimIterator.hasNext()) {
            return null;
        }

        List<AttributeBean> attributeList = new ArrayList<AttributeBean>();
        String tokenType = providerParameters.getTokenRequirements().getTokenType();

        AttributeStatementBean attrBean = new AttributeStatementBean(); 3
        while (claimIterator.hasNext()) {
            Claim claim = claimIterator.next();
            AttributeBean attributeBean = new AttributeBean(); 4
            URI name = claim.getNamespace().relativize(claim.getClaimType());
            if (WSConstants.WSS_SAML2_TOKEN_TYPE.equals(tokenType)
                    || WSConstants.SAML2_NS.equals(tokenType)) {
                attributeBean.setQualifiedName(name.toString());
                attributeBean.setNameFormat(claim.getNamespace().toString());
            } else {
                attributeBean.setSimpleName(name.toString());
                attributeBean.setQualifiedName(claim.getNamespace().toString());
            }
            attributeBean.setAttributeValues(Collections.singletonList(claim.getValue())); 5
            attributeList.add(attributeBean);
        }
        attrBean.setSamlAttributes(attributeList);

        return attrBean;
    }

}

1

The first part of the getStatement method implementation is centered around the invocation of the ClaimsManager.retrieveClaimValues method.

In preparation for invoking the retrieveClaimValues method, you populate the ClaimsParameters object, which encapsulates most of the parameters needed to invoke retrieveClaimValues. The ClaimsParameters object is initialized simply by copying the relevant parameters from the TokenProviderParameters object.

2

Invoke the retrieveClaimValues method on the claims manager instance. This has the effect of retrieving the requested claim values from persistent storage, with the help of the claims handlers plug-ins (see Figure 9.9).

3

The AttributeStatementBean class is a WSS4J class that is used to encapsulate a SAML attribute statement.

4

The WSS4J AttributeBean class encapsulates a single SAML attribute.

5

Each claim value is inserted into an AttributeBean instance.

Configuring the custom AttributeStatementProvider

The custom attribute statement provider can be installed into the SAMLTokenProvider instance, as follows:

<beans ...>
    ...
    <bean id="transportSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="issueOperation" ref="transportIssueDelegate" />
        <property name="validateOperation" ref="transportValidateDelegate" />
    </bean>

    <bean id="transportIssueDelegate" class="org.apache.cxf.sts.operation.TokenIssueOperation">
        ...
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="claimsManager" ref="claimsManager" />
        ...
    </bean>

    <util:list id="transportTokenProviders">
        <ref bean="transportSamlTokenProvider" />
        ...
    </util:list>
    ...
    <bean id="transportSamlTokenProvider"
          class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
        <property name="attributeStatementProviders" ref="attributeStatementProvidersList" />
    </bean>

    <util:list id="attributeStatementProvidersList">
        <ref bean="defaultAttributeProvider" />
        <ref bean="customAttributeProvider" />
    </util:list>

    <bean id="defaultAttributeProvider"
        class="org.apache.cxf.sts.token.provider.DefaultAttributeStatementProvider">
    </bean>

    <bean id="customAttributeProvider"
        class="org.apache.cxf.systest.sts.deployment.CustomAttributeStatementProvider">
    </bean>
    ...   
</beans>

Note that a DefaultAttributeStatementProvider instance should also be included in the list of attribute statement providers, so that the issued SAML token also includes the default attribute statement.

PK HA拁* * OEBPS/STS-Demo-BuildAndRun.html Build and Run the Demonstration

Build and Run the Demonstration

Steps to run the demonstration

To build and run the STS demonstration, perform the following steps:

  1. Open a command prompt and change directory to the CXFInstallDir/samples/sts directory. Enter the following command to build the demonstration:

    mvn clean install

  2. To start the STS process, enter the following command:

    mvn -Psts

  3. To start the WS server process, open a new command prompt, change directory to the CXFInstallDir/samples/sts directory, and enter the following command:

    mvn -Pserver

  4. To run the WS client, open a new command prompt, change directory to the CXFInstallDir/samples/sts directory, and enter the following command:

    mvn -Pclient

    Because CXF logging has been enabled, you should see the SOAP messages being logged to each of the command windows. If the client runs successfully, you should see the following message in the client command window:

    ...
--------------------------------------
Server responded with: Hello YourName
PK HA_;;OEBPS/STS-Demo-Client.html Client Configuration

Client Configuration

Overview

Figure 9.8 shows an overview of the configuration for the demonstration client.

Figure 9.8. Demonstration Client Configuration

Demonstration Client Configuration

Aspects of configuration

The most important aspects of the client configuration are, as follows:

Configure the connection to the STS

You must configure the client so that it is capable of contacting the STS to retrieve an issued SAML token. To enable the STS connection, initialize the client's ws-security.sts.client property with an STSClient instance, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:cxf="http://cxf.apache.org/core"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://cxf.apache.org/configuration/security"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  xsi:schemaLocation="
           http://cxf.apache.org/core
           http://cxf.apache.org/schemas/core.xsd
           http://cxf.apache.org/configuration/security
           http://cxf.apache.org/schemas/configuration/security.xsd
           http://cxf.apache.org/jaxws
           http://cxf.apache.org/schemas/jaxws.xsd
           http://cxf.apache.org/transports/http/configuration
           http://cxf.apache.org/schemas/configuration/http-conf.xsd
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd">
    ...
    <jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort"
                  createdFromAPI="true">
       <jaxws:properties>
           ...
           <entry key="ws-security.sts.client">
               <bean class="org.apache.cxf.ws.security.trust.STSClient">
                   <constructor-arg ref="cxf"/>
                   <property name="wsdlLocation" 
                             value="http://localhost:8080/SecurityTokenService/UT?wsdl"/>
                   <property name="serviceName" 
                             value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/}SecurityTokenService"/>
                   <property name="endpointName" 
                             value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/}UT_Port"/>
                   <property name="properties">
                       <map>
                           <entry key="ws-security.username" value="alice"/>
                           <entry key="ws-security.callback-handler" 
                                  value="demo.wssec.client.ClientCallbackHandler"/>
                           <entry key="ws-security.encryption.properties"
                                  value="keys/clientKeystore.properties"/> 
                           <entry key="ws-security.encryption.username" value="mystskey"/>
                           <entry key="ws-security.sts.token.username" value="myclientkey"/>
                           <entry key="ws-security.sts.token.properties"
                                  value="keys/clientKeystore.properties"/> 
                           <entry key="ws-security.sts.token.usecert" value="true"/> 
                       </map>
                   </property>
               </bean>            
           </entry> 
       </jaxws:properties>
   </jaxws:client>
    ...
</beans>

Besides the usual properties required for connecting to a Web service endpoint (specified by the wsdlLocation, serviceName, and endpointName properties), you must set the following security-related properties:

ws-security.username

In this demonstration, the STS is configured to authenticate the client using UsernameToken credentials. This property specifies the username part of the UsernameToken credentials.

ws-security.callback-handler

The callback handler class provides both private key passwords and UsernameToken passwords.

ws-security.encryption.properties

A WSS4J properties file that defines the properties for accessing the STS X.509 certificate. This certificate is needed by the symmetric binding protocol, which uses it to generate a symmetric session key.

ws-security.encryption.username

The alias of the X.509 certificate referenced by ws-security.encryption.properties.

ws-security.sts.token.properties

A WSS4J properties file that defines the properties for accessing the client's X.509 certificate. This is the certificate that is used to identify the client to the server in the Holder-of-Key scenario. This token gets embedded in the request that is sent to the STS (and is also embedded in the SAML token returned from the STS).

ws-security.sts.token.username

The alias of the STS X.509 certificate referenced by ws-security.sts.token.properties.

ws-security.sts.token.usecert

Setting this boolean property to true indicates that the specified token should be included in the request sent to the STS (the RequestSecurityToken message).

Configure the connection to the server

To configure the connection to the server, set the relevant properties directly on the JAX-WS client bean, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<beans ... >
    ...
    <jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort" createdFromAPI="true">
       <jaxws:properties>
           <entry key="ws-security.signature.properties" value="keys/clientKeystore.properties"/>
           <entry key="ws-security.signature.username" value="myclientkey"/>
           <entry key="ws-security.callback-handler" 
                  value="demo.wssec.client.ClientCallbackHandler"/>
           <entry key="ws-security.encryption.properties" value="keys/clientKeystore.properties"/> 
           <entry key="ws-security.encryption.username" value="myservicekey"/>
           <entry key="ws-security.sts.client">
               <bean class="org.apache.cxf.ws.security.trust.STSClient">
                   ...
               </bean>            
           </entry> 
       </jaxws:properties>
   </jaxws:client>
    ...
</beans>

Because the client-server connection uses an asymmetric binding (with an issued token), the following aspects of security need to be configured.

Configure the client's signing key (also used for decrypting message parts received from the server), using the following properties:

ws-security.signature.properties

A WSS4J properties file that defines the properties for accessing the client's signing key.

ws-security.signature.username

The alias of the client's signing key in the corresponding Java keystore file.

ws-security.callback-handler

The callback handler instance that can return the password for accessing the client's signing key.

Configure the client's encryption key (also used for verifying signatures on message parts received from the server), using the following properties:

ws-security.encryption.properties

A WSS4J properties file that defines the properties for accessing the client's encryption key (X.509 certificate).

ws-security.encryption.username

The alias of the client's encryption key in the corresponding Java keystore file.

Configure the client to support the IssuedToken policy by setting the ws-security.sts.client property, as already described in Configure the connection to the STS.

Client callback handler

The client callback handler class is multi-purpose. It is capable of returning both passwords for private keys and the password part of UsernameToken credentials. In this demonstration, the client callback handler class is defined as follows:

// Java
package demo.wssec.client;

import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.ws.security.WSPasswordCallback;

public class ClientCallbackHandler implements CallbackHandler {

    public void handle(Callback[] callbacks) throws IOException,
            UnsupportedCallbackException {
        for (int i = 0; i < callbacks.length; i++) {
            if (callbacks[i] instanceof WSPasswordCallback) {
                WSPasswordCallback pc = (WSPasswordCallback) callbacks[i];
                if ("myclientkey".equals(pc.getIdentifier())) {
                    pc.setPassword("ckpass");
                    break;
                } else if ("alice".equals(pc.getIdentifier())) {
                    pc.setPassword("clarinet");
                    break;
                } else if ("bob".equals(pc.getIdentifier())) {
                    pc.setPassword("trombone");
                    break;
                } else if ("eve".equals(pc.getIdentifier())) {
                    pc.setPassword("evekpass");
                    break;
                }
            }
        }
    }
}

Related STS configuration

In this demonstration, the STS authenticates the client by checking the client's UsernameToken credentials. Hence, you must ensure that the client's UsernameToken credentials are known to the STS. In this demonstration, the known UsernameToken credentials are embedded in the code of the STS callback handler class, STS callback handler .

PK HAP))OEBPS/STS-Demo-Overview.html Overview of the Demonstration

Overview of the Demonstration

Overview

The standalone Apache CXF distribution includes an STS demonstration in the following location:

CXFInstallDir/samples/sts

This demonstration illustrates a complete Holder-of-Key scenario, including all of the code for the client, server, and standalone STS.

The demonstration scenario

Figure 9.5 shows an overview of the STS demonstration scenario and the steps required to implement single-sign on in the context of WS-Trust and the STS.

Figure 9.5. STS Demonstration Scenario

STS Demonstration Scenario

In this Holder-of-Key scenario, there are two main stages involved in invoking an operation on the server: first the client obtains a single-sign on token (SAML token) from the STS; then the client invokes the WSDL operation on the server, embedding the SAML token in the SOAP security header.

The client-STS connection

The client-STS connection is used to obtain the single-sign on token (SAML token) from the STS. This connection is secured by a symmetric binding (for message protection) and messages must include a UsernameToken (for client authentication).

The symmetric binding is characterized by the fact that only one key pair is required (the STS X.509 certificate and private key) and the symmetric session key is derived from this key pair. To support the symmetric binding, the client must be configured with the STS X.509 certificate (public key) and the STS must be configured with the corresponding STS private key.

The UsernameToken credentials, which must accompany the Issue request sent to the STS, are used to authenticate the client.

The client-server connection

The client-server connection is established after the client has obtained the single-sign on token from the STS and is used to invoke the greetMe WSDL operation. This connection is secured by an asymmetric binding (for message protection and authentication).

The asymmetric binding is characterized by the fact that two key pairs are required: the Initiator token (a SAML token containing the client X.509 certificate); and the Recipient token (server X.509 certificate and private key). Both the client key pair and the server key pair are used for message protection.

The SAML token sent by the client contains a copy of the client's X.509 certificate and is used to authenticate the client (in a Holder-of-Key scenario).

Invocation steps

In the STS demonstration scenario shown in Figure 9.5, the client makes a secure invocation on the server as follows:

  1. The secure invocation is initiated when the client calls the greetMe() method.

  2. Before sending a request message to the server, the client must ask the STS to issue the token that will be used for single sign-on. The client delegates this task to the STSClient bean, which is itself a fully-fledged WS client that can communicate with the STS.

    To establish the connection to the STS, the STSClient bean must initialize a symmetric binding, as follows:

    1. The STSClient generates an ephemeral key (the symmetric session key).

    2. The STSClient encrypts the ephemeral key using the STS public key (X.509 certificate).

    3. The ephemeral key is then used for signing and encrypting the SOAP message parts sent between the STSClient bean and the STS.

  3. The STSClient bean now constructs the RequestSecurityToken (RST) message, which it sends to the STS. The STSClient embeds the client's X.509 certificate (to be used as the client's identity in the Holder-of-Key scenario) and the client's UsernameToken credentials (UT) into the RST message.

    The STSClient bean now uses the RST message to invoke the STS Issue operation.

  4. When the RST message arrives in the STS, the STS endpoint immediately tries to authenticate the embedded UsernameToken credentials. If the UsernameToken credentials could not be authenticated, the message would be rejected.

  5. The STS now processes the issue token request. The RST asks the STS to generate a SAML token, using the client's X.509 certificate as the Holder-of-Key identity. The STS constructs a RequestSecurityTokenResponse (RSTR) message containing a SAML token, taking care to sign the generated SAML token using the STS signing key.

  6. The STS returns the RSTR message containing the signed SAML token.

  7. The client is now ready to send the greetMe request to the server. The signed SAML token that was issued by the STS is embedded in the SOAP security header of the request message.

  8. The first thing that the server does is to check that the SAML token is signed by the STS public key. To be more precise, what the server actually does is to check whether the SAML token is signed by any trusted key—that is, any of the public keys that can be found in the servicestore.jks keystore file.

    If the SAML token is not signed by a trusted key, the message is rejected, because it is then impossible to establish trust in the SAML token.

  9. The server now performs the Holder-of-Key check, to establish the client's identity (effectively, authenticating the client).

    The X.509 certificate embedded in the SAML token is meant to be the client identity, but the client must also prove that it possesses the corresponding private key for the certificate, in order to be authentic. It turns out that, as part of the natural configuration of the asymmetric binding policy, the client is configured to sign various parts of the SOAP message using the myclientkey private key. The server therefore checks all of the message's signing keys and if it finds one that matches the X.509 certificate in the SAML token, it knows that the client is in possession of the private key.

  10. If all of the security checks have been successful, the server now invokes the implementation of the greetMe WSDL operation.

Single-sign on and scalability

Notice that the client in this scenario is required to hold a copy of the server's X.509 certificate (myservicekey certificate). The server's certificate must be distributed to the clients using some out-of-band approach, which creates some extra work when scaling up to a large system.

On the other hand, the server requires absolutely no knowledge whatsoever about the client. It relies entirely on the STS to establish trust with a client. This is a great advantage for scalability of the system.

PK HA[FFOEBPS/STS-Demo-STS.html Security Token Service Configuration

Security Token Service Configuration

Overview

Figure 9.6 shows an overview of how the STS is configured for the current demonstration.

Figure 9.6. Demonstration STS Configuration

Demonstration STS Configuration

Aspects of configuration

The current demonstration configures the following aspects of the STS:

  • WSDL contract and security policies—as already discussed in STS WSDL Contract, the policies in the WSDL contract are used to define the type of security that protects incoming connections to the STS. In particular, it is important that some form of client authentication is required by these security policies.

  • STS plug-in configuration—as described in Overview of the STS, the STS has a plug-in architecture. In order to instantiate an STS server, you must assemble and configure the STS plug-ins that you want to use.

  • STS signing key—you must configure the STS with its own signing key, which effectively provides the stamp of authenticity for any tokens issued by the STS.

  • List of known Web service endpoints—you can optionally install a service plug-in into the STS, which is used to define a list of known Web service endpoints that can use the STS (see Enabling AppliesTo in the STS).

  • JAX-WS endpoint configuration—you must define a Web service endpoint for the STS, which clients use to connect to the STS. In the JAX-WS endpoint you specify the X.509 certificate and private key that are used as the protection token in the symmetric binding and you also specify a callback handler, that accesses the database of UsernameToken credentials for authenticating clients.

Location of the STS Spring configuration

The STS Spring configuration file can be found in the following location:

CXFInstallDir/samples/sts/src/demo/wssec/sts/wssec-sts.xml

STS plug-in configuration

The first part of the wssec-sts.xml Spring configuration file is concerned with instantiating the STS implementation and specifying the relevant STS plug-ins to use:

<beans 
    xmlns="http://www.springframework.org/schema/beans"
    xmlns:cxf="http://cxf.apache.org/core"
    xmlns:jaxws="http://cxf.apache.org/jaxws"
    xmlns:test="http://apache.org/hello_world_soap_http"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:util="http://www.springframework.org/schema/util"
    xsi:schemaLocation="
        http://cxf.apache.org/core
        http://cxf.apache.org/schemas/core.xsd
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
        http://cxf.apache.org/jaxws                                     
        http://cxf.apache.org/schemas/jaxws.xsd
        http://www.springframework.org/schema/util
        http://www.springframework.org/schema/util/spring-util-2.0.xsd">
  ...
    <bean id="utSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="issueOperation" ref="utIssueDelegate"/>
        <property name="validateOperation" ref="utValidateDelegate"/>
    </bean>    

    <bean id="utIssueDelegate"
        class="org.apache.cxf.sts.operation.TokenIssueOperation">
        <property name="tokenProviders" ref="utSamlTokenProvider"/>
        <property name="services" ref="utService"/>
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    
    <bean id="utValidateDelegate"
        class="org.apache.cxf.sts.operation.TokenValidateOperation">
        <property name="tokenValidators" ref="utSamlTokenValidator"/>
        <property name="stsProperties" ref="utSTSProperties"/>
    </bean>
    
    <bean id="utSamlTokenProvider"
        class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
    </bean>
    
    <bean id="utSamlTokenValidator"
        class="org.apache.cxf.sts.token.validator.SAMLTokenValidator">
    </bean>
  ...
</beans>

In the demonstration STS instance, only two STS operations are supported: Issue, implemented by the utIssueDelegate bean, and Validate, implemented by the utValidateDelegate bean. The Validate operation is not used in the current demonstration.

The utIssueDelegate bean is configured with the following properties:

tokenProviders

A list of plug-ins that can generate various kinds of token. In this demonstration, this list is initialized with a single provider, SAMLTokenProvider, which is capable of generating SAML tokens.

services

(Optional) The services property enables you to specify the Web services that are secured by the STS, by specifying a list of regular expressions that must match the Web service URLs.

stsProperties

The stsProperties specifies some generic configuration settings that are common to many of the plug-ins in the STS.

STS signing key

The STS signing key—which is used to sign all of the tokens issued by the STS—is specified by setting the following properties on the StaticSTSProperties class:

signaturePropertiesFile

A WSS4J properties file that defines the properties for accessing the keys/stsstore.jks Java keystore file.

signatureUsername

The alias of the STS signing key in the Java keystore file.

callbackHandlerClass

A callback handler class that returns the password for accessing the STS signing key.

The StaticSTSProperties class is instantiated as the utSTSProperties bean in the wssec-sts.xml configuration file:

<beans ... >
    ...
    <bean id="utSTSProperties"
         class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="keys/stsKeystore.properties"/>
        <property name="signatureUsername" value="mystskey"/>
        <property name="callbackHandlerClass" value="demo.wssec.sts.STSCallbackHandler"/>
        <property name="issuer" value="DoubleItSTSIssuer"/>
    </bean>
    ...
</beans>

List of known Web service endpoints

The utService bean enables you to specify the Web service endpoints that are known to the STS, as follows:

<beans ... >
    ...
    <bean id="utService"
        class="org.apache.cxf.sts.service.StaticService">
        <property name="endpoints" ref="utEndpoints"/>
    </bean>
    
    <util:list id="utEndpoints">
        <value>http://localhost:(\d)*/SoapContext/SoapPort</value>
    </util:list>
    ...
</beans>

The utEndpoints bean instantiates a java.util.List object containing a list of regular expressions that must match the server's endpoint URL. When a client requests a new token from the STS, it includes the server's endpoint URL in the request, so that the STS can check whether or not the target endpoint is a known endpoint.

For more details about how to configure this, see Enabling AppliesTo in the STS.

JAX-WS endpoint configuration

To create a HTTP/SOAP endpoint that listens for incoming connections to the STS, define a jaxws:element, as follows:

<beans ... >
  ...
    <jaxws:endpoint id="UTSTS"
        implementor="#utSTSProviderBean"
        address="http://localhost:8080/SecurityTokenService/UT" 
        wsdlLocation="wsdl/ws-trust-1.4-service.wsdl"
        xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        serviceName="ns1:SecurityTokenService"
        endpointName="ns1:UT_Port">
        <jaxws:properties>
            <entry key="ws-security.callback-handler" value="demo.wssec.sts.STSCallbackHandler"/>
            <entry key="ws-security.signature.properties" value="keys/stsKeystore.properties"/>
            <entry key="ws-security.signature.username" value="mystskey"/>
        </jaxws:properties> 
    </jaxws:endpoint>
  ...
</beans>

In addition to the usual attributes required for a JAX-WS endpoint, the jaxws:endpoint element defines properties for accessing the protection token and a reference to a callback handler instance.

Protection token for the symmetric binding

The protection token provides the fundamental basis for the symmetric binding. It is used to generate all of the sessions keys for the connection. Although you might expect the corresponding properties to be called something like protection.token, the following properties of jaxws:endpoint are, in fact, used to specify the protection token:

ws-security.signature.properties

A WSS4J properties file that defines the properties for accessing the keys/stsstore.jks Java keystore file.

ws-security.signature.username

The alias of the protection token (X.509 certificate and private key pair) in the Java keystore file.

ws-security.callback-handler

A callback handler class that returns the password for accessing the protection token.

It so happens that in this demonstration, the protection token uses the same X.509 certificate and private key as the STS signing key.

STS callback handler

The jaxws:endpoint element is also configured with a callback handler (through the ws-security.callback-handler property), as follows:

// Java
package demo.wssec.sts;

import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.ws.security.WSPasswordCallback;

public class STSCallbackHandler implements CallbackHandler {

    public void handle(Callback[] callbacks) throws IOException,
            UnsupportedCallbackException {
        for (int i = 0; i < callbacks.length; i++) {
            if (callbacks[i] instanceof WSPasswordCallback) {
                WSPasswordCallback pc = (WSPasswordCallback) callbacks[i];
                if ("mystskey".equals(pc.getIdentifier())) {
                    pc.setPassword("stskpass");
                    break;
                } else if ("alice".equals(pc.getIdentifier())) {
                    pc.setPassword("clarinet");
                    break;
                }
            }
        }
    }
}

The security callback handler can be used for multiple purposes (for example, see Providing Client Credentials). In particular, in this demonstration the callback handler on the jaxws:element is used for the following purposes:

  • Retrieving the password for the protection tokenthe protection token consists of a private key/public key pair and a password is needed to access the private key (which is stored in a Java keystore file).

  • Retrieving the password for a client's UsernameToken credentialsthe symmetric binding policy in this demonstration requires the client to send UsernameToken credentials to the STS, for the purpose of authenticating the client. The callback handler must therefore have access to a database of UsernameToken credentials, in order to authenticate the incoming UsernameToken credentials. In this example, just a single UsernameToken credential is supported, with username, alice, and password, clarinet.

    [Note]Note

    In an enterprise security system, it is more likely that you would use an LDAP server to store the client UsernameToken credentials.

PK HAr511OEBPS/STS-Demo-Server.html Server Configuration

Server Configuration

Overview

Figure 9.7 shows an overview of the configuration for the demonstration server.

Figure 9.7. Demonstration Server Configuration

Demonstration Server Configuration

Aspects of configuration

The most important aspects of the server configuration are, as follows:

  • WSDL contract and security policies—as already discussed in Server WSDL Contract, the policies in the WSDL contract are used to define the type of security that protects incoming connections to the Greeter server.

  • JAX-WS endpoint configuration—in the JAX-WS endpoint you specify the X.509 certificate and private key that are used as the recipient token in the asymmetric binding and you also specify the certificate (or certificates) for checking the signature of a SAML token.

  • Recipient token—is specified by setting the relevant properties in the JAX-WS endpoint configuration.

  • Server-side SAML token interceptor—the SAML token interceptor checks the signature of the SAML token, using the X.509 certificates (public keys) stored in the keystore file referenced by the ws-security.encryption.properties property.

  • Server callback handler—is used to provide the passwords for private keys.

  • Related STS configuration—when setting up a new server, you must remember to add an appropriate regular expression to the list of known Web service endpoints in the STS, or the STS will refuse to perform any operations for this server.

JAX-WS endpoint configuration

To create a HTTP/SOAP endpoint that listens for incoming connections to the server, define a jaxws:element, as follows:

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:cxf="http://cxf.apache.org/core"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://cxf.apache.org/configuration/security"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  xsi:schemaLocation="
            http://cxf.apache.org/core
            http://cxf.apache.org/schemas/core.xsd 
            http://cxf.apache.org/configuration/security                
            http://cxf.apache.org/schemas/configuration/security.xsd
            http://cxf.apache.org/jaxws
            http://cxf.apache.org/schemas/jaxws.xsd
            http://cxf.apache.org/transports/http/configuration
            http://cxf.apache.org/schemas/configuration/http-conf.xsd
            http://cxf.apache.org/transports/http-jetty/configuration
            http://cxf.apache.org/schemas/configuration/http-jetty.xsd
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans.xsd">
    ...
    <jaxws:endpoint id="server"
      implementor="demo.wssec.server.GreeterImpl"
      endpointName="s:SoapPort"
      serviceName="s:SOAPService"
      address="http://localhost:9001/SoapContext/SoapPort"
      wsdlLocation="wsdl/hello_world.wsdl"
      xmlns:s="http://apache.org/hello_world_soap_http">
        
      <jaxws:properties>
         <entry key="ws-security.signature.username" value="myservicekey"/>
         <entry key="ws-security.callback-handler" 
                value="demo.wssec.server.ServerCallbackHandler"/>
         <entry key="ws-security.signature.properties" value="keys/serviceKeystore.properties"/>
         <entry key="ws-security.encryption.properties" value="keys/serviceKeystore.properties"/>
      </jaxws:properties> 
    </jaxws:endpoint>
    ...
</beans>

In addition to the usual attributes required for a JAX-WS endpoint, the jaxws:endpoint element defines properties for accessing the recipient token, properties for accessing SAML signature-checking tokens, and a reference to a callback handler instance.

Recipient token

The recipient token for the asymmetric binding has both a public key part (used for encrypting outgoing messages) and a private key part (used for signing outgoing messages). These parts of the recipient token are specified by the following properties on the server's jaxws:endpoint element:

ws-security.signature.properties

A WSS4J properties file that defines the properties for accessing the private key part of the recipient token.

ws-security.signature.username

The alias of the recipient token (X.509 certificate and private key pair) in the Java keystore file.

ws-security.callback-handler

A callback handler class that returns the password for accessing the private key part of the recipient token.

ws-security.encryption.properties

A WSS4J properties file that defines the properties for accessing the public key part of the recipient token.

Server-side SAML token interceptor

The SAML token interceptor is automatically installed in the server, whenever the corresponding security policy is configured to use the IssuedToken policy. The SAML token interceptor is responsible for verifying the signature of the SAML token received from the client (initiator token).

Hence, it is necessary to configure one or more trusted certificates that can be used to check the signature of the SAML token. The SAML token will be rejected unless it is signed by one of the specified trusted certificates.

As it happens, there is not a dedicated property for specifying these trusted certificates. Instead, the SAML token interceptor re-uses the ws-security.encryption.properties property. Any trusted certificates found in the Java keystore file specified by ws-security.encryption.properties will be used for checking the signature of the SAML token. The configuration of the SAML token interceptor is thus the very same configuration that was used to specify the public key part of the recipient token:

<jaxws:endpoint ... >
  
  <jaxws:properties>
    ...
    <entry key="ws-security.encryption.properties" value="keys/serviceKeystore.properties"/>
  </jaxws:properties> 
</jaxws:endpoint>

In practice, configuring the SAML token interceptor consists of using a Java keystore utility to add the trusted STS X.509 certificate to the Java keystore file that is referenced by ws-security.encryption.properties.

Server callback handler

The jaxws:endpoint element is also configured with a callback handler (through the ws-security.callback-handler property), as follows:

// Java
package demo.wssec.server;

import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.ws.security.WSPasswordCallback;

public class ServerCallbackHandler implements CallbackHandler {

    public void handle(Callback[] callbacks) throws IOException,
            UnsupportedCallbackException {
        for (int i = 0; i < callbacks.length; i++) {
            if (callbacks[i] instanceof WSPasswordCallback) { // CXF
                WSPasswordCallback pc = (WSPasswordCallback) callbacks[i];
                if ("myservicekey".equals(pc.getIdentifier())) {
                    pc.setPassword("skpass");
                    break;
                }
            }
        }
    }
}

In this case, the security callback handler is used solely for the purpose of retrieving the password for accessing the private key part of the recipient token (which has the alias, myservicekey).

Related STS configuration

When setting up a server, you must remember to add an appropriate regular expression to the list of known Web service endpoints in the STS. For example, as discussed in the context of configuring the STS, you need to include a regular expression that matches the server's endpoint URL, which is set in the wssec-sts.xml file as follows: 

<beans ... >
    ...
    <bean id="utService"
        class="org.apache.cxf.sts.service.StaticService">
        <property name="endpoints" ref="utEndpoints"/>
    </bean>
    
    <util:list id="utEndpoints">
        <value>http://localhost:(\d)*/SoapContext/SoapPort</value>
    </util:list>
    ...
</beans>
PK HA7bGbGOEBPS/STS-Demo-ServerWsdl.html Server WSDL Contract

Server WSDL Contract

Overview

The server WSDL contract determines the kind of security policies that are applied to the client-server connection. In the current demonstration, this connection is secured by an asymmetric binding policy.

A particularly important aspect of this policy is that the InitiatorToken is specified by an IssuedToken policy element. It is the presence of the IssuedToken element in the policy which triggers the client to call out to the STS, requesting the STS to issue a SAML token for single sign-on.

Location of the server WSDL contract

The server WSDL contract can be found in the following location:

CXFInstallDir/samples/sts/wsdl/hello_world.wsdl

Parts of the contract

The most important parts of the server WSDL contract are, as follows:

Greeter port type

The Greeter port type defines the logical interface to the Web service provided by the server, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="HelloWorld" targetNamespace="http://apache.org/hello_world_soap_http" 
    xmlns="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
    xmlns:tns="http://apache.org/hello_world_soap_http"
    xmlns:x1="http://apache.org/hello_world_soap_http/types"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
    xmlns:t="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
    xmlns:wsaw="http://www.w3.org/2005/08/addressing"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    ...
    <wsdl:portType name="Greeter">
        
        <wsdl:operation name="greetMe">
            <wsdl:input message="tns:greetMeRequest" name="greetMeRequest"/>
            <wsdl:output message="tns:greetMeResponse" name="greetMeResponse"/>
        </wsdl:operation>
        
    </wsdl:portType>
    ...
</wsdl:definitions>

Binding

The WSDL binding for the Greeter port type is a regular SOAP binding, except for the wsp:PolicyReference elements, which are used to apply the relevant security policies to the binding. Hence, the policy identified by AsymmetricSAML2Policy is applied to the whole binding and the Input_policy and the Output_policy are applied respectively to the input messages and the output messages of each operation.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
    ...
    <wsdl:binding name="Greeter_SOAPBinding" type="tns:Greeter">
        <wsp:PolicyReference URI="#AsymmetricSAML2Policy" />
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        
        <wsdl:operation name="greetMe">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="greetMeRequest">
                <soap:body use="literal"/>
                <wsp:PolicyReference URI="#Input_Policy" />
            </wsdl:input>
            <wsdl:output name="greetMeResponse">
                <soap:body use="literal"/>
                <wsp:PolicyReference URI="#Output_Policy" />
            </wsdl:output>
        </wsdl:operation>
        
    </wsdl:binding>
    ...
</wsdl:definitions>

For full details of how policy references work, see Policies and policy references.

Service and port

The WSDL service and WSDL port elements are used to define the address of the Greeter WS endpoint (specified by the location attribute of soap:address).

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
    ...
    <wsdl:service name="SOAPService">
        <wsdl:port binding="tns:Greeter_SOAPBinding" name="SoapPort">
            <soap:address location="http://localhost:9001/SoapContext/SoapPort"/>
        </wsdl:port>
    </wsdl:service>
    ...
</wsdl:definitions>

Binding policy

The binding policy, AsymmetricSAML2Policy, defines what kind of security is applied to incoming server connections.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
    ...
    <wsp:Policy wsu:Id="AsymmetricSAML2Policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsam:Addressing wsp:Optional="false">
                    <wsp:Policy />
                </wsam:Addressing>
                <sp:AsymmetricBinding>
                    <wsp:Policy>
                        <sp:InitiatorToken>
                            <wsp:Policy>
                                <sp:IssuedToken
                                    sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                                    <sp:RequestSecurityTokenTemplate>
                                        <t:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</t:TokenType>
                                        <t:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey</t:KeyType>
                                    </sp:RequestSecurityTokenTemplate>
                                    <wsp:Policy>
                                        <sp:RequireInternalReference />
                                    </wsp:Policy>
                                    <sp:Issuer>
                                        <wsaw:Address>http://localhost:8080/SecurityTokenService/
                                        </wsaw:Address>
                                    </sp:Issuer>
                                </sp:IssuedToken>
                            </wsp:Policy>
                        </sp:InitiatorToken>
                        <sp:RecipientToken>
                            <wsp:Policy>
                                <sp:X509Token
                                    sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                                    <wsp:Policy>
                                        <sp:WssX509V3Token10 />
                                        <sp:RequireIssuerSerialReference />
                                    </wsp:Policy>
                                </sp:X509Token>
                            </wsp:Policy>
                        </sp:RecipientToken>
                        <sp:Layout>
                            <wsp:Policy>
                                <sp:Lax />
                            </wsp:Policy>
                        </sp:Layout>
                        <sp:IncludeTimestamp />
                        <sp:OnlySignEntireHeadersAndBody />
                        <sp:AlgorithmSuite>
                            <wsp:Policy>
                                <sp:Basic128 />
                            </wsp:Policy>
                        </sp:AlgorithmSuite>
                    </wsp:Policy>
                </sp:AsymmetricBinding>
                <sp:Wss11>
                    <wsp:Policy>
                        <sp:MustSupportRefIssuerSerial />
                        <sp:MustSupportRefThumbprint />
                        <sp:MustSupportRefEncryptedKey />
                    </wsp:Policy>
                </sp:Wss11>
                <sp:Trust13>
                    <wsp:Policy>
                        <sp:MustSupportIssuedTokens />
                        <sp:RequireClientEntropy />
                        <sp:RequireServerEntropy />
                    </wsp:Policy>
                </sp:Trust13>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
    ...
</wsdl:definitions>

The binding policy defines the Greeter server security policy to be an asymmetric binding. This implies that security is applied at the SOAP message level, where parts of the SOAP payload are liable to be encrypted and/or signed. Because this is an asymmetric binding, two keys must be provided:

For a more detailed discussion of the asymmetric binding policy, see .

IssuedToken policy

Take a closer look at the IssuedToken policy, which is the IntiatorToken in the server's asymmetric binding. It is defined as follows:

<sp:IssuedToken
      sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
    <sp:RequestSecurityTokenTemplate>
        <t:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</t:TokenType>
        <t:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey</t:KeyType>
    </sp:RequestSecurityTokenTemplate>
    <wsp:Policy>
        <sp:RequireInternalReference />
    </wsp:Policy>
    <sp:Issuer>
        <wsaw:Address>http://localhost:8080/SecurityTokenService/</wsaw:Address>
    </sp:Issuer>
</sp:IssuedToken>

The IssuedToken policy is the key component of WS-Trust. It triggers the client to request an issued token from the STS. The sp:RequestSecurityTokenTemplate element specifies some elements that are to be included in the request that is sent to the STS. It includes the following elements:

<t:TokenType>...#SAMLV2.0</t:TokenType>

Indicates that the client wishes the STS to issue a SAML 2.0 token.

<t:KeyType>.../PublicKey</t:KeyType>

Indicates that the client wants the STS to support the Holder-of-Key scenario, where an X.509 certificate (public key) is used to verify the client identity. This implies that the client's X.509 certificate will be included in the request sent to the STS.

Signed parts and encrypted parts policies

The Input_policy policy is used to specify exactly which parts of an input message should be encrypted and/or signed by the asymmetric session keys (initiator token and recipient token). In addition to signing and encrypting the SOAP body, the standard WS-Addressing SOAP headers are also signed (which protects them from tampering by third-parties).

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
    ...
    <wsp:Policy wsu:Id="Input_Policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <sp:EncryptedParts>
                    <sp:Body />
                </sp:EncryptedParts>
                <sp:SignedParts>
                    <sp:Body />
                    <sp:Header ... />
                    ...
                </sp:SignedParts>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
    ...
</wsdl:definitions>

The Output_policy policy is used to specify exactly which parts of an output message should be encrypted and/or signed by the asymmetric session keys (initiator token and recipient token).

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
    ...
    <wsp:Policy wsu:Id="Output_Policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <sp:EncryptedParts>
                    <sp:Body />
                </sp:EncryptedParts>
                <sp:SignedParts>
                    <sp:Body />
                    <sp:Header ... />
                    ...
                </sp:SignedParts>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
    ...
</wsdl:definitions>
PK HADK??OEBPS/STS-Demo-StsWsdl.html STS WSDL Contract

STS WSDL Contract

Overview

The STS WSDL contract specifies the address used to contact the STS and the STS WSDL also specifies the kind of security that applies to incoming connections. In the current demonstration, the STS requires clients to support the symmetric binding and to authenticate by providing UsernameToken credentials.

Location of the STS WSDL contract

The STS WSDL contract can be found in the following location:

CXFInstallDir/samples/sts/wsdl/ws-trust-1.4-service.wsdl

Parts of the contract

The most important parts of the STS WSDL contract are, as follows:

STS port type

The STS port type provides an abstract description of all the WSDL operations supported by the STS. The STS port type appearing the STS WSDL file is taken directly from the WS-Trust specification. Only the Issue operation is actually implemented in this demonstration, however.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
        targetNamespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:wstrust="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    >
  ...
  <!-- This portType is an example of an STS supporting full protocol -->
  <wsdl:portType name="STS">
    <wsdl:operation name="Cancel"> ... </wsdl:operation>
    <wsdl:operation name="Issue"> ... </wsdl:operation>
    <wsdl:operation name="Renew"> ... </wsdl:operation>
    <wsdl:operation name="Validate"> ... </wsdl:operation>
    <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
    <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>

WSDL binding

The WSDL binding for the STS is a regular SOAP binding (as could be generated using the Apache CXF wsdl2soap utility), except for the wsp:PolicyReference elements, which are used to apply the relevant security policies to the binding. Hence, the policy identified by UT_policy is applied to the whole binding and the Input_policy and the Output_policy are applied respectively to the input messages and the output messages of each operation.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
  <wsdl:binding name="UT_Binding" type="wstrust:STS">
      <wsp:PolicyReference URI="#UT_policy" />
      <soap:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
      <wsdl:operation name="Issue">
          <soap:operation
              soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue" />
          <wsdl:input>
              <wsp:PolicyReference URI="#Input_policy" />
              <soap:body use="literal" />
          </wsdl:input>
          <wsdl:output>
              <wsp:PolicyReference URI="#Output_policy" />
              <soap:body use="literal" />
          </wsdl:output>
      </wsdl:operation>
      <wsdl:operation name="Validate"> ... </wsdl:operation>
      <wsdl:operation name="Cancel"> ... </wsdl:operation>
      <wsdl:operation name="Renew"> ... </wsdl:operation>
      <wsdl:operation name="KeyExchangeToken"> ... </wsdl:operation>
      <wsdl:operation name="RequestCollection"> ... </wsdl:operation>
  </wsdl:binding>
  ...
</wsdl:definitions>

For full details of how policy references work, see Policies and policy references.

WSDL service and port

The WSDL service and WSDL port elements are used to define the address of the STS endpoint (specified by the location attribute of soap:address).

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
  <wsdl:service name="SecurityTokenService">
      <wsdl:port name="UT_Port" binding="tns:UT_Binding">
         <soap:address location="http://localhost:8080/SecurityTokenService/UT" />
      </wsdl:port>
  </wsdl:service>
  ...
</wsdl:definitions>

Binding policy

The binding policy, UT_policy, defines what kind of security is applied to incoming STS connections.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
  <wsp:Policy wsu:Id="UT_policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsap10:UsingAddressing/>
            <sp:SymmetricBinding
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:ProtectionToken>
                     <wsp:Policy>
                        <sp:X509Token
                           sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                           <wsp:Policy>
                              <sp:RequireDerivedKeys />
                              <sp:RequireThumbprintReference />
                              <sp:WssX509V3Token10 />
                           </wsp:Policy>
                        </sp:X509Token>
                     </wsp:Policy>
                  </sp:ProtectionToken>
                  <sp:AlgorithmSuite>
                     <wsp:Policy>
                        <sp:Basic128 />
                     </wsp:Policy>
                  </sp:AlgorithmSuite>
                  <sp:Layout>
                     <wsp:Policy>
                        <sp:Lax />
                     </wsp:Policy>
                  </sp:Layout>
                  <sp:IncludeTimestamp />
                  <sp:EncryptSignature />
                  <sp:OnlySignEntireHeadersAndBody />
               </wsp:Policy>
            </sp:SymmetricBinding>
            <sp:SignedSupportingTokens
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:UsernameToken
                     sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                     <wsp:Policy>
                        <sp:WssUsernameToken10 />
                     </wsp:Policy>
                  </sp:UsernameToken>
               </wsp:Policy>
            </sp:SignedSupportingTokens>
            <sp:Wss11
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportRefKeyIdentifier />
                  <sp:MustSupportRefIssuerSerial />
                  <sp:MustSupportRefThumbprint />
                  <sp:MustSupportRefEncryptedKey />
               </wsp:Policy>
            </sp:Wss11>
            <sp:Trust13
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <wsp:Policy>
                  <sp:MustSupportIssuedTokens />
                  <sp:RequireClientEntropy />
                  <sp:RequireServerEntropy />
               </wsp:Policy>
            </sp:Trust13>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>
  ...
</wsdl:definitions>

The binding policy defines the STS security policy to be a symmetric binding. This implies that security is applied at the SOAP message level, where parts of the SOAP payload are liable to be encrypted and/or signed. Because this is a symmetric binding, the keys used for encrypting and signing in both directions are derived from a single key, specified by the sp:ProtectionToken element (which is ultimately configured to be the mystskey private key and X.509 certificate on the STS server). The client is required to include a WSS UsernameToken in the SOAP security header, which is used by the STS to authenticate the client.

For a more detailed discussion of the symmetric binding policy, see .

Signed parts and encrypted parts policies

The Input_policy policy is used to specify exactly which parts of an input message should be encrypted and/or signed by the symmetric session keys. In addition to signing and encrypting the SOAP body, the standard WS-Addressing SOAP headers are also signed (which protects them from tampering by third-parties).

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
   <wsp:Policy wsu:Id="Input_policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <sp:SignedParts
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <sp:Body />
               <sp:Header Name="To"
                  Namespace="http://www.w3.org/2005/08/addressing" />
               ...
            </sp:SignedParts>
            <sp:EncryptedParts
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <sp:Body />
            </sp:EncryptedParts>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>
  ...
</wsdl:definitions>

The Output_policy policy is used to specify exactly which parts of an output message should be encrypted and/or signed by the symmetric session keys.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions ... >
  ...
   <wsp:Policy wsu:Id="Output_policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <sp:SignedParts
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <sp:Body />
               <sp:Header ... />
               ...
            </sp:SignedParts>
            <sp:EncryptedParts
               xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
               <sp:Body />
            </sp:EncryptedParts>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>
  ...
</wsdl:definitions>
PK HAQqqOEBPS/STS-Demo.html STS Demonstration

STS Demonstration

Overview of the Demonstration
STS WSDL Contract
Security Token Service Configuration
Server WSDL Contract
Server Configuration
Client Configuration
Build and Run the Demonstration
PK HAgA1rxrxOEBPS/STS-Realms-Demo.html Realms Demonstration

Realms Demonstration

Overview

The sample code in this section is taken from the STS system tests in the source distribution of Fuse Services Framework. The test illustrates several different aspects of STS realms, including realm-aware token issuing, validation across realms, and token transformation.

Demonstration location

You can find the Java code under the following directory:

CXFInstallDir/services/sts/systests/advanced/src/test/java/org/apache/cxf/systest/sts/realms

And the associated resource files under the following directory:

CXFInstallDir/services/sts/systests/advanced/src/test/resources/org/apache/cxf/systest/sts/realms

First STS server for A and C realms

Figure 9.13 shows how the first STS server is configured for realms A, C and default.

Figure 9.13. STS Server for A and C realms

STS Server for A and C realms

The first STS server supports the realms A, C, and default and opens distinct Web service ports for each of these three realms.

STS for realms A and C

The STS for realms A and C is configured as follows:

STS endpoint configuration for realms A and C

The WS endpoints of the STS for realms A and C are configured as follows in the STS's Spring XML file:

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:cxf="http://cxf.apache.org/core"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://cxf.apache.org/configuration/security"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  xmlns:util="http://www.springframework.org/schema/util"
  xsi:schemaLocation="
            http://cxf.apache.org/core
            http://cxf.apache.org/schemas/core.xsd
            http://cxf.apache.org/configuration/security
            http://cxf.apache.org/schemas/configuration/security.xsd
            http://cxf.apache.org/jaxws
            http://cxf.apache.org/schemas/jaxws.xsd
            http://cxf.apache.org/transports/http/configuration
            http://cxf.apache.org/schemas/configuration/http-conf.xsd
            http://cxf.apache.org/transports/http-jetty/configuration
            http://cxf.apache.org/schemas/configuration/http-jetty.xsd
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans.xsd
            http://www.springframework.org/schema/util
            http://www.springframework.org/schema/util/spring-util-2.0.xsd">
    
    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
    
    <cxf:bus>
        <cxf:features>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>

    <bean id="transportSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="issueOperation" ref="transportIssueDelegate" />
        <property name="validateOperation" ref="transportValidateDelegate" />
    </bean>
    ...
    <jaxws:endpoint id="RealmASTS" implementor="#transportSTSProviderBean"
        address="https://localhost:${testutil.ports.STSServer.2}/SecurityTokenService/realmA"
        ...
    </jaxws:endpoint>

    <jaxws:endpoint id="RealmCSTS" implementor="#transportSTSProviderBean"
        address="https://localhost:${testutil.ports.STSServer.2}/SecurityTokenService/realmC"
        ...
    </jaxws:endpoint>

    <jaxws:endpoint id="DefaultRealmSTS" implementor="#transportSTSProviderBean"
        address="https://localhost:${testutil.ports.STSServer.2}/SecurityTokenService/realmdefault"
        ...
    </jaxws:endpoint>

    <httpj:engine-factory id="ClientAuthHttpsSettings"
        bus="cxf">
        <httpj:engine port="${testutil.ports.STSServer.2}">
            <httpj:tlsServerParameters>
                ...
                <sec:clientAuthentication want="true" required="true" />
            </httpj:tlsServerParameters>
        </httpj:engine>
    </httpj:engine-factory>
   
</beans>

Note, in particular that the STS defines three different endpoints: for realm A, for realm C, and for the default realm. The endpoint URL that the client connects to, determines the realm in which the token is issued (see Example 9.5).

Issue configuration for realms A and C

For realms A and C, the TokenIssueOperation instance is configured as follows:

<beans ... >
    ...
    <bean id="transportIssueDelegate" class="org.apache.cxf.sts.operation.TokenIssueOperation">
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="services" ref="transportService" />
        <property name="stsProperties" ref="transportSTSProperties" />
    </bean>

    <util:list id="transportTokenProviders">
        <ref bean="transportSAMLProvider" />
    </util:list>

    <bean id="transportSAMLProvider" class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
        <property name="realmMap" ref="realms" />
    </bean>

    <util:map id="realms">
        <entry key="A" value-ref="realmA" />
        <entry key="C" value-ref="realmC" />
    </util:map>

    <bean id="realmA" class="org.apache.cxf.sts.token.realm.SAMLRealm">
        <property name="issuer" value="A-Issuer" />
        <property name="signatureAlias" value="myclientkey" />
    </bean>

    <bean id="realmC" class="org.apache.cxf.sts.token.realm.SAMLRealm">
        <property name="issuer" value="C-Issuer" />
        <property name="signatureAlias" value="myservicekey" />
    </bean>

    <!-- List of Web service endpoints that can use this STS -->
    <bean id="transportService" class="org.apache.cxf.sts.service.StaticService">
        <property name="endpoints" ref="transportEndpoints" />
    </bean>

    <util:list id="transportEndpoints">
        <value>https://localhost:(\d)*/doubleit/services/doubleitrealm.*
        </value>
    </util:list>
    ...
</beans>

As usual, the TokenIssueOperation is configured with a SAML token provider, but this SAML token provider is also configured with a realm map (through the realmMap property). The SAML token provider uses the realm map to retrieve the extra data that it needs to generate and sign a SAML token in each of the supported realms (see Issuing Tokens in Multiple Realms).

Validate configuration for realms A and C

For realms A and C, the TokenValidateOperation instance is configured as follows:

<beans ... >
    ...
    <bean id="transportValidateDelegate" class="org.apache.cxf.sts.operation.TokenValidateOperation">
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="tokenValidators" ref="transportTokenValidators" />
        <property name="stsProperties" ref="transportSTSProperties" />
    </bean>

    <util:list id="transportTokenProviders">
        <ref bean="transportSAMLProvider" />
    </util:list>
    ...
    <util:list id="transportTokenValidators">
        <ref bean="transportSAMLValidator" />
    </util:list>

    <bean id="transportSAMLValidator"
          class="org.apache.cxf.sts.token.validator.SAMLTokenValidator">
    </bean>
    ...
</beans>

Notice how both a list of token validators and token providers is set on the TokenValidateOperation instance. The token provider list is needed in case the STS is asked to issue a new token, in the context of token transformation (see Token Transformation across Realms).

STS properties for realms A and C

The STS properties instance encapsulates some general-purpose configuration settings that are used by various components of the STS. The STS properties instance for realms A and C is configured as follows:

<beans ... >
    ...
    <bean id="transportSTSProperties" class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile"
            value="org/apache/cxf/systest/sts/realms/stsKeystoreRealms.properties" />
        <property name="signatureUsername" value="mystskey" />
        <property name="callbackHandlerClass"
            value="org.apache.cxf.systest.sts.common.CommonCallbackHandler" />
        <property name="realmParser" ref="customRealmParser" />
        <property name="issuer" value="saml1-issuer" />
    </bean>

    <bean id="customRealmParser"
          class="org.apache.cxf.systest.sts.realms.URLRealmParser" />
    ...
</beans>

Note in particular that the realmParser property is initialized with an instance of the URLRealmParser class, whose implementation is shown in Example 9.5. The realm parser figures out the current realm by examining the message context.

Second STS server for B realm

Figure 9.14 shows how the second STS server is configured for the B realm.

Figure 9.14. STS Server for B realm

STS Server for B realm

The second STS server supports just realm B, and is configured to support a token transformation scenario.

STS for realm B

The STS for realm B is configured as follows:

STS configuration for realm B

The WS endpoint of the STS for realm B is configured as follows in the STS's Spring XML file:

<beans ... >
    
    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
    
    <cxf:bus>
        <cxf:features>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>

    <bean id="transportSTSProviderBean"
        class="org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider">
        <property name="issueOperation" ref="transportIssueDelegate" />
        <property name="validateOperation" ref="transportValidateDelegate" />
    </bean>
    ...
    <jaxws:endpoint id="RealmBSTS" implementor="#transportSTSProviderBean"
        address="https://localhost:${testutil.ports.STSServer}/SecurityTokenService/realmB"
        ...
    </jaxws:endpoint>

    <httpj:engine-factory id="ClientAuthHttpsSettings"
        bus="cxf">
        <httpj:engine port="${testutil.ports.STSServer}">
            <httpj:tlsServerParameters>
                ...
                <sec:clientAuthentication want="true"
                    required="true" />
            </httpj:tlsServerParameters>
        </httpj:engine>
    </httpj:engine-factory>
   
</beans>

Note, in particular that the STS embeds the name of the realm, realmB, in the WS endpoint address URL. The endpoint URL that the client connects to, determines the realm in which the token is issued (see Example 9.5).

Issue configuration for realm B

For realm B, the TokenIssueOperation instance is configured as follows:

<beans ... >
    ...
    <bean id="transportIssueDelegate" class="org.apache.cxf.sts.operation.TokenIssueOperation">
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="services" ref="transportService" />
        <property name="stsProperties" ref="transportSTSProperties" />
    </bean>

    <util:list id="transportTokenProviders">
        <ref bean="transportSAMLProvider" />
    </util:list>

    <bean id="transportSAMLProvider"
          class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
        <property name="realmMap" ref="realms" />
    </bean>

    <util:map id="realms">
        <entry key="B" value-ref="realmB" />
    </util:map>

    <bean id="realmB" class="org.apache.cxf.sts.token.realm.SAMLRealm">
        <property name="issuer" value="B-Issuer" />
    </bean>

    <!-- List of Web service endpoints that can use this STS -->
    <bean id="transportService" class="org.apache.cxf.sts.service.StaticService">
        <property name="endpoints" ref="transportEndpoints" />
    </bean>

    <util:list id="transportEndpoints">
        <value>https://localhost:(\d)*/doubleit/services/doubleitrealm.*
        </value>
    </util:list>
    ...
</beans>

As usual, the TokenIssueOperation is configured with a SAML token provider, but this SAML token provider is also configured with a realm map (through the realmMap property). The SAML token provider uses the realm map to retrieve the extra data that it needs to generate and sign a SAML token in each of the supported realms (see Issuing Tokens in Multiple Realms).

Validate configuration for realm B

For realm B, the TokenValidateOperation instance is configured as follows:

<beans ... >
    ...
    <bean id="transportValidateDelegate" class="org.apache.cxf.sts.operation.TokenValidateOperation">
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="tokenValidators" ref="transportTokenValidators" />
        <property name="stsProperties" ref="transportSTSProperties" />
    </bean>

    <util:list id="transportTokenProviders">
        <ref bean="transportSAMLProvider" />
    </util:list>
    ...
    <util:list id="transportTokenValidators">
        <ref bean="transportSAMLValidator" />
    </util:list>

    <bean id="transportSAMLValidator" class="org.apache.cxf.sts.token.validator.SAMLTokenValidator">
        <property name="subjectConstraints" ref="subjectConstraintList" />
        <property name="samlRealmCodec" ref="customSAMLRealmCodec" />
    </bean>

    <util:list id="subjectConstraintList">
        <value>.*CN=www.client.com.*</value>
        <value>.*CN=www.sts.com.*</value>
    </util:list>

    <bean id="customSAMLRealmCodec"
          class="org.apache.cxf.systest.sts.realms.IssuerSAMLRealmCodec" />
    ...
</beans>

In one of the test scenarios, the STS for realm B is expected to validate a token that was issued in a different realm. For this reason, the SAML token validator initializes the samlRealmCodec property with a reference to the SAML realm codec implementation, IssuerSAMLRealmCodec. The SAML realm codec parses the received token in order to discover what realm it was originally issued in. See Example 9.6.

STS properties for realm B

The STS properties instance encapsulates some general-purpose configuration settings that are used by various components of the STS. The STS properties instance for realm B is configured as follows:

<beans ... >
    ...
    <bean id="transportSTSProperties" class="org.apache.cxf.sts.StaticSTSProperties">
        <property name="signaturePropertiesFile" value="stsKeystore.properties" />
        <property name="signatureUsername" value="mystskey" />
        <property name="callbackHandlerClass"
            value="org.apache.cxf.systest.sts.common.CommonCallbackHandler" />
        <property name="issuer" value="saml2-issuer" />
        <property name="identityMapper" ref="customIdentityMapper" />
        <property name="realmParser" ref="customRealmParser" />
    </bean>

    <bean id="customIdentityMapper"
          class="org.apache.cxf.systest.sts.realms.CustomIdentityMapper" />

    <bean id="customRealmParser"
          class="org.apache.cxf.systest.sts.realms.URLRealmParser" />
    ...
</beans>

In particular, the STS properties are configured with a realm parser (whose implementation is shown in Example 9.5) and an identity mapper (whose implementation is shown in Example 9.7).

The identity mapper is needed to support the token transformation scenario—see Token Transformation across Realms.

Realm parser implementation

Example 9.5 shows the sample implementation of the realm parser. This implementation of the realm parser examines the address URL of the STS endpoint that the client sent its request to. The tail of the URL path determines the realm name. If no realm name is recognized, the parseRealm method returns null, to select the default realm (that is, the realm configured by default, by the STS properties instance).

Example 9.5. Demonstration RealmParser Implementation

// Java
package org.apache.cxf.systest.sts.realms;

import javax.xml.ws.WebServiceContext;

import org.apache.cxf.sts.RealmParser;
import org.apache.cxf.ws.security.sts.provider.STSException;

/**
 * A test implementation of RealmParser which returns a realm depending on a String contained
 * in the URL of the service request.
 */
public class URLRealmParser implements RealmParser {

    public String parseRealm(WebServiceContext context) throws STSException {
        String url = (String)context.getMessageContext().get("org.apache.cxf.request.url");
        if (url.contains("realmA")) {
            return "A";
        } else if (url.contains("realmB")) {
            return "B";
        } else if (url.contains("realmC")) {
            return "C";
        }
        
        return null;
    }
    
}

SAMLRealmCodec implementation

Example 9.6 shows the sample implementation of the SAMLRealmCodec. The purpose of the codec is to determine the realm that originally issued the received token, by inspecting the contents of the token. In this implementation, it is assumed the SAML assertion's Issuer string uniquely identifies the issuing realm.

Example 9.6. Demonstration SAMLRealmCodec Implementation

// Java
package org.apache.cxf.systest.sts.realms;

import org.apache.cxf.sts.token.realm.SAMLRealmCodec;
import org.apache.ws.security.saml.ext.AssertionWrapper;


/**
 * This class returns a realm associated with a SAML Assertion depending on the issuer.
 */
public class IssuerSAMLRealmCodec implements SAMLRealmCodec {
    
    /**
     * Get the realm associated with the AssertionWrapper parameter
     * @param assertion a SAML Assertion wrapper object
     * @return the realm associated with the AssertionWrapper parameter
     */
    public String getRealmFromToken(AssertionWrapper assertion) {
        if ("A-Issuer".equals(assertion.getIssuerString())) {
            return "A";
        } else if ("B-Issuer".equals(assertion.getIssuerString())) {
            return "B";
        }
        return null;
    }
    
}

IdentityMapper implementation

Example 9.7 shows the sample implementation of the identity mapper. The purpose of the identity mapper is to map the principal name from the source realm to the corresponding principal name in the target realm, in the context of a token transformation scenario.

Example 9.7. Demonstration IdentityMapper Implementation

// Java
package org.apache.cxf.systest.sts.realms;

import java.security.Principal;

import org.apache.cxf.sts.IdentityMapper;
import org.apache.ws.security.CustomTokenPrincipal;

/**
 * A test implementation of RealmParser.
 */
public class CustomIdentityMapper implements IdentityMapper {

    /**
     * Map a principal in the source realm to the target realm
     * @param sourceRealm the source realm of the Principal
     * @param sourcePrincipal the principal in the source realm
     * @param targetRealm the target realm of the Principal
     * @return the principal in the target realm
     */
    public Principal mapPrincipal(String sourceRealm, Principal sourcePrincipal, String targetRealm) {
        if ("A".equals(sourceRealm) && "B".equals(targetRealm)) {
            return new CustomTokenPrincipal("B-Principal");
        } else if ("B".equals(sourceRealm) && "A".equals(targetRealm)) {
            return new CustomTokenPrincipal("A-Principal");
        }
        return null;
    }

}
PK HAd<//OEBPS/STS-Realms-Issuing.html Issuing Tokens in Multiple Realms

Issuing Tokens in Multiple Realms

Overview

Fuse Services Framework optionally supports the concept of security realms in the STS. The WS-Trust specification does not explicitly discuss the concept of security realms, but one fairly natural approach you can use is to identify an STS issuer identity with a security realm. Enabling security realms requires you to implement and configure a variety of custom components in the STS.

Figure 9.11 shows an overview of how SAML tokens are issued in a realm-aware STS.

Figure 9.11. Realm-Aware SAML Token Issuer

Realm-Aware SAML Token Issuer

Realm aware token issuing steps

A realm-aware STS can issue SAML tokens in the following manner:

  1. When a realm-aware STS receives an issue token request, it tries to find out what realm to issue the token in, by calling out to the realm parser instance.

    WS-Trust does not define a standard way to associate a token with a realm. Hence, you must work out your own approach for indicating the realm and codify this approach by providing a custom implementation of the RealmParser interface. The realm parser's parseRealm method returns a string, which is the name of the realm to issue the token in.

    For example, you could identify the realm, by inspecting the URL of the STS Web service endpoint that was invoked. The pathname of the URL could include a segment that identifies the realm.

  2. The TokenIssueOperation instance then calls the canHandleToken method on each of the registered token providers. In this example, only the SAMLTokenProvider token provider is registered. The canHandleToken method parameters include the token type and the realm name.

  3. Assuming that the token type matches (for example, the client is requesting a SAML token), the SAMLTokenProvider looks up the realm name in its realm map to make sure that it can handle this realm. If the SAMLTokenProvider finds the realm name in its map, it returns true from the canHandleToken method.

  4. The TokenIssueOperation instance now calls the createToken method on the SAMLTokenProvider instance, in order to issue the token in the specified realm.

  5. The SAMLTokenProvider looks up the specified realm in the realm map and retrieves the corresponding SAMLRealm instance. The SAMLRealm instance encapsulates the data that is specific to this realm.

    For example, if the specified realm is A, the SAMLRealm instance records that the corresponding issuer name is A-Issuer and the alias of the signing key to use for this realm is StsKeyA.

  6. The SAMLTokenProvider now uses the realm-specific data in combination with the generic data from the STS properties instance to issue the SAML token in the specified realm.

    For example, if the specified realm is A, the SAMLTokenProvider embeds the A-Issuer string in the SAML token's issuer element and the SAML token is signed using the StsKeyA private key from the stsstore.jks Java keystore file.

Configuring the realm parser

Because there is no standard way to associate a realm with an issue token request, you must decide yourself how to identify a realm. Codify the approach by implementing the RealmParser interface and then register your custom realm parser by injecting it into the realmParser property of the STS properties bean.

For example, you could register the custom URLRealmParser instance with the StaticSTSProperties bean as follows:

<beans ... >
    ...
    <bean id="transportSTSProperties" class="org.apache.cxf.sts.StaticSTSProperties">
        ...
        <property name="realmParser" ref="customRealmParser" />
        ...
    </bean>

    <bean id="customRealmParser"
          class="org.apache.cxf.systest.sts.realms.URLRealmParser" />
    ...
</beans>

Sample URL realm parser

To implement a custom realm parser, you must override and implement the following method from the RealmParser interface:

public String parseRealm(WebServiceContext context) throws STSException;

The parseRealm passes an instance of javax.xml.ws.WebServiceContext, which provides access to message context and security information about the current request message (issue token request). You can use this message context information to identify the current realm.

For example, the URLRealmParser used in the previous example works by examining the URL of the invoked STS Web service endpoint and checking whether any known realm names are embedded in the URL. The realm name embedded in the URL is then taken to be the realm to issue the token in and the realm is then returned from the parseRealm method.

// Java
package org.apache.cxf.systest.sts.realms;

import javax.xml.ws.WebServiceContext;

import org.apache.cxf.sts.RealmParser;
import org.apache.cxf.ws.security.sts.provider.STSException;

/**
 * A test implementation of RealmParser which returns a realm depending on a String contained
 * in the URL of the service request.
 */
public class URLRealmParser implements RealmParser {

    public String parseRealm(WebServiceContext context) throws STSException {
        String url = (String)context.getMessageContext().get("org.apache.cxf.request.url");
        if (url.contains("realmA")) {
            return "A";
        } else if (url.contains("realmB")) {
            return "B";
        } else if (url.contains("realmC")) {
            return "C";
        }
        
        return null;
    }
    
}

A null return value indicates that the STS should use the default realm (as defined by the issuer and signatureUsername properties of the STS properties bean).

Configuring the realm map

In a realm-aware STS, the SAMLTokenProvider token provider must be initialized with a realm map, which provides the requisite data about each realm. For example, the scenario shown in Figure 9.11 uses a realm map like the following:

<beans ... >
    ...
    <bean id="transportIssueDelegate" class="org.apache.cxf.sts.operation.TokenIssueOperation">
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="services" ref="transportService" />
        <property name="stsProperties" ref="transportSTSProperties" />
    </bean>

    <util:list id="transportTokenProviders">
        <ref bean="transportSAMLProvider" />
    </util:list>

    <bean id="transportSAMLProvider" class="org.apache.cxf.sts.token.provider.SAMLTokenProvider">
        <property name="realmMap" ref="realms" />
    </bean>

    <util:map id="realms">
        <entry key="A" value-ref="realmA" />
        <entry key="B" value-ref="realmB" />
        <entry key="C" value-ref="realmC" />
    </util:map>

    <bean id="realmA" class="org.apache.cxf.sts.token.realm.SAMLRealm">
        <property name="issuer" value="A-Issuer" />
        <property name="signatureAlias" value="StsKeyA" />
    </bean>

    <bean id="realmB" class="org.apache.cxf.sts.token.realm.SAMLRealm">
        <property name="issuer" value="B-Issuer" />
        <property name="signatureAlias" value="StsKeyB" />
    </bean>

    <bean id="realmC" class="org.apache.cxf.sts.token.realm.SAMLRealm">
        <property name="issuer" value="C-Issuer" />
        <property name="signatureAlias" value="StsKeyC" />
    </bean>
    ...
</beans>
PK HAA;>>$OEBPS/STS-Realms-TokenTransform.html Token Transformation across Realms

Token Transformation across Realms

Overview

Token transformation is a special case of token validation across realms. As explained in Validating Tokens in Multiple Realms, it is possible to configure the STS to recognize and validate tokens that were issued in a different realm. But this is usually not sufficient for cross-realm interoperability. The foreign token might not have the right format for the target realm and the token's principal might not be recognized.

The solution to this interoperability problem is to re-issue the foreign token in the format required by the target realm and, if necessary, to map the token's principal to its equivalent in the target realm (assuming, of course, that the principal has an account in both realms). This is what is meant by token transformation.

Because the need for token transformation is usually recognized during token validation, the token transformation process is implemented as an extension of the Validate operation.

Triggering token transformation

Token transformation gets triggered when you configure the WS endpoint of the relying party to validate incoming tokens, as follows: 

<beans ... >
   ...
   <jaxws:endpoint id="doubleitrealmtransform"
      implementor="org.apache.cxf.systest.sts.common.DoubleItPortTypeImpl"
      endpointName="s:DoubleItRealmTransformPort"
      serviceName="s:DoubleItService"
      depends-on="ClientAuthHttpsSettings"
      address="https://localhost:${testutil.ports.Server}/doubleit/services/doubleitrealmtransform"
      wsdlLocation="org/apache/cxf/systest/sts/realms/DoubleIt.wsdl"
      xmlns:s="http://www.example.org/contract/DoubleIt">
        
      <jaxws:properties>
         <entry key="ws-security.saml2.validator">
            <bean class="org.apache.cxf.ws.security.trust.STSTokenValidator"/>
         </entry>
         <entry key="ws-security.sts.client">
               <bean class="org.apache.cxf.ws.security.trust.STSClient">
                   <constructor-arg ref="cxf"/>
                   <property name="wsdlLocation" 
                       value="https://localhost:${testutil.ports.STSServer}/SecurityTokenService/realmB?wsdl"/>
                   <property name="serviceName" 
                       value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/}SecurityTokenService"/>
                   <property name="endpointName" 
                       value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/}Transport_Port"/>
                   <property name="properties">
                       <map>
                           <entry key="ws-security.username" value="alice"/>
                           <entry key="ws-security.callback-handler" 
                                  value="org.apache.cxf.systest.sts.common.CommonCallbackHandler"/>
                           <entry key="ws-security.sts.token.username" value="myclientkey"/>
                           <entry key="ws-security.sts.token.properties" value="clientKeystore.properties"/> 
                           <entry key="ws-security.sts.token.usecert" value="true"/> 
                       </map>
                   </property>
                   <property name="tokenType" 
                        value="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"/>
               </bean>            
         </entry> 
      </jaxws:properties> 
   </jaxws:endpoint>
   ...
</beans>

The following properties set on jaxws:endpoint element are of key importance in configuring token transformation:

ws-security.saml2.validator

By initializing this property with an instance of the STSTokenValidator class, you are instructing the JAX-WS endpoint to validate incoming tokens by contacting the STS and invoking the Validate operation.

ws-security.sts.client

When validation is enabled on the JAX-WS endpoint, you must also configure an STSClient instance, which encapsulates all of the settings required to connect to the STS. The properties you can set on the STSClient instance are discussed in detail in Creating an STSClient Instance.

tokenType

In order to enable a token transformation request (as distinct from a simple validation request), you must also set the tokenType property on the STSClient instance. This is the key setting that triggers token transformation. When this setting is present, the Validate operation will perform token transformation and return a newly issued token of the specified type in the Validate response message.

For the list of possible token type URIs you can specify here, see Table 8.2.

Relying party as a gateway service

The relying party in the token transformation scenario typically acts as a gateway service. That is, having obtained a transformed token from the STS, it can then make invocations in the target realm on behalf of the client, using the newly-issued transformed token.

Transformation algorithm

When the STS receives a token transformation request (through the Validate operation), it processes the request as follows:

  1. When the STS receives the Validate request message, it performs all of the usual tests to validate the received token (see Customizing the Validate Operation).

  2. After validating the token successfully, the STS checks whether the TokenType has been explicitly set in the Validate request message (that is, whether the token type has some value other than the default dummy value).

  3. If the token type was explicitly set, the STS proceeds to transform the token, which means that it issues a new token to replace the validated token.

  4. The STS now checks whether the current realm (as determined by the realm parser—see Configuring the realm parser) is the same as the realm that issued the received token (as determined by the configured SAMLRealmCodec—see Configuring the SAMLRealmCodec). If the realms are different, the STS checks whether an IdentityMapper instance is configured on the STS properties object.

  5. If an IdentityMapper is configured, the STS transforms the validated token's principal by calling the mapPrincipal method on the IdentityMapper. The mapped identity will now be used as the transformed token's principal.

    [Note]Note

    In the context of SAML tokens, the principal corresponds to the value of the Subject/NameID element in the SAML token.

  6. The STS now proceeds to issue a new token in the current realm using the (possibly transformed) principal, based on the data in the validated token. The STS iterates over all of the registered token providers, until it finds a token provider that can handle the requested token type in the current realm.

  7. The STS then issues a new token by calling out to the token provider and returns the newly issued token in the Validate response message.

Configuring the TokenValidateOperation

The following Spring XML fragment shows an example of how the TokenValidateOperation instance is configured in an STS that supports token transformation:

<beans ... >
   ...
    <bean id="transportValidateDelegate" class="org.apache.cxf.sts.operation.TokenValidateOperation">
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="tokenValidators" ref="transportTokenValidators" />
        <property name="stsProperties" ref="transportSTSProperties" />
    </bean>
   ...
</beans>

As you might expect, you are required to provide a list of token validators to the tokenValidators property (as is usual for the Valdate operation—for example, see Customizing the Validate Operation). What you might not expect, however, is that you are also required to provide a list of token providers to the tokenProviders property: this is because the Validate operation is also responsible for issuing new tokens, in the token transformation scenario.

Implementing an IdentityMapper

In the context of token transformation, it is frequently necessary to implement an identity mapper, because the principal in the source realm is typically not the same as the principal in the target realm. To implement an identity mapper class, you inherit from the IdentityMapper interface and implement the mapPrincipal method, as shown in the following example:

// Java
package org.apache.cxf.systest.sts.realms;

import java.security.Principal;

import org.apache.cxf.sts.IdentityMapper;
import org.apache.ws.security.CustomTokenPrincipal;

/**
 * A test implementation of RealmParser.
 */
public class CustomIdentityMapper implements IdentityMapper {

    /**
     * Map a principal in the source realm to the target realm
     * @param sourceRealm the source realm of the Principal
     * @param sourcePrincipal the principal in the source realm
     * @param targetRealm the target realm of the Principal
     * @return the principal in the target realm
     */
    public Principal mapPrincipal(String sourceRealm, Principal sourcePrincipal, String targetRealm) {
        if ("A".equals(sourceRealm) && "B".equals(targetRealm)) {
            return new CustomTokenPrincipal("B-Principal");
        } else if ("B".equals(sourceRealm) && "A".equals(targetRealm)) {
            return new CustomTokenPrincipal("A-Principal");
        }
        return null;
    }

}

The CustomTokenPrincipal class is just a simple implementation of the java.security.Principal interface, which holds the string value of the returned principal.

Configuring the IdentityMapper

The IdentityMapper instance is configured by setting the identityMapper property on the STS properties instance, as follows:

<beans ... >
    ...
    <bean id="transportSTSProperties" class="org.apache.cxf.sts.StaticSTSProperties">
        ...
        <property name="identityMapper" ref="customIdentityMapper" />
        <property name="realmParser" ref="customRealmParser" />
    </bean>

    <bean id="customIdentityMapper"
          class="org.apache.cxf.systest.sts.realms.CustomIdentityMapper" />

    <bean id="customRealmParser"
          class="org.apache.cxf.systest.sts.realms.URLRealmParser" />
    ...
</beans>
PK HArH(0(0 OEBPS/STS-Realms-Validating.html Validating Tokens in Multiple Realms

Validating Tokens in Multiple Realms

Overview

Figure 9.12 shows an overview of how SAML tokens are validated in a realm-aware STS.

Figure 9.12. Realm-Aware SAML Token Validation

Realm-Aware SAML Token Validation

Realm aware token validating steps

A realm-aware STS can validate SAML tokens in the following manner:

  1. When a realm-aware STS receives a validate token request, it tries to find out what realm to issue the token in, by calling out to the realm parser instance.

    [Note]Note

    The realm identified by the realm parser in this step is not necessarily the same realm that the token was originally issued in. See Validating tokens across realms.

  2. The TokenValidateOperation instance then calls the canHandleToken method on each of the registered token validators. In this example, only the SAMLTokenValidator token validator is registered. The canHandleToken method parameters include the token type and the realm name.

    [Note]Note

    The default SAMLTokenValidator class ignores the realm parameter in the canHandleToken method, so it will attempt to validate the token in any realm. If you need to implement realm-specific validation steps, however, you have the option of implementing a custom SAML token validator that pays attention to the realm parameter.

  3. The TokenValidateOperation instance then calls the validateToken method on the SAMLTokenValidator, in order to validate the token in the specified realm.

  4. The SAMLTokenValidator attempts to validate the received SAML token by checking whether it has been signed by a trusted key. The public part of the signing key pair must match one of the trusted certificates stored in the signature trust store (as configured by the signaturePropertiesFile property in the STS properties instance).

    Hence, for each of the supported realms, the public part of the realm's signing key must be present in the signature trust store (or at least one of the certificate's in that realm's trust chain). Otherwise, the SAMLTokenValidator will not be able to validate tokens that were issued in that realm.

    For example, if you want to be able to validate tokens in the realms, A, B, and C, you must store the corresponding certificates (public part of the signature keys), StsKeyA, StsKeyB, and StsKeyC, in the stsstore.jks Java keystore file.

  5. In case the client needs the information, the SAMLTokenValidator also embeds the name of the realm where the token was originally issued into the Validate response message. This is not necessarily the same realm as the realm that the token has just been validated in.

    To find the original realm that the token was issued in, the SAMLTokenValidator calls out to the custom SAMLRealmCodec instance. The SAMLRealmCodec instance tries to figure out the issuing realm by examining the token contents. If the issuing realm can be established, this information is included in the Validate response message.

Configuring the realm parser

The realm-aware SAML token validator requires a realm parser, just like the realm-aware SAML token provider. Generally, both validator and provider can share the same realm parser instance—see Issuing Tokens in Multiple Realms.

Validating tokens across realms

It can happen that a token needs to be validated in a realm that is not the same realm as the realm where the token was issued. When you consider that the main purpose of the WS-Trust standard is to enable single-sign on, you can understand why it is desirable to support this feature. If a WS client needs to send requests to servers that are in different security realms, it would be a serious drawback, if the client was forced to obtain separate tokens for each of the realms. Hence, the STS Validate operation must be prepared to validate a token issued in a realm that is different from the realm it is being validated in.

Response from Validate operation

For the convenience of the client, which might need to know the realm that a token was originally issued in, the SAMLTokenValidator can be configured to discover the token's issuing realm and embed this information in the Validate operation's response. To give the SAMLTokenValidator the ability to discover the token's issuing realm, you must implement and register a SAMLRealmCodec instance.

Configuring the SAMLRealmCodec

The following Spring XML fragment shows how to instantiate and register the custom IssuerSAMLRealmCodec instance, which implements the SAMLRealmCodec interface:

<beans ... >
    ...
    <bean id="transportValidateDelegate" class="org.apache.cxf.sts.operation.TokenValidateOperation">
        <property name="tokenProviders" ref="transportTokenProviders" />
        <property name="tokenValidators" ref="transportTokenValidators" />
        <property name="stsProperties" ref="transportSTSProperties" />
    </bean>
    ...
    <util:list id="transportTokenValidators">
        <ref bean="transportSAMLValidator" />
    </util:list>

    <bean id="transportSAMLValidator"
          class="org.apache.cxf.sts.token.validator.SAMLTokenValidator">
        ...
        <property name="samlRealmCodec" ref="customSAMLRealmCodec" />
    </bean>

    <bean id="customSAMLRealmCodec"
          class="org.apache.cxf.systest.sts.realms.IssuerSAMLRealmCodec" />
    ...
</beans>

Sample implementation of SAMLRealmCodec

To implement a SAMLRealmCodec, you need to override and implement the following method:

public String getRealmFromToken(AssertionWrapper assertion)

Where the assertion parameter holds the contents of the SAML token. The assumption made here is that the realm name is either embedded in the SAML token somehow or the identity of the realm can somehow be inferred from the SAML token contents. For example, the SAML issuer name can typically be identified with a security realm.

The following examples shows a sample implementation, IssuerSAMLRealmCodec, which infers the realm name from the value of the issuer string:

// Java
package org.apache.cxf.systest.sts.realms;

import org.apache.cxf.sts.token.realm.SAMLRealmCodec;
import org.apache.ws.security.saml.ext.AssertionWrapper;


/**
 * This class returns a realm associated with a SAML Assertion depending on the issuer.
 */
public class IssuerSAMLRealmCodec implements SAMLRealmCodec {
    
    /**
     * Get the realm associated with the AssertionWrapper parameter
     * @param assertion a SAML Assertion wrapper object
     * @return the realm associated with the AssertionWrapper parameter
     */
    public String getRealmFromToken(AssertionWrapper assertion) {
        if ("A-Issuer".equals(assertion.getIssuerString())) {
            return "A";
        } else if ("B-Issuer".equals(assertion.getIssuerString())) {
            return "B";
        }
        return null;
    }
    
}
PK HAvOEBPS/STS-Realms.html Enabling Realms in the STS

Enabling Realms in the STS

Issuing Tokens in Multiple Realms
Validating Tokens in Multiple Realms
Token Transformation across Realms
Realms Demonstration
PK HA:[Y##OEBPS/STS.html Chapter 9. The Security Token Service

Chapter 9. The Security Token Service

The Security Token Service (STS) is the core component of the WS-Trust single-sign on framework. This chapter explains the modular architecture of the STS and takes you step-by-step through the demonstration included in the Apache CXF distribution.

STS Architecture
Overview of the STS
Customizing the STS WSDL
Customizing the Issue Operation
Customizing the Validate Operation
Customizing the Cancel Operation
Configuring STS Properties
STS Demonstration
Overview of the Demonstration
STS WSDL Contract
Security Token Service Configuration
Server WSDL Contract
Server Configuration
Client Configuration
Build and Run the Demonstration
Enabling Claims in the STS
Enabling AppliesTo in the STS
Enabling Realms in the STS
Issuing Tokens in Multiple Realms
Validating Tokens in Multiple Realms
Token Transformation across Realms
Realms Demonstration
PK HAX00OEBPS/WsPolicy-Expressions.html Policy Expressions

Policy Expressions

Overview

In general, a wsp:Policy element is composed of multiple different policy settings (where individual policy settings are specified as policy assertions). Hence, the policy defined by a wsp:Policy element is really a composite object. The content of the wsp:Policy element is called a policy expression, where the policy expression consists of various logical combinations of the basic policy assertions. By tailoring the syntax of the policy expression, you can determine what combinations of policy assertions must be satisfied at runtime in order to satisfy the policy overall.

This section describes the syntax and semantics of policy expressions in detail.

Policy assertions

Policy assertions are the basic building blocks that can be combined in various ways to produce a policy. A policy assertion has two key characteristics: it adds a basic unit of functionality to the policy subject and it represents a boolean assertion to be evaluated at runtime. For example, consider the following policy assertion that requires a WS-Security username token to be propagated with request messages:

<sp:SupportingTokens xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
  <wsp:Policy>
    <sp:UsernameToken/>
  </wsp:Policy>
</sp:SupportingTokens>

When associated with an endpoint policy subject, this policy assertion has the following effects:

Note that if a policy assertion returns false, this does not necessarily result in an error. The net effect of a particular policy assertion depends on how it is inserted into a policy and on how it is combined with other policy assertions.

Policy alternatives

A policy is built up using policy assertions, which can additionally be qualified using the wsp:Optional attribute, and various nested combinations of the wsp:All and wsp:ExactlyOne elements. The net effect of composing these elements is to produce a range of acceptable policy alternatives. As long as one of these acceptable policy alternatives is satisfied, the overall policy is also satisified (evaluates to true).

wsp:All element

When a list of policy assertions is wrapped by the wsp:All element, all of the policy assertions in the list must evaluate to true. For example, consider the following combination of authentication and authorization policy assertions:

<wsp:Policy wsu:Id="AuthenticateAndAuthorizeWSSUsernameTokenPolicy">
  <wsp:All>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:UsernameToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:SamlToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
  </wsp:All>
</wsp:Policy>

The preceding policy will be satisfied for a particular incoming request, if the following conditions both hold:

[Note]Note

The wsp:Policy element is semantically equivalent to wsp:All. Hence, if you removed the wsp:All element from the preceding example, you would obtain a semantically equivalent example

wsp:ExactlyOne element

When a list of policy assertions is wrapped by the wsp:ExactlyOne element, at least one of the policy assertions in the list must evaluate to true. The runtime goes through the list, evaluating policy assertions until it finds a policy assertion that returns true. At that point, the wsp:ExactlyOne expression is satisfied (returns true) and any remaining policy assertions from the list will not be evaluated. For example, consider the following combination of authentication policy assertions:

<wsp:Policy wsu:Id="AuthenticateUsernamePasswordPolicy">
  <wsp:ExactlyOne>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:UsernameToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:SamlToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
  </wsp:ExactlyOne>
</wsp:Policy>

The preceding policy will be satisfied for a particular incoming request, if either of the following conditions hold:

Note, in particular, that if both credential types are present, the policy would be satisfied after evaluating one of the assertions, but no guarantees can be given as to which of the policy assertions actually gets evaluated.

The empty policy

A special case is the empty policy, an example of which is shown in Example 5.1.

Example 5.1. The Empty Policy

<wsp:Policy ... > 
   <wsp:ExactlyOne>
      <wsp:All/>
   </wsp:ExactlyOne>
</wsp:Policy>

Where the empty policy alternative, <wsp:All/>, represents an alternative for which no policy assertions need be satisfied. In other words, it always returns true. When <wsp:All/> is available as an alternative, the overall policy can be satisified even when no policy assertions are true.

The null policy

A special case is the null policy, an example of which is shown in Example 5.2.

Example 5.2. The Null Policy

<wsp:Policy ... >
   <wsp:ExactlyOne/>
</wsp:Policy>

Where the null policy alternative, <wsp:ExactlyOne/>, represents an alternative that is never satisfied. In other words, it always returns false.

Normal form

In practice, by nesting the <wsp:All> and <wsp:ExactlyOne> elements, you can produce fairly complex policy expressions, whose policy alternatives might be difficult to work out. To facilitate the comparison of policy expressions, the WS-Policy specification defines a canonical or normal form for policy expressions, such that you can read off the list of policy alternatives unambiguously. Every valid policy expression can be reduced to the normal form.

In general, a normal form policy expression conforms to the syntax shown in Example 5.3.

Example 5.3. Normal Form Syntax

<wsp:Policy ... >
   <wsp:ExactlyOne>
        <wsp:All> <Assertion .../> ... <Assertion .../> </wsp:All>
        <wsp:All> <Assertion .../> ... <Assertion .../> </wsp:All>
        ...
   </wsp:ExactlyOne>
</wsp:Policy>

Where each line of the form, <wsp:All>...</wsp:All>, represents a valid policy alternative. If one of these policy alternatives is satisfied, the policy is satisfied overall.

PK HAs?P3P3OEBPS/WsPolicy-Intro.html Introduction to WS-Policy

Introduction to WS-Policy

Overview

The WS-Policy specification provides a general framework for applying policies that modify the semantics of connections and communications at runtime in a Web services application. Fuse Services Framework security uses the WS-Policy framework to configure message protection and authentication requirements.

Policies and policy references

The simplest way to specify a policy is to embed it directly where you want to apply it. For example, to associate a policy with a specific port in the WSDL contract, you can specify it as follows:

<wsdl:definitions targetNamespace="http://tempuri.org/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
  ...
  <wsdl:service name="PingService10">
    <wsdl:port name="UserNameOverTransport_IPingService" binding="BindingName">
      <wsp:Policy>
        <!-- Policy expression comes here! -->
      </wsp:Policy>
      <soap:address location="SOAPAddress"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

An alternative way to specify a policy is to insert a policy reference element, wsp:PolicyReference, at the point where you want to apply the policy and then insert the policy element, wsp:Policy, at some other point in the XML file. For example, to associate a policy with a specific port using a policy reference, you could use a configuration like the following:

<wsdl:definitions targetNamespace="http://tempuri.org/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
  ...
  <wsdl:service name="PingService10">
    <wsdl:port name="UserNameOverTransport_IPingService" binding="BindingName">
      <wsp:PolicyReference URI="#PolicyID"/>
      <soap:address location="SOAPAddress"/>
    </wsdl:port>
  </wsdl:service>
  ...
  <wsp:Policy wsu:Id="PolicyID">
    <!-- Policy expression comes here ... -->
  </wsp:Policy>
</wsdl:definitions>

Where the policy reference, wsp:PolicyReference, locates the referenced policy using the ID, PolicyID (note the addition of the # prefix character in the URI attribute). The policy itself, wsp:Policy, must be identified by adding the attribute, wsu:Id="PolicyID".

Policy subjects

The entities with which policies are associated are called policy subjects. For example, you can associate a policy with an endpoint, in which case the endpoint is the policy subject. It is possible to associate multiple policies with any given policy subject. The WS-Policy framework supports the following kinds of policy subject:

Service policy subject

To associate a policy with a service, insert either a <wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of the following WSDL 1.1 element:

Endpoint policy subject

To associate a policy with an endpoint, insert either a <wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of any of the following WSDL 1.1 elements:

For example, you can associate a policy with an endpoint binding as follows (using a policy reference):

<wsdl:definitions targetNamespace="http://tempuri.org/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
  ...
  <wsdl:binding name="EndpointBinding" type="i0:IPingService">
    <wsp:PolicyReference URI="#PolicyID"/>
    ...
  </wsdl:binding>
  ...
  <wsp:Policy wsu:Id="PolicyID"> ... </wsp:Policy>
  ...
</wsdl:definitions>

Operation policy subject

To associate a policy with an operation, insert either a <wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of any of the following WSDL 1.1 elements:

For example, you can associate a policy with an operation in a binding as follows (using a policy reference):

<wsdl:definitions targetNamespace="http://tempuri.org/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
  ...
  <wsdl:binding name="EndpointBinding" type="i0:IPingService">
    <wsdl:operation name="Ping">
      <wsp:PolicyReference URI="#PolicyID"/>
      <soap:operation soapAction="http://xmlsoap.org/Ping" style="document"/>
      <wsdl:input name="PingRequest"> ... </wsdl:input>
      <wsdl:output name="PingResponse"> ... </wsdl:output>
    </wsdl:operation>
    ...
  </wsdl:binding>
  ...
  <wsp:Policy wsu:Id="PolicyID"> ... </wsp:Policy>
  ...
</wsdl:definitions>

Message policy subject

To associate a policy with a message, insert either a <wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of any of the following WSDL 1.1 elements:

For example, you can associate a policy with a message in a binding as follows (using a policy reference):

<wsdl:definitions targetNamespace="http://tempuri.org/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
  ...
  <wsdl:binding name="EndpointBinding" type="i0:IPingService">
    <wsdl:operation name="Ping">
      <soap:operation soapAction="http://xmlsoap.org/Ping" style="document"/>
      <wsdl:input name="PingRequest">
        <wsp:PolicyReference URI="#PolicyID"/>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="PingResponse"> ... </wsdl:output>
    </wsdl:operation>
    ...
  </wsdl:binding>
  ...
  <wsp:Policy wsu:Id="PolicyID"> ... </wsp:Policy>
  ...
</wsdl:definitions>
PK HA/OEBPS/WsPolicy.html Chapter 5. The WS-Policy Framework

Chapter 5. The WS-Policy Framework

This chapter provides an introduction to the basic concepts of the WS-Policy framework, defining policy subjects and policy assertions, and explaining how policy assertions can be combined to make policy expressions.

Introduction to WS-Policy
Policy Expressions
PK HAZj'' OEBPS/WsTrust-BasicScenario.html Basic Scenarios

Basic Scenarios

Overview

This section describes the basic scenarios supported by WS-Trust, which are closely related to some of the use cases defined in the SAML standard. It is, therefore, worth taking a moment to look at the relationship between the SAML standard and the WS-Trust standard.

SAML architecture

The SAML standard is specified in four distinct parts, as follows:

WS-Trust and SAML

There are close parallels between the WS-Trust architecture and the SAML architecture. In particular, WS-Trust explicitly relies on and uses SAML assertions (that is, SAML tokens). On the other hand, WS-Trust does not use any of the protocol, bindings, or profiles components of the SAML standard.

The relationship between WS-Trust and SAML can be quite confusing, in fact, because WS-Trust does define an abstract protocol (for communicating with the STS), a binding (to the SOAP protocol), and scenarios that are remarkably similar to some of the SAML scenarios. But these aspects of WS-Trust are defined independently of the SAML standard.

Scenarios

SAML defines the following fundamental types of authentication scenario, which are also supported by WS-Trust:

Bearer scenario

In the bearer scenario, the server automatically trusts the SAML token (after verifying its signature). Thus, in the bearer scenario, any client that presents the token can make use of the claims contained in the token (roles, permissions, and so on). It follows that the client must be very careful not to expose the SAML token or to pass it to any untrusted applications. For example, the client/server connection must use encryption, to protect the SAML token from snooping.

Figure 8.2 shows a general outline of a typical bearer scenario.

Figure 8.2. Bearer Scenario

Bearer Scenario

Steps in the bearer scenario

The bearer scenario proceeds as follows:

  1. Before invoking an operation on the server, the client sends a RequestSecurityToken (RST) message to the Issue binding of the STS. The RST specifies a KeyType of Bearer.

    The STS generates a SAML token with subject confirmation type bearer, signs the token using its private key, and then returns the token in a RequestSecurityTokenReply (RSTR) message.

  2. The client attempts to invoke an operation on the server, with the SAML token embedded in the SOAP header of the request message, where either the SOAP header or the transport connection must be encrypted, to protect the token.

  3. The server checks the signature of the SAML token (using a local copy of the STS public key), to ensure that it has not been tampered with.

Holder-of-key scenario

The holder-of-key scenario is a refinement of the bearer scenario where, instead of accepting the SAML token when presented by any client, the server attempts to authenticate the client and checks that the client identity matches the holder-of-key identity embedded in the SAML token.

There are two variations on the Holder-of-Key scenario, depending on the value of the KeyType specified in the RST, as follows:

Figure 8.3 shows a general outline of a typical holder-of-key scenario.

Figure 8.3. Holder-of-Key Scenario

Holder-of-Key Scenario

Steps in the holder-of-key scenario

The bearer scenario proceeds as follows:

  1. Before invoking an operation on the server, the client sends a RequestSecurityToken (RST) message to the Issue binding of the STS. The STS generates a SAML token with subject confirmation type holder-of-key, embeds the client identity in the token (the holder-of-key identity), signs the token using its private key, and then returns the token in a RequestSecurityTokenReply (RSTR) message.

  2. The client attempts to invoke an operation on the server, with the SAML token embedded in the SOAP header of the request message.

  3. The server checks the signature of the SAML token (using a local copy of the STS public key), to ensure that it has not been tampered with.

  4. The server attempts to authenticate the client (for example, by requiring a client X.509 certificate or by checking WS-Security UsernameToken credentials) and checks that the client's identity matches the holder-of-key identity.

PK HA{t;$$OEBPS/WsTrust-Intro.html Introduction to WS-Trust

Introduction to WS-Trust

Overview

The WS-Trust standard is based around a centralized security server (the Security Token Service), which is capable of authenticating clients and can issue tokens containing various kinds of authentication and authorization data.

WS-Trust specification

The WS-Trust features of Fuse Services Framework are based on the WS-Trust standard from Oasis:

http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/ws-trust.html

Supporting specifications

Apart from the WS-Trust specification itself, several other specifications play an important role in the WS-Trust architecture, as follows:

WS-Trust architecture

Figure 8.1 shows a general overview of the WS-Trust architecture.

Figure 8.1. WS-Trust Architecture

WS-Trust Architecture

Requestor

A requestor is an entity that tries to invoke a secure operation over a network connection. In practice, a requestor is typically a Web service client.

Relying party

A relying party refers to an entity that has some services or resources that must be secured against unauthorized access. In practice, a relying party is typically a Web service.

[Note]Note

This is a term defined by the SAML specification, not by WS-Trust.

Security token

A security token is a collection of security data that a requestor sends inside a request (typically embedded in the message header) in order to invoke a secure operation or to gain access to a secure resource. In the WS-Trust framework, the notion of a security token is quite general and can be used to describe any block of security data that might accompany a request.

In principle, WS-Trust can be used with the following kinds of security token:

SAML token

A SAML token is a particularly flexible kind of security token. The SAML specification defines a general-purpose XML schema that enables you to wrap almost any kind of security data and enables you to sign and encrypt part or all of the token.

SAML is a popular choice of token to use in the context of WS-Trust, because SAML has all of the necessary features to support typical WS-Trust authentication scenarios.

Claims

A SAML security token is formally defined to consist of a collection of claims. Each claim typically contains a particular kind of security data.

Policy

In WS-Trust scenarios, a policy can represent the security configuration of a participant in a secure application. The requestor, the relying party, and the security token service are all configured by policies. For example, a policy can be used to configure what kinds of authentication are supported and required.

Security token service

The security token service (STS) lies at the heart of the WS-Trust security architecture. In the WS-Trust standard, the following bindings are defined (not all of which are supported by Apache CXF):

PK HAvRKRKOEBPS/WsTrust-IssuedToken.html Defining an IssuedToken Policy

Defining an IssuedToken Policy

Overview

In general, an IssuedToken policy can appear in any context where a regular token can appear. When an sp:IssuedToken element appears in a policy, it indicates that the application must call out to the STS to obtain a token (as specified in the sp:IssuedToken element) and then use the token in the current context.

Fundamentally, an IssuedToken policy consists of two parts: one part is aimed at the client, specifying how the client must use the IssuedToken; and another part is aimed at the STS, specifying what type of token to issue and how the token should be constructed. The part that is aimed at the STS is put inside the special element, sp:RequestSecurityTokenTemplate. All of the children of this element will be copied directly into the body of the RequestSecurityToken (RST) message that is sent to the STS when the client asks the STS to issue a token, as shown in Figure 8.4.

Figure 8.4. Injecting Parameters into the Outgoing RequestSecurityToken Message

Injecting Parameters into the Outgoing RequestSecurityToken Message

Namespaces

A typical IssuedToken policy is defined using elements from the following schema namespaces:

Table 8.1. XML Namespaces used with IssuedToken

PrefixXML Namespace
wsp:http://schemas.xmlsoap.org/ws/2004/09/policy
sp:http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702
wst:http://docs.oasis-open.org/ws-sx/ws-trust/200512

Sample policy

The following example shows a minimal IssuedToken policy, where the client requests the STS to issue a SAML 2.0 token (specified by the value of the trust:TokenType element). The issued token will be included in the client's request header (indicated by setting the sp:IncludeToken attribute to AlwaysToRecipient).

<sp:IssuedToken
    sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
  <sp:RequestSecurityTokenTemplate>
    <trust:TokenType
        xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
      >urn:oasis:names:tc:SAML:2.0:assertion</trust:TokenType>
  </sp:RequestSecurityTokenTemplate>
  <wsp:Policy>
    <!-- No extra policies needed in this demo. -->
  </wsp:Policy>
</sp:IssuedToken>

In an example such as this, where the IssuedToken policy contains few settings, it is assumed that the STS is already configured with sensible default properties.

Syntax

The IssuedToken element is defined with the following syntax:

<sp:IssuedToken
    sp:IncludeToken="xs:anyURI"?
    xmlns:sp="..." ... >
  (
   <sp:Issuer>wsa:EndpointReferenceType</sp:Issuer> |
   <sp:IssuerName>xs:anyURI</sp:IssuerName>
  ) ?
  <sp:RequestSecurityTokenTemplate TrustVersion="xs:anyURI"? >
    <wst:TokenType>...</wst:TokenType> ?
    <wst:KeyType>...</wst:KeyType> ?
    <wsp:AppliesTo>...</wsp:AppliesTo> ?
    <wst:Claims Dialect="..."> ... </wst:Claims> ?
    <!-- Many other WS-Trust elements allowed here -->
    ...
  </sp:RequestSecurityTokenTemplate>
  <wsp:Policy xmlns:wsp="...">
    (
     <sp:RequireDerivedKeys ... /> |
     <sp:RequireImpliedDerivedKeys ... /> |
     <sp:RequireExplicitDerivedKeys ... />
    ) ?
    <sp:RequireExternalReference ... /> ?
    <sp:RequireInternalReference ... /> ?
    ...
  </wsp:Policy>
  ...
</sp:IssuedToken>

XML elements

An IssuedToken policy is specified using the following XML elements:

sp:IssuedToken

The element containing the IssuedToken policy assertion. The IncludeToken attribute specifies whether the issued token is meant to be included in the security header of the client's request messages. The allowed values of this attribute are given in sp:IncludeToken attribute.

On the client side, the presence of this assertion signals that the client should attempt to obtain a token by contacting a remote STS.

sp:IssuedToken/sp:Issuer

(Optional) Contains a reference to the issuer of the token, of wsa:EndpointReferenceType type.

There is no need to specify the issuer's endpoint reference using sp:Issuer in Fuse Services Framework, because the issuer endpoint (that is, the STS address) is taken directly from the STS WSDL file instead.

sp:IssuedToken/sp:IssuerName

(Optional) The name of the issuing service (that is, the STS), in the format of a URI.

sp:IssuedToken/sp:RequestSecurityTokenTemplate

(Required) This element contains a list of WS-Trust policy assertions to be included in the outgoing RequestSecurityToken (RST) message that is sent to the STS. In other words, this element enables you to modify the Issue query that is sent to the STS to obtain the issued token. Thie element can contain any of the WS-Trust assertions that are valid children of the sp:RequestSecurityToken element, as specified by WS-Trust.

sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:TokenType

(Optional) The type of security token to issue, specified as a URI string. This element is usually specified together with a wst:KeyType element. Table 8.2 shows the list of standard token type URIs for the following token types: SAML 1.1, SAML 2.0, UsernameToken, X.509v3 single certificate, X509v1 single certificate, X.509 PKI certificate chain, X.509 PKCS7, and Kerberos.

Table 8.2. Token Type URIs

Token Type URI
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v1
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#PKCS7
http://docs.oasisopen.org/wss/oasiswss-kerberos-tokenprofile-1.1#Kerberosv5APREQSHA1

Consult the documentation for your third-party STS to find out what token types it supports. An STS can also support custom token types not listed in the preceding table.

sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:KeyType

(Optional) The type of key that the client will use to establish its identity to the WS server. The key type indirectly determines the subject confirmation type as either Holder-of-Key or bearer (see Basic Scenarios). Table 8.3 shows the list of standard key type URIs.

Table 8.3. Key Type URIs

Key Type URI
http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey
http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer
sp:IssuedToken/sp:RequestSecurityTokenTemplate/wsp:AppliesTo

(Optional) This WS-PolicyAttachment assertion can be specified as an alternative to or in addition to the wst:TokenType assertion (in the latter case, it takes precedence over the wst:TokenType assertion). It is used to specify the policy scope for which this token is required. In practice, this enables you to refer to a service or group of services for which this token is issued. The STS can then be configured to specify what kind of token to issue for that service (or services).

For more details, see Enabling AppliesTo in the STS.

sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:Claims

(Optional) Specifies the required claims that the issued token must contain in order to satisfy the IssuedToken policy assertion. Claims are used to provide additional data about the token subject—for example, e-mail address, first name, surname, and so on.

For more details, see Enabling Claims in the STS.

sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:OtherElements

(Optional) You can optionally include many other WS-Trust assertions in the RST template. The purpose of these assertions is to specify exactly what the content of the issued token should be and whether it is signed, encrypted, and so on. In practice, however, the details of the issued token are often configured in the STS, which makes it unnecessary to include all of these details in the RST template.

For a full list of of WS-Trust assertions that can be included in the RST template, see the OASIS WS-Trust 1.4 Specification.

sp:IssuedToken/sp:Policy

(Required) This element must be included in the IssuedToken, even if it is empty.

sp:IssuedToken/sp:Policy/sp:RequireDerivedKeys

(Optional) Only applicable when using WS-SecureConversation. The WS-SecureConversation specification enables you to establish a security context (analogous to a session), which is used for sending multiple secured messages to a given service. Normally, if you use the straightforward approach of authenticating every message sent to a particular service, the authentication adds a considerable overhead to secure communications. If you know in advance that a client will be sending multiple messages to a Web service, however, it makes sense to establish a security context between the client and the server, in order to cut the overheads of secure communication. This is the basic idea of WS-SecureConversation.

When a security context is established, the client and the server normally establish a shared secret. In order to prevent the shared secret being discovered, it is better to avoid using the shared secret directly and use it instead to generate the keys needed for encryption, signing, and so on—that is, to generate derived keys.

When the sp:RequireDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation and both implied derived keys and explicit derived keys are allowed.

[Note]Note

Only one of sp:RequireDerivedKeys, sp:RequireImpliedDerivedKeys, or sp:RequireExplicitDerivedKeys, can be included in sp:IssuedToken.

sp:IssuedToken/sp:Policy/sp:RequireImpliedDerivedKeys

(Optional) When the sp:RequireImpliedDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation, but only implied derived keys are allowed.

sp:IssuedToken/sp:Policy/sp:RequireExplicitDerivedKeys

(Optional) When the sp:RequireExplicitDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation, but only explicit derived keys are allowed.

sp:IssuedToken/sp:Policy/sp:RequireExternalReference

(Optional) When included, requires that external references to the issued token must be enabled.

sp:IssuedToken/sp:Policy/sp:RequireInternalReference

(Optional) When included, requires that internal references to the issued token must be enabled, where an internal reference uses one of the elements, wsse:Reference, wsse:KeyIdentifier, or wsse:Embedded.

PK HA7OEBPS/WsTrust-STSClient.html Creating an STSClient Instance

Creating an STSClient Instance

Overview

Whenever an IssuedToken policy is configured on a WSDL port, you must also configure the client to connect to an STS server to obtain a token. The code for connecting to the STS and obtaining a token is implemented by the following class:

org.apache.cxf.ws.security.trust.STSClient

The client must explicitly create an STSClient instance to manage the client-STS connection. You can do this in either of the following ways:

In addition to creating an STSClient instance, it is usually also necessary to enable SSL/TLS security on the STS proxy.

Direct configuration

In the case of direct configuration, your JAX-WS client proxy references an STSClient instance directly, by setting the ws-security.sts.client property on the client proxy. The value of ws-security.sts.client must be a reference to an STSClient instance.

For example, the following XML configuration shows how to instantiate a JAX-WS client proxy that references the STSClient with bean ID equal to default.sts-client (the bean ID is the same as the value of the name attribute):

<beans ...>
  ...
  <jaxws:client
    id="helloWorldProxy"
    serviceClass="org.apache.hello_world_soap_http.Greeter"
    address="https://localhost:9001/SoapContext/SoapPort">
    <jaxws:properties>
      <entry key="ws-security.sts.client" 
             value-ref="default.sts-client" />
    </jaxws:properties>
  </jaxws:client>
  ...
  <bean name="default.sts-client" 
    class="org.apache.cxf.ws.security.trust.STSClient">
    <constructor-arg ref="cxf"/>
    <property name="wsdlLocation" value="sts/wsdl/ws-trust-1.4-service.wsdl"/>
    <property name="serviceName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceProvider"/>
    <property name="endpointName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceSOAP"/>
  </bean>
  ...
</beans>

Indirect configuration

In the case of indirect configuration, there is no need to set any property on the JAX-WS client proxy. Implicitly, if the IssuedToken policy assertion is applied to the relevant WSDL port, the runtime automatically searches for an STSClient bean named, WSDLPortQName.sts-client. To configure the STSClient bean indrectly, perform the following steps:

  1. Define an STSClient bean, whose name attribute has the value, WSDLPortQName.sts-client.

  2. Set abstract="true" on the bean element. This prevents Spring from instantiating the bean. The reason for this is that the runtime is responsible for the lifecycle of the STSClient object.

  3. Set the relevant properties of the STSClient bean (typically, the wsdlLocation, serviceName, and endpointName properties). After the STSClient is instantiated in Java, the properties specified in XML will be injected into the STSClient instance.

For example, the following XML configuration creates a JAX-WS client proxy, which is associated with the {http://apache.org/hello_world_soap_http}SoapPort port (this is specified in an annotation on the service class, Greeter). When the client proxy needs to fetch an issued token for the first time, the runtime automatically creates an STSClient instance, searches for the bean named WSDLPortQName.sts-client, and injects the properties from that bean into the STSClient instance.

<beans ...>
  ...
  <jaxws:client
    id="helloWorldProxy"
    serviceClass="org.apache.hello_world_soap_http.Greeter"
    address="https://localhost:9001/SoapContext/SoapPort"
    />
  ...
  <bean name="{http://apache.org/hello_world_soap_http}SoapPort.sts-client" 
    class="org.apache.cxf.ws.security.trust.STSClient"
    abstract="true">
    <constructor-arg ref="cxf"/>
    <property name="wsdlLocation" value="sts/wsdl/ws-trust-1.4-service.wsdl"/>
    <property name="serviceName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceProvider"/>
    <property name="endpointName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceSOAP"/>
  </bean>
  ...
</beans>
PK HA$KaOEBPS/WsTrust.html Chapter 8. WS-Trust

Chapter 8. WS-Trust

WS-Trust provides the necessary security infrastructure for supporting advanced authentication and authorization requirements. In particular, WS-Trust enables you to store security data in a central location (in the Security Token Service) and support various single sign-on scenarios.

Introduction to WS-Trust
Basic Scenarios
Defining an IssuedToken Policy
Creating an STSClient Instance
PK HAs<<OEBPS/bk01-toc.html Web Services Security Guide

Web Services Security Guide

Table of Contents

1. Security for HTTP-Compatible Bindings
2. Managing Certificates
What is an X.509 Certificate?
Certification Authorities
Choice of CAs
Commercial Certification Authorities
Private Certification Authorities
Certificate Chaining
Special Requirements on HTTPS Certificates
Creating Your Own Certificates
Prerequisites
Set Up Your Own CA
Use the CA to Create Signed Certificates in a Java Keystore
Use the CA to Create Signed PKCS#12 Certificates
3. Configuring HTTPS
Authentication Alternatives
Target-Only Authentication
Mutual Authentication
Specifying Trusted CA Certificates
When to Deploy Trusted CA Certificates
Specifying Trusted CA Certificates for HTTPS
Specifying an Application’s Own Certificate
Deploying Own Certificate for HTTPS
4. Configuring HTTPS Cipher Suites
Supported Cipher Suites
Cipher Suite Filters
SSL/TLS Protocol Version
5. The WS-Policy Framework
Introduction to WS-Policy
Policy Expressions
6. Message Protection
Transport Layer Message Protection
SOAP Message Protection
Introduction to SOAP Message Protection
Basic Signing and Encryption Scenario
Specifying an AsymmetricBinding Policy
Specifying a SymmetricBinding Policy
Specifying Parts of Message to Encrypt and Sign
Providing Encryption Keys and Signing Keys
Specifying the Algorithm Suite
7. Authentication
Introduction to Authentication
Specifying an Authentication Policy
Providing Client Credentials
Authenticating Received Credentials
8. WS-Trust
Introduction to WS-Trust
Basic Scenarios
Defining an IssuedToken Policy
Creating an STSClient Instance
9. The Security Token Service
STS Architecture
Overview of the STS
Customizing the STS WSDL
Customizing the Issue Operation
Customizing the Validate Operation
Customizing the Cancel Operation
Configuring STS Properties
STS Demonstration
Overview of the Demonstration
STS WSDL Contract
Security Token Service Configuration
Server WSDL Contract
Server Configuration
Client Configuration
Build and Run the Demonstration
Enabling Claims in the STS
Enabling AppliesTo in the STS
Enabling Realms in the STS
Issuing Tokens in Multiple Realms
Validating Tokens in Multiple Realms
Token Transformation across Realms
Realms Demonstration
A. ASN.1 and Distinguished Names
ASN.1
Distinguished Names
Index

List of Figures

2.1. A Certificate Chain of Depth 2
2.2. A Certificate Chain of Depth 3
3.1. Target Authentication Only
3.2. Mutual Authentication
6.1. Basic Signing and Encryption Scenario
8.1. WS-Trust Architecture
8.2. Bearer Scenario
8.3. Holder-of-Key Scenario
8.4. Injecting Parameters into the Outgoing RequestSecurityToken Message
9.1. STS Architecture
9.2. Configuring TokenIssueOperation
9.3. Configuring TokenValidateOperation
9.4. Configuring TokenCancelOperation
9.5. STS Demonstration Scenario
9.6. Demonstration STS Configuration
9.7. Demonstration Server Configuration
9.8. Demonstration Client Configuration
9.9. Processing Claims
9.10. Processing the AppliesTo Policy
9.11. Realm-Aware SAML Token Issuer
9.12. Realm-Aware SAML Token Validation
9.13. STS Server for A and C realms
9.14. STS Server for B realm

List of Tables

4.1. Namespaces Used for Configuring Cipher Suite Filters
4.2. SSL/TLS Protocols Supported by SUN’s JSSE Provider
6.1. Encryption and Signing Properties
6.2. WSS4J Keystore Properties
6.3. Properties for Specifying Crypto Objects
6.4. Algorithm Suites
6.5. Key Length Properties
7.1. Client Credentials Properties
8.1. XML Namespaces used with IssuedToken
8.2. Token Type URIs
8.3. Key Type URIs
A.1. Commonly Used Attribute Types

List of Examples

1.1. Specifying HTTPS in the WSDL
1.2. Specifying HTTPS in the Server Code
1.3. Sample HTTPS Client with No Certificate
1.4. Sample HTTPS Client with Certificate
1.5. Sample HTTPS Server Configuration
4.1. Structure of a sec:cipherSuitesFilter Element
5.1. The Empty Policy
5.2. The Null Policy
5.3. Normal Form Syntax
6.1. Client HTTPS Configuration in Spring
6.2. Server HTTPS Configuration in Spring
6.3. Example of a Transport Binding
6.4. Example of an Asymmetric Binding
6.5. Example of a Symmetric Binding
6.6. Integrity and Encryption Policy Assertions
6.7. WSS4J Crypto Interface
7.1. Example of a Supporting Tokens Policy
7.2. Callback Handler for UsernameToken Passwords
9.1. Configuring the STS Issue Operation
9.2. Configuring the STS Validate Operation
9.3. Configuring the STS Cancel Operation
9.4. The CustomAttributeStatementProvider Class
9.5. Demonstration RealmParser Implementation
9.6. Demonstration SAMLRealmCodec Implementation
9.7. Demonstration IdentityMapper Implementation
PK HA)aaOEBPS/ch02s02s01.html Choice of CAs

Choice of CAs

A CA consists of a set of tools for generating and managing certificates and a database that contains all of the generated certificates. When setting up a Fuse Services Framework system, it is important to choose a suitable CA that is sufficiently secure for your requirements.

There are two types of CA you can use:

PK HAa&v v OEBPS/ch02s05s01.html Prerequisites

Prerequisites

OpenSSL utilities

The steps described in this section are based on the OpenSSL command-line utilities from the OpenSSL project. Further documentation of the OpenSSL command-line utilities can be obtained at http://www.openssl.org/docs.

Sample CA directory structure

For the purposes of illustration, the CA database is assumed to have the following directory structure:

X509CA/ca
X509CA/certs
X509CA/newcerts
X509CA/crl

Where X509CA is the parent directory of the CA database.

PK HAOۣ OEBPS/ch03s02s01.html When to Deploy Trusted CA Certificates

When to Deploy Trusted CA Certificates

Overview

When an application receives an X.509 certificate during an SSL/TLS handshake, the application decides whether or not to trust the received certificate by checking whether the issuer CA is one of a pre-defined set of trusted CA certificates. If the received X.509 certificate is validly signed by one of the application’s trusted CA certificates, the certificate is deemed trustworthy; otherwise, it is rejected.

Which applications need to specify trusted CA certificates?

Any application that is likely to receive an X.509 certificate as part of an HTTPS handshake must specify a list of trusted CA certificates. For example, this includes the following types of application:

PK HAٿJ1J1OEBPS/content.opf _CXFSecurityWeb Services Security GuideJuly 2012Copyright © 2012 FuseSource Corp. All rights reserved.FuseSourceenPK HA!ߕOEBPS/cover.html Cover
Third Party Acknowledgements
PK HAԃ2__OEBPS/i284538.html What is an X.509 Certificate?

What is an X.509 Certificate?

Role of certificates

An X.509 certificate binds a name to a public key value. The role of the certificate is to associate a public key with the identity contained in the X.509 certificate.

Integrity of the public key

Authentication of a secure application depends on the integrity of the public key value in the application’s certificate. If an impostor replaces the public key with its own public key, it can impersonate the true application and gain access to secure data.

To prevent this type of attack, all certificates must be signed by a certification authority (CA). A CA is a trusted node that confirms the integrity of the public key value in a certificate.

Digital signatures

A CA signs a certificate by adding its digital signature to the certificate. A digital signature is a message encoded with the CA’s private key. The CA’s public key is made available to applications by distributing a certificate for the CA. Applications verify that certificates are validly signed by decoding the CA’s digital signature with the CA’s public key.

[Warning]Warning

The demonstration certificates supplied with are self-signed certificates. These certificates are insecure because anyone can access their private key. To secure your system, you must create new certificates signed by a trusted CA. This chapter describes the set of certificates required by a Fuse Services Framework application and describes how to replace the default certificates.

The contents of an X.509 certificate

An X.509 certificate contains information about the certificate subject and the certificate issuer (the CA that issued the certificate). A certificate is encoded in Abstract Syntax Notation One (ASN.1), a standard syntax for describing messages that can be sent or received on a network.

The role of a certificate is to associate an identity with a public key value. In more detail, a certificate includes:

  • X.509 version information.

  • A serial number that uniquely identifies the certificate.

  • A subject distinguished name (DN) that identifies the certificate owner.

  • The public key associated with the subject.

  • An issuer DN that identifies the CA that issued the certificate.

  • The digital signature of the issuer.

  • Information about the algorithm used to sign the certificate.

  • Some optional X.509 v.3 extensions; for example, an extension exists that distinguishes between CA certificates and end-entity certificates.

Distinguished names

A DN is a general purpose X.500 identifier that is often used in the context of security.

See Appendix Afor more details about DNs.

PK HA)yOEBPS/i284542.html Certification Authorities

Certification Authorities

Choice of CAs
Commercial Certification Authorities
Private Certification Authorities
PK HA\FOEBPS/i284546.html Certificate Chaining

Certificate Chaining

Certificate chain

A certificate chain is a sequence of certificates, where each certificate in the chain is signed by the subsequent certificate.

Self-signed certificate

The last certificate in the chain is normally a self-signed certificate—a certificate that signs itself.

Example

Figure 2.1 shows an example of a simple certificate chain.

Figure 2.1. A Certificate Chain of Depth 2

a certificate chain of depth 2 has only one CA signature

Chain of trust

The purpose of a certificate chain is to establish a chain of trust from a peer certificate to a trusted CA certificate. The CA vouches for the identity in the peer certificate by signing it. If the CA is one that you trust (indicated by the presence of a copy of the CA certificate in your root certificate directory), this implies you can trust the signed peer certificate as well.

Certificates signed by multiple CAs

A CA certificate can be signed by another CA. For example, an application certificate could be signed by the CA for the finance department of Progress Software, which in turn is signed by a self-signed commercial CA. Figure 2.2 shows what this certificate chain looks like.

Figure 2.2. A Certificate Chain of Depth 3

a certificate chain of depth 3 has two CA signatures

Trusted CAs

An application can accept a peer certificate, provided it trusts at least one of the CA certificates in the signing chain.

See Specifying Trusted CA Certificates.

PK HA9 OEBPS/i284891.html ASN.1

ASN.1

Overview

The Abstract Syntax Notation One (ASN.1) was defined by the OSI standards body in the early 1980s to provide a way of defining data types and structures that are independent of any particular machine hardware or programming language. In many ways, ASN.1 can be considered a forerunner of modern interface definition languages, such as the OMG’s IDL and WSDL, which are concerned with defining platform-independent data types.

ASN.1 is important, because it is widely used in the definition of standards (for example, SNMP, X.509, and LDAP). In particular, ASN.1 is ubiquitous in the field of security standards—the formal definitions of X.509 certificates and distinguished names are described using ASN.1 syntax. You do not require detailed knowledge of ASN.1 syntax to use these security standards, but you need to be aware that ASN.1 is used for the basic definitions of most security-related data types.

BER

The OSI’s Basic Encoding Rules (BER) define how to translate an ASN.1 data type into a sequence of octets (binary representation). The role played by BER with respect to ASN.1 is, therefore, similar to the role played by GIOP with respect to the OMG IDL.

DER

The OSI’s Distinguished Encoding Rules (DER) are a specialization of the BER. The DER consists of the BER plus some additional rules to ensure that the encoding is unique (BER encodings are not).

References

You can read more about ASN.1 in the following standards documents:

PK HAҊ""OEBPS/i284895.html Distinguished Names

Distinguished Names

Overview

Historically, distinguished names (DN) are defined as the primary keys in an X.500 directory structure. However, DNs have come to be used in many other contexts as general purpose identifiers. In Fuse Services Framework, DNs occur in the following contexts:

  • X.509 certificates—for example, one of the DNs in a certificate identifies the owner of the certificate (the security principal).

  • LDAP—DNs are used to locate objects in an LDAP directory tree.

String representation of DN

Although a DN is formally defined in ASN.1, there is also an LDAP standard that defines a UTF-8 string representation of a DN (see RFC 2253). The string representation provides a convenient basis for describing the structure of a DN.

[Note]Note

The string representation of a DN does not provide a unique representation of DER-encoded DN. Hence, a DN that is converted from string format back to DER format does not always recover the original DER encoding.

DN string example

The following string is a typical example of a DN:

C=US,O=IONA Technologies,OU=Engineering,CN=A. N. Other

Structure of a DN string

A DN string is built up from the following basic elements:

OID

An OBJECT IDENTIFIER (OID) is a sequence of bytes that uniquely identifies a grammatical construct in ASN.1.

Attribute types

The variety of attribute types that can appear in a DN is theoretically open-ended, but in practice only a small subset of attribute types are used. Table A.1 shows a selection of the attribute types that you are most likely to encounter:

Table A.1. Commonly Used Attribute Types

String RepresentationX.500 Attribute TypeSize of DataEquivalent OID

C

countryName

2

2.5.4.6

O

organizationName

1...64

2.5.4.10

OU

organizationalUnitName

1...64

2.5.4.11

CN

commonName

1...64

2.5.4.3

ST

stateOrProvinceName

1...64

2.5.4.8

L

localityName

1...64

2.5.4.7

STREET

streetAddress

  

DC

domainComponent

  

UID

userid

  

AVA

An attribute value assertion (AVA) assigns an attribute value to an attribute type. In the string representation, it has the following syntax:

<attr-type>=<attr-value>

For example:

CN=A. N. Other

Alternatively, you can use the equivalent OID to identify the attribute type in the string representation (see Table A.1 ). For example:

2.5.4.3=A. N. Other

RDN

A relative distinguished name (RDN) represents a single node of a DN (the bit that appears between the commas in the string representation). Technically, an RDN might contain more than one AVA (it is formally defined as a set of AVAs). However, this almost never occurs in practice. In the string representation, an RDN has the following syntax:

<attr-type>=<attr-value>[+<attr-type>=<attr-value> ...]

Here is an example of a (very unlikely) multiple-value RDN:

OU=Eng1+OU=Eng2+OU=Eng3

Here is an example of a single-value RDN:

OU=Engineering
PK HANOEBPS/i296682.html Authentication Alternatives

Authentication Alternatives

Target-Only Authentication
Mutual Authentication
PK HA;fOEBPS/i296690.html Specifying an Application’s Own Certificate

Specifying an Application’s Own Certificate

Deploying Own Certificate for HTTPS
PK HA9 OEBPS/i298219.html Commercial Certification Authorities

Commercial Certification Authorities

Signing certificates

There are several commercial CAs available. The mechanism for signing a certificate using a commercial CA depends on which CA you choose.

Advantages of commercial CAs

An advantage of commercial CAs is that they are often trusted by a large number of people. If your applications are designed to be available to systems external to your organization, use a commercial CA to sign your certificates. If your applications are for use within an internal network, a private CA might be appropriate.

Criteria for choosing a CA

Before choosing a CA, consider the following criteria:

PK HALXOEBPS/i298223.html Private Certification Authorities

Private Certification Authorities

Choosing a CA software package

If you want to take responsibility for signing certificates for your system, set up a private CA. To set up a private CA, you require access to a software package that provides utilities for creating and signing certificates. Several packages of this type are available.

OpenSSL software package

One software package that allows you to set up a private CA is OpenSSL, http://www.openssl.org. OpenSSL is derived from SSLeay, an implementation of SSL developed by Eric Young (). The OpenSSL package includes basic command line utilities for generating and signing certificates. Complete documentation for the OpenSSL command line utilities is available at http://www.openssl.org/docs.

Setting up a private CA using OpenSSL

To set up a private CA, see the instructions in Creating Your Own Certificates .

Choosing a host for a private certification authority

Choosing a host is an important step in setting up a private CA. The level of security associated with the CA host determines the level of trust associated with certificates signed by the CA.

If you are setting up a CA for use in the development and testing of Fuse Services Framework applications, use any host that the application developers can access. However, when you create the CA certificate and private key, do not make the CA private key available on any hosts where security-critical applications run.

Security precautions

If you are setting up a CA to sign certificates for applications that you are going to deploy, make the CA host as secure as possible. For example, take the following precautions to secure your CA:

  • Do not connect the CA to a network.

  • Restrict all access to the CA to a limited set of trusted users.

  • Use an RF-shield to protect the CA from radio-frequency surveillance.

PK HALssOEBPS/i305153.html Creating Your Own Certificates

Creating Your Own Certificates

Prerequisites
Set Up Your Own CA
Use the CA to Create Signed Certificates in a Java Keystore
Use the CA to Create Signed PKCS#12 Certificates
PK HA$))OEBPS/i305191.html Set Up Your Own CA

Set Up Your Own CA

Substeps to perform

This section describes how to set up your own private CA. Before setting up a CA for a real deployment, read the additional notes in Choosing a host for a private certification authority .

To set up your own CA, perform the following steps:

  1. Add the bin directory to your PATH

  2. Create the CA directory hierarchy

  3. Copy and edit the openssl.cnf file

  4. Initialize the CA database

  5. Create a self-signed CA certificate and private key

Add the bin directory to your PATH

On the secure CA host, add the OpenSSL bin directory to your path:

Windows

> set PATH=OpenSSLDir\bin;%PATH%

UNIX 

% PATH=OpenSSLDir/bin:$PATH; export PATH

This step makes the openssl utility available from the command line.

Create the CA directory hierarchy

Create a new directory, X509CA, to hold the new CA. This directory is used to hold all of the files associated with the CA. Under the X509CA directory, create the following hierarchy of directories:

X509CA/ca
X509CA/certs
X509CA/newcerts
X509CA/crl

Copy and edit the openssl.cnf file

Copy the sample openssl.cnf from your OpenSSL installation to the X509CA directory.

Edit the openssl.cnf to reflect the directory structure of the X509CA directory, and to identify the files used by the new CA.

Edit the [CA_default] section of the openssl.cnf file to look like the following:

#############################################################
[ CA_default ]
    
dir        = X509CA            # Where CA files are kept
certs      = $dir/certs  # Where issued certs are kept
crl_dir    = $dir/crl          # Where the issued crl are kept
database   = $dir/index.txt    # Database index file
new_certs_dir = $dir/newcerts  # Default place for new certs
    
certificate   = $dir/ca/new_ca.pem # The CA certificate
serial        = $dir/serial        # The current serial number
crl           = $dir/crl.pem       # The current CRL
private_key   = $dir/ca/new_ca_pk.pem  # The private key
RANDFILE      = $dir/ca/.rand
# Private random number file

x509_extensions = usr_cert  # The extensions to add to the cert
...

You might decide to edit other details of the OpenSSL configuration at this point—for more details, see http://www.openssl.org/docs.

Initialize the CA database

In the X509CA directory, initialize two files, serial and index.txt.

Windows

To initialize the serial file in Windows, enter the following command:

> echo 01 > serial

To create an empty file, index.txt, in Windows start Windows Notepad at the command line in the X509CA directory, as follows:

> notepad index.txt

In response to the dialog box with the text, Cannot find the text.txt file. Do you want to create a new file?, click Yes, and close Notepad.

UNIX

To initialize the serial file and the index.txt file in UNIX, enter the following command:

% echo "01" > serial
% touch index.txt

These files are used by the CA to maintain its database of certificate files.

[Note]Note

The index.txt file must initially be completely empty, not even containing white space.

Create a self-signed CA certificate and private key

Create a new self-signed CA certificate and private key with the following command:

openssl req -x509 -new -config X509CA/openssl.cnf -days 365 -out X509CA/ca/new_ca.pem -keyout X509CA/ca/new_ca_pk.pem

The command prompts you for a pass phrase for the CA private key and details of the CA distinguished name. For example:

Using configuration from X509CA/openssl.cnf
Generating a 512 bit RSA private key
....+++++
.+++++
writing new private key to 'new_ca_pk.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished
Name or a DN. There are quite a few fields but you can leave
some blank. For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:IE
State or Province Name (full name) []:Co. Dublin
Locality Name (eg, city) []:Dublin
Organization Name (eg, company) []:Progress
Organizational Unit Name (eg, section) []:Finance
Common Name (eg, YOUR name) []:Gordon Brown
Email Address []:gbrown@progress.com
[Note]Note

The security of the CA depends on the security of the private key file and the private key pass phrase used in this step.

You must ensure that the file names and location of the CA certificate and private key, new_ca.pem and new_ca_pk.pem, are the same as the values specified in openssl.cnf (see the preceding step).

You are now ready to sign certificates with your CA.

PK HA}qOEBPS/i305897.html Target-Only Authentication

Target-Only Authentication

Overview

When an application is configured for target-only authentication, the target authenticates itself to the client but the client is not authentic to the target object, as shown in Figure 3.1.

Figure 3.1. Target Authentication Only

authentication pattern for target authentication only

Security handshake

Prior to running the application, the client and server should be set up as follows:

During the security handshake, the server sends its certificate chain to the client (see Figure 3.1). The client then searches its trusted CA lists to find a CA certificate that matches one of the CA certificates in the server’s certificate chain.

HTTPS example

On the client side, there are no policy settings required for target-only authentication. Simply configure your client without associating an X.509 certificate with the HTTPS port. You must provide the client with a list of trusted CA certificates, however (see Specifying Trusted CA Certificates).

On the server side, in the server’s XML configuration file, make sure that the sec:clientAuthentication element does not require client authentication. This element can be omitted, in which case the default policy is to not require client authentication. However, if the sec:clientAuthentication element is present, it should be configured as follows:

<http:destination id="{Namespace}PortName.http-destination"> 
  <http:tlsServerParameters>
    ...
 
  <sec:clientAuthentication want="false" required="false"/>
  </http:tlsServerParameters>
</http:destination>

Where the want attribute is set to false (the default), specifying that the server does not request an X.509 certificate from the client during a TLS handshake. The required attribute is also set to false (the default), specifying that the absence of a client certificate does not trigger an exception during the TLS handshake.

[Note]Note

The want attribute can be set either to true or to false. If set to true, the want setting causes the server to request a client certificate during the TLS handshake, but no exception is raised for clients lacking a certificate, so long as the required attribute is set to false.

It is also necessary to associate an X.509 certificate with the server’s HTTPS port (see Specifying an Application’s Own Certificate ) and to provide the server with a list of trusted CA certificates (see Specifying Trusted CA Certificates ).

[Note]Note

The choice of cipher suite can potentially affect whether or not target-only authentication is supported (see Configuring HTTPS Cipher Suites).

PK HA#ѼOEBPS/i305901.html Mutual Authentication

Mutual Authentication

Overview

When an application is configured for mutual authentication, the target authenticates itself to the client and the client authenticates itself to the target. This scenario is illustrated in Figure 3.2 . In this case, the server and the client each require an X.509 certificate for the security handshake.

Figure 3.2. Mutual Authentication

both client and server authenticate with the other party

Security handshake

Prior to running the application, the client and server must be set up as follows:

During the TLS handshake, the server sends its certificate chain to the client, and the client sends its certificate chain to the server—see Figure 3.1 .

HTTPS example

On the client side, there are no policy settings required for mutual authentication. Simply associate an X.509 certificate with the client’s HTTPS port (see Specifying an Application’s Own Certificate). You also need to provide the client with a list of trusted CA certificates (see Specifying Trusted CA Certificates).

On the server side, in the server’s XML configuration file, make sure that the sec:clientAuthentication element is configured to require client authentication. For example:

<http:destination id="{Namespace}PortName.http-destination"> 
  <http:tlsServerParameters>
    ... 
    <sec:clientAuthentication want="true" required="true"/>
  </http:tlsServerParameters>
</http:destination>

Where the want attribute is set to true, specifying that the server requests an X.509 certificate from the client during a TLS handshake. The required attribute is also set to true, specifying that the absence of a client certificate triggers an exception during the TLS handshake.

It is also necessary to associate an X.509 certificate with the server’s HTTPS port (see Specifying an Application’s Own Certificate) and to provide the server with a list of trusted CA certificates (see Specifying Trusted CA Certificates).

[Note]Note

The choice of cipher suite can potentially affect whether or not mutual authentication is supported (see Configuring HTTPS Cipher Suites).

PK HA7(BOEBPS/i343418.html Supported Cipher Suites

Supported Cipher Suites

Overview

A cipher suite is a collection of security algorithms that determine precisely how an SSL/TLS connection is implemented.

For example, the SSL/TLS protocol mandates that messages be signed using a message digest algorithm. The choice of digest algorithm, however, is determined by the particular cipher suite being used for the connection. Typically, an application can choose either the MD5 or the SHA digest algorithm.

The cipher suites available for SSL/TLS security in Fuse Services Framework depend on the particular JSSE provider that is specified on the endpoint.

JCE/JSSE and security providers

The Java Cryptography Extension (JCE) and the Java Secure Socket Extension (JSSE) constitute a pluggable framework that allows you to replace the Java security implementation with arbitrary third-party toolkits, known as security providers.

SunJSSE provider

In practice, the security features of Fuse Services Framework have been tested only with SUN’s JSSE provider, which is named SunJSSE.

Hence, the SSL/TLS implementation and the list of available cipher suites in Fuse Services Framework are effectively determined by what is available from SUN’s JSSE provider.

Cipher suites supported by SunJSSE

The following cipher suites are supported by SUN’s JSSE provider in the J2SE 1.5.0 Java development kit (see also Appendix A of SUN’s JSSE Reference Guide):

  • Standard ciphers:

    SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA
TLS_DHE_DSS_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
TLS_KRB5_EXPORT_WITH_RC4_40_MD5
TLS_KRB5_EXPORT_WITH_RC4_40_SHA
TLS_KRB5_WITH_3DES_EDE_CBC_MD5
TLS_KRB5_WITH_3DES_EDE_CBC_SHA
TLS_KRB5_WITH_DES_CBC_MD5
TLS_KRB5_WITH_DES_CBC_SHA
TLS_KRB5_WITH_RC4_128_MD5
TLS_KRB5_WITH_RC4_128_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA

  • Null encryption, integrity-only ciphers:

    SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA

  • Anonymous Diffie-Hellman ciphers (no authentication):

    SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_WITH_DES_CBC_SHA
SSL_DH_anon_WITH_RC4_128_MD5
TLS_DH_anon_WITH_AES_128_CBC_SHA
TLS_DH_anon_WITH_AES_256_CBC_SHA

JSSE reference guide

For more information about SUN’s JSSE framework, please consult the JSSE Reference Guide at the following location:

http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html

PK HA7j#j#OEBPS/i343422.html Cipher Suite Filters

Cipher Suite Filters

Overview

In a typical application, you usually want to restrict the list of available cipher suites to a subset of the ciphers supported by the JSSE provider.

Namespaces

Table 4.1 shows the XML namespaces that are referenced in this section:

Table 4.1. Namespaces Used for Configuring Cipher Suite Filters

PrefixNamespace URI
httphttp://cxf.apache.org/transports/http/configuration
httpjhttp://cxf.apache.org/transports/http-jetty/configuration
sechttp://cxf.apache.org/configuration/security

sec:cipherSuitesFilter element

You define a cipher suite filter using the sec:cipherSuitesFilter element, which can be a child of either a http:tlsClientParameters element or a httpj:tlsServerParameters element. A typical sec:cipherSuitesFilter element has the outline structure shown in Example 4.1 .

Example 4.1. Structure of a sec:cipherSuitesFilter Element

<sec:cipherSuitesFilter>
    <sec:include>RegularExpression</sec:include>
    <sec:include>RegularExpression</sec:include>
    ...
    <sec:exclude>RegularExpression</sec:exclude>
    <sec:exclude>RegularExpression</sec:exclude>
    ...
</sec:cipherSuitesFilter>

Semantics

The following semantic rules apply to the sec:cipherSuitesFilter element:

  1. If a sec:cipherSuitesFilter element does not appear in an endpoint’s configuration (that is, it is absent from the relevant http:conduit or httpj:engine-factory element), the following default filter is used:

    <sec:cipherSuitesFilter>
    <sec:include>.*_EXPORT_.*</sec:include>
    <sec:include>.*_EXPORT1024.*</sec:include>
    <sec:include>.*_DES_.*</sec:include>
    <sec:include>.*_WITH_NULL_.*</sec:include>
</sec:cipherSuitesFilter>

  2. If the sec:cipherSuitesFilter element does appear in an endpoint’s configuration, all cipher suites are excluded by default.

  3. To include cipher suites, add a sec:include child element to the sec:cipherSuitesFilter element. The content of the sec:include element is a regular expression that matches one or more cipher suite names (for example, see the cipher suite names in Cipher suites supported by SunJSSE).

  4. To refine the selected set of cipher suites further, you can add a sec:exclude element to the sec:cipherSuitesFilter element. The content of the sec:exclude element is a regular expression that matches zero or more cipher suite names from the currently included set.

    [Note]Note

    Sometimes it makes sense to explicitly exclude cipher suites that are currently not included, in order to future-proof against accidental inclusion of undesired cipher suites.

Regular expression matching

The grammar for the regular expressions that appear in the sec:include and sec:exclude elements is defined by the Java regular expression utility, java.util.regex.Pattern. For a detailed description of the grammar, please consult the Java reference guide, http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html.

Client conduit example

The following XML configuration shows an example of a client that applies a cipher suite filter to the remote endpoint, {WSDLPortNamespace}PortName. Whenever the client attempts to open an SSL/TLS connection to this endpoint, it restricts the available cipher suites to the set selected by the sec:cipherSuitesFilter element.

<beans ... >
  <http:conduit name="{WSDLPortNamespace}PortName.http-conduit">
    <http:tlsClientParameters>
      ...
      <sec:cipherSuitesFilter>
        <sec:include>.*_WITH_3DES_.*</sec:include>
        <sec:include>.*_WITH_DES_.*</sec:include>
        <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
        <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
    </http:tlsClientParameters>
  </http:conduit>

  <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl"/>
</beans>
PK HAT7??OEBPS/i343948.html SSL/TLS Protocol Version

SSL/TLS Protocol Version

Overview

The versions of the SSL/TLS protocol that are supported by Fuse Services Framework depend on the particular JSSE provider configured. By default, the JSSE provider is configured to be SUN’s JSSE provider implementation.

SSL/TLS protocol versions supported by SunJSSE

Table 4.2 shows the SSL/TLS protocol versions supported by SUN’s JSSE provider.

Table 4.2. SSL/TLS Protocols Supported by SUN’s JSSE Provider

ProtocolDescription
SSLSupports some version of SSL; may support other versions

SSLv2

Supports SSL version 2 or higher

SSLv3

Supports SSL version 3; may support other versions

TLS

Supports some version of TLS; may support other versions

TLSv1

Supports TLS version 1; may support other versions

Specifying the SSL/TLS protocol version

You can specify the preferred SSL/TLS protocol version as an attribute on the http:tlsClientParameters element (client side) or on the httpj:tlsServerParameters element (server side).

Client side SSL/TLS protocol version

You can specify the protocol to be TLS on the client side by setting the secureSocketProtocol attribute as follows:

<?xml version="1.0" encoding="UTF-8"?>
<beans ... >
  ...
  <http:conduit name="{Namespace}PortName.http-conduit">
    ...
    <http:tlsClientParameters secureSocketProtocol="TLS">
    ...
    </http:tlsClientParameters>
  </http:conduit>
  ...
</beans>

Server side SSL/TLS protocol version

You can specify the protocol to be TLS on the server side by setting the secureSocketProtocol attribute as follows:

<?xml version="1.0" encoding="UTF-8"?>
<beans ... >
  ...
  <httpj:engine-factory bus="cxf">
    <httpj:engine port="9001">
      ...
      <httpj:tlsServerParameters secureSocketProtocol="TLS">
        ...
      </httpj:tlsClientParameters>
    </httpj:engine>
  </httpj:engine-factory>
  ...
</beans>
PK HA#OEBPS/i359656.html Specifying Trusted CA Certificates

Specifying Trusted CA Certificates

When to Deploy Trusted CA Certificates
Specifying Trusted CA Certificates for HTTPS
PK HAG9##OEBPS/i372104.html Deploying Own Certificate for HTTPS

Deploying Own Certificate for HTTPS

Overview

When working with the HTTPS transport the application's certificate is deployed using the XML configuration file.

Procedure

To deploy an application’s own certificate for the HTTPS transport, perform the following steps:

  1. Obtain an application certificate in Java keystore format, CertName.jks. For instructions on how to create a certificate in Java keystore format, see Use the CA to Create Signed Certificates in a Java Keystore.

    [Note]Note

    Some HTTPS clients (for example, Web browsers) perform a URL integrity check, which requires a certificate’s identity to match the hostname on which the server is deployed. See Special Requirements on HTTPS Certificates for details.

  2. Copy the certificate’s keystore, CertName.jks, to the certificates directory on the deployment host; for example, X509Deploy/certs.

    The certificates directory should be a secure directory that is writable only by administrators and other privileged users.

  3. Edit the relevant XML configuration file to specify the location of the certificate keystore, CertName.jks. You must include the sec:keyManagers element in the configuration of the relevant HTTPS ports.

    For example, you can configure a client port as follows:

    <http:conduit id="{Namespace}PortName.http-conduit"> 
  <http:tlsClientParameters>
    ...
    <sec:keyManagers keyPassword="CertPassword">
      <sec:keyStore type="JKS"
                    password="KeystorePassword"
                    file="certs/CertName.jks"/>
    </sec:keyManagers>
    ...
  </http:tlsClientParameters>
</http:conduit>

    Where the keyPassword attribute specifies the password needed to decrypt the certificate’s private key (that is, CertPassword), the type attribute specifes that the truststore uses the JKS keystore implementation, and the password attribute specifies the password required to access the CertName.jks keystore (that is, KeystorePassword).

    Configure a server port as follows:

    <http:destination id="{Namespace}PortName.http-destination"> 
  <http:tlsServerParameters>
    ...
    <sec:keyManagers keyPassword="CertPassword">
      <sec:keyStore type="JKS"
                    password="KeystorePassword"
                    file="certs/CertName.jks"/>
    </sec:keyManagers>
    ...
  </http:tlsServerParameters>
</http:destination>
    [Warning]Warning

    The directory containing the application certificates (for example, X509Deploy/certs/) should be a secure directory (that is, readable and writable only by the administrator).

    [Warning]Warning

    The directory containing the XML configuration file should be a secure directory (that is, readable and writable only by the administrator), because the configuration file contains passwords in plain text.

PK HAyiOEBPS/i379776.html Specifying Trusted CA Certificates for HTTPS

Specifying Trusted CA Certificates for HTTPS

CA certificate format

CA certificates must be provided in Java keystore format.

CA certificate deployment in the Fuse Services Framework configuration file

To deploy one or more trusted root CAs for the HTTPS transport, perform the following steps:

  1. Assemble the collection of trusted CA certificates that you want to deploy. The trusted CA certificates can be obtained from public CAs or private CAs (for details of how to generate your own CA certificates, see Set Up Your Own CA). The trusted CA certificates can be in any format that is compatible with the Java keystore utility; for example, PEM format. All you need are the certificates themselves—the private keys and passwords are not required.

  2. Given a CA certificate, cacert.pem, in PEM format, you can add the certificate to a JKS truststore (or create a new truststore) by entering the following command:

    keytool -import -file cacert.pem -alias CAAlias -keystore truststore.jks -storepass StorePass

    Where CAAlias is a convenient tag that enables you to access this particular CA certificate using the keytool utility. The file, truststore.jks, is a keystore file containing CA certificates—if this file does not already exist, the keytool utility creates one. The StorePass password provides access to the keystore file, truststore.jks.

  3. Repeat step 2 as necessary, to add all of the CA certificates to the truststore file, truststore.jks.

  4. Edit the relevant XML configuration files to specify the location of the truststore file. You must include the sec:trustManagers element in the configuration of the relevant HTTPS ports.

    For example, you can configure a client port as follows:

    <!-- Client port configuration -->
<http:conduit id="{Namespace}PortName.http-conduit"> 
  <http:tlsClientParameters>
    ...
    <sec:trustManagers>
      <sec:keyStore type="JKS"
                    password="StorePass"
                    file="certs/truststore.jks"/>
    </sec:trustManagers>
    ...
  </http:tlsClientParameters>
</http:conduit>

    Where the type attribute specifes that the truststore uses the JKS keystore implementation and StorePass is the password needed to access the truststore.jks keystore.

    Configure a server port as follows:

    <!-- Server port configuration -->
<http:destination id="{Namespace}PortName.http-destination"> 
  <http:tlsServerParameters>
    ...
    <sec:trustManagers>
      <sec:keyStore type="JKS"
                    password="StorePass"
                    file="certs/truststore.jks"/>
    </sec:trustManagers>
    ...
  </http:tlsServerParameters>
</http:destination>
    [Warning]Warning

    The directory containing the truststores (for example, X509Deploy/truststores/) should be a secure directory (that is, writable only by the administrator).

PK HAyM M OEBPS/i382183.html Special Requirements on HTTPS Certificates

Special Requirements on HTTPS Certificates

Overview

The HTTPS specification mandates that HTTPS clients must be capable of verifying the identity of the server. This can potentially affect how you generate your X.509 certificates. The mechanism for verifying the server identity depends on the type of client. Some clients might verify the server identity by accepting only those server certificates signed by a particular trusted CA. In addition, clients can inspect the contents of a server certificate and accept only the certificates that satisfy specific constraints.

In the absence of an application-specific mechanism, the HTTPS specification defines a generic mechanism, known as the HTTPS URL integrity check, for verifying the server identity. This is the standard mechanism used by Web browsers.

HTTPS URL integrity check

The basic idea of the URL integrity check is that the server certificate’s identity must match the server host name. This integrity check has an important impact on how you generate X.509 certificates for HTTPS: the certificate identity (usually the certificate subject DN’s common name) must match the host name on which the HTTPS server is deployed.

The URL integrity check is designed to prevent man-in-the-middle attacks.

Reference

The HTTPS URL integrity check is specified by RFC 2818, published by the Internet Engineering Task Force (IETF) at http://www.ietf.org/rfc/rfc2818.txt.

How to specify the certificate identity

The certificate identity used in the URL integrity check can be specified in one of the following ways:

Using commonName

The usual way to specify the certificate identity (for the purpose of the URL integrity check) is through the Common Name (CN) in the subject DN of the certificate.

For example, if a server supports secure TLS connections at the following URL:

https://www.progress.com/secure

The corresponding server certificate would have the following subject DN:

C=IE,ST=Co. Dublin,L=Dublin,O=Progress,
OU=System,CN=www.progress.com

Where the CN has been set to the host name, www.progress.com.

For details of how to set the subject DN in a new certificate, see Use the CA to Create Signed Certificates in a Java Keystore.

Using subjectAltName (multi-homed hosts)

Using the subject DN’s Common Name for the certificate identity has the disadvantage that only one host name can be specified at a time. If you deploy a certificate on a multi-homed host, however, you might find it is practical to allow the certificate to be used with any of the multi-homed host names. In this case, it is necessary to define a certificate with multiple, alternative identities, and this is only possible using the subjectAltName certificate extension.

For example, if you have a multi-homed host that supports connections to either of the following host names:

www.progress.com
fusesource.com

Then you can define a subjectAltName that explicitly lists both of these DNS host names. If you generate your certificates using the openssl utility, edit the relevant line of your openssl.cnf configuration file to specify the value of the subjectAltName extension, as follows:

subjectAltName=DNS:www.progress.com,DNS:fusesource.com

Where the HTTPS protocol matches the server host name against either of the DNS host names listed in the subjectAltName (the subjectAltName takes precedence over the Common Name).

The HTTPS protocol also supports the wildcard character, *, in host names. For example, you can define the subjectAltName as follows:

subjectAltName=DNS:*.progress.com

This certificate identity matches any three-component host name in the domain progress.com. For example, the wildcarded host name matches either www.progress.com or progress.com, but does not match www.fusesource.com.

[Warning]Warning

You must never use the wildcard character in the domain name (and you must take care never to do this accidentally by forgetting to type the dot, ., delimiter in front of the domain name). For example, if you specified *progress.com, your certificate could be used on any domain that ends in the letters progress.

For details of how to set up the openssl.cnf configuration file to generate certificates with the subjectAltName certificate extension, see Use the CA to Create Signed PKCS#12 Certificates .

PK HAAļ**OEBPS/i382664.html Use the CA to Create Signed Certificates in a Java Keystore

Use the CA to Create Signed Certificates in a Java Keystore

Substeps to perform

To create and sign a certificate in a Java keystore (JKS), CertName.jks, perform the following substeps:

  1. Add the Java bin directory to your PATH

  2. Generate a certificate and private key pair

  3. Create a certificate signing request

  4. Sign the CSR

  5. Convert to PEM format

  6. Concatenate the files

  7. Update keystore with the full certificate chain

  8. Repeat steps as required

Add the Java bin directory to your PATH

If you have not already done so, add the Java bin directory to your path:

Windows 

> set PATH=JAVA_HOME\bin;%PATH%

UNIX 

% PATH=JAVA_HOME/bin:$PATH; export PATH

This step makes the keytool utility available from the command line.

Generate a certificate and private key pair

Open a command prompt and change directory to the directory where you store your keystore files, KeystoreDir. Enter the following command:

keytool -genkey -dname "CN=Alice, OU=Engineering, O=Progress, ST=Co. Dublin, C=IE" -validity 365 -alias CertAlias -keypass CertPassword -keystore CertName.jks -storepass CertPassword

This keytool command, invoked with the -genkey option, generates an X.509 certificate and a matching private key. The certificate and the key are both placed in a key entry in a newly created keystore, CertName.jks. Because the specified keystore, CertName.jks, did not exist prior to issuing the command, keytool implicitly creates a new keystore.

The -dname and -validity flags define the contents of the newly created X.509 certificate, specifying the subject DN and the days before expiration respectively. For more details about DN format, see Appendix A.

Some parts of the subject DN must match the values in the CA certificate (specified in the CA Policy section of the openssl.cnf file). The default openssl.cnf file requires the following entries to match:

  • Country Name (C)

  • State or Province Name (ST)

  • Organization Name (O)

[Note]Note

If you do not observe the constraints, the OpenSSL CA will refuse to sign the certificate (see Sign the CSR ).

Create a certificate signing request

Create a new certificate signing request (CSR) for the CertName.jks certificate, as follows:

keytool -certreq -alias CertAlias -file CertName_csr.pem -keypass CertPassword -keystore CertName.jks -storepass CertPassword

This command exports a CSR to the file, CertName_csr.pem.

Sign the CSR

Sign the CSR using your CA, as follows:

openssl ca -config X509CA/openssl.cnf -days 365 -in CertName_csr.pem -out CertName.pem

To sign the certificate successfully, you must enter the CA private key pass phrase (see Set Up Your Own CA).

[Note]Note

If you want to sign the CSR using a CA certificate other than the default CA, use the -cert and -keyfile options to specify the CA certificate and its private key file, respectively.

Convert to PEM format

Convert the signed certificate, CertName.pem, to PEM only format, as follows:

openssl x509 -in CertName.pem -out CertName.pem -outform PEM

Concatenate the files

Concatenate the CA certificate file and CertName.pem certificate file, as follows:

Windows 

copy CertName.pem + X509CA\ca\new_ca.pem CertName.chain

UNIX

cat CertName.pem X509CA/ca/new_ca.pem > CertName.chain

Update keystore with the full certificate chain

Update the keystore, CertName.jks, by importing the full certificate chain for the certificate, as follows:

keytool -import -file CertName.chain -keypass CertPassword -keystore CertName.jks -storepass CertPassword

Repeat steps as required

Repeat steps 2 through 7, to create a complete set of certificates for your system.

PK HAqAqAOEBPS/i382674.html Use the CA to Create Signed PKCS#12 Certificates

Use the CA to Create Signed PKCS#12 Certificates

Substeps to perform

If you have set up a private CA, as described in Set Up Your Own CA , you are now ready to create and sign your own certificates.

To create and sign a certificate in PKCS#12 format, CertName.p12, perform the following substeps:

  1. Add the bin directory to your PATH .

  2. Configure the subjectAltName extension (Optional) .

  3. Create a certificate signing request .

  4. Sign the CSR .

  5. Concatenate the files .

  6. Create a PKCS#12 file .

  7. Repeat steps as required .

  8. (Optional) Clear the subjectAltName extension .

Add the bin directory to your PATH

If you have not already done so, add the OpenSSL bin directory to your path, as follows:

Windows 

> set PATH=OpenSSLDir\bin;%PATH%

UNIX

% PATH=OpenSSLDir/bin:$PATH; export PATH

This step makes the openssl utility available from the command line.

Configure the subjectAltName extension (Optional)

Perform this step, if the certificate is intended for a HTTPS server whose clients enforce URL integrity check, and if you plan to deploy the server on a multi-homed host or a host with several DNS name aliases (for example, if you are deploying the certificate on a multi-homed Web server). In this case, the certificate identity must match multiple host names and this can be done only by adding a subjectAltName certificate extension (see Special Requirements on HTTPS Certificates).

To configure the subjectAltName extension, edit your CA’s openssl.cnf file as follows:

  1. Add the following req_extensions setting to the [req] section (if not already present in your openssl.cnf file):

    # openssl Configuration File
...
[req]
req_extensions=v3_req

  2. Add the [v3_req] section header (if not already present in your openssl.cnf file). Under the [v3_req] section, add or modify the subjectAltName setting, setting it to the list of your DNS host names. For example, if the server host supports the alternative DNS names, www.progress.com and fusesource.com, set the subjectAltName as follows:

    # openssl Configuration File
...
[v3_req]
subjectAltName=DNS:www.progress.com,DNS:fusesource.com

  3. Add a copy_extensions setting to the appropriate CA configuration section. The CA configuration section used for signing certificates is one of the following:

    • The section specified by the -name option of the openssl ca command,

    • The section specified by the default_ca setting under the [ca] section (usually [CA_default]).

    For example, if the appropriate CA configuration section is [CA_default], set the copy_extensions property as follows:

    # openssl Configuration File
...
[CA_default]
copy_extensions=copy

    This setting ensures that certificate extensions present in the certificate signing request are copied into the signed certificate.

Create a certificate signing request

Create a new certificate signing request (CSR) for the CertName.p12 certificate, as shown:

openssl req -new -config X509CA/openssl.cnf -days 365 -out X509CA/certs/CertName_csr.pem -keyout X509CA/certs/CertName_pk.pem

This command prompts you for a pass phrase for the certificate’s private key, and for information about the certificate’s distinguished name.

Some of the entries in the CSR distinguished name must match the values in the CA certificate (specified in the CA Policy section of the openssl.cnf file). The default openssl.cnf file requires that the following entries match:

The certificate subject DN’s Common Name is the field that is usually used to represent the certificate owner’s identity. The Common Name must comply with the following conditions:

[Note]Note

For the purpose of the HTTPS URL integrity check, the subjectAltName extension takes precedence over the Common Name.

Using configuration from X509CA/openssl.cnf
Generating a 512 bit RSA private key
.+++++
.+++++
writing new private key to
      'X509CA/certs/CertName_pk.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished
Name or a DN. There are quite a few fields but you can leave
some blank. For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:IE
State or Province Name (full name) []:Co. Dublin
Locality Name (eg, city) []:Dublin
Organization Name (eg, company) []:Progress
Organizational Unit Name (eg, section) []:Systems
Common Name (eg, YOUR name) []:Artix
Email Address []:info@progress.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:password
An optional company name []:Progress

Sign the CSR

Sign the CSR using your CA, as follows:

openssl ca -config X509CA/openssl.cnf -days 365 -in X509CA/certs/CertName_csr.pem -out X509CA/certs/CertName.pem

This command requires the pass phrase for the private key associated with the new_ca.pem CA certificate. For example:

Using configuration from X509CA/openssl.cnf
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName :PRINTABLE:'IE'
stateOrProvinceName :PRINTABLE:'Co. Dublin'
localityName :PRINTABLE:'Dublin'
organizationName :PRINTABLE:'Progress'
organizationalUnitName:PRINTABLE:'Systems'
commonName :PRINTABLE:'Bank Server Certificate'
emailAddress :IA5STRING:'info@progress.com'
Certificate is to be certified until May 24 13:06:57 2000 GMT (365 days)
Sign the certificate? [y/n]:y
1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

To sign the certificate successfully, you must enter the CA private key pass phrase (see Set Up Your Own CA).

[Note]Note

If you did not set copy_extensions=copy under the [CA_default] section in the openssl.cnf file, the signed certificate will not include any of the certificate extensions that were in the original CSR.

Concatenate the files

Concatenate the CA certificate file, CertName.pem certificate file, and CertName_pk.pem private key file as follows:

Windows 

copy X509CA\ca\new_ca.pem + X509CA\certs\CertName.pem + X509CA\certs\CertName_pk.pem X509CA\certs\CertName_list.pem

UNIX

cat X509CA/ca/new_ca.pem X509CA/certs/CertName.pem X509CA/certs/CertName_pk.pem > X509CA/certs/CertName_list.pem

Create a PKCS#12 file

Create a PKCS#12 file from the CertName_list.pem file as follows:

openssl pkcs12 -export -in X509CA/certs/CertName_list.pem -out X509CA/certs/CertName.p12 -name "New cert"

You are prompted to enter a password to encrypt the PKCS#12 certificate. Usually this password is the same as the CSR password (this is required by many certificate repositories).

Repeat steps as required

Repeat steps 3 through 6, to create a complete set of certificates for your system.

(Optional) Clear the subjectAltName extension

After generating certificates for a particular host machine, it is advisable to clear the subjectAltName setting in the openssl.cnf file to avoid accidentally assigning the wrong DNS names to another set of certificates.

In the openssl.cnf file, comment out the subjectAltName setting (by adding a # character at the start of the line), and also comment out the copy_extensions setting.

PK HA驥DDOEBPS/images/_config_auth1.gifGIF89aOߟwߟߟOϿw߿wwOwwwwwwwOwwwOOwwOOOOOOwOwO7>FMUl"Dfƪ3"J1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu! ,OH*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJիXjʵׯ`ÊKٳhӪ]˶۷pʝKݻx˷߿ LÈ+^̸ǐ#KL˘3k̹ϠCMӨS^ͺװc˞M۸sͻ Nȓ+_μ9h$XA .dC%NXE5nG!E$YI)UdK1eΤYM9uOA%ZQI.eSQNZUYnWaŎ%[Yi>$[qΥ[]y/ߵ{[aĉ/;% ^!G\dY1g.3UϟEG=jiQ^ka={bmBq 7ݿxq䴓+_~9ϥ>fحԎ3\QPh^'P` z]oW9}&ak+r#@ˏ$yA&l?DX` 4h# 7d,B k1!_(F# o\ "`ȳh##SKH,ID HDCT? d&'E Kð<@\Dƣ D2NL T ݊oB$hM|-г-"%P)?oJ#19+u΄uKBM9VF]m օApYuK_S _ R +JFIf}@_C ՙN\rB# g=P(ԱHu W yqZ-x ;xSݴRPGDVuqЊa8EpiEM:r=y =--ud^G,Z a%^}mu.,fg 弙JidY, [M{lc޸ uϬ k-&H.X{Y%(p֚X5nuD\qn ;H*\ȰÇI@Hŋ3j(qG>9% :  ) Q` 19ɂ+[&1)TH}:m2AEe~@ V^J @H_aǶpʝ{ݷq˷B~ L0a/Iyn˯FbalWA 2nՑj z`⧥EM,̐e\6} ihy݇POf6WpBJD"gO"UY (Z?ΩZVi( hydUn h)[d)ꙜfZ Ehp: x{B^VxULHZ%H )V+ m6珿ԫYmm]zj~ꑫy龛N.jPbkcծ <\Ee?˕*BgߎDkk*2Yֻ2ʲ/\kf,ܡEXKO2·ND-[ c%HYFhk-5%0pRˈl )ؗ߱4rYט&-wĮ ֘jkc)ޙKb8j IܑPxQ7> >f<MrXSNX݂^`8kߤn] /cKv" e8>@.?8#;po'9WGYM6֮r3y`Jye8@jwF3bǂapF< !r'uJzyUB:a$?*8G^C+."?{(1Aak8#:|⅖D)1QyR4aDÄ@oMܢuh1RqKxQ x21Z!:ЍlL$D:9/T ͨlj4kL$!%ٿ. #%79E=#(ґxSTcWbҖ\eoi%R&*wHK 3O 2 X *9 \xϋm _%r2qJ5Qj蜋bmD JcR})3t 4xaB 6t" )V8.f8P$Q!"IU $fL3cygN;yS'K>  F" u @hBFFfVOvikNH Q@`ȑ@M|%\Xj {o^{[1 wT֭{S&X`ёj9mWv)6}ujb\K2S֌*^,hy0` VdEȔFl;u|xv<х,!e5t:^?h;r뮦+:θ ζ@!m&TE0M3)P8h)P1#Ed6C31t\An$@#|N!E&#L,%3) dS 7kOΆ3W32S4LIT=fm%@#C PG 4OHo-T9rQ-;QKC4˦dё4┢QTSܾj.@̲ td+EOG< qw|V\ՖHOk[neコuG eղvUx{#S`J}3V1 Ra %+65êSBATXz!S$@Wt6`Yג E<1c>+f%c_Ź>f 54X7R0f/}ꫧ-R*ځ>VWX0nt.jdmoԚ/~JR`x=HjI%.!;sxQq5|!CvWm .E%tlg_D7M_襟ꭿ짇j{a;w\1`}tZp{.g}&jK]5 r+ٻ6i T@> ".,>RK;d|:k9ɯ'ۋa ,VF~}\7;P~xqHxAW$a!qtb"]Bʎm@̉ xQ9{d.-|KwuB-mB B)#BQ:3" +1~p d׈qO Ar9剗aLHE~e#e6RM46GIr+! EySbzQR=샔d]+1MrҖ2E!gT4Et0G&giZ"̜҇Źp g9I&fJ,Ɠe YOFQ? )PLF φ$th29PUIt.ԓ}HYEo~%JR!ƞ$)9'Q;!uN-2 4xaB 6t" )VxcD$8v1@ H4ydH+YtfL3'JygN6W8eP:hR[")SVzS[j!Ш( lZh+u(vPsֵK]L{f^ 6(+.iC2P+-mp9] b:ƮN̑Gp(,!$S1!,ɘJr-$˞L2\s3aNHa^ana"a&b*!H2H#Ոc2#_:$H7Id.8J.ѐL> "ReF9ie?N鐖^_rI&YbfjVBk)Rp2f[͹xi'B{©AIhSbZg&hN:T:Bji vঢ*P~fS *떛֪$.k*Z(@$XA .dC*XE5nG$@$YɌUdK1eΤY&C9uO?o%ZePIGTiGQNZթO.+IaŶZV'Siue[q 5ݧr7_P&\၁U$b7eإČ;#S9sN˚;{ :ѤK>:լ[~ ;ٴk۾;ݼ{ <?|s393ԥWn~rǓ?0Ç}|\(}8\V| g7WXo>&׹.U\zu'nLrgzO{q[,)ި|m;W@mπC`xI:J#耧}_S hzT|)oygSYM,dib-Xü,ІIJyp+ڞ&. o#$#Օ0CyET`Epa=Ũה ad =fV$l4}1^\XL8!=D| F6< 9F44#GII^2U4\4NђFIHrD*QJV쓯sJYgS,uЖ_9̽Ҙl`1o,h „ 2l!Ĉ'Rh7r#ȅ$F i$ʔIfTÖ0gҬi&Μ/eF@=I(҈<2m)ԍKR*լPjE:+ذb%k6гjo]k۸rzkgۻz=rkKLpż7˘ǒ'ǍL2Fǘ1kެвТ=XiʝScd5^؋Yuڶw6߈W-8rƓW%ΜsϧS.7:F`B Hl=@$<!KT^$TWG_} : ]$E"v#<*VIx"Iz#D AxK3xUbA 9kz3 8(P'Q!Y@%]BM->P:@>$I1z5I5ݜ$Hvm~'Ap#gT%=Z!Y&z!p`, @,U9*y^R8'm# @j!O][T:d$$ੳ*%zUu`5VK뒨>8Ԋz%,9ݛ/B.zjJVcz+>"#2&n:LP^q*&;n52-21<3*UA8r4@k?r0=-< ;̐C@pDK41kA & !Fz *`"P f1Gt,:PÆ<1;+SJ.һ-)R==" iAnsJ mD5 'ȢqH9,J5-LF#tR h+B$Q@O(C 1 *{sPQ Ȕ+%>P$N==RJ4`5Xd/jضuf "ߒSBZIRNY$w* bMxKw^| ^0H}e``V ꦫxbZ.kzyl-SNms6yK_ntﾭ 6q#\s5rY Om|q|t'2p=`uv{tAwڛ.}vȔ}ۋVo(6bܓO2&دɡ]IOeؖBYHx&ns:'Ky=Y]OJ]#t^?P7~eQʁH#[v5!O" p ILp!ÆB(q"Ŋ/b̨q#ǎI(rdD G<8  :: aa H9'ϞC 1 %hdҁ&7,e*ugR] ЀR`֭Js$±fϢMv-۶źpMYn2! = ,܍+>D*DNIp`2b2Ūu/`6&YXòONz5kL[EڠI?N57Εa::cz{SR PΝ ߫\i{/~<iq\~D2j|3tH1cw^IWziE5a 2Rq} QסW]HP"I܃+آI!eC1-#@!c4Șc5A؇DT^}&t )4cXT|7:dRaMY]iF2ogpnGxH;%Q#[9}]SJtwSn8Iy'lN%D}emUvXB!Bgf[qZPqvjvZrPZ*D`Ar,vݟ) 𪒯j, 剫EFD! h䀎Z*Dj[um=oA '/D&VnXPڶeg[PBQ:* k*`/G':P$LjCզ)R,mh+{-.̆rBBPolP#YDƲWc-^abYm amR_x8KsfmYյD --udzl>Q-t#x\pay@C4~=!yyhld*M'^xC5l1~Mչ{mOu8kPέv|>]FNQ"[9m*A"eI"P,uDޒri"$6E0lDP{U0tO ]6IU4lk萹j),ɇ~"d57շJlt+bRiC^Χu։Dj6a^1#(9FqcSڪvmdg7^٥j3-MX׶ }l7\Vkn<]cLZx:ҢInS, W*,,Wk^7yn[;8`$ &TaC Q@$0f8È РD)IÕ-H0AI^VK?:hQG&UiSO>jU^eUkf*Bʒ706X#o5I0gL.5S#̺:paÇ'VXTƏ ;\|*2^|A*ļps窼kק] 5-ֽwo߿J>p╉ algX;r[L-7t &1p _M}{j\>|_}oO / -N Р̫#KI \8A}Dbc+ #ed. H <# +'ڐ%lI&M|(yˏJ /$ɳIiǁ.ˆKh$$$0u,rh4*ы odD)) 9ZB)唅=ыN2dK(!`iaa8jy%gE)pRhiiQ|V7Y'硈H{\#褔 4xaB  @#Nņ5&G#I4I*YtfL3iִygN;q,gʓ@IiP`SzkV[vlXM/-[uYj!m6Sr!\{p`NҰG#lxX`͛9w‘ג.2sToK*ذ}wnݻy[k{ னFMi[UxoөW.yѝfl%w˙'8ٷw~G9s@~㊳)H%tO?]4IH)T44R5TJF54V]=rDSiZ\ R^oTWvX1W_qMe`j_vXVݖOVGmܭ p "LpB$B(q"Ŋ/b̨q#ǎz0$ɒ&OLr%˖._Œ)$ș6o̩b͎#w *t(ѢF" 3)ӦNg.)ժVbͪhԭ^bq*زfϢMRj…)6.ݺvjtn޾~+x0u lxaČC,Y^Ǔ/{Uy3Ξ#ZƩ3iKNiWÖ:6ڶ6oy.|rO.q6pΟC7% V_8:t(~<ϣO~=Ï/>}?UX"zנOE8ZU!Rơ!#E'2%"+Ģ/ޤ"3Z$#7(9xЎ=yA8$G"$F*do8`A&TaC!F8bE1fԸ" A9dI'QTeK/aƔ9F5qԹgO?:hќ7&UiSOF:(RWfպkW_"lYgEm[oƕ{R\wջѺ}8NőFB^ "MbtFЌFuٴY̻Iz*vq1▭8KF.8DË~OЖ n/o+N?p ^]!AuheO~X !P^y8e Db(I-ӄAȐ(z8a(c I} #A: TVi,S qv`=asfaFg^n2t"i矀f6d`D}m'`[Y)Թ#cՇCC~j꩗m(i%jD(o&+mM#Zeꐪ&,YCa_KB[mA誧pRmrJIB LGRk8wkyZ}[л 7P 4]Mzkd\A3Z+/:|$ gʡ_fLJ7tIL$׮ƳL Z DtOvIEIPV i:Agt܊#sX >yېGnR&W/{Lj ') 旎`zWK!=R]{ף+i`7-;̳  H`B 6thp# 8"$D,X耣Dž)ZXR` $HT%! TIbCZԀ"2{#ƇK6ujTLNzkV[vlXcɖ5{vEk])tD ղm;ݢd,%\;-H&! Ve͛9wthѣI?Ȗ1s|-oM++\ό&NɔK7ߜytөW~{v۹w {xɗ7}zw~|׷}5O <L|%j - 5p 9EDs8t*֬ZrhUǒ-kXhײM;-ܳ_uxu.޼z nƸ˂lnÂ1Ȓ'S1FǙ1_ܙEϡA[4ԪWvJ花k]mܭ5ή7‡+ܗ*g|9q݅Snln;c9<걟oܾ` 7/>z|*G_Hҁ޷`~ nZ:h ]`m(!!ib8"1ʨvءX6އ3#%9i׍$M68")%o:RNj%PZeP`F-%i祑d^YYgd]㗧'&n ')ߡ%Jb}:hplN9(cR:Hnʨ:jiVYlbV*~>Eԙz_ʙ驼j)_*kĺt*Wnm&ta߬Sz-M8`$ &TaC$:ĉ-6ĘF =~|Q$H'DPeȒ/G|(fM7qԹgO?:"Q._"MJҒN?BʴJ+Sb5'խ_;lYgъzVjƶn>+[vӖ+qn^xq [UywvWױg׾ӫys侞}{C/-;L/~~t@˃i(:9P #t0B A Q,<@?,aQFJP-m1ǩ`|q 郬#L*lI#+$JKK(Ō,LS!q4Y|S9-2<K1TQ7GR UYmVTYi ,8 2lhB'Rh"ƌ7rcB Di$ʔ*Wl%̘2gN,Iț:wSbΏ6-j(ҤJZ4(ӨR)լZrAV-KvFfײm-\hҭsnFvY)Š3n"Ȓ'Sl2̚7s3ТG.MzdǪWnM4زgӮm6nͨ]7³n8ʗ.9:Kn:AR;kwo<ٖ_=ao>?VןD * :xRJ8aERx!bjGraH 8"C'_+bآ1X#@@0PB >QD-^ĘQF+"RH%MDRJ-]FRL5mĩ0fN=}TЗ;ET҃L>UTF^ŚU@[~V,Ϯc͞E[lZmݾWܴkśW^}W`… F2pbƍ?9bɕ-_ƜYLʛ=+΢I6Zdԫk&Zlڵ-6ܽ}^ݱGpn]t̩_|nvj1?{x^gq:ۿ1}| O~~0o@@SpAekA"B p ILp!ÆB(q"Ŋ/b̨q#ǎz )r$ɒ&OLr%˖.#|)s&͚6oT3'Ϟ> *t˝D"MtANB*uPTbͪUխ^ +gױf5H[صl+۹v U{Wlݽ~,x̼z Sx1Ǝ5|RŔ/cάysOɖ9 z4ҦO/֮_þ,9MѴoέiE}N۶Ə#O^U9ΟC_I<:֯};7k.<~>Ox??x݀&` w {  H`B 6tbD)VHDF/vdH 94yeJ+YtfL3!ygΉ73MC5ziRC.u&ϦPZkV[vzkXRŖ= lZkٶՊm\=en^{-o`6|qⱊ7[qdɓ)W|9+d̛9wthE6}ujOIvvlٳ}wnݻxpá&~y^ə7wѩW~t۹wXw8ɗ7|zD~|=?}g߿P,ALл|3H@*\ȰÇ#JHŋ3jȱcECIɓ(S\ɲˈ _ʜI͛8ɳϟ@ r'ѣH*]zӧPJ*(իXjhuׯ`ÊuٳhKM˶۷bK׭ܺx.߿ LaÃ+^21ǐ#KLʘ3k̹3˞CMiO^ͺ뽩_˞Moͻo ȓ7yrΣC|:WϮ;_}UƭWߝvS'N2 ;PK HAMH||OEBPS/images/_config_auth2.gifGIF89aLߟwߟߟOϿ߿w߿wwOwwwwwwOwwwOOwwOOOOOOwOwO7>FMUl"Dfƪ3"J1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu!,LH*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJիXjʵׯ`ÊKٳhӪ]˶۷pʝKݻx˷߿ LÈ+^̸ǐ#KL˘3k̹ϠCMH^z(8 ~0@ Ac>ͼ}7WX:UX0  睛r,@합_4޸uןAup^z 6GFV(GEҽwPw T{ '"$~Y],_!Rm^!IAo |hBBrD/&n)HAY mGXޔpGk # %bAЄ+@Y#k9'|T'"GxT߀ݗ-j>rڙ e@ Ayh(Azl?:T^Dێeۇ`#`p BpF)2dގힿ~)Ah[ 4xaB 6tbD)VxcF9vdH# 0A$D, Hl(@JXĩS OMr L! b K 5T JiО,;gKkٶun\sֵ{o^{ۦuigLg &*BjhIPLsEH22FBjAc-s|Yvvlٳi׶}u4iqJCN h6\ L np%gljOG{\`wɗ7}z󅙹t[{D~1?z$+ΡCLRӯA[ ې=E( >h>Fdi,ndH+;7bD0HI\&|(t(F/Rȗ,[l*V13ts GD0ܓ>@;:JM"N+8 G`*K)D4lQr=TU]Uv#ˁsIZ, sQ TECam5Z9fTVlv.R>TS>Ќ=A^Xs-Kn >W`A ;@{,i-Or7߂͸Xƪ,] Bb_-uemV4a  hz53D&0bi4ރ>M{!2hֺC`UkE).^"iV kigU >5_%-5ߜ=EM?U_]emuߝ}7 ,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gҬi&Μ:w'РB-j(ҤJ2m)ԨRRj*֬Zr+ذbǒ-k,ڴjײm-ܸrҭk.޼z/.l0Ċ3n1Ȓ'Sl2̚7s3ТG.m4ԪWn5زgӮm6^w07ݾ=x+_.sͣOw^uУ^;q0ɷs7N?G=>{O  4xaB 6tbD)VxcF9vdH# yeJ+YtYĿ3iִygN;yhgPChRK6ujHQVz5!R[vթaɖ5{mZkٶ=9m\sֵ{o^pp` K-|qbŋ7vrdɓ)W|sf͛9w4CI6}ujUvve׶}wn2u o5i7~{}=}]=&H*\ȰÇ#JHŋ3jȱǏ C$Aɓ&EN$˗0cʜI#5sɳϟ@ }ѣ'wʴӧPUތJիXjʮ2nKYSϪ]˶[]S+ݻx˷߿z +fwǐ# Ò3kfxϠCSj"ШS^ͺF&۸s뾋qlIN+i“KNu?gËgǫ_Ͼ{o/wuB E($$DЄ#@P!$URurԄEeP$h!B:J $;HF&dFx"A X I#CUj(P9 Pd. jBMNwX  b  Efhi^XRKmyi)FS3䡕HXz4-* Y6:b":zATj !kyXҰyEAa*$)'Y[l~zg=Q}ːz͒A$A0k>VgЄJݛ8yϝo֌4C N <XJP\!ރ ro2︂Cfki L]|aՎ p1!! #)"A2!gn)+RU GӐIR 052rH$9mG%OK٪@AQR5†+(+2$: RFb tNˊrĠLOCOTU],Yn:LFղ ձH zt94tSOco `GݵWBh- QrlcIOoV )8ݤL$3+_)L@~BZY T!Yb2?& uoœ(´XaRM>r6ƭܐ V]馝6ڧ钚ꪭ뒢Κ뮽-RY>Q&[ڷzQpg.I\ƹt?Qyx B! rBZ_KjX݀#&aFY"-ؑ1Xbg3p!cp48$)y|Gޘ#?:cO>dBF)Xʷ%Rz ^_Ee9ZeMaךi$xisnh'PjڢH 4xaB 6tbD)VxcF9&$AcH#I4y2Ǎ*Wˌ01Dy͋$hPCmiiRe."ԨMwRz4S2lXcɖ-Ykg:-ܴr9M9W]>Bp` %|AE:lxȒΜ1wtˡI# TԪOZjKvnݻ۴[س+~]*+q+wMѩ.A+ήG/yu3<$?/>3|?ҋ ,s *tܐC[Dĩ.¹Zѿ4`,19cL.kE"3Ҵ8ˑ&v .,BR<.{Q L,3)MRH _jN: Sܓ!PdsB$T4/S>FH%r=PLM [Z5I+=/S-R8=E4Q E VWݕ3yLW+9Ua7ՔF_]Iee+ؼfb@gv#, J |"\ A\U/kvXcŷFm(v%z7^ &]u7z`װbYcݬ^dHaoGM9d7f= p "Lp!ÆB(q"Ŋ/b̨q#C9 1B‡& `r`J 8*L&A'i̩G=}3ЋE-ݩtiIc*u*ժVb4HHI\4Thu}u.]N'˕^B\wpGHNx1ƎҤ jҫG+Cchf;&h6ikr,A _7؞ohM1ƏE1oDų:9֯c?"М-]& Agٷ'V`_] |}GVp[͗MEG5a J$B.H!br t{ѧ^nx-v&`HX(Y3}G{(X'gȟG6چQ8׆MIe]r=IUuإc@M,6ߜZI7q6l#fi)JM܀~%VgDiN mYvZ:4xڹ{c t耰҉Vqm/ z9t硷ժ:f@A5V{郢vQo; ~Yr)C+N,2-P 7-ؒ MWsleNd۪Vz(biY ^zrЁ)3M@;sJ%Aׁ+i7sk+X4lwuKimi gVR/w+8J-u=+mZ|txBJ:p.l+~>;i@^ۻpxvh^[3V;d5^8[bA2X“Է壟VJǹ@bjFʧ6#+,{ƫ>ݤ~SJջO}|H&h ^J)1^*GlRsXә4Y#jBpgi gB\>YF,@췛t2 `jgkap^)zbCC\cD61iE͆D>AE%(V3߸$Pzd¥F<2B$+)HZq;$'Fu2*(Rr L%+EVe'WI[^GD#clK $XA .dC%NXE5R$AbG!E$YrG;dK1OYM9uԸOA9QI&eS*iFZΎYnWaŎ%[YiծevUqm]y_&#z/flncȑ%O\9&b˙5o~gСE<駝Qf눥aϦmRum.vb/=Ǖ/W(sšOOuαo-=2& !^ x!P(p:wǧ/{P "ϼS4m>>##A  Ktp$Ĩ \ @ZE KzCDDqGLGtlCBh j<#KO2&G5p Pd3= <2M+L 89)KňqL J4&Ъt*08̈́6ı@;2 :Լ:*tU,d՞_TPMhM۲1;$G"W`5HU:Y#̅cV= V PAUmtYpeJ6\r\Ç\RR][ @rH*\ȰÇ#JHŋ3j@Ə > aOp˗(YXIp ɳ'O> JѣH*]ʴӧPvudɆ*0p$ב0arൠʁ1t۷pʝKݻxAN+t$̓YaY M0aV -˘3k̹x'B$L4=X&$cfjy N mN.x,꿫sejtaËO滒m[+듲 D^I fMo(zX}v1brt} rF?!hC\X@s.'aGݝ<*5b@-uTniGncv1NAVi `)GZi&p^fhkibni\or։v9zV~Ɖgg8hk.裚 ?9Ji^\nih~jeڔz'jLjJzʫ++šk ,>+nA-um)AK>&ҸEe@@ DPB >QD-^Ę! =~RH%=v4YR-90@"D\%L9-( TOA괙RR IkUTUxUV]@$ k6A#0ٹk/E'˸2i6D>5XbU6Yְs0s$@trf-% $H$ \dƝ[7ǻ}~ΰ[-8Ćviي Z?Wc^xC6^7]^{7׉#R4n \  &B #CB 7<"!t25z-NV:kAQ@G2 $H5꣉  GܶG|qti°PWrg9*pԗ!NuoVVdWuw]l ksFGe,|ľV6t3:?ΏQcwgwjvw^$*OEh^F%CAܷ]g}{кWE|i-}'|IFAȽR3!DŽ /QD-^h=~RH%#r4RJ-] Ŀ5męF=}ePEEZrfRM>5TU_UVvVlCc͞ՊZmwtWѲsu^}~XpǺ ^bP7̸pd~ܘYfΝ=ZhҥMFZj֭SW{dٵ^Zn޽}\xhō}\7i/nytꖛW~zٽ]C.^?M^_?L .@JAsP+0 3*׾3*Pd<͜c :B?C4}tܫ)6Zؙe۾]6ݼuY *ԫK]<]qٵs?n="Û?ߵ;b?W k޾C_m|XsNx^(>i *Y(,{߁蚈#.#> Bt4xdcIWnA %YOFIei2&8#Z^d┡yYe|5)f|]9i.I\+if)gXdyf{p :jrg'hwn"Z)z(J(iLz ^⡥gtgUP\jJuny*HZiaS]kQl.ˬd>֭kk B;YKnۂn[hbr*TYz*@$XA .dC%$AbE5nXG!E$YɆQbK_ʌqƛ8+IN?sL8?I.ٓSFZU,RtʲWS'uٳ<\v+َHΥ ݕpׯAV:L80)K]lX۶!gM̐ܿVY gϡEtƎa<5ljƊeom3iykۚow+]Y'w:>o?nz׵o\ϝdͯ=q/=z2 TpLoԯ<%P /Ì6L< ;0A\B`FSBoDѹbG^r!\FQ-HXʿr +Ԓ2t˲q,+4sͧ$M8uZR$ӔpJ6is=M&SPTL@SAu.ltRJ TK5,Q*3S #I(RK55SSUUU[eLOVAmS(cVEmU^^YvUXi:cXfL=$igvZl){6[D%Zvܨ%2ϥV\kUݓ̅W  p "Lp!ÆB( !P↋ X`H`F@(dJ.+)s&͚6o̩s'O0{ *t(Ѣ3$(ӦN "Źr#U5T8rc,U~e)ٲfϢM;qڶneҸvΝU{DW..ƎZ|1ʖ=N2gőoNapjᙂ> !pX;Î-{gȵg5ͺM3  LtY+8nn};.w*xn|[9OBj jqK7vX`PU 2kv 2Qt Ga 4@}I @dHUi8Q(3BW4ۍEcn;"4ҋ ^q8 Y5X}XdKG[r YZrn^FYqC.daK~}VP:IA bnħgJ#N RV@!Pj g|Y`֤YjjWbZi9誦g祥$A!jVg4ǖ+Q"l*䪳j& M [wJbXemEl&k[⛯ۯ+j첪V6T"On_)-21K0 #\roL jB|0߂)ѼS)=ͥA{{ZaG/ԭ1G?KZs],qWVJ_kCݫSP;]Ov-y)ÔދsiTEc5ߓ 9cfe6 zO_X4zߙ^會r-Rڭoyٚn˓ǼH7&.P+/;kҧ߾/ 4xaB 6tbDIxcF#VdH#I4yeJ+YtfL3iXg͛9yhPC5ĿK}dԡSSVzkVAn RWaŖ5{mZkKve Y<ε{o^{Wkߖ6 aŋe|㑑%WNrf=o^J3FСIO\uJUݚkسҶ};6ktO(w𔽅OٸMg\r#ҹ׹/<^Enm<_ݾ__/ҧ퟿ +A| NA+ 10& 94B8HC =4QK`!Qqk\Ѳ HҒԬEZn ;ٴɮܼ{';‡?^8孉3ѧ[:ڻS=I/~oy=l? 'SZ^߁ `:1DbEP  ]BW$(TՊ#F-޸cQh$I.)Qd8`A&TaC!F8bE1fԸcGA9 'QTeKI{9fM7qԹgO&}:hQG&UiSA>:jUWfպkׁQ;lYgѦUZoƕ;n]wջo[3(ѢF"(3)ӦM:*u*՗PbͪuЙ\ +v,ٲMvmʥl+w.݂hͫw/߾~Vx0†#NŎC,y2e+cάy3Ξ?-ѦONz5Ҭ_Î-۪ل]έ{7on{ |8+<9!#v.[ώ2ػ<=|‡B& /̐C6? F,ENLVl^Ffnq"H*\ȰÇ#JHE3jȱǏ CIɓ('bLɲ˗0cʜI&6sɳϟ@[ JѣHӧPJutիXj Yuׯ`Ê%uٳh,۷pʝKRv˷߿ LÈ+Kvlٳi׶}wnݻyxp߮~yr˙7^|2kkW*KnwB _^y\׷}GΧ}߿ / $@|kjA & M [J`6 ؂"! "ĸ4E k1BK6ЊDTb qA$eI GDX` 4@$I\<4G:#C0߼$!ϾO p "Lp!ÆB$q"Ŋ/b̨Qč/@F@bH h r&D"̩aǝ> ТF"M:ҦN:d Ha h׬ar%7 D)0Ȗ#n 07 |֥Aac arU_&=<͞? z4EN"jVw{#8 FD(,찵U{{:qڞ-sae c'x<Ïϰҿt~[s`)L`iFAtV (  `[y@d \v^2U[K\ox$6s&X_ԏAY$kF"ِA6"tPe!)qT~xRX ]7d& g1f<ƥM)չUUdd("(rfdxnXPK,6X$e29PhPc͕HzĜfAox:=(F5[`׫&d}[%Aa~أ%n^ Y1jڶ㼴@޶N[T,¤IV'֥o®^tW${5UoBlqɫ(, UB>ϴ3C%4ш cY0I7ˆn] z5UVÙ.^PE#cu+,n ѫ4vϝiz}~MaG*xkwF5WJ,I[Z[Ix婅Vۇw=U] ֪yF@Rk4Wީ3|e=(ǭ~>FλEТ r![-qb3䅵sc@,=+V6xQ!q`Vx|J](ok! So`2gBzxE:?)sb4,x'ĐM(h; =lH݈NPqn1.bHeaQDsl$;;nHSHMH4s" Di"[ʐBV6ɤIbS՛N2.!`BH]d!CÔ=ޑ#~]-H?;0h s<5kgknV+MAerE4 8/ Gɔ_ 8xӞIфXət'%D"Mqru痬2@LN|& .GP4tcx:eN?BidSy,)NT#uAT9ԧ.EEBǫb5ٺdVw.]+]]Vq\zfTkFC"4[eGX֨h p "Lp!ÆB$q"Ŋ/bXPC=f$`$ɒ&IfLr%˖._Œ)%ș6o4&Ú<# j2'ѢFt)S>>U)R(զVbͪuҭ^TAMڶ0yvչqeYCͫwoʸ|.$!x0† X.J ؎s2>9y3L%{ řCN-W ]|5ڶ5kŲKψ#,wΟx`HϾܝ.}Y!_~4$iEx$o"%NT@}bj@BUiؕr墔5aiI"lGMHS%ba([Zv"tA.*P9|R#WSf ]2a&d @J-v(B]*n$d:Z~ BA+n맷5 *.a^}id<ʒ`` w驕 )kS/d.rX n<@ry~6hhRe6$ǭe/~֯'zzrm~b彟|*(*t2~y`ڥ^/{*>p0y<1q;t.MOZ W"vdw2| Y4)L"T^B2Wa!5%Q*șP0=)Y +.4r  $XA .dC$ NX1@> F@r$ b$, 3bC9qV4HBOAYQI.eSQNZUYne @"OaQb0)5*$#! `9P¸o~Mx!ߊ>*aĉ/f|pcϺ<&H$1ѣBƬKB; &LkرeϦ]ّ#O~yZz-hRBu{ojaYuٵS|q̲S~ެ٤涗:9˦v ]!} {ĩ)Pȃҫk+ + -p@K4:O52ʣ3`˾:4H$j<+;)\.,*Jj|F9nHTs#d2bq*z0v\o1;,/!MB 5Pz:T'Khez6hUi2W5Чzgvαrzn苋6{mflmݦ养vWoYn4G;m w[p`9r#;g,\X?oMkͱtm}Q[{=}Mkםٌ}~`҇7~,>/^ӧYmѭ>{{z"M <0… :|ĉ+Z1F$x2Ǎ$K<2ʕ,[2̙4vd͝<{СD̙ҥL:ԩ("I5VQzU`˚={+ڵYŎ6܋j%ݽ|n7˼c ⒄.~ ynȔ#Z93ɚ;lԳB9 :1MٴI86fܼ;_o3|鬝Sgַ,ܻxgWPx[ϳ/x=oi~߀C h`)X jV;9(a?EhLfTma,a(J (t.bQ-ƈx:VP(w(D3$H:tZ)dX@jeAigSeZ]+b)[ efjɦb8`A&TaC!8bE1fԨAdI'QTe˂]Ɣ9fÎ"qgOa:(Û9sUiS>:Q"f*5V_ZlYgvE6رƕ{Q\Dݾoߍuvw`qV\ŏ!MrķX+gfJsgϟA=tiӧQVuk՗Cj={k۷qֽjdixq/7Fy¡G:rձg[zwy]|ѧi8⢅;8䴏+[f;9͑/{씳ѤK>:լ[~ ;ٴk۾;ݼ{ <ċ+$a<妑3=zKҫ[:ܗk>vǛ?/<쭫o?~Mh jH`6 h` >PNHUVfa/ma(b&D*.v2J6.X:>4@@ DPB >QD-QF=~RH%MD9cJ-]SL5 SN=}gPEETPM>UKS^ŚUkȪ[~V,ɮc͞EvfYmݾ[m\uśW^}X`… FXbƍ?Ydʕ-_ƜYfΝ=ZhҥMFrnj֭v[ٵm˽[7Cػ} \ÍXrʙ?gtҩ_mvڹoxɟmzٿ|olD$XA .dC%NX" 5nG!E$YI1dK1eΤYJ9uO-q%ZQIuUSQd:UYWaŒ:YigU[Eƥ[.ܹwa^ aĉV㋐%Oqe̙5ogСE&]iԩUfkرeϦ]mܹuo'rqW޼4sѕC^}3u}c1wi_/yUW{ǧ?v~} <0… :|1ĉ+Z$a1ƍ;z2ȑ$K>8VÊ;~|ɔ29˚;{ 3Ѥӊ.:5Ӫ> ;NP`$,4$0`p|;)ԫn-a.ٜc wwW8& !bώ? ЛK՗{1zwAu| ^GWmaeb`Jhv΍ۊG%'("H>ZaBۏFg)Hv\w eJ &KDΆRa eZlν`z$fTp8PDb'P1'=J:)$$Ofn *b9HB _0ΦܞE)lVVx8p7BU~i}z۫jBaeAčܔhTp0 A,B2ޔݽ{o?aw-X.] pS2ʛ[з<:}2 廦#+3[OY KY A6_\4'RZoO'Bhw3ʛ[jp,6t@R=3hMŢKo{)mN,)2|y"=A*l}-cFm9J8`AH0AĂ4H~8rÏ! H0B ]ȑ F1!V B65vbƍBw&UT) OF:jUWfJRkW_t lYZǞUm[fT `ܛsF0_%0]VjWF.OiHx-ԴA=,WҧFϭaǖvݢ: eYc恌Ex!q$PN&jPڍDșy:|!p߱_?|TT:kj]ne$*¨> ".xCN ?KϾHbB QDqLL1,YlQD%N¼n& s?n>,6f-)s/  L.G.LS컽.l@*sÆZ$> P,R';:*O\RK55e NA. )cPO: J$l2i@%CڒЅ,2CtIIv7@j2VuHOCm2ohOkų a+9R,h 9&L Dn#MN}ہC`O=-kn8nͲIҩ8OJ™ H PCOV}KiM矁4術n>ZAl5N[h^L.ێ]osf / oǃ^1L5ǪA]G>]Yo)]7/iau?+w;(Xܶ_R_xv3H*\ȰÇ#JHE3jȱǏH* J"\r`<Ҕp$ϟ@ JѣH*]ʴiСNJjp$ԥHt !bAŗ90Q@"ImOpʝK]WݫT#$|(KQ w-jf4/˘3kΠN:a|X,P5ʢYˌu%?ͻ& z;JMplٱV \)fA#T;ΒiRGRlx/ϿؓHnA{ʩG@-0w)ݴKViV'V&@xVaUm<'[3h8J`J#TJA1luvډ"MKAZ OcUk=)M)M MfBƠ/}% Aa9g sI :fh18r*pJft(ROx&Z6IM^ͽ!6k.xaYJl}F+mn\bwekdHznmkZڸkCknAj~V&omjܪSݤGwS)0M|gy&"[0#%lɧmj҅" 2TamlU6dqͨY|zVme]:t*[PtL`9곙׺$r)eյT ,tmx|7qA\U߃]އ]߉89+N;9ލsݝX^/,x⻩_~ bkÚv*-o-̣}w6@6(* ls?"A 5 (HA2 nD ˺DЀDD>F!C F@EWrJO%Rsj2I RclHȐB8,d(-sN0Hat3ԑ0#1THLhڌDH%%*:Ktф$AтÐd,;А@(ԡeGsU,iA#O(B?10fQXl@RžUЪ#C"mQpҭk.޼oAnM#- `U\иA:]o-=Zas˂/؜o>?{O`u`TdtXUWPu9QIfr WN.~MH*"1_2ږyYֱ!^ hE5ZC\=`LqV艸zT>"|."eC^9&ejf5^BL~P<Y$OH%dA# QIOF%9wj;g'B:)e)ipIuw=!JGM`9e9Qk ZhCĕ!Zzi+,'ܫƖt$U`!WuȘsN6F`Mːozk孲.)ܰRnAIsXSiaW'ɍv!B:REdiF)l/ M-DӹQǐ=B'qIHHuR˓)'BU yeLMmO"qZ#(-֋3-Wl԰mK3P, ak,_ۭPFt9f K'GrMwFdiAhgF( Q>^=ǐ&9yDGu-wս׬z~׏>QGԍf 1>g֜뙸r3[`s-"W)ܗ1E/t{FOVO;) <ϞD@Kئ~iy7C&vp:EuSCBr)ށP/^ 7?$K&0!5$ ÛP9!38'4%ȇl*D9A D)|Y(EPJ9V4j ѓȆ1#Ƭ+GCxH+x?ɏ}אq! ZD+{c9Q;ܙ'5Qp ҔO%Ȟ<#l7N#Ȉ6|'tB&d2swt!)hf`."L0G`a|Ahҍ3BiQ 5ɐxjʚiT#RiOD%5K} p )ψsl llTe[ڐLT*kX1 Ή&.mbCI'QB $a0… :$HD> 1FP$%RHqH E`P$G J^V 4СDҥL:} 5ԨZ5aլ\zef*B˒70$k6!Z#u5Ipe˺{fΟ=iČ;~ yȔN93Śv"Ȉ~BT{īR|cj(M,t}V,9c‹?^23"$ "o}+n vϖ;;2;w'*:T~Ź_=$AAԝ] ma{Մy5}Ȑ(Ȣqً0Ψ}ucG ս 8`]dV ަnUhZOLZneY%c`ɢVY%(^&IIMJtQĖy![WgCh.JИ~iEZ\Mm&C:diFWF!pi^3*PsTꨦ&JJkPr lK,^뱙l> -FдԊymn-v{KnbknR};. o+oKo Vo\ / qĒ*,qg{qžq r"Lr&r*b(2Ls Vs> tBӜ30t= Vg3M:CMuN.V+^ֻ v]v@@0PB @PD-^ĘQF=~|H%MDRJ-]SL0I\N=}LMEETRMV$ TSU1U]~Vح>EYeվW\]d[W^y5X`…bcDXdʕ-Lej7[Yhҥ j)f[lHaۼ][wL׻}hn?ir͝Vҩ_Ǟ}6qCB^x޿Gdzk[_|1w^>DP> ? 'n/0C ,B,CH0EWJr1G*0jd1Gw+F}qDQGD2IRĶ6#J+{bɍFa2L1ǼO-|̿kJ2߄96RM~}kz~9O ,53PA\!P,%P-P K8I,D(,#J \' 8)*F*Q+ SL l 1;5LlS8 p "LpBB(q"Ŋ/b̨q#ǎ? )r$H&8r%˖._Œ)s&͚6o̩s'Ϟ> * ɢF"Mt)Ӧo*u*ժVbͪu+׮^ +v,YeϢMv-۶n+w.ݓQͫw/߾~,#Nx1Ǝ, y2ʖ/甌y3糚;-zϤOi:5֮_W] {6턲kέ{ۼ |8ⓅO~\9#.֯}\ܿ/MӻdɛO</>Ưt"Ё 2 tB bmء@$Xp .dC%NXE5nG!E$YI)UdҥK/eΤYM9uOA9QI.eSQNZՐEnWaŎ%SkYiծe[*ƥ[]y9_&\8_É/fc!O\yd˙b箜A.+iԩͪfMtkرe|=6ڷu0wo8'^i@= a{ -0/9sAܘT( a& 7&$  Ć`"D?.hŔ&dH| Ν<{ 4СD=4ҥL:} 5ԩR qf˜#  P]?fiW(UJ9 y5޽| 8 FjAb2P,)'<0&͐ ܠy *X6h5,Y+;ݼ{ <ĺ%CQ`L7efx}ԭHZw?>ۻWJdBI$C5D}g5td&و薌]:iEbIffפK͆ߖc[@L< cvVZmFߙih.hL8芌QYh9S :Rjmv' >|!j +f+eiCֺizj*/IPB]+T6 mNs[U`1d-%[ЬV l0Vz#O=nK_ٕMb)d^[h| ;luIiE+q_!ń-iPw-M, Z.j^f+Bils:΂=̧&+f,DL,<371sO>gu^_u`q7Z'# M9] Êl74>-x睨aX 1ܭ銖MteL[B8z뮯E7L>gwҚynz^޶hyڢ8?}GO}TW}^}{~s/~:o~ϯ@$Xp .dC%NXE5nؑ"B!E$YI)UdKAƤYM9_OA%ZhBG.eTgRQNZUPWaŎ%[Yiծe[qb[]yԊS_&\{/f}or\ٲDʗ5ob63&xtiԩUf2tӭeO=mܹIY['^qǕL^rѥOٜ'>w۹'_P;կ'}㿧__?#! TpAL@!#B*D E[LDTt4͛FsFzqH"# ,%lR$:H* ,8 2lhB@h"ƌ'JEA($ʔ*W˘2gҬi&Μ:w'РBmFڱhL4dKOR% 5jլZr+ذbU*KiͪTۖmJoҥ7nݼz/ja"/V̑qc?l2̚7sJ(䉡EYh5Sw^5زgӮtP uƽB mǗ3o9dL^|WgN=:Ǔ]o~z#ϯo>T|o{{Mǟ * !{7>h j!6] T$2)">]Q#56b9#Q(b#x$I*YՏ1ԤC>XHRKj%]%%Q)#SVFV/z&qdoFjUr :(+9f>i!w{V(AedZz}Ygrh|(Y)N.jC\3kj׭Q*Q&žfz椯,Ϻ(V)H%h^jъ;8`$ &TaC$:ĉ-6ĘqF =~|QdI'Qv$"K/aƔ9fM7qԹgO6Wd$ѢA4Zr)SBl*iTWfպkW_:u*Dzf~?QCD G!'A%J1t@H@*\ȰAJHŋ3jȱǏ#~ ɓ(S\ɲ˗0cʜI&ɚ !ɳϟ u ѣH*]ʴӊD }JՖS=Fʵׯ`ÊgֱhR=˱ڷpʝK[l݋2ƻ| L`8^XbKLei>Yf;Mt2!^ͺװc˞M۸sͻo%QNqm^μУK;سkW|mOxI+G>Prw7DuůO׾]tv}W8>|3/>}{QO:|G?~~k? k@K! ,h „ 2l!Ĉ'Rh"ƌ7Z$#Ȑ"G,i$ʔ*Wl%̘2gҬisǛ:w'РB-j(R92m)ԨRRj*˥Xr+ذbǒ,ڴjײm-\gҭkݹx򕩷/K0⎉3nXǒGl2Õ3$y3璠C.mZ~?{V-5زg#kwJw><ʗ3g⭡S|N:ֳG?_O^aճoڼ#O>?v xW" :J8!B H`B 6tbD)VxcF9vdH#I4yeJ+YtK3iִygN;yhP;c5ziRK6ujTSVz5dQ[vlXcZmZkٶuDܳoΥ{o^{+R 6|qb+9qdɓ)W˸e5w2gf1)tjիբf}ke׶})m03wpax˙7/ yҩWu/o]uw:7x1g[3_O,RAl/ $a0… :|1ĉ+Z1ƍ;z2ȑ$K<2ʕ,[t̙4kڼ3Ν<{ 4Н1=4ҥL:} 5TSZ5֭\z(رd˚=6ڵXŲ} 7ܹtڽ7^n 8-8Ō;xɔ+[62͜;{ ФK>Ԭ[:ղk۾M68u U/<ʛ{dFMUl"Dfƪ3"J1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu!7,OH*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJիXjʵׯ`ÊKٳhӪ]˶۷pʝKݻx˷߿ LÈ+^̸ǐ#KL˘3k̹ϠCMӨS^ͺװc˞M۸sͻ Nȓ+_μ9h$XA .dC%NXE5nG!E$YI)UdK1eΤYM9uOA%ZQI.eSQNZUYnWaŎ%[Yi>$[qΥ[]y/ߵ{[aĉ/;% ^!G\dY1g.3UϟEG=jiQ^ka={bmBq 7ݿxq䴓+_~9ϥ>fحԎ3\QPh^'P` z]oW9}&ak+r#@ˏ$yA&l?DX` 4h# 7d,B k1!_(F# o\ "`ȳh##SKH,ID HDCT? d&'E Kð<@\Dƣ D2NL T ݊oB$hM|-г-"%P)?oJ#19+u΄uKBM9VF]m օApYuK_S _ R +JFIf}@_C ՙN\rB# g=P(ԱHu W yqZ-x ;xSݴRPGDVuqЊa8EpiEM:r=y =--ud^G,Z a%^}mu.,fg 弙JidY, [M{lc޸ uϬ k-&H.X{Y%(p֚X5nuD\qn ;H*\ȰÇI@Hŋ3j(qG>9% :  ) Q` 19ɂ+[&1)TH}:m2AEe~@ V^J @H_aǶpʝ{ݷq˷B~ L0a/Iyn˯FbalWA 2nՑj z`⧥EM,̐e\6} ihy݇POf6WpBJD"gO"UY (Z?ΩZVi( hydUn h)[d)ꙜfZ Ehp: x{B^VxULHZ%H )V+ m6珿ԫYmm]zj~ꑫy龛N.jPbkcծ <\Ee?˕*BgߎDkk*2Yֻ2ʲ/\kf,ܡEXKO2·ND-[ c%HYFhk-5%0pRˈl )ؗ߱4rYט&-wĮ ֘jkc)ޙKb8j IܑPxQ7> >f<MrXSNX݂^`8kߤn] /cKv" e8>@.?8#;po'9WGYM6֮r3y`Jye8@jwF3bǂapF< !r'uJzyUB:a$?*8G^C+."?{(1Aak8#:|⅖D)1QyR4aDÄ@oMܢuh1RqKxQ x21Z!:ЍlL$D:9/T ͨlj4kL$!%ٿ. #%79E=#(ґxSTcWbҖ\eoi%R&*wHK 3O 2 X *9 \xϋm _%r2qJ5Qj蜋bmD JcR})3t 4xaB 6t" )V8.f8P$Q!"IU $fL3cygN;yS'K>  F" u @hBFFfVOvikNH Q@`ȑ@M|%\Xj {o^{[1 wT֭{S&X`ёj9mWv)6}ujb\K2S֌*^,hy0` VdEȔFl;u|xv<х,!e5t:^?h;r뮦+:θ ζ@!m&TE0M3)P8h)P1#Ed6C31t\An$@#|N!E&#L,%3) dS 7kOΆ3W32S4LIT=fm%@#C PG 4OHo-T9rQ-;QKC4˦dё4┢QTSܾj.@̲ td+EOG< qw|V\ՖHOk[neコuG eղvUx{#S`J}3V1 Ra %+65êSBATXz!S$@Wt6`Yג E<1c>+f%c_Ź>f 54X7R0f/}ꫧ-R*ځ>VWX0nt.jdmoԚ/~JR`x=HjI%.!;sxQq5|!CvWm .E%tlg_D7M_襟ꭿ짇j{a;w\1`}tZp{.g}&jK]5 r+ٻ6i T@> ".,>RK;d|:k9ɯ'ۋa ,VF~}\7;P~xqHxAW$a!qtb"]Bʎm@̉ xQ9{d.-|KwuB-mB B)#BQ:3" +1~p d׈qO Ar9剗aLHE~e#e6RM46GIr+! EySbzQR=샔d]+1MrҖ2E!gT4Et0G&giZ"̜҇Źp g9I&fJ,Ɠe YOFQ? )PLF φ$th29PUIt.ԓ}HYEo~%JR!ƞ$)9'Q;!uN-2 4xaB 6t" )VxcD$8v1@ H4ydH+YtfL3'JygN6W8eP:hR[")SVzS[j!Ш( lZh+u(vPsֵK]L{f^ 6(+.iC2P+-mp9] b:ƮN̑Gp(,!$S1!,ɘJr-$˞L2\s3aNHa^ana"a&b*!H2H#Ոc2#_:$H7Id.8J.ѐL> "ReF9ie?N鐖^_rI&YbfjVBk)Rp2f[͹xi'B{©AIhSbZg&hN:T:Bji vঢ*P~fS *떛֪$.k*Z(@$XA .dC*XE5nG$@$YɌUdK1eΤY&C9uO?o%ZePIGTiGQNZթO.+IaŶZV'Siue[q 5ݧr7_P&\၁U$b7eإČ;#S9sN˚;{ :ѤK>:լ[~ ;ٴk۾;ݼ{ <?|s393ԥWn~rǓ?0Ç}|\(}8\V| g7WXo>&׹.U\zu'nLrgzO{q[,)ި|m;W@mπC`xI:J#耧}_S hzT|)oygSYM,dib-Xü,ІIJyp+ڞ&. o#$#Օ0CyET`Epa=Ũה ad =fV$l4}1^\XL8!=D| F6< 9F44#GII^2U4\4NђFIHrD*QJV쓯sJYgS,uЖ_9̽Ҙl`1o,h „ 2l!Ĉ'Rh7r#ȅ$F i$ʔIfTÖ0gҬi&Μ/eF@=I(҈<2m)ԍKR*լPjE:+ذb%k6гjo]k۸rzkgۻz=rkKLpż7˘ǒ'ǍL2Fǘ1kެвТ=XiʝScd5^؋Yuڶw6߈W-8rƓW%ΜsϧS.7:F`B Hl=@$<!KT^$TWG_} : ]$E"v#<*VIx"Iz#D AxK3xUbA 9kz3 8(P'Q!Y@%]BM->P:@>$I1z5I5ݜ$Hvm~'Ap#gT%=Z!Y&z!p`, @,U9*y^R8'm# @j!O][T:d$$ੳ*%zUu`5VK뒨>8Ԋz%,9ݛ/B.zjJVcz+>"#2&n:LP^q*&;n52-21<3*UA8r4@k?r0=-< ;̐C@pDK41kA & !Fz *`"P f1Gt,:PÆ<1;+SJ.һ-)R==" iAnsJ mD5 'ȢqH9,J5-LF#tR h+B$Q@O(C 1 *{sPQ Ȕ+%>P$N==RJ4`5Xd/jضuf "ߒSBZIRNY$w* bMxKw^| ^0H}e``V ꦫxbZ.kzyl-SNms6yK_ntﾭ 6q#\s5rY Om|q|t'2p=`uv{tAwڛ.}vȔ}ۋVo(6bܓO2&دɡ]IOeؖBYHx&ns:'Ky=Y]OJ]#t^?P7~eQʁH#[v5!O" p ILp!ÆB(q"Ŋ/b̨q#ǎI(rdD G<8  :: aa H9'ϞC 1 %hdҁ&7,e*ugR] ЀR`֭Js$±fϢMv-۶źpMYn2! = ,܍+>D*DNIp`2b2Ūu/`6&YXòONz5kL[EڠI?N57Εa::cz{SR PΝ ߫\i{/~<iq\~D2j|3tH1cw^IWziE5a 2Rq} QסW]HP"I܃+آI!eC1-#@!c4Șc5A؇DT^}&t )4cXT|7:dRaMY]iF2ogpnGxH;%Q#[9}]SJtwSn8Iy'lN%D}emUvXB!Bgf[qZPqvjvZrPZ*D`Ar,vݟ) 𪒯j, 剫EFD! h䀎Z*Dj[um=oA '/D&VnXPڶeg[PBQ:* k*`/G':P$LjCզ)R,mh+{-.̆rBBPolP#YDƲWc-^abYm amR_x8KsfmYյD --udzl>Q-t#x\pay@C4~=!yyhld*M'^xC5l1~Mչ{mOu8kPέv|>]FNQ"[9m*A"eI"P,uDޒri"$6E0lDP{U0tO ]6IU4lk萹j),ɇ~"d57շJlt+bRiC^Χu։Dj6a^1#(9FqcSڪvmdg7^٥j3-MX׶ }l7\Vkn<]cLZx:ҢInS, W*,,Wk^7yn[;8`$ &TaC Q@$0f8È РD)IÕ-H0AI^VK?:hQG&UiSO>jU^eUkf*Bʒ706X#o5I0gL.5S#̺:paÇ'VXTƏ ;\|*2^|A*ļps窼kק] 5-ֽwo߿J>p╉ algX;r[L-7t &1p _M}{j\>|_}oO / -N Р̫#KI \8A}Dbc+ #ed. H <# +'ڐ%lI&M|(yˏJ /$ɳIiǁ.ˆKh$$$0u,rh4*ы odD)) 9ZB)唅=ыN2dK(!`iaa8jy%gE)pRhiiQ|V7Y'硈H{\#褔 4xaB  @#Nņ5&G#I4I*YtfL3iִygN;q,gʓ@IiP`SzkV[vlXM/-[uYj!m6Sr!\{p`NҰG#lxX`͛9w‘ג.2sToK*ذ}wnݻy[k{ னFMi[UxoөW.yѝfl%w˙'8ٷw~G9s@~㊳)H%tO?]4IH)T44R5TJF54V]=rDSiZ\ R^oTWvX1W_qMe`j_vXVݖOVGmܭ p "LpB$B(q"Ŋ/b̨q#ǎz0$ɒ&OLr%˖._Œ)$ș6o̩b͎#w *t(ѢF" 3)ӦNg.)ժVbͪhԭ^bq*زfϢMRj…)6.ݺvjtn޾~+x0u lxaČC,Y^Ǔ/{Uy3Ξ#ZƩ3iKNiWÖ:6ڶ6oy.|rO.q6pΟC7% V_8:t(~<ϣO~=Ï/>}?UX"zנOE8ZU!Rơ!#E'2%"+Ģ/ޤ"3Z$#7(9xЎ=yA8$G"$F*do8`A&TaC!F8bE1fԸ" A9dI'QTeK/aƔ9F5qԹgO?:hќ7&UiSOF:(RWfպkW_"lYgEm[oƕ{R\wջѺ}8NőFB^ "MbtFЌFuٴY̻Iz*vq1▭8KF.8DË~OЖ n/o+N?p ^]!AuheO~X !P^y8e Db(I-ӄAȐ(z8a(c I} #A: TVi,S qv`=asfaFg^n2t"i矀f6d`D}m'`[Y)Թ#cՇCC~j꩗m(i%jD(o&+mM#Zeꐪ&,YCa_KB[mA誧pRmrJIB LGRk8wkyZ}[л 7P 4]Mzkd\A3Z+/:|$ gʡ_fLJ7tIL$׮ƳL Z DtOvIEIPV i:Agt܊#sX >yېGnR&W/{Lj ') 旎`zWK!=R]{ף+i`7-;̳  H`B 6thp# 8"$D,X耣Dž)ZXR` $HT%! TIbCZԀ"2{#ƇK6ujTLNzkV[vlXcɖ5{vEk])tD ղm;ݢd,%\;-H&! Ve͛9wthѣI?Ȗ1s|-oM++\ό&NɔK7ߜytөW~{v۹w {xɗ7}zw~|׷}5O <L|%j - 5p 9EDs8t*֬ZrhUǒ-kXhײM;-ܳ_uxu.޼z nƸ˂lnÂ1Ȓ'S1FǙ1_ܙEϡA[4ԪWvJ花k]mܭ5ή7‡+ܗ*g|9q݅Snln;c9<걟oܾ` 7/>z|*G_Hҁ޷`~ nZ:h ]`m(!!ib8"1ʨvءX6އ3#%9i׍$M68")%o:RNj%PZeP`F-%i祑d^YYgd]㗧'&n ')ߡ%Jb}:hplN9(cR:Hnʨ:jiVYlbV*~>Eԙz_ʙ驼j)_*kĺt*Wnm&ta߬Sz-M8`$ &TaC$:ĉ-6ĘF =~|Q$H'DPeȒ/G|(fM7qԹgO?:"Q._"MJҒN?BʴJ+Sb5'խ_;lYgъzVjƶn>+[vӖ+qn^xq [UywvWױg׾ӫys侞}{C/-;L/~~t@˃i(:9P #t0B A Q,<@?,aQFJP-m1ǩ`|q 郬#L*lI#+$JKK(Ō,LS!q4Y|S9-2<K1TQ7GR UYmVTYi ,8 2lhB'Rh"ƌ7rcB Di$ʔ*Wl%̘2gN,Iț:wSbΏ6-j(ҤJZ4(ӨR)լZrAV-KvFfײm-\hҭsnFvY)Š3n"Ȓ'Sl2̚7s3ТG.MzdǪWnM4زgӮm6nͨ]7³n8ʗ.9:Kn:AR;kwo<ٖ_=ao>?VןD * :xRJ8aERx!bjGraH 8"C'_+bآ1X#@@0PB >QD-^ĘQF+"RH%MDRJ-]FRL5mĩ0fN=}TЗ;ET҃L>UTF^ŚU@[~V,Ϯc͞E[lZmݾWܴkśW^}W`… F2pbƍ?9bɕ-_ƜYLʛ=+΢I6Zdԫk&Zlڵ-6ܽ}^ݱGpn]t̩_|nvj1?{x^gq:ۿ1}| O~~0o@@SpAekA"B p ILp!ÆB(q"Ŋ/b̨q#ǎz )r$ɒ&OLr%˖.#|)s&͚6oT3'Ϟ> *t˝D"MtANB*uPTbͪUխ^ +gױf5H[صl+۹v U{Wlݽ~,x̼z Sx1Ǝ5|RŔ/cάysOɖ9 z4ҦO/֮_þ,9MѴoέiE}N۶Ə#O^U9ΟC_I<:֯};7k.<~>Ox??x݀&` w {  H`B 6tbD)VHDF/vdH 94yeJ+YtfL3!ygΉ73MC5ziRC.u&ϦPZkV[vzkXRŖ= lZkٶՊm\=en^{-o`6|qⱊ7[qdɓ)W|9+d̛9wthE6}ujOIvvlٳ}wnݻxpá&~y^ə7wѩW~t۹wXw8ɗ7|zD~|=?}g߿P,ALл|3H@*\ȰÇ#JHŋ3jȱcECIɓ(S\ɲˈ _ʜI͛8ɳϟ@ r'ѣH*]zӧPJ*(իXjhuׯ`ÊuٳhKM˶۷bK׭ܺx.߿ LaÃ+^21ǐ#KLʘ3k̹3˞CMiO^ͺ뽩_˞Moͻo ȓ7yrΣC|:WϮ;_}UƭWߝvS'N2 ;PK HAH||OEBPS/images/_config_auth4.gifGIF89aLߟwߟߟOϿ߿w߿wwOwwwwwwOwwwOOwwOOOOOOwOwO7>FMUl"Dfƪ3"J1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu! ,LH*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJիXjʵׯ`ÊKٳhӪ]˶۷pʝKݻx˷߿ LÈ+^̸ǐ#KL˘3k̹ϠCMH^z(8 ~0@ Ac>ͼ}7WX:UX0  睛r,@합_4޸uןAup^z 6GFV(GEҽwPw T{ '"$~Y],_!Rm^!IAo |hBBrD/&n)HAY mGXޔpGk # %bAЄ+@Y#k9'|T'"GxT߀ݗ-j>rڙ e@ Ayh(Azl?:T^Dێeۇ`#`p BpF)2dގힿ~)Ah[ 4xaB 6tbD)VxcF9vdH# 0A$D, Hl(@JXĩS OMr L! b K 5T JiО,;gKkٶun\sֵ{o^{ۦuigLg &*BjhIPLsEH22FBjAc-s|Yvvlٳi׶}u4iqJCN h6\ L np%gljOG{\`wɗ7}z󅙹t[{D~1?z$+ΡCLRӯA[ ې=E( >h>Fdi,ndH+;7bD0HI\&|(t(F/Rȗ,[l*V13ts GD0ܓ>@;:JM"N+8 G`*K)D4lQr=TU]Uv#ˁsIZ, sQ TECam5Z9fTVlv.R>TS>Ќ=A^Xs-Kn >W`A ;@{,i-Or7߂͸Xƪ,] Bb_-uemV4a  hz53D&0bi4ރ>M{!2hֺC`UkE).^"iV kigU >5_%-5ߜ=EM?U_]emuߝ}7 ,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gҬi&Μ:w'РB-j(ҤJ2m)ԨRRj*֬Zr+ذbǒ-k,ڴjײm-ܸrҭk.޼z/.l0Ċ3n1Ȓ'Sl2̚7s3ТG.m4ԪWn5زgӮm6^w07ݾ=x+_.sͣOw^uУ^;q0ɷs7N?G=>{O  4xaB 6tbD)VxcF9vdH# yeJ+YtYĿ3iִygN;yhgPChRK6ujHQVz5!R[vթaɖ5{mZkٶ=9m\sֵ{o^pp` K-|qbŋ7vrdɓ)W|sf͛9w4CI6}ujUvve׶}wn2u o5i7~{}=}]=&H*\ȰÇ#JHŋ3jȱǏ C$Aɓ&EN$˗0cʜI#5sɳϟ@ }ѣ'wʴӧPUތJիXjʮ2nKYSϪ]˶[]S+ݻx˷߿z +fwǐ# Ò3kfxϠCSj"ШS^ͺF&۸s뾋qlIN+i“KNu?gËgǫ_Ͼ{o/wuB E($$DЄ#@P!$URurԄEeP$h!B:J $;HF&dFx"A X I#CUj(P9 Pd. jBMNwX  b  Efhi^XRKmyi)FS3䡕HXz4-* Y6:b":zATj !kyXҰyEAa*$)'Y[l~zg=Q}ːz͒A$A0k>VgЄJݛ8yϝo֌4C N <XJP\!ރ ro2︂Cfki L]|aՎ p1!! #)"A2!gn)+RU GӐIR 052rH$9mG%OK٪@AQR5†+(+2$: RFb tNˊrĠLOCOTU],Yn:LFղ ձH zt94tSOco `GݵWBh- QrlcIOoV )8ݤL$3+_)L@~BZY T!Yb2?& uoœ(´XaRM>r6ƭܐ V]馝6ڧ钚ꪭ뒢Κ뮽-RY>Q&[ڷzQpg.I\ƹt?Qyx B! rBZ_KjX݀#&aFY"-ؑ1Xbg3p!cp48$)y|Gޘ#?:cO>dBF)Xʷ%Rz ^_Ee9ZeMaךi$xisnh'PjڢH 4xaB 6tbD)VxcF9&$AcH#I4y2Ǎ*Wˌ01Dy͋$hPCmiiRe."ԨMwRz4S2lXcɖ-Ykg:-ܴr9M9W]>Bp` %|AE:lxȒΜ1wtˡI# TԪOZjKvnݻ۴[س+~]*+q+wMѩ.A+ήG/yu3<$?/>3|?ҋ ,s *tܐC[Dĩ.¹Zѿ4`,19cL.kE"3Ҵ8ˑ&v .,BR<.{Q L,3)MRH _jN: Sܓ!PdsB$T4/S>FH%r=PLM [Z5I+=/S-R8=E4Q E VWݕ3yLW+9Ua7ՔF_]Iee+ؼfb@gv#, J |"\ A\U/kvXcŷFm(v%z7^ &]u7z`װbYcݬ^dHaoGM9d7f= p "Lp!ÆB(q"Ŋ/b̨q#C9 1B‡& `r`J 8*L&A'i̩G=}3ЋE-ݩtiIc*u*ժVb4HHI\4Thu}u.]N'˕^B\wpGHNx1ƎҤ jҫG+Cchf;&h6ikr,A _7؞ohM1ƏE1oDų:9֯c?"М-]& Agٷ'V`_] |}GVp[͗MEG5a J$B.H!br t{ѧ^nx-v&`HX(Y3}G{(X'gȟG6چQ8׆MIe]r=IUuإc@M,6ߜZI7q6l#fi)JM܀~%VgDiN mYvZ:4xڹ{c t耰҉Vqm/ z9t硷ժ:f@A5V{郢vQo; ~Yr)C+N,2-P 7-ؒ MWsleNd۪Vz(biY ^zrЁ)3M@;sJ%Aׁ+i7sk+X4lwuKimi gVR/w+8J-u=+mZ|txBJ:p.l+~>;i@^ۻpxvh^[3V;d5^8[bA2X“Է壟VJǹ@bjFʧ6#+,{ƫ>ݤ~SJջO}|H&h ^J)1^*GlRsXә4Y#jBpgi gB\>YF,@췛t2 `jgkap^)zbCC\cD61iE͆D>AE%(V3߸$Pzd¥F<2B$+)HZq;$'Fu2*(Rr L%+EVe'WI[^GD#clK $XA .dC%NXE5R$AbG!E$YrG;dK1OYM9uԸOA9QI&eS*iFZΎYnWaŎ%[YiծevUqm]y_&#z/flncȑ%O\9&b˙5o~gСE<駝Qf눥aϦmRum.vb/=Ǖ/W(sšOOuαo-=2& !^ x!P(p:wǧ/{P "ϼS4m>>##A  Ktp$Ĩ \ @ZE KzCDDqGLGtlCBh j<#KO2&G5p Pd3= <2M+L 89)KňqL J4&Ъt*08̈́6ı@;2 :Լ:*tU,d՞_TPMhM۲1;$G"W`5HU:Y#̅cV= V PAUmtYpeJ6\r\Ç\RR][ @rH*\ȰÇ#JHŋ3j@Ə > aOp˗(YXIp ɳ'O> JѣH*]ʴӧPvudɆ*0p$ב0arൠʁ1t۷pʝKݻxAN+t$̓YaY M0aV -˘3k̹x'B$L4=X&$cfjy N mN.x,꿫sejtaËO滒m[+듲 D^I fMo(zX}v1brt} rF?!hC\X@s.'aGݝ<*5b@-uTniGncv1NAVi `)GZi&p^fhkibni\or։v9zV~Ɖgg8hk.裚 ?9Ji^\nih~jeڔz'jLjJzʫ++šk ,>+nA-um)AK>&ҸEe@@ DPB >QD-^Ę! =~RH%=v4YR-90@"D\%L9-( TOA괙RR IkUTUxUV]@$ k6A#0ٹk/E'˸2i6D>5XbU6Yְs0s$@trf-% $H$ \dƝ[7ǻ}~ΰ[-8Ćviي Z?Wc^xC6^7]^{7׉#R4n \  &B #CB 7<"!t25z-NV:kAQ@G2 $H5꣉  GܶG|qti°PWrg9*pԗ!NuoVVdWuw]l ksFGe,|ľV6t3:?ΏQcwgwjvw^$*OEh^F%CAܷ]g}{кWE|i-}'|IFAȽR3!DŽ /QD-^h=~RH%#r4RJ-] Ŀ5męF=}ePEEZrfRM>5TU_UVvVlCc͞ՊZmwtWѲsu^}~XpǺ ^bP7̸pd~ܘYfΝ=ZhҥMFZj֭SW{dٵ^Zn޽}\xhō}\7i/nytꖛW~zٽ]C.^?M^_?L .@JAsP+0 3*׾3*Pd<͜c :B?C4}tܫ)6Zؙe۾]6ݼuY *ԫK]<]qٵs?n="Û?ߵ;b?W k޾C_m|XsNx^(>i *Y(,{߁蚈#.#> Bt4xdcIWnA %YOFIei2&8#Z^d┡yYe|5)f|]9i.I\+if)gXdyf{p :jrg'hwn"Z)z(J(iLz ^⡥gtgUP\jJuny*HZiaS]kQl.ˬd>֭kk B;YKnۂn[hbr*TYz*@$XA .dC%$AbE5nXG!E$YɆQbK_ʌqƛ8+IN?sL8?I.ٓSFZU,RtʲWS'uٳ<\v+َHΥ ݕpׯAV:L80)K]lX۶!gM̐ܿVY gϡEtƎa<5ljƊeom3iykۚow+]Y'w:>o?nz׵o\ϝdͯ=q/=z2 TpLoԯ<%P /Ì6L< ;0A\B`FSBoDѹbG^r!\FQ-HXʿr +Ԓ2t˲q,+4sͧ$M8uZR$ӔpJ6is=M&SPTL@SAu.ltRJ TK5,Q*3S #I(RK55SSUUU[eLOVAmS(cVEmU^^YvUXi:cXfL=$igvZl){6[D%Zvܨ%2ϥV\kUݓ̅W  p "Lp!ÆB( !P↋ X`H`F@(dJ.+)s&͚6o̩s'O0{ *t(Ѣ3$(ӦN "Źr#U5T8rc,U~e)ٲfϢM;qڶneҸvΝU{DW..ƎZ|1ʖ=N2gőoNapjᙂ> !pX;Î-{gȵg5ͺM3  LtY+8nn};.w*xn|[9OBj jqK7vX`PU 2kv 2Qt Ga 4@}I @dHUi8Q(3BW4ۍEcn;"4ҋ ^q8 Y5X}XdKG[r YZrn^FYqC.daK~}VP:IA bnħgJ#N RV@!Pj g|Y`֤YjjWbZi9誦g祥$A!jVg4ǖ+Q"l*䪳j& M [wJbXemEl&k[⛯ۯ+j첪V6T"On_)-21K0 #\roL jB|0߂)ѼS)=ͥA{{ZaG/ԭ1G?KZs],qWVJ_kCݫSP;]Ov-y)ÔދsiTEc5ߓ 9cfe6 zO_X4zߙ^會r-Rڭoyٚn˓ǼH7&.P+/;kҧ߾/ 4xaB 6tbDIxcF#VdH#I4yeJ+YtfL3iXg͛9yhPC5ĿK}dԡSSVzkVAn RWaŖ5{mZkKve Y<ε{o^{Wkߖ6 aŋe|㑑%WNrf=o^J3FСIO\uJUݚkسҶ};6ktO(w𔽅OٸMg\r#ҹ׹/<^Enm<_ݾ__/ҧ퟿ +A| NA+ 10& 94B8HC =4QK`!Qqk\Ѳ HҒԬEZn ;ٴɮܼ{';‡?^8孉3ѧ[:ڻS=I/~oy=l? 'SZ^߁ `:1DbEP  ]BW$(TՊ#F-޸cQh$I.)Qd8`A&TaC!F8bE1fԸcGA9 'QTeKI{9fM7qԹgO&}:hQG&UiSA>:jUWfպkׁQ;lYgѦUZoƕ;n]wջo[3(ѢF"(3)ӦM:*u*՗PbͪuЙ\ +v,ٲMvmʥl+w.݂hͫw/߾~Vx0†#NŎC,y2e+cάy3Ξ?-ѦONz5Ҭ_Î-۪ل]έ{7on{ |8+<9!#v.[ώ2ػ<=|‡B& /̐C6? F,ENLVl^Ffnq"H*\ȰÇ#JHE3jȱǏ CIɓ('bLɲ˗0cʜI&6sɳϟ@[ JѣHӧPJutիXj Yuׯ`Ê%uٳh,۷pʝKRv˷߿ LÈ+Kvlٳi׶}wnݻyxp߮~yr˙7^|2kkW*KnwB _^y\׷}GΧ}߿ / $@|kjA & M [J`6 ؂"! "ĸ4E k1BK6ЊDTb qA$eI GDX` 4@$I\<4G:#C0߼$!ϾO p "Lp!ÆB$q"Ŋ/b̨Qč/@F@bH h r&D"̩aǝ> ТF"M:ҦN:d Ha h׬ar%7 D)0Ȗ#n 07 |֥Aac arU_&=<͞? z4EN"jVw{#8 FD(,찵U{{:qڞ-sae c'x<Ïϰҿt~[s`)L`iFAtV (  `[y@d \v^2U[K\ox$6s&X_ԏAY$kF"ِA6"tPe!)qT~xRX ]7d& g1f<ƥM)չUUdd("(rfdxnXPK,6X$e29PhPc͕HzĜfAox:=(F5[`׫&d}[%Aa~أ%n^ Y1jڶ㼴@޶N[T,¤IV'֥o®^tW${5UoBlqɫ(, UB>ϴ3C%4ш cY0I7ˆn] z5UVÙ.^PE#cu+,n ѫ4vϝiz}~MaG*xkwF5WJ,I[Z[Ix婅Vۇw=U] ֪yF@Rk4Wީ3|e=(ǭ~>FλEТ r![-qb3䅵sc@,=+V6xQ!q`Vx|J](ok! So`2gBzxE:?)sb4,x'ĐM(h; =lH݈NPqn1.bHeaQDsl$;;nHSHMH4s" Di"[ʐBV6ɤIbS՛N2.!`BH]d!CÔ=ޑ#~]-H?;0h s<5kgknV+MAerE4 8/ Gɔ_ 8xӞIфXət'%D"Mqru痬2@LN|& .GP4tcx:eN?BidSy,)NT#uAT9ԧ.EEBǫb5ٺdVw.]+]]Vq\zfTkFC"4[eGX֨h p "Lp!ÆB$q"Ŋ/bXPC=f$`$ɒ&IfLr%˖._Œ)%ș6o4&Ú<# j2'ѢFt)S>>U)R(զVbͪuҭ^TAMڶ0yvչqeYCͫwoʸ|.$!x0† X.J ؎s2>9y3L%{ řCN-W ]|5ڶ5kŲKψ#,wΟx`HϾܝ.}Y!_~4$iEx$o"%NT@}bj@BUiؕr墔5aiI"lGMHS%ba([Zv"tA.*P9|R#WSf ]2a&d @J-v(B]*n$d:Z~ BA+n맷5 *.a^}id<ʒ`` w驕 )kS/d.rX n<@ry~6hhRe6$ǭe/~֯'zzrm~b彟|*(*t2~y`ڥ^/{*>p0y<1q;t.MOZ W"vdw2| Y4)L"T^B2Wa!5%Q*șP0=)Y +.4r  $XA .dC$ NX1@> F@r$ b$, 3bC9qV4HBOAYQI.eSQNZUYne @"OaQb0)5*$#! `9P¸o~Mx!ߊ>*aĉ/f|pcϺ<&H$1ѣBƬKB; &LkرeϦ]ّ#O~yZz-hRBu{ojaYuٵS|q̲S~ެ٤涗:9˦v ]!} {ĩ)Pȃҫk+ + -p@K4:O52ʣ3`˾:4H$j<+;)\.,*Jj|F9nHTs#d2bq*z0v\o1;,/!MB 5Pz:T'Khez6hUi2W5Чzgvαrzn苋6{mflmݦ养vWoYn4G;m w[p`9r#;g,\X?oMkͱtm}Q[{=}Mkםٌ}~`҇7~,>/^ӧYmѭ>{{z"M <0… :|ĉ+Z1F$x2Ǎ$K<2ʕ,[2̙4vd͝<{СD̙ҥL:ԩ("I5VQzU`˚={+ڵYŎ6܋j%ݽ|n7˼c ⒄.~ ynȔ#Z93ɚ;lԳB9 :1MٴI86fܼ;_o3|鬝Sgַ,ܻxgWPx[ϳ/x=oi~߀C h`)X jV;9(a?EhLfTma,a(J (t.bQ-ƈx:VP(w(D3$H:tZ)dX@jeAigSeZ]+b)[ efjɦb8`A&TaC!8bE1fԨAdI'QTe˂]Ɣ9fÎ"qgOa:(Û9sUiS>:Q"f*5V_ZlYgvE6رƕ{Q\Dݾoߍuvw`qV\ŏ!MrķX+gfJsgϟA=tiӧQVuk՗Cj={k۷qֽjdixq/7Fy¡G:rձg[zwy]|ѧi8⢅;8䴏+[f;9͑/{씳ѤK>:լ[~ ;ٴk۾;ݼ{ <ċ+$a<妑3=zKҫ[:ܗk>vǛ?/<쭫o?~Mh jH`6 h` >PNHUVfa/ma(b&D*.v2J6.X:>4@@ DPB >QD-QF=~RH%MD9cJ-]SL5 SN=}gPEETPM>UKS^ŚUkȪ[~V,ɮc͞EvfYmݾ[m\uśW^}X`… FXbƍ?Ydʕ-_ƜYfΝ=ZhҥMFrnj֭v[ٵm˽[7Cػ} \ÍXrʙ?gtҩ_mvڹoxɟmzٿ|olD$XA .dC%NX" 5nG!E$YI1dK1eΤYJ9uO-q%ZQIuUSQd:UYWaŒ:YigU[Eƥ[.ܹwa^ aĉV㋐%Oqe̙5ogСE&]iԩUfkرeϦ]mܹuo'rqW޼4sѕC^}3u}c1wi_/yUW{ǧ?v~} <0… :|1ĉ+Z$a1ƍ;z2ȑ$K>8VÊ;~|ɔ29˚;{ 3Ѥӊ.:5Ӫ> ;NP`$,4$0`p|;)ԫn-a.ٜc wwW8& !bώ? ЛK՗{1zwAu| ^GWmaeb`Jhv΍ۊG%'("H>ZaBۏFg)Hv\w eJ &KDΆRa eZlν`z$fTp8PDb'P1'=J:)$$Ofn *b9HB _0ΦܞE)lVVx8p7BU~i}z۫jBaeAčܔhTp0 A,B2ޔݽ{o?aw-X.] pS2ʛ[з<:}2 廦#+3[OY KY A6_\4'RZoO'Bhw3ʛ[jp,6t@R=3hMŢKo{)mN,)2|y"=A*l}-cFm9J8`AH0AĂ4H~8rÏ! H0B ]ȑ F1!V B65vbƍBw&UT) OF:jUWfJRkW_t lYZǞUm[fT `ܛsF0_%0]VjWF.OiHx-ԴA=,WҧFϭaǖvݢ: eYc恌Ex!q$PN&jPڍDșy:|!p߱_?|TT:kj]ne$*¨> ".xCN ?KϾHbB QDqLL1,YlQD%N¼n& s?n>,6f-)s/  L.G.LS컽.l@*sÆZ$> P,R';:*O\RK55e NA. )cPO: J$l2i@%CڒЅ,2CtIIv7@j2VuHOCm2ohOkų a+9R,h 9&L Dn#MN}ہC`O=-kn8nͲIҩ8OJ™ H PCOV}KiM矁4術n>ZAl5N[h^L.ێ]osf / oǃ^1L5ǪA]G>]Yo)]7/iau?+w;(Xܶ_R_xv3H*\ȰÇ#JHE3jȱǏH* J"\r`<Ҕp$ϟ@ JѣH*]ʴiСNJjp$ԥHt !bAŗ90Q@"ImOpʝK]WݫT#$|(KQ w-jf4/˘3kΠN:a|X,P5ʢYˌu%?ͻ& z;JMplٱV \)fA#T;ΒiRGRlx/ϿؓHnA{ʩG@-0w)ݴKViV'V&@xVaUm<'[3h8J`J#TJA1luvډ"MKAZ OcUk=)M)M MfBƠ/}% Aa9g sI :fh18r*pJft(ROx&Z6IM^ͽ!6k.xaYJl}F+mn\bwekdHznmkZڸkCknAj~V&omjܪSݤGwS)0M|gy&"[0#%lɧmj҅" 2TamlU6dqͨY|zVme]:t*[PtL`9곙׺$r)eյT ,tmx|7qA\U߃]އ]߉89+N;9ލsݝX^/,x⻩_~ bkÚv*-o-̣}w6@6(* ls?"A 5 (HA2 nD ˺DЀDD>F!C F@EWrJO%Rsj2I RclHȐB8,d(-sN0Hat3ԑ0#1THLhڌDH%%*:Ktф$AтÐd,;А@(ԡeGsU,iA#O(B?10fQXl@RžUЪ#C"mQpҭk.޼oAnM#- `U\иA:]o-=Zas˂/؜o>?{O`u`TdtXUWPu9QIfr WN.~MH*"1_2ږyYֱ!^ hE5ZC\=`LqV艸zT>"|."eC^9&ejf5^BL~P<Y$OH%dA# QIOF%9wj;g'B:)e)ipIuw=!JGM`9e9Qk ZhCĕ!Zzi+,'ܫƖt$U`!WuȘsN6F`Mːozk孲.)ܰRnAIsXSiaW'ɍv!B:REdiF)l/ M-DӹQǐ=B'qIHHuR˓)'BU yeLMmO"qZ#(-֋3-Wl԰mK3P, ak,_ۭPFt9f K'GrMwFdiAhgF( Q>^=ǐ&9yDGu-wս׬z~׏>QGԍf 1>g֜뙸r3[`s-"W)ܗ1E/t{FOVO;) <ϞD@Kئ~iy7C&vp:EuSCBr)ށP/^ 7?$K&0!5$ ÛP9!38'4%ȇl*D9A D)|Y(EPJ9V4j ѓȆ1#Ƭ+GCxH+x?ɏ}אq! ZD+{c9Q;ܙ'5Qp ҔO%Ȟ<#l7N#Ȉ6|'tB&d2swt!)hf`."L0G`a|Ahҍ3BiQ 5ɐxjʚiT#RiOD%5K} p )ψsl llTe[ڐLT*kX1 Ή&.mbCI'QB $a0… :$HD> 1FP$%RHqH E`P$G J^V 4СDҥL:} 5ԨZ5aլ\zef*B˒70$k6!Z#u5Ipe˺{fΟ=iČ;~ yȔN93Śv"Ȉ~BT{īR|cj(M,t}V,9c‹?^23"$ "o}+n vϖ;;2;w'*:T~Ź_=$AAԝ] ma{Մy5}Ȑ(Ȣqً0Ψ}ucG ս 8`]dV ަnUhZOLZneY%c`ɢVY%(^&IIMJtQĖy![WgCh.JИ~iEZ\Mm&C:diFWF!pi^3*PsTꨦ&JJkPr lK,^뱙l> -FдԊymn-v{KnbknR};. o+oKo Vo\ / qĒ*,qg{qžq r"Lr&r*b(2Ls Vs> tBӜ30t= Vg3M:CMuN.V+^ֻ v]v@@0PB @PD-^ĘQF=~|H%MDRJ-]SL0I\N=}LMEETRMV$ TSU1U]~Vح>EYeվW\]d[W^y5X`…bcDXdʕ-Lej7[Yhҥ j)f[lHaۼ][wL׻}hn?ir͝Vҩ_Ǟ}6qCB^x޿Gdzk[_|1w^>DP> ? 'n/0C ,B,CH0EWJr1G*0jd1Gw+F}qDQGD2IRĶ6#J+{bɍFa2L1ǼO-|̿kJ2߄96RM~}kz~9O ,53PA\!P,%P-P K8I,D(,#J \' 8)*F*Q+ SL l 1;5LlS8 p "LpBB(q"Ŋ/b̨q#ǎ? )r$H&8r%˖._Œ)s&͚6o̩s'Ϟ> * ɢF"Mt)Ӧo*u*ժVbͪu+׮^ +v,YeϢMv-۶n+w.ݓQͫw/߾~,#Nx1Ǝ, y2ʖ/甌y3糚;-zϤOi:5֮_W] {6턲kέ{ۼ |8ⓅO~\9#.֯}\ܿ/MӻdɛO</>Ưt"Ё 2 tB bmء@$Xp .dC%NXE5nG!E$YI)UdҥK/eΤYM9uOA9QI.eSQNZՐEnWaŎ%SkYiծe[*ƥ[]y9_&\8_É/fc!O\yd˙b箜A.+iԩͪfMtkرe|=6ڷu0wo8'^i@= a{ -0/9sAܘT( a& 7&$  Ć`"D?.hŔ&dH| Ν<{ 4СD=4ҥL:} 5ԩR qf˜#  P]?fiW(UJ9 y5޽| 8 FjAb2P,)'<0&͐ ܠy *X6h5,Y+;ݼ{ <ĺ%CQ`L7efx}ԭHZw?>ۻWJdBI$C5D}g5td&و薌]:iEbIffפK͆ߖc[@L< cvVZmFߙih.hL8芌QYh9S :Rjmv' >|!j +f+eiCֺizj*/IPB]+T6 mNs[U`1d-%[ЬV l0Vz#O=nK_ٕMb)d^[h| ;luIiE+q_!ń-iPw-M, Z.j^f+Bils:΂=̧&+f,DL,<371sO>gu^_u`q7Z'# M9] Êl74>-x睨aX 1ܭ銖MteL[B8z뮯E7L>gwҚynz^޶hyڢ8?}GO}TW}^}{~s/~:o~ϯ@$Xp .dC%NXE5nؑ"B!E$YI)UdKAƤYM9_OA%ZhBG.eTgRQNZUPWaŎ%[Yiծe[qb[]yԊS_&\{/f}or\ٲDʗ5ob63&xtiԩUf2tӭeO=mܹIY['^qǕL^rѥOٜ'>w۹'_P;կ'}㿧__?#! TpAL@!#B*D E[LDTt4͛FsFzqH"# ,%lR$:H* ,8 2lhB@h"ƌ'JEA($ʔ*W˘2gҬi&Μ:w'РBmFڱhL4dKOR% 5jլZr+ذbU*KiͪTۖmJoҥ7nݼz/ja"/V̑qc?l2̚7sJ(䉡EYh5Sw^5زgӮtP uƽB mǗ3o9dL^|WgN=:Ǔ]o~z#ϯo>T|o{{Mǟ * !{7>h j!6] T$2)">]Q#56b9#Q(b#x$I*YՏ1ԤC>XHRKj%]%%Q)#SVFV/z&qdoFjUr :(+9f>i!w{V(AedZz}Ygrh|(Y)N.jC\3kj׭Q*Q&žfz椯,Ϻ(V)H%h^jъ;8`$ &TaC$:ĉ-6ĘqF =~|QdI'Qv$"K/aƔ9fM7qԹgO6Wd$ѢA4Zr)SBl*iTWfպkW_:u*Dzf~?QCD G!'A%J1t@H@*\ȰAJHŋ3jȱǏ#~ ɓ(S\ɲ˗0cʜI&ɚ !ɳϟ u ѣH*]ʴӊD }JՖS=Fʵׯ`ÊgֱhR=˱ڷpʝK[l݋2ƻ| L`8^XbKLei>Yf;Mt2!^ͺװc˞M۸sͻo%QNqm^μУK;سkW|mOxI+G>Prw7DuůO׾]tv}W8>|3/>}{QO:|G?~~k? k@K! ,h „ 2l!Ĉ'Rh"ƌ7Z$#Ȑ"G,i$ʔ*Wl%̘2gҬisǛ:w'РB-j(R92m)ԨRRj*˥Xr+ذbǒ,ڴjײm-\gҭkݹx򕩷/K0⎉3nXǒGl2Õ3$y3璠C.mZ~?{V-5زg#kwJw><ʗ3g⭡S|N:ֳG?_O^aճoڼ#O>?v xW" :J8!B H`B 6tbD)VxcF9vdH#I4yeJ+YtK3iִygN;yhP;c5ziRK6ujTSVz5dQ[vlXcZmZkٶuDܳoΥ{o^{+R 6|qb+9qdɓ)W˸e5w2gf1)tjիբf}ke׶})m03wpax˙7/ yҩWu/o]uw:7x1g[3_O,RAl/ $a0… :|1ĉ+Z1ƍ;z2ȑ$K<2ʕ,[t̙4kڼ3Ν<{ 4Н1=4ҥL:} 5TSZ5֭\z(رd˚=6ڵXŲ} 7ܹtڽ7^n 8-8Ō;xɔ+[62͜;{ ФK>Ԭ[:ղk۾M68u U/<ʛ{dzuױg'yAOηϴK;eǗ?~}_ݡ{G2+ =4N l"P ) 1!2.<(H$j'HH˿Piq*VDB9+OQ'R)rBkHE42ALS5l7xЋm[ @i'ZkCHm~*d @K ZY*^ibʧ+mRڡ4M?:)mfY=~w$r)=`rۯ-[W!ho&T77oA2c +F9|Оv<#\'3t\*?tuNVT3GI@mܤĜelΡfؚ!K3t,5C>%~ͪlq+T5q3 lo7^p3$0?K?G ]aɞY8*: ;cB'裓^S_7HkzjllRsAyq3M^EXݿ:0&C=NRUOmQ;xy0b b9mvNi@$XA .dC%NXE5nG!E$YI)-*cA.Urr3n#,X1A 9gȘ`h ΈZpjNh0j0 ҦV%4LqΥ[]y_u'蓱FǏ%O\e̙5oٳ\J4fIEg,ۂnZ]Ჵѵn ;ңU+͚/ n G^uٵo{ų& [W\EZtpy=As@'6R [/,bh,i:pB +;;CCqD=2@ Łd0s PVqDDP1لūRMG~+%i,qK.K0 I3s*z&6jm<T4D(4< .jsN8S5:ӌKQH#tRJ+443$5%P,PZ6T Z3OPkݱEuKvXb5S6Mi ڃjUb{!ee55*j rvhJ_Yvu]x5@-!o^*_eaHQ[Q3^Xm)vu=X^3c ;cCydK6dOl7Z(:6i.*oܝTXV`.t5g~L&Yç7jU*kUƑggmC gN2lU?& h*GCrʵ3o:=lb 7 GX6ׄ\I.()xb#F2pZ)Yݴnپ`_|vkLv/ŝԩ56[<駎ZNWtwT=-sTZtӟ:s{_>|xW)gس|~\f-J}rOqlsyQ9bw@&$T -aY=~lۦжEAyA%l1]7Zi%O Py,<`OPZxfto6BI h5Qu3Ymwi3V3T欵6筽mNN>Ayڑ0Uτ;y>PuBYMt ?q!\Ү[\q EV BdUnܢ8t.m)X}?/o>XtT7*LzuTTナBy?0O域7#nvy6oJ`bB4h d)hUY`dfɦk!8DgY/Zh?c F&PmU7L_ЛnW8 Q,h „ 2l!Ĉ'Rh"ƌ7rqጏ"G,i$ʓ!Sl%2e:yp&Μ:w'PR aF H U4iA ;_BTV䌱``֭]0j  *ᕠX-.lV٫6hV^.l0Ċ=\1KlrND/k,Q\C*cA8JU7.{TlJZ7Vh y3ҧSڷ_;x#zգT}<>yD'b#v Zj J8BQx!eaKND| "֖ G!-a82x#H8a$b|<C@]D#I*@62vNByLYjey>bB`\NMy&i'mBƦqext ƞAxzYr'() Zv~(:B:iwhZ)Ψ$jjg*ꢬ*QKjݬz++\ ;7+*kѱ^,R'-ZlתQ+ݷ݊;.ܒˤB{@$XA .dC%NXE5nE$YI'CdKgsfM9uOAUHQI4ӧ7b:UYndSan;YUd[qΥKZyزx*Fcȑ\Y2e˙s2YgСE.L_̧UojرeZg oKh@bF wpl'gͥO^]j8A9zGNuŪG{ϻVT0S/>@TpAL 7@$Ԫ = <C;qD+s%f W C 1pKFBqG{N(p 8\GtI&rJp,ILȂRdK 0 ӠfO  DCJ2q , K/4T'+ utRJ+ ș(ͷn aɓ&c,@Hr I% XAs%2&9= L:PNKYl9cCå5:!`ɬN5iU UPgYH!ʝKݻx˷߿ Lr"61Wf=,kFzd<"ͩTOO F^BF췯xqX(m\ Q7T.v%=!*Swn0#MCydG0x" '$x9J(M[=BY8̡ Ƈ>bo"ňwAH8`A&TaC!F8bE1fԸcG g|9$I3b,(dʕ/)9Ӡ. a m4OG&UiSOF:jՍ2fEJ`FO\j5ɮ]K`6ΐ13XqvB]];^@ʥk/A]}4{6Ą{6;tiӧQVukd]NָeGpb*ڝ! < ergЉ# }&泸 ?8Y 꾉?~}qԛ+9O)ÄSd0J0n4#(o* , [M41,$Py -@ rȣjQ ͹O L8,E,K)7JTo/', (P-C,+M"S=OS}Mt6D Z <;|=M.[20>dt M|S*-hAYmWa5Be5Z550' 3#3UUm؃H5,XrUmVqV\i=Nm2Q%ѷ+]߅ԥ:7^j gMXnxrx%Kηu]N32>Nc˄* / QSKWqY}#]pU CIkKMiԄze6R7mSE$S.7-Y$~FkUTQ.j"志0!-],k*)rܾ=j\p/E =utåeWӢ+5^_o>Rcw0UQ|T_.1B~}%o_Rht0BܡSQT Rr{Y u;@0kAXp[#s= ҥl}<_lRbTJ:E5< ĶA.Mܙ *(bd3.9d؇`AVS'B[LeB*hfم10N 4xaB 6tbD)VxcF9vpG#I4yɐ)YtfL3iִygN;y3JC5 @QK6ujTSV2U[flXcɖ5{mXiٶ͸m\sֵ{oޒpEo` 6|G3]rdɓ)We23othѣw&}ZiԫYvvLձi]wnݻyoÉ7~plg4wztөW~{v۹w|xYɗ}z\k~|׷?" Pƚ+D k -l Pû&PDH,ѭQ4 ,h „ 2l!Ĉ'Rh"ƌ7rqጏ"G,i$ʓ!Sl%̘gi&Μ:w'Р=k -j(RD2m&ͧRRj*֬Z.Ԯ`ǒ=,ڴjײmVطrfK.ޙv/ .̖ć+n1;Kܔ̗1k3ȜC~94jgSn5Ӱg[Mոw[m /Pʗ&|‘KnzCkߎ\N^yӳo>N>Ug8 Fz` B&J8!Zx!j!z!!8"%xA@@ DPB >QD-^ĘQF=VH%MDa*]S̎"ięSN=}TЂ-EQM>jTU^ŚUVR~kXe5VZmݾ%\św#Z}X0ƻ -|Xq^?Y2ē-?|Y3ƛ=tfѥFsj֭]J쏲i.n޽}s[56\'w9rխ_?{o}S^Dx7?|z5t|ǟ_l=$31\L@н#lB sB p "Lp!ÆB(q"Ŋ/b̨q#ǎ(r$ɒ&O<2%˖._Œ)qJ6o̩s'Ϟ> ڳТF"-H4)ӦNm|*u*ժVbͪҭ^R v,YQˢMv-۶n?}+wƸtx6/߾~|Ѯr Nu/A+,y29[V3g@y4Ҧ'c>zgծS*5ڶo7m=Q c@4#O|qΗ0 |+fp[Ƅq,{ÏW$";ӕ@}q 'P~3P}t|&䘇r#C GB1 /R"4rWل tlG }ؘG2٤-ЄD*$iyДt IcB.M fX{oYsE !B_>hB]fp]*"04Rw&gMsR^5iBV.P8Cgd9wl.ԪLrJ^⚫R՗jP*k,CҴ@W@ 7G*(mA+"^&X.:jwj]w鑨zг-s .iqPnAqK8]"gKoA*n\ڛѰCYܳ?;t31W9\| Щ|ܕ*Q'e8seAh6X:= `g`j}X`Q9ή]^1<|y:}{Ǘ?~3z-_7CH?. h:v ڔ[A :T(<r:&2ϾiqlQyDϣ$-R$5ܭȫBd.] 7.#r$NAr̂ :S 鬓=S=?񢙨$Aj0DW<) KTD-s{M;%:m&HҢF71C/MQ'5HP@iƠlU]y׏fhRT B[Y&%3,`TJj[DБ^{:mZlUS/9G%0Vu'{W}X}-,^E;mOl!0["q2Re%~KT )+.8c8]ՒeVURք-Xy矁Zhp.裑FhሢM+b68;nVW\1׬zof.wdlkcOf,ň[si]ℚU@}x#mkUbK/rk^6nsU%nrh:.x"D.D\NZb&7$B> n=Ax>.jniQBgUnq \SQաֱ6fņ.[_nt)X nN)BF`M}]qgXNhJv]%\8<4A#^C$pOL2]%RP"AxHE $t#EYeĺX="vJ͙JC{0f3O .ge(d7t~8iE6Ue/>Ik4T,u†ܮȣ4)X--[╺1Q7CIFl+_Q0b`;OyhlY.V OӞԧ@@ DPB >QD-^ĘQF=.QH%/X1I-tS&0gęSN5yTPEjR ,єRU5U֤T~VXcEQB i{M\aśW^Y<02&ѻ?dʕ-U|٭3\L1s蛒Ilj֭]Z+JA.ny\nś7.yrC}7]ӭǬ~sݱg^ɟ/"w+w_~x O?}Do@#>d t;[0B*0C pC:CqDOE,QZt1FwqFjG_qGL5VrHD23J-tdG w,H*\ȰÇ#JHŋ3jȱDž3>ɐ%0CNK8s ϟ' Jѣ "]ʴӧPJJU ϪKP1|9@`b]+*۷K.Tv˷߿XeS/ތ1g̜(@DVL7|cgϓ6qװc˞M{ Ѻ(dZkogbcƬ5ӞQc]MP9_GO-ËO|F T離/D/Fh}dgdVGPf_ 6s-o)fAY]{[ Yj !wiHcOMT .i@97{YM`36P~$cymСg)֋ btB dv^jAiW|NGLFw;)ҍ% VD5yJ(*M4%&S)F,R"MA&zQR %TUwҺ <0… :|1ĉ+Z1ƍ;z\8ȑ %̘᠂, 1E+Q|s&͓%Xq2@2w,HT'<}ΈԩBR5ɋ?g:լ[~ دC%vػeL0`'}bYL;QAr w.m3 `a Wv*>s}[6$/DZ)t@LLo &Wvt]u^anayUnh dۈ5} ӊM{2L/:8#XMcU(QR $TYfh ٶg-#}UzLiڈTNy17 +x A]T 3|0eee)ʵIߘ)dJh\uZ]yQ]mvًqIeJI9(eX6(ӎ>1j9'~5Qh&ryVУ2Z$7~8|*gKn;2[^ guo8;e('APhg\a5U؛}LǯokBbliB qx)[qzլi!lp> t+4bFv*[%j@Q2T@EDׯ^},pT˦9(jk 6=mA=~ okg~y7cՍmbONy喧{9 ݝ|6/slWag~ٰRK${CsH/RWu/T Ż|w>6p`AhA -_.H`"B& EF*8غ !a khu;4,Ⰷ"u0["DA1ThqYD ,h „ 2l!Ĉ'Rh"ƌ7rqጏ"G,i$ʓ!SlIrJ2gҬis&̛:w'РBwj(Ҥ *m1ӨRքJ*֬Zrʴ+ذ`j,ڴRϪm-ܸCʭk$ݻ@W#߿.,6Ć+v1d#SlFƘ7XY'.m_ШWUz"ײƞm6wt{En83+?Հx %h U`S:8!Veaw b8Ku!!X"W"-h݉/VNh5 4xaB 6tbD)VxcF9vpG#I4yɐ)Yt+czYgN;yhPC#$ziR.uQNzkV[vJWc%{mE[צun\sǚ{ͼ{Ӷo` kpbˆ7 *dǓ)W|,fqo SɟI6}:ohԫfha׶}7N׹yݻ6m7~9MfNϩWNuʷÞ{wy^ym~|=7^>B@ ж tk\|P 0B0Ы |HBM< QLE`tˋFpQ7ڱ&@q"H*\ȰÇ#JHŋ3jȱDž3>Iɓ(OLɲ˗0ΘI̘"o:Yϟ@ JѣHLʴӧ JjR:&̊֯`ÊKYWϖ$0C 37 ]nV [3eLP2-ÈxȕlVKLe cB3 躥zZ捚_jc1֞ۧ^( D.?>| 轮=rA(@Dg@Gzo)vﯾ?#z' ZX؀ jB\jMXZs=W |V]^F7Egx.x#@{ BVcCyBP"AaxVG& )%91=BZ FZarA #ؒ%IMw4q)$D WB e!hO1A9B(oV~I[&%`Yh#~AoX+dgN{~A:򸜜(FV`DZЦ Ak]޵LGEb&zc&Yk+Cf٫普1J۽˒RZb顚m0s -OwM~;k>z]A.PUr|LHS̓+$l+M'.Z%%k*P1=- qpP65J[gm2,- pUQ=]j7[(#T؅ghZmU#>*78Ny^,B>ݵ]v3pԖ7or'TI._7iSa-i/tv_rϛ1h,Njݪmd&'߹8î]}}5wQ=uc]bJWVł "<%xzb{*[ 4}ulTp*<)ճ[sud6x\ Wx䈸 B" Q@mJ _k$ B<ˎt*{xKȷvdWp)EfuC$:UR[ߛ6:-DqH]W!P %mJ. sZew#B8Le| Ģ![PŰ:6YcdBa(OQ'C^?XGCnr!H/7԰Rz4h'OtQEG?bzF:wH69Dh R:LfZJSQRɩNw 3$(oQYsqS@ ]6u?q*.:,8`A&D@  %pQ 2&(h#D5z0b#PyqnjW0p3: bL*@bF fqE&]gL-*Sj3ǘ]HLDnܫ ջo_zw"  9+h7F4(DNM%rJO*Ri$NS *I#躧pG D$ZMq C1 TL%"P05cr79\&A9>F RDl&.lASʽTC P2" ʩ+42%T24XL $zEL4xE`gt<{0XiV5J\T'㔠F#w֌(Mέ[٣=UVo .JG2.O){yT5߯PtV+3XvO6aA\ I΍j{tu>]Ư._Iw=;HWݎino-6NzKCzĭo/fCZJzmjBE߉襜ņ;gWzNj0MZ'׍f yamEKiWD@V̍Pͳ6MO^ IvB{* aCΐq!83 Ob ^VP_2"MtDyu᫐C p"घ1 *јF52gdfb-G=x|X-:Jtc HE^k|#x2$$1IM&h%=P'  GJUl+K5$K]e/K`RY%MN <0… :|1ĉ+Z1ƍ;z\8ȑ$Kۻ?ۿ?Asv݁*U >cF8ۄ%eaeᇩ(bGщ(ȢS*x0Rhc:_8 >>v@$XA .dC%NXE5nE$YICdҥɕ/eΤY3aL9uOA~9QF&eTRQZUYn= WN%K٪cѮe[jΥQn]w-_^ṆUǑ%Qe̙5ogЖ'ly —o~ϭh{ p#JpAlA d8 '³*pC \55-,qDPT%3<W,eFaq 1~PH ,Hz$KD2'5r2J\ ,h „ 2l!Ĉ'Rl8cC 3dL@1Ƃ4\,ydA&7x,qŊ2gҬi"ƛ:w'Р?s -j(ҁD2mĥPRj*V1 1E*_&j$J#`Qp n#njԻz;3 lpˆ3nآb.wFp*HV ͒\YkǪ ^5lֱg#mMa۸wU7h̞F۸|cG+ȢZڍb@/ov݅k~ Pcr-r8ßwʿ?'yxV*`UiXcEHAkefrW"Xbn(Љ+ M6q 14et@q(WAbS-"d_J2iOU{%!elVh䖆"V&mcl¹sibxfPpҐ) {p ayLu2_樤UziyʧLeyV*)ꛬE⫓:mtY  |`*3+8w$ &lM2ӳ9-=JqkYd`YjcF2t-V{"ԮS/tawYr[[9/&|0w ;p4#<Їk_t+/#k2֦rmQ ě e'd^u ̲?G+44]Эklqtgܴs}3]G*@$XA .dC%Npƌ4̐13\(A$I / ӂ*UHUAaG=VZqT5~%W8TĖ*RXJeb{+fZVv[54sUk.Mf;erZڂ]hx`7m_x`X7f@Wc"K!u:Rh^UȤ 8a,yǓS aDz;JdgSvcQm7{mYVy'k <0… :|1ĉΘƍ;z2H/V<2ʔb\ 3+.HfDK@0B$fX  5×RZe֭\zJرd˚=K$گj׺ 2[@7 mXW݅J6$:cBGqܲa;~1ɔJ9grfygC@ SFC2& .쇪=> 4k?|̛;@l@; pQQغCQvۧX~ u X׵՟vyu$B r@-_ ƞAR(bhb*fFtcו6ވc: rTC){ !BTJC&+V"&ZnVcbI&\ dEAymg$_[ʼnRkxUyJ(hQ Z(AfhNDVӣ&|-(9 e&姠2稦zRک*C*a"TW2TkM2T_u29kBkP|ꩨn>,JKH}Ԟ^`onD[C -F ;ܼko\}SFdI䚤d^۞ t0A +/dw 2-I}G Q[Y].cLP]Njk^ rA6`lYH'ʹK4Y$b3Vc8,0s;AN]544Q]Fpϝۣ |M| GQ!VGtמιݎ=۩+ 8؈F@G|8`A&TaC!F8b3*fԸQEAH'QTeK%]Ɣ9ċky&̝?:K/{&UiSOfպͮ_֔ȱeѦU(Uݾ;un]wbŻYj8Hܵg\ys̝G>jWv7Woq}{<ǿҏ;ˍLPA<\% -kp+ imgͻ/m@“+_μO/j|سkνׇCV?ӫ__tK_t8|g&gq)D Vh 4xaB 6tbA°xcF9jd81!H"xeJ+YtfL3iִygN;yhPC5ziRK5 cTS8Rզ[vlXcɖ5{mZkٶusJU5ַ{p` 6|qqKuXoI#+|sf͛9wthC)C6]5d%vvlٳi׶}7f"On֕s7~yr˙7wqcYZDϹw|xNŻ6^~|׷_= <o??%T - 5m M<U\ŵ:1 [uܑ!zFdĮƊ*$\& 1ֲ,ܒ. <0… :| 1ƍ;zX`H#GJx1ʕ,[| 3̙4kڼ3Ν<{ 4СD=4ҥL:}ӤE Z1ԁ%b 6رd˚=6ڵlۺ} 7ܹKMĊ7oG.LI7 >8Ō;~|/UIVȜ;{ :ѤK>d[_L2Դk۾;ݼ{Vڵpes;̛;=t[赯ӻ{>/~=}v?7>nn_H``XRU~mq NHa^a-8Yq'!UiHb&b* !k "ζb6ވc:Q/~{3cFdJ9T4.IeV^}8`A&TaC! QpD1fԸcGV4(I&#TeK/aƔ9fM7qԹgO?:hQG&UiS3M8jU QJ$S_;lYgѦUm[oUuUwοMI,QL0̬PYPiq9\ƭ4Q!,#$oY1DR)?H*\ȰÇa(ŋ3jȱGA)2$ē(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴiĉ?JJU’Q b괫ׯ`ÊKٳhӪ]˶۷pbY]WMf]5߿ LÈ+^8\w#{$þ3k̹ϠCMtQ%Jk˦c˞M۸smx.1:6ȓ+_μ7{'ËO|`_q^˟OGvU߁& 6 Q6' q|=v aJUv݀7b,0(cY+4:@)DbӍ#Zq<.YPF)TWNJuY`)@@ DPB >Da\ĸPł;VRH%MDRJ-]SL5męSN=}TPR`RL>UTU^ŚUV]~EfutbݾW\uśW^ϚimѶIXbƍ?YdB_|aጁ?-VteҥMFZj֭]+<@i.;hhڣ_\pō8Xɋ_|߯qCI0[K?D0AdA 1-<%sC?1DG(L"-ß<=3L1$̾ P#]Ұ+}r.ͤN;3LH*$ca@t8PÉ-FhDC#B Q\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧ,Un4(!ī&jH5+PfJ5ٳhӪ]˶۷pʝKݻxےzpɫ}5fd+X ˸ǐ#KL˘3kIV\ G̺װc˞M۲.ݷݨE捻ȓ+_μu^\ ËO֣v~Z؇kϿVuY5wmE_߃F(Vha7 I]^`-hv^h(,Tj`|cD#F| @)Di8Ѹ!E"cbFViXfr!i|x҈.E%Trlo[٥$tvJv&*蠄ʜs4բ9Mf"Rj饘f1@@ DXFB €HC'2PQ"F'jxQB?RJ-]SL5męSN=}TPEETRM>G(MrrԞYMF8IQ͞EVZmݾW\uśWKc&ɵ/яA5|Rbƍ?Ydʕ-_Ɯ.bXlQׁA՜Zj֭][lڵYVI$N 'mōG\r͝Cŝ;zT lݽ^xR/%7ǟ_~Olj;8нF A0B 'S JؒO BOD1EWd<>KO& J$JlG2H!BT&E-$#4  \P`N/aH3D3M54Pf1%?.'w >'MEeQG9D@IzOG 41A`j xTSOE5(I:+j༮΍<P:̥TUa%Xc_ <`„06<0Å+Zhq"Fn2H 2$,FBAʙ|ђΝ<{ 4СD=4ҥL:} 5ԩTZUIGJ"X5+ŴPx!b 0V@2"yL8DL R\ 7a߷q)f 'p 8Üg;{ :ѤK>:լ[oL;VNi_,έ{M_~|WW8yB5/_V" 7^M˛?>ۻ?>sv󗬈_S1wXaeY^ZǙq  va҄AFqs'_*b.c28_o<kU=[UmcF 0Dto!naMTܒ@c!yqҹ%ffjfT%fIOHVDnxV'E/M&%gEڜWnYNyPQea&%]> uJjzYue ~'Dz|2#VrdUa)R$DZ䝱 兊Ԭ[&yinm~ nJ/EmRPVx߮b .S۟C)`-k_.UCU5-Aeb)9 nWqA]ưzD0[5 }} ԐbЪPbFKJPp桛v )S j~ږENwo߿OpՏg~8Ũ}u:jP;3 \ 9Aʾf3i-T ] #9npOCb6KCLR%[\88T,R ,[iB1s MjLE6arD5A/R4:qCMTQ&,ȯ8jԡcO^4(%jJ/̘IONM ^]TYīJ'#MJIk%ĂR *"!5Ճ4k)435b]<̳ɼHuP+ՄeM.N4HGQ'{NBXXN IE7>Jߞe(ߘZ HބdBN' 6PfF駡nRekiޔYZ̮[z&.8ARv3&;9"_A8׆Ni$Oc3n/;텞qVՎ}T+;R%EVwy <{*n%/ԃU[hC#sF ǴۅPرZp2JǞz[eW0!ɻP[tN7-PdG Բ- trF}YWBX$= k0Js[ڀlfrNtYU F}ףZ=jR2͌Y:|>03_Abg]#Ej|+i Pw.mO4!ltPmuXDz(K;,+0iKn ?Y#rSEAr)a1y(ڪYCL2ʓ x2x 8 [C : Y C}Ax!j8v!J8 ")bp'FaW5"5x#Ix.(#A 9$&}1ZX$M: OJI-FבSj%}P@v9&eibDl&qfzry')љg{' 'wYz(cF~f(J#nj"4Tz)Xz*DإY%WH3*.Z +Jũ"iEگyBVZJ;c϶Z25ҏz߮,L؊{.fkiHbI8`A&TaC!F8bEadqcGA9C),eK/aƔ9fM7q3d(8BB'8@Cu@  ՘4+ 8;lYg-Dm۵j1ft{pUa`YҦ$;paÇp1G'|rF``r (@aLe R+HzubU@.T/LN:2AN7qU0[׿ٺ P*+Ďj9bJP ) 5i)׼k/܋M@|MD`e QʫqQ! R!,R;‚ Qd%ct J +R-- K$ #nEТi=83tS='̰O@IrS\|POB!QB }*6,h*2K1=(#MUU}?XXQ<5[4ʧ**T4EM J9x4,Y `sosՄZ6Mܼ섮rMEwJpސ {S6R`Ob/s4kZv'+6̳5nt!k`f8#ۛ $seߕwyYT5eVC&vd矁.(_TUO+/l2r<͇yA+Ӊiiv F5TpG3mswQjkO^y*]'zգNaCMo[ޱUn'|ν[^~ʻY+NV:y{j@}5h 4H(TH`[\T6 lYX L @ mOVb怄b7RF5ȖĹ%k6 WAO#,yDl6lBQ|0L'Cb"-=(|!Ry"<87Y2* {Dt.4Ӣd*I a$d-jgf̤ J(R?Qt :uXX r- p "Lp!ÆB(q"Ŋ/2#G0: )rdF&OA#4^Ɗ.a L@Ӧ̝7_HfÙD ӧ`h'B,oˆ))PԂIǢ,1-۶n+Wڹvjy6}ڲ`Y/qZՊ_++y2ʖ/cάa޺z,:mp_x6W0\(4@ J5}&hupၨ7:`w-aݖ6};ٻ/~<ϣ'yۻUdL󕑧ӖYzYAgϹF|­$]}61|{X'+rw,G"ǓUm:V.uD]O\YA}$YLyN=Q7dqE6%`IwBjm8gT&k٦o)\uXdg0OuՓmuW{y(t`VWKFkcWQBoiqzڪ)Z4i$]SKSoJagBNWT\.h: N.Yh F,W.[[n{bn⛯)ټ/%0d0 3ܰÜ嵙OU| ejuo!k|2/bp772뼳?mBs}4I+ݴO93EC}3U{5[sRZ*e@$XA .dC%NXE albG #pBB`P00ʖ!!!H9uO7II7 fS6qFZUYnW9Vҍ dRe[/kB-]yK(ZLU9wU/fcȑ%$I5I6&M3L(l&a`Eٔ#I0A$sL2˴mEnϣ?X>}R/Zc-H#Ǟ\X"PpQ4c {ٹǐwVb-QiÄ^D߆(9Q%;أ? Bͩt4ZZ'P+.@ g@bCjI#0aLhЍNۓ6Z٥A\sYBgLM@өug[w@ _|W)pjy"%hN9}uhy9YJڪRzF`Mh2dؑTnv(wP*5 rպXAN )7gϢ)$ME[n[Z"{m̲o8YZ,B(v4LwIc֛O=<ۤmiE,8cUoQ0hp['.A-K'2#K;%P1,^j~3 &2vӰLcGc9jV[4B^[w㝷\9CDG*ӄ G@c 92KtS5ƕO޹/ߌszc<]$o3#>{{e׮N 4xaB 6tbD)Vxcƈ08vq #I4PI+Yt˔1iքǏ.sLC5ziRK6uN zUU[vkX8{ Xkٶun\l֭:WZ{۷_H|aŋ7v2ƺ$e͛)fBϡI6}uꆓ9VVmtkهc϶mݻy}Toj[ə7wrOu'o|xuݵޡyg~|Q緯{sn+@LlA"|P@  5ܰ+ C@ QI<3DKk`m/oLG p "Lp!ÆB(q"Ŋ/b̨1!? Ȓ&OLrG,_Œ)s&ͅ.k̩s'Ϟ> *t(Q7"x4)ӦNw.}*u*UQbͪu+׮^b رf-v-ۜj+w.ݺv'3޾~G ,!#NxqŒC:~,9ȓ/Ŭy3ΞZ1Va&lz5Y֮_Î홴ƵoD-mܾ5-|85Fn;A^|x`.?^yկw>7o?]6kMW+\0)cP<!L -C08찱A 4MTlETlBH*\ȰÇ#JHŋ3jLcǏ C*(ɓ(S\$˗0cʜIs˚8sɳϟ@ JT͢H=MʴӝKJJdԪXjʵׯX}*vٳCˢ]6ڶpʝK݉o̫ߑ vwÈ+^\0㐎Ky尗3k̹ʞ#MҨkNͺ~W({msͻSk8BƓVμ7꺯cν{f{Io-~<ӫ_=gx!h` .hWF(m!t]Zn@$XA .dC%NXE52G! vYI)U,IK1eΤieM9uOA%fQ&eϥON1jUYnׯW;٦eѮe Sm[qΥ[Ʒw_/D  4@DpA #pB MB S 3CCtCK\ħ3qE[t1%_1SqFw <0… :|1ĉ+Z1ƍ; ãȑ$K<2ʕ,[$ș1kڼ3Ν<{ 4СD~ i4ҥL: i4Z5֭\z ve԰d˚=vUUѺ} 7ܹt޽|*m[ >8Ō;~S![9͜;{ ڠd+>:լ[~zҦa۾;ݼ{.);)ڿ?<7:xԫ[=vHG=@˛?_ѻ?Pߦ}{o~ؙ> . |6b]r 4xaB 6tbD)VxcF9vG#I4yeJ+Yd eI1iִygN;yhPCYiRK6yiAQVzkV[vrWcɖ*Zkٶun\s7{o^6p` 6,aŋ? 5qcɓ)W|rd̛9wfϣI6}ujիYC]ukٳi׶}wn`A_xpÉ7~oʑ7wztө+dzu۹w<0>LJ7}zٓ,}{׷x|;.o2 <0… :|1ĉ+Z1ƍ; ãȑ$K<2ʕ,[$̘4kڼ3Ν<{ 4СD,4ҥL< ԨTZ5֭\zU9رdˎ Kٵlۺ} 7ܹҽ7^v 8 Ō̚ɔ+[\92͜;}UѤK>,Ԭ[]ٴk۾]X6ݼċ?<@+=ԫ[gܻ{>1xy>ۻy^gۿ?8`HdZ r 4xaB 6tbD)VxcF9vdH#I4yeJ+€2K3iִygN;yhP5e5ziRKuejSSVzkV[lXc~jlZkٶun\hֵ{AL2Mp`+ X 0.5 )W|ٗ9wI! 6 ㅄ/$Ze0@|}wn GGA2ل%*NkЩW~jq۹S.{ٵ~ ӯ~|"Ϸk}}p k2\k,; "P,H:2SL\ڐa /XT jo i+OF"QiK#O$\Ү|ʏiʜJ3`6,-0^[VQ.Ɓ ML,R  Q1PX(]F}*s&q10DPNس¸4S<]GܴKV#]aМ ,H-Z׉Y3VM~B֍c"E>Kaa-uޙgx&[ /B-]LDWX r.Ґ:^:! Wg@Ȯz!S:+H*\ȰÇ#JHŋ3jȱǏ CI O$ɲ˗0arfG6 &0y Ha` E]Z &UIU`(*PV]:Z'X_OzdשL59߿ LÈ+^̸1M!;LrƜb|2rgkAVh]LhUפZ>֨Um.dnvmaq3KNسkݱ䈟?ruC QkTnWnp@x'aenQ\At~=yVhfaz0lHއ$^u'Jz#64Tot 'V @½'2 WhhWDl4*$dDKWTViXa\*Ԣ_v)&c)JWg[Z^pY)iT=)S0p9'm:6PF*&^}vhB䘘f馜&vf9ѧZSڑp7DqԍΘdsJZx[*㟷*½,]zO6iv n,_pjV쪹ym'%zqU^ˠW&)[$P %,SQ֗VB/}/1k(<*[v^8MH-Kb7oHYC &UZn!_OOF7I(s&մ ]}5mhsڇTl du tsf`y &s&W"_j*Pm騧.ߪDŽmaGdwN&wC!NԪ'7QΟPncN{Ô=D=IpPx3`K&~oΏE/{>}`Ʒ A`H=tyY˄ p̠7z[bB2#Ṡ!/Ѯ8̡wolh/% wB00)TL92="ef(@qn=̢@@ DPB >QD-^ĘQF=~RH0`P$`C#4BA &](䊁N ͕>aHĥFTiPiPP243LSRZ?ThiĖ$K1oëUKX`… FXbƍ?Ydʕ3}\+^]9*R 8쉴qQ$U5ASH@,_hWG<7 SN8Z"f˝-rW(6jC͟G^zݿ?|ǟ~|#jF믏Lɪrjm+Э-~+H s H6@Ä"G uQa%XcEv^[6Y [oU"* 15(Vf>pi@69$3,;Z+PKLp[7r j=uYY YF8af;~劺^F@u]p`s9>\s[EϓҸBrQ^zW-}1|Āu∇&hFcCsNIƣK>T57r=3Ӑ]͒]^nLjv]9٭gaxno<%o:`"*ARdF׮ϔ{lnmqU֞>|Ǿƶ>xݼDZՃ[%l;T z.;ĭ&u~OpR fR3t]6ǗrUn6<Ѐe7)>srܫ|qsoSXNӭ8W.V7 *X3Ƀ!!~LiB.0.$bxJ~+ϵA#z]iI1 jnFQzA9u8A@.(̢/@oJؿҼmLW0'ib'HNђĤM6x̤bT6&2G(+~"ae(e9KZOHHqK)_WKyDL WHS{fg瓛 ~ᚖ9O&Iry*AysbcW5+֛pAeʉL% <0… :|1ĉ+Z1ƍ a`( &B[zt`` .=(8DM7#z4С 5J4ҥLN `:UjbV[y@' rSlMO="lK'],,[fwꂁȚҮUwqŒ[g۱1Bv)Y`^z :ѤK>:uƮm0݄y[X Kf37d:8iU? ?<9B]\DO70oˊ `3xݿL*>ܬKo{o޷A%Rn,ug[9@Swi]݇Gi6R}'&]~b"Hbi s"gy}ѧ@9v%XcB:Eu$>.Xx~nUt,ɧ`^]cRF!5:YPAle٥God hJhzl%V'ByMx\nD=ZݒF.m j BxCtDck8h 4[o}\1^Dz8_5 iAN*NKm^mBElz)KǢf =nA )K,X#mSkmXߟ(D>zw+ K]Ox {԰&r* uyT,B!6xť-*F)>-}AS@pafe 3.ϛ(_jEԱ8Gl}d= irMtvߍwIn~_G-zu᢭n)Њ?N""m5'.S¹lK1o\Kϧƾ8+0Aʊ>2]:O|%y,C)V1-{]'ni55.y[Dj'}0ϬKXkIZ>bkl726*pIR]P3~ 9ɔ+[9Fs؉32m3Pi=Yٴkoݼ{ <u6NNj_?e˿?-ڟ_8VaH` .`!؜N^YHanaaȡZHb*b(b2U5Έc:ۍcBdJ@z= eRNIeQ"dZ%S]n fbQ}If9j gr*mnΉpug~R 4xaB 6tbD)VxcF€dȂE4yeJ+Yt#I&eδygN;yhPCX(GI6ujԁKNXkV[vlخTŎZmZk[m\sֵ{/Wp` F7obŋ"qdɓ)W|Y1wfA6}ujiImvlҖ}wnݻy+wo}jxr˙7.z6tөDzu۹w.qoamɗ{Xwf/}|+w~}021C'|%t*ù.i =0(E<1+]|D߃dTu ,h „ 2l!Ĉ'Rh"ƌ72ǐ"G,i$ʔ*z%̘2gҬi&Μ[ɳ'РB-j(ҤJ2mџP_Jj*֬ZFʵׯbǒ-k,ڴjײu-؏pҭkw[y/;0ĊkEX.Ȓ'Slr[l5c[g9.m4ԪNz5}_C-6ܺw~V%‡d)7dm;e9ҧg>95b_};qǓ5 ?a~? 8g]e R6X* Ju98!`z!![{%Xq"ن"1Q8#b= 4xaB 6tbD)VxcF€dȂE4yeJ+YtrG3eIfN;yhPC5ziDIo~djTS yYvlXcɖAiٶuՙ^µ{o^{[-` N*W0Ć7vrdɊD|sf͛7#\<th <ujիY,l׳iÕkvnݻyQ࿉q˙7wϩWHt۹wɗ87{tٷw\<]{~~Kг;R|Ÿj 5ܐ=E> M<*j#em@QkQ* }N!#+ȐDiI p "Lp!ÆB(q"Ŋ/b̨q#C08 YУȒ&OLr%K$[Œ)s&͚ _̩sgH>)(QB"Mt)Ӧ:5*ժVbu+׮*z GɚMv-۶+w.ݺvuw/_y,RX41Ǝ1;'[ά9!͍{ :4Ҧ;|z5e[æ:Y]{wj}⿉;a̟C Oe2}zo~=v;bs_gt}z.Ͽǿ_~ !l+P/ͣ!P ) 19DL<A<QKYlS14i yGmѳ ]QHŎLR%#ʌ.' ,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$J0`l%̘2 i&B8wQϠB-j(ҤJ2-Y)ԨRE>j5լZV+ذbǒ-ka׳jL˶۷r_Ɲk.޼zY/`L0Z3n1䥆#S:2G1?3ТGWLͨ3T:oײgӮmۧۺAMSkfc /n8r߽3g8->:>>rfֽ'U<<^yݿo6~O_;}Ņ_ *`v2I`j!ir蘇ՍX")H+ie:@@ DPB >QD-^ĘQF=~RH%MD-]Sf3mDaM=}POEETRM>TUIJ5gDZpWe͞EVZ"öw[H>\yރy'X`… Jb7v _gJYYfΝ=^h˘I4 餗5f[lڵc(n;ōGpG2wn6E9m]vݽ]>azտ_>\buA/@$' @2ksB /DoB S0: 3rCB OD1E*qZ(?lkF]1G qGz 3D8 ʤqgϗ@ ͹4ʧRRdI*֬(j+ذbǒ-k,ڴnD .Wд-ϤI;pn]n*]W+[-r]1Ɛ'Sl2̚7s8#,<!ݐn `pZWt 3ϸKm‡/n8kS"  " ACclz\Y+ !(o+Y9yD f#Q*W|E[0zv:eF@׌qD+g_<+HZG? 5߁w 32JC{}Ow"]B/ D?|<_?(z_bn )+kc?p~3ݤu;Jnt &8+Gk˜9=0x (ʰ6!*F Z8%;EOk @ }""^\ @r)\":Æ& @H*\ȰÇ#JHŋ3jȱǏ CIɓ(€qq  XSK F9 ΄eЅ;](H(LMa`' Z`ҥ;O0+S NeHΩw 5{5T!WL#ˆ+^L0ǐ#KL˘3k,Y0^H@UM:y z ` vBЦ]t@i=ӫQ3|PvB.8GN S9zL^Ӌ<˟O'FtqٹBhWp9q75s7 C6V #paB fgiz!Z(J}DiHⅆF41Z"hrH\WTM0NZyW%5 AC}yyEUeyv_Jg[hZV䒗 裄9 餔Vj饘fZآW'B;1bO-Jjb^HJ+@teG*[z&Ъ:kV*'U4ܭވlP(bxv+.}l4qۚ&ڨzILۧh ыXz:(ꟊ^;n`gw q"?Z%\Ei.,4ל6U23C0dBmH'Jc.ܴ@LO]_Vg\C*uW_75ꝍleemКPGvwݨ5|߃w9,8yY7o9͒bG~yW7 4xaB 6tbD)VxcF9vdH#I4yB0RtfLWδy!K;yĨgPC5ziRKjT"NjV*vlXcɖXlZ1Ѯ5 m\pֵ{o^{@a%|xaċ7vr_ő)o\d̍5oth{/6-tΩfvlٳM}{m ].wpÉ{]Ł'ytө[^rױ/|xNOj'?ܼ煮g~|O>x}2 дw\i3A 0* 9CPC&|Ct <0… :|1ĉ+Z1ƍ;z2ȑ$K<0Ō;~ Ȕ r2ƚ7{ :轗G|cyW~ ;&KӾ=6w;=.km<-C|9ؗr>N'n^B׳?|N}mhڀG`y .` f a{^a!!a>!N:@@ DPB >QD-^ĘQF=~RH%MD-]Sf3mDN=1TPEETR%k6UȧS漚Uʭ]~VXe#V5VmLku&\uśWޠm,o`t hbƍ?Wqd[W9sc͛=ZˣMK>ݱs꼫Y[lii;n\pyGˁ'tխ]~z͛3pjx͟Gϖ|zA{Εǟ?{{>@Dd |iB /0CpC )B>0OD18T_1FgFo1FZI'H*\ȰÇ#JHŋ3jȱǏ CIɓ(€˗0c,͛8sɳϟ@ sѣHKLʴӧPJJիXʵW[f*pسh#M˶۷pʝKeغx>W&Pk nxÈ+^.Ɛ#k-,٣O+kyϠC1xMaէ_ÞM۴UmU7o9U&-{ȓ+[|s]ֳkΝ{1~r7n!ѫ_Ͼ}㗅{<`yϿם}(T 6n!x FxTfMarzX#h텈"n*j$4X6u2R8`A&TaC!F8bE1fԸcGA9dI'Q*#eK/aƔYpL7ĹgO:}:hQG&UiɚMF*T9fժrkW_;lوUͦUZ@Ƶ Wn]wջ7h[ &]‡'FqcǏ!UANXfϟAhӒOw:j֯aǖ=diڷGƝ}>gő?<^xr͝G>e՝/'~RN?v ~^zǗ/׷/S~ Mp,/l6 B#l 1̐35$l;I'H*\ȰÇ#JHŋ3jȱǏ CIɓ(€˗0c,r͛Yɳ'F> JѣH*]ʴdͦPJt՜WjUׯ`ÊKlĪfӪvQnڄ+ݻx-߿ . #^̸ǐ*Ly 'cnyϠC{yiɧ;vNw5װc˞}4#mۮ Z7<+УKU9u։?t;Ëjw}|ý~\IϿ(h&8xWF(| Vhfvxy N蔈$h(蛊20(4R^] 4xaB 6tbD)VxcF9vdH#I4yeJ+YtfL#ayg΃5uhPC5ziRK6u$OSJzkV[vlXcZmųiٶun\sֵ{WcMxp` 6|qYerdɓ)W|bA5othѣItΩYvvlٳUmݻy8&~yr˙7w/sΩW~{У|x'ɗ}6zٷw~XEs~ߜOd ,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gaM: Ĺ'РB-j(ҤJ2m)ԨRyjD9r+ذbǒ-k,ڴjjڸrҭk.޼z{.Q~.l0Ċ3n@Ȓ'S2̚7s3ТG.m4ԪWn5زgӮm6ܺw7‡/n8ʗ3o9ҧSn:ڷs; Ǔ/o< p "Lp!ÆB(q"Ŋ/b̨q#ǎ? )r$ɒ&OLr%˖._Œ)s&͚6o̩s'Ϟ> *t(ѢF"Mt)ӦNB*u*ժVbͪu+׮^ +v,ٲfϢMv-۶n+w.ݺvͫw/߾~,x0†#Nx1ƎC,y2ʖ/cάy3Ξ?-z4ҦONz5֮_Î-{6ڶoέ{7޾.|8Ə#O|9Ο@@ DPB >QD-^ĘQF=~RH%MDRJ-]SL5męSN=}TPEETRM>UTU^ŚUV]~VXe͞EVZmݾW\uśW^}X`… FXbƍ?Ydʕ-_ƜYfΝ=ZhҥMFZj֭][lڵmߞ;PK HAV9l9l"OEBPS/images/_http_compatible3.gifGIF89aߟwߟ߿wߟO߿ߟ߿wOwwwwOwwwwwwwwwwOwOwOOOwOwwOOOOOOOOwwwwOOwOOwOJ1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu!?,H*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sϞ: JѣH*]ʴӧPJJD jӪׯ`ÊKٳhӪ]˶A&궮ݻx˷߿w+ta+^̸ǐ#K.A˓3k̹ϠCvYi邧G^ͺװc>imgͻ/m@“+_μO/j|سkνׇCV?ӫ__tK_t8|g&gq)D Vh 4xaB 6tbA°xcF9jd81!H"xeJ+YtfL3iִygN;yhPC5ziRK5 cTS8Rզ[vlXcɖ5{mZkٶusJU5ַ{p` 6|qqKuXoI#+|sf͛9wthC)C6]5d%vvlٳi׶}7f"On֕s7~yr˙7wqcYZDϹw|xNŻ6^~|׷_= <o??%T - 5m M<U\ŵ:1 [uܑ!zFdĮƊ*$\& 1ֲ,ܒ. <0… :| 1ƍ;zX`H#GJx1ʕ,[| 3̙4kڼ3Ν<{ 4СD=4ҥL:}ӤE Z1ԁ%b 6رd˚=6ڵlۺ} 7ܹKMĊ7oG.LI7 >8Ō;~|/UIVȜ;{ :ѤK>d[_L2Դk۾;ݼ{Vڵpes;̛;=t[赯ӻ{>/~=}v?7>nn_H``XRU~mq NHa^a-8Yq'!UiHb&b* !k "ζb6ވc:Q/~{3cFdJ9T4.IeV^}8`A&TaC! QpD1fԸcGV4(I&#TeK/aƔ9fM7qԹgO?:hQG&UiS3M8jU QJ$S_;lYgѦUm[oUuUwοMI,QL0̬PYPiq9\ƭ4Q!,#$oY1DR)?H*\ȰÇa(ŋ3jȱGA)2$ē(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴiĉ?JJU’Q b괫ׯ`ÊKٳhӪ]˶۷pbY]WMf]5߿ LÈ+^8\w#{$þ3k̹ϠCMtQ%Jk˦c˞M۸smx.1:6ȓ+_μ7{'ËO|`_q^˟OGvU߁& 6 Q6' q|=v aJUv݀7b,0(cY+4:@)DbӍ#Zq<.YPF)TWNJuY`)@@ DPB >Da\ĸPł;VRH%MDRJ-]SL5męSN=}TPR`RL>UTU^ŚUV]~EfutbݾW\uśW^ϚimѶIXbƍ?YdB_|aጁ?-VteҥMFZj֭]+<@i.;hhڣ_\pō8Xɋ_|߯qCI0[K?D0AdA 1-<%sC?1DG(L"-ß<=3L1$̾ P#]Ұ+}r.ͤN;3LH*$ca@t8PÉ-FhDC#B Q\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧ,Un4(!ī&jH5+PfJ5ٳhӪ]˶۷pʝKݻxےzpɫ}5fd+X ˸ǐ#KL˘3kIV\ G̺װc˞M۲.ݷݨE捻ȓ+_μu^\ ËO֣v~Z؇kϿVuY5wmE_߃F(Vha7 I]^`-hv^h(,Tj`|cD#F| @)Di8Ѹ!E"cbFViXfr!i|x҈.E%Trlo[٥$tvJv&*蠄ʜs4բ9Mf"Rj饘f1@@ DXFB €HC'2PQ"F'jxQB?RJ-]SL5męSN=}TPEETRM>G(MrrԞYMF8IQ͞EVZmݾW\uśWKc&ɵ/яA5|Rbƍ?Ydʕ-_Ɯ.bXlQׁA՜Zj֭][lڵYVI$N 'mōG\r͝Cŝ;zT lݽ^xR/%7ǟ_~Olj;8нF A0B 'S JؒO BOD1EWd<>KO& J$JlG2H!BT&E-$#4  \P`N/aH3D3M54Pf1%?.'w >'MEeQG9D@IzOG 41A`j xTSOE5(I:+j༮΍<P:̥TUa%Xc_ <`„06<0Å+Zhq"Fn2H 2$,FBAʙ|ђΝ<{ 4СD=4ҥL:} 5ԩTZUIGJ"X5+ŴPx!b 0V@2"yL8DL R\ 7a߷q)f 'p 8Üg;{ :ѤK>:լ[oL;VNi_,έ{M_~|WW8yB5/_V" 7^M˛?>ۻ?>sv󗬈_S1wXaeY^ZǙq  va҄AFqs'_*b.c28_o<kU=[UmcF 0Dto!naMTܒ@c!yqҹ%ffjfT%fIOHVDnxV'E/M&%gEڜWnYNyPQea&%]> uJjzYue ~'Dz|2#VrdUa)R$DZ䝱 兊Ԭ[&yinm~ nJ/EmRPVx߮b .S۟C)`-k_.UCU5-Aeb)9 nWqA]ưzD0[5 }} ԐbЪPbFKJPp桛v )S j~ږENwo߿OpՏg~8Ũ}u:jP;3 \ 9Aʾf3i-T ] #9npOCb6KCLR%[\88T,R ,[iB1s MjLE6arD5A/R4:qCMTQ&,ȯ8jԡcO^4(%jJ/̘IONM ^]TYīJ'#MJIk%ĂR *"!5Ճ4k)435b]<̳ɼHuP+ՄeM.N4HGQ'{NBXXN IE7>Jߞe(ߘZ HބdBN' 6PfF駡nRekiޔYZ̮[z&.8ARv3&;9"_A8׆Ni$Oc3n/;텞qVՎ}T+;R%EVwy <{*n%/ԃU[hC#sF ǴۅPرZp2JǞz[eW0!ɻP[tN7-PdG Բ- trF}YWBX$= k0Js[ڀlfrNtYU F}ףZ=jR2͌Y:|>03_Abg]#Ej|+i Pw.mO4!ltPmuXDz(K;,+0iKn ?Y#rSEAr)a1y(ڪYCL2ʓ x2x 8 [C : Y C}Ax!j8v!J8 ")bp'FaW5"5x#Ix.(#A 9$&}1ZX$M: OJI-FבSj%}P@v9&eibDl&qfzry')љg{' 'wYz(cF~f(J#nj"4Tz)Xz*DإY%WH3*.Z +Jũ"iEگyBVZJ;c϶Z25ҏz߮,L؊{.fkiHbI8`A&TaC!F8bEadqcGA9C),eK/aƔ9fM7q3d(8BB'8@Cu@  ՘4+ 8;lYg-Dm۵j1ft{pUa`YҦ$;paÇp1G'|rF``r (@aLe R+HzubU@.T/LN:2AN7qU0[׿ٺ P*+Ďj9bJP ) 5i)׼k/܋M@|MD`e QʫqQ! R!,R;‚ Qd%ct J +R-- K$ #nEТi=83tS='̰O@IrS\|POB!QB }*6,h*2K1=(#MUU}?XXQ<5[4ʧ**T4EM J9x4,Y `sosՄZ6Mܼ섮rMEwJpސ {S6R`Ob/s4kZv'+6̳5nt!k`f8#ۛ $seߕwyYT5eVC&vd矁.(_TUO+/l2r<͇yA+Ӊiiv F5TpG3mswQjkO^y*]'zգNaCMo[ޱUn'|ν[^~ʻY+NV:y{j@}5h 4H(TH`[\T6 lYX L @ mOVb怄b7RF5ȖĹ%k6 WAO#,yDl6lBQ|0L'Cb"-=(|!Ry"<87Y2* {Dt.4Ӣd*I a$d-jgf̤ J(R?Qt :uXX r- p "Lp!ÆB(q"Ŋ/2#G0: )rdF&OA#4^Ɗ.a L@Ӧ̝7_HfÙD ӧ`h'B,oˆ))PԂIǢ,1-۶n+Wڹvjy6}ڲ`Y/qZՊ_++y2ʖ/cάa޺z,:mp_x6W0\(4@ J5}&hupၨ7:`w-aݖ6};ٻ/~<ϣ'yۻUdL󕑧ӖYzYAgϹF|­$]}61|{X'+rw,G"ǓUm:V.uD]O\YA}$YLyN=Q7dqE6%`IwBjm8gT&k٦o)\uXdg0OuՓmuW{y(t`VWKFkcWQBoiqzڪ)Z4i$]SKSoJagBNWT\.h: N.Yh F,W.[[n{bn⛯)ټ/%0d0 3ܰÜ嵙OU| ejuo!k|2/bp772뼳?mBs}4I+ݴO93EC}3U{5[sRZ*e@$XA .dC%NXE albG #pBB`P00ʖ!!!H9uO7II7 fS6qFZUYnW9Vҍ dRe[/kB-]yK(ZLU9wU/fcȑ%$I5I6&M3L(l&a`Eٔ#I0A$sL2˴mEnϣ?X>}R/Zc-H#Ǟ\X"PpQ4c {ٹǐwVb-QiÄ^D߆(9Q%;أ? Bͩt4ZZ'P+.@ g@bCjI#0aLhЍNۓ6Z٥A\sYBgLM@өug[w@ _|W)pjy"%hN9}uhy9YJڪRzF`Mh2dؑTnv(wP*5 rպXAN )7gϢ)$ME[n[Z"{m̲o8YZ,B(v4LwIc֛O=<ۤmiE,8cUoQ0hp['.A-K'2#K;%P1,^j~3 &2vӰLcGc9jV[4B^[w㝷\9CDG*ӄ G@c 92KtS5ƕO޹/ߌszc<]$o3#>{{e׮N 4xaB 6tbD)Vxcƈ08vq #I4PI+Yt˔1iքǏ.sLC5ziRK6uN zUU[vkX8{ Xkٶun\l֭:WZ{۷_H|aŋ7v2ƺ$e͛)fBϡI6}uꆓ9VVmtkهc϶mݻy}Toj[ə7wrOu'o|xuݵޡyg~|Q緯{sn+@LlA"|P@  5ܰ+ C@ QI<3DKk`m/oLG p "Lp!ÆB(q"Ŋ/b̨1!? Ȓ&OLrG,_Œ)s&ͅ.k̩s'Ϟ> *t(Q7"x4)ӦNw.}*u*UQbͪu+׮^b رf-v-ۜj+w.ݺv'3޾~G ,!#NxqŒC:~,9ȓ/Ŭy3ΞZ1Va&lz5Y֮_Î홴ƵoD-mܾ5-|85Fn;A^|x`.?^yկw>7o?]6kMW+\0)cP<!L -C08찱A 4MTlETlBH*\ȰÇ#JHŋ3jLcǏ C*(ɓ(S\$˗0cʜIs˚8sɳϟ@ JT͢H=MʴӝKJJdԪXjʵׯX}*vٳCˢ]6ڶpʝK݉o̫ߑ vwÈ+^\0㐎Ky尗3k̹ʞ#MҨkNͺ~W({msͻSk8BƓVμ7꺯cν{f{Io-~<ӫ_=gx!h` .hWF(m!t]Zn@$XA .dC%NXE52G! vYI)U,IK1eΤieM9uOA%fQ&eϥON1jUYnׯW;٦eѮe Sm[qΥ[Ʒw_/D  4@DpA #pB MB S 3CCtCK\ħ3qE[t1%_1SqFw <0… :|1ĉ+Z1ƍ; ãȑ$K<2ʕ,[$ș1kڼ3Ν<{ 4СD~ i4ҥL: i4Z5֭\z ve԰d˚=vUUѺ} 7ܹt޽|*m[ >8Ō;~S![9͜;{ ڠd+>:լ[~zҦa۾;ݼ{.);)ڿ?<7:xԫ[=vHG=@˛?_ѻ?Pߦ}{o~ؙ> . |6b]r 4xaB 6tbD)VxcF9vG#I4yeJ+Yd eI1iִygN;yhPCYiRK6yiAQVzkV[vrWcɖ*Zkٶun\s7{o^6p` 6,aŋ? 5qcɓ)W|rd̛9wfϣI6}ujիYC]ukٳi׶}wn`A_xpÉ7~oʑ7wztө+dzu۹w<0>LJ7}zٓ,}{׷x|;.o2 <0… :|1ĉ+Z1ƍ; ãȑ$K<2ʕ,[$̘4kڼ3Ν<{ 4СD,4ҥL< ԨTZ5֭\zU9رdˎ Kٵlۺ} 7ܹҽ7^v 8 Ō̚ɔ+[\92͜;}UѤK>,Ԭ[]ٴk۾]X6ݼċ?<@+=ԫ[gܻ{>1xy>ۻy^gۿ?8`HdZ r 4xaB 6tbD)VxcF9vdH#I4yeJ+€2K3iִygN;yhP5e5ziRKuejSSVzkV[lXc~jlZkٶun\hֵ{AL2Mp`+ X 0.5 )W|ٗ9wI! 6 ㅄ/$Ze0@|}wn GGA2ل%*NkЩW~jq۹S.{ٵ~ ӯ~|"Ϸk}}p k2\k,; "P,H:2SL\ڐa /XT jo i+OF"QiK#O$\Ү|ʏiʜJ3`6,-0^[VQ.Ɓ ML,R  Q1PX(]F}*s&q10DPNس¸4S<]GܴKV#]aМ ,H-Z׉Y3VM~B֍c"E>Kaa-uޙgx&[ /B-]LDWX r.Ґ:^:! Wg@Ȯz!S:+H*\ȰÇ#JHŋ3jȱǏ CI O$ɲ˗0arfG6 &0y Ha` E]Z &UIU`(*PV]:Z'X_OzdשL59߿ LÈ+^̸1M!;LrƜb|2rgkAVh]LhUפZ>֨Um.dnvmaq3KNسkݱ䈟?ruC QkTnWnp@x'aenQ\At~=yVhfaz0lHއ$^u'Jz#64Tot 'V @½'2 WhhWDl4*$dDKWTViXa\*Ԣ_v)&c)JWg[Z^pY)iT=)S0p9'm:6PF*&^}vhB䘘f馜&vf9ѧZSڑp7DqԍΘdsJZx[*㟷*½,]zO6iv n,_pjV쪹ym'%zqU^ˠW&)[$P %,SQ֗VB/}/1k(<*[v^8MH-Kb7oHYC &UZn!_OOF7I(s&մ ]}5mhsڇTl du tsf`y &s&W"_j*Pm騧.ߪDŽmaGdwN&wC!NԪ'7QΟPncN{Ô=D=IpPx3`K&~oΏE/{>}`Ʒ A`H=tyY˄ p̠7z[bB2#Ṡ!/Ѯ8̡wolh/% wB00)TL92="ef(@qn=̢@@ DPB >QD-^ĘQF=~RH0`P$`C#4BA &](䊁N ͕>aHĥFTiPiPP243LSRZ?ThiĖ$K1oëUKX`… FXbƍ?Ydʕ3}\+^]9*R 8쉴qQ$U5ASH@,_hWG<7 SN8Z"f˝-rW(6jC͟G^zݿ?|ǟ~|#jF믏Lɪrjm+Э-~+H s H6@Ä"G uQa%XcEv^[6Y [oU"* 15(Vf>pi@69$3,;Z+PKLp[7r j=uYY YF8af;~劺^F@u]p`s9>\s[EϓҸBrQ^zW-}1|Āu∇&hFcCsNIƣK>T57r=3Ӑ]͒]^nLjv]9٭gaxno<%o:`"*ARdF׮ϔ{lnmqU֞>|Ǿƶ>xݼDZՃ[%l;T z.;ĭ&u~OpR fR3t]6ǗrUn6<Ѐe7)>srܫ|qsoSXNӭ8W.V7 *X3Ƀ!!~LiB.0.$bxJ~+ϵA#z]iI1 jnFQzA9u8A@.(̢/@oJؿҼmLW0'ib'HNђĤM6x̤bT6&2G(+~"ae(e9KZOHHqK)_WKyDL WHS{fg瓛 ~ᚖ9O&Iry*AysbcW5+֛pAeʉL% <0… :|1ĉ+Z1ƍ a`( &B[zt`` .=(8DM7#z4С 5J4ҥLN `:UjbV[y@' rSlMO="lK'],,[fwꂁȚҮUwqŒ[g۱1Bv)Y`^z :ѤK>:uƮm0݄y[X Kf37d:8iU? ?<9B]\DO70oˊ `3xݿL*>ܬKo{o޷A%Rn,ug[9@Swi]݇Gi6R}'&]~b"Hbi s"gy}ѧ@9v%XcB:Eu$>.Xx~nUt,ɧ`^]cRF!5:YPAle٥God hJhzl%V'ByMx\nD=ZݒF.m j BxCtDck8h 4[o}\1^Dz8_5 iAN*NKm^mBElz)KǢf =nA )K,X#mSkmXߟ(D>zw+ K]Ox {԰&r* uyT,B!6xť-*F)>-}AS@pafe 3.ϛ(_jEԱ8Gl}d= irMtvߍwIn~_G-zu᢭n)Њ?N""m5'.S¹lK1o\Kϧƾ8+0Aʊ>2]:O|%y,C)V1-{]'ni55.y[Dj'}0ϬKXkIZ>bkl726*pIR]P3~ 9ɔ+[9Fs؉32m3Pi=Yٴkoݼ{ <u6NNj_?e˿?-ڟ_8VaH` .`!؜N^YHanaaȡZHb*b(b2U5Έc:ۍcBdJ@z= eRNIeQ"dZ%S]n fbQ}If9j gr*mnΉpug~R 4xaB 6tbD)VxcF€dȂE4yeJ+Yt#I&eδygN;yhPCX(GI6ujԁKNXkV[vlخTŎZmZk[m\sֵ{/Wp` F7obŋ"qdɓ)W|Y1wfA6}ujiImvlҖ}wnݻy+wo}jxr˙7.z6tөDzu۹w.qoamɗ{Xwf/}|+w~}021C'|%t*ù.i =0(E<1+]|D߃dTu ,h „ 2l!Ĉ'Rh"ƌ72ǐ"G,i$ʔ*z%̘2gҬi&Μ[ɳ'РB-j(ҤJ2mџP_Jj*֬ZFʵׯbǒ-k,ڴjײu-؏pҭkw[y/;0ĊkEX.Ȓ'Slr[l5c[g9.m4ԪNz5}_C-6ܺw~V%‡d)7dm;e9ҧg>95b_};qǓ5 ?a~? 8g]e R6X* Ju98!`z!![{%Xq"ن"1Q8#b= 4xaB 6tbD)VxcF€dȂE4yeJ+YtrG3eIfN;yhPC5ziDIo~djTS yYvlXcɖAiٶuՙ^µ{o^{[-` N*W0Ć7vrdɊD|sf͛7#\<th <ujիY,l׳iÕkvnݻyQ࿉q˙7wϩWHt۹wɗ87{tٷw\<]{~~Kг;R|Ÿj 5ܐ=E> M<*j#em@QkQ* }N!#+ȐDiI p "Lp!ÆB(q"Ŋ/b̨q#C08 YУȒ&OLr%K$[Œ)s&͚ _̩sgH>)(QB"Mt)Ӧ:5*ժVbu+׮*z GɚMv-۶+w.ݺvuw/_y,RX41Ǝ1;'[ά9!͍{ :4Ҧ;|z5e[æ:Y]{wj}⿉;a̟C Oe2}zo~=v;bs_gt}z.Ͽǿ_~ !l+P/ͣ!P ) 19DL<A<QKYlS14i yGmѳ ]QHŎLR%#ʌ.' ,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$J0`l%̘2 i&B8wQϠB-j(ҤJ2-Y)ԨRE>j5լZV+ذbǒ-ka׳jL˶۷r_Ɲk.޼zY/`L0Z3n1䥆#S:2G1?3ТGWLͨ3T:oײgӮmۧۺAMSkfc /n8r߽3g8->:>>rfֽ'U<<^yݿo6~O_;}Ņ_ *`v2I`j!ir蘇ՍX")H+ie:@@ DPB >QD-^ĘQF=~RH%MD-]Sf3mDaM=}POEETRM>TUIJ5gDZpWe͞EVZ"öw[H>\yރy'X`… Jb7v _gJYYfΝ=^h˘I4 餗5f[lڵc(n;ōGpG2wn6E9m]vݽ]>azտ_>\buA/@$' @2ksB /DoB S0: 3rCB OD1E*qZ(?lkF]1G qGz 3D8 ʤqgϗ@ ͹4ʧRRdI*֬(j+ذbǒ-k,ڴnD .Wд-ϤI;pn]n*]W+[-r]1Ɛ'Sl2̚7s8#,<!ݐn `pZWt 3ϸKm‡/n8kS"  " ACclz\Y+ !(o+Y9yD f#Q*W|E[0zv:eF@׌qD+g_<+HZG? 5߁w 32JC{}Ow"]B/ D?|<_?(z_bn )+kc?p~3ݤu;Jnt &8+Gk˜9=0x (ʰ6!*F Z8%;EOk @ }""^\ @r)\":Æ& @H*\ȰÇ#JHŋ3jȱǏ CIɓ(€qq  XSK F9 ΄eЅ;](H(LMa`' Z`ҥ;O0+S NeHΩw 5{5T!WL#ˆ+^L0ǐ#KL˘3k,Y0^H@UM:y z ` vBЦ]t@i=ӫQ3|PvB.8GN S9zL^Ӌ<˟O'FtqٹBhWp9q75s7 C6V #paB fgiz!Z(J}DiHⅆF41Z"hrH\WTM0NZyW%5 AC}yyEUeyv_Jg[hZV䒗 裄9 餔Vj饘fZآW'B;1bO-Jjb^HJ+@teG*[z&Ъ:kV*'U4ܭވlP(bxv+.}l4qۚ&ڨzILۧh ыXz:(ꟊ^;n`gw q"?Z%\Ei.,4ל6U23C0dBmH'Jc.ܴ@LO]_Vg\C*uW_75ꝍleemКPGvwݨ5|߃w9,8yY7o9͒bG~yW7 4xaB 6tbD)VxcF9vdH#I4yB0RtfLWδy!K;yĨgPC5ziRKjT"NjV*vlXcɖXlZ1Ѯ5 m\pֵ{o^{@a%|xaċ7vr_ő)o\d̍5oth{/6-tΩfvlٳM}{m ].wpÉ{]Ł'ytө[^rױ/|xNOj'?ܼ煮g~|O>x}2 дw\i3A 0* 9CPC&|Ct <0… :|1ĉ+Z1ƍ;z2ȑ$K<0Ō;~ Ȕ r2ƚ7{ :轗G|cyW~ ;&KӾ=6w;=.km<-C|9ؗr>N'n^B׳?|N}mhڀG`y .` f a{^a!!a>!N:@@ DPB >QD-^ĘQF=~RH%MD-]Sf3mDN=1TPEETR%k6UȧS漚Uʭ]~VXe#V5VmLku&\uśWޠm,o`t hbƍ?Wqd[W9sc͛=ZˣMK>ݱs꼫Y[lii;n\pyGˁ'tխ]~z͛3pjx͟Gϖ|zA{Εǟ?{{>@Dd |iB /0CpC )B>0OD18T_1FgFo1FZI'H*\ȰÇ#JHŋ3jȱǏ CIɓ(€˗0c,͛8sɳϟ@ sѣHKLʴӧPJJիXʵW[f*pسh#M˶۷pʝKeغx>W&Pk nxÈ+^.Ɛ#k-,٣O+kyϠC1xMaէ_ÞM۴UmU7o9U&-{ȓ+[|s]ֳkΝ{1~r7n!ѫ_Ͼ}㗅{<`yϿם}(T 6n!x FxTfMarzX#h텈"n*j$4X6u2R8`A&TaC!F8bE1fԸcGA9dI'Q*#eK/aƔYpL7ĹgO:}:hQG&UiɚMF*T9fժrkW_;lوUͦUZ@Ƶ Wn]wջ7h[ &]‡'FqcǏ!UANXfϟAhӒOw:j֯aǖ=diڷGƝ}>gő?<^xr͝G>e՝/'~RN?v ~^zǗ/׷/S~ Mp,/l6 B#l 1̐35$l;I'H*\ȰÇ#JHŋ3jȱǏ CIɓ(€˗0c,r͛Yɳ'F> JѣH*]ʴdͦPJt՜WjUׯ`ÊKlĪfӪvQnڄ+ݻx-߿ . #^̸ǐ*Ly 'cnyϠC{yiɧ;vNw5װc˞}4#mۮ Z7<+УKU9u։?t;Ëjw}|ý~\IϿ(h&8xWF(| Vhfvxy N蔈$h(蛊20(4R^] 4xaB 6tbD)VxcF9vdH#I4yeJ+YtfL#ayg΃5uhPC5ziRK6u$OSJzkV[vlXcZmųiٶun\sֵ{WcMxp` 6|qYerdɓ)W|bA5othѣItΩYvvlٳUmݻy8&~yr˙7w/sΩW~{У|x'ɗ}6zٷw~XEs~ߜOd ,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gaM: Ĺ'РB-j(ҤJ2m)ԨRyjD9r+ذbǒ-k,ڴjjڸrҭk.޼z{.Q~.l0Ċ3n@Ȓ'S2̚7s3ТG.m4ԪWn5زgӮm6ܺw7‡/n8ʗ3o9ҧSn:ڷs; Ǔ/o< p "Lp!ÆB(q"Ŋ/b̨q#ǎ? )r$ɒ&OLr%˖._Œ)s&͚6o̩s'Ϟ> *t(ѢF"Mt)ӦNB*u*ժVbͪu+׮^ +v,ٲfϢMv-۶n+w.ݺvͫw/߾~,x0†#Nx1ƎC,y2ʖ/cάy3Ξ?-z4ҦONz5֮_Î-{6ڶoέ{7޾.|8Ə#O|9Ο@@ DPB >QD-^ĘQF=~RH%MDRJ-]SL5męSN=}TPEETRM>UTU^ŚUV]~VXe͞EVZmݾW\uśW^}X`… FXbƍ?Ydʕ-_ƜYfΝ=ZhҥMFZj֭][lڵmߞ;PK HA=޼0OEBPS/images/_manage_certs1.gifGIF89a$ߟw߿wߟOwOwOwwwOOwwOOOwOOOwO3J` w(/7>FMUl"Dfƪ3"J1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu!,$H*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8rɳϟ@ JѣH*]4ӧ JJիXB)`k+ٳ3͢]֣ڶpMKܺx;˗޾% LˆNXlC.,y2e˘sV3͞MniƣOMzu%Y+{ڶo޽7o .|x#|yΟG~:u֯>6;޿ /my_V4={×_<>}'_`Lh`d Jנ`MHaqx҆ X\'D+R蟌7d};c:izяFdoKj|O69SRYQaiDZw_  DPB >QD VĘQF=QH%M* yRJ-]zLRLcęS;}lPEG 5TCK> UTT^֚Z~ VNc͞mXZjپWHsZ{Wo{7ୀ 5|mbŋ?^2Xɓ [V\捚9OihѣKz.iDYv [׳wֶwnݼ}Oep,7\yK6wN7:VV{۹w^ܑ{x#w:WӺ/BAZ?W@ 0Z|3p ݻ0B24<$D S%;K4i\tddIۑ0QU rHIߔI#z$'m2*D 8,h „ 2l!Ĉ'RH"ƌ7rŏ"G,iRaȓ*Wlcʗ2g&8pP'P7-*sQ:yLiGPRXU w }^xg%P{P|wD ~%HaAbn $ Hrҕhx)'"VbfBK妟.(_B$"~.rbA-w2!Cz$ݓ RbU_5@ɁC Afyq醤 tKf]UBB*^;iЗYprMx %vəТ T(D"\{(^aX؟X`8;zPY%` ,Śnu0+1:V+*JȐꆥb;N>+T>tUꞵ"yJ;"S !OUl&\E+k+{=ޓ&oA"-BfDeC 4Jn /o~nRܧƻfI6|*0s~vI(KC?$^S:+砬= ]W$/()T(,ۛVR]YA ㋷;\gd"D< NJ-",]ZiYӗLE\ºc#j^ `FKgr-~}|Ӡ9nO^&8};`qȕn-s1yqɗN4"FF-Nx2ɠ69:pI e6Z[ FȗEqY^G4υH?p()n}sAN`j Q[Ѫe^}J@Ma|!:rqe?.*₠4*® ,k80J! 2"c5?wX2ryg$5Cw*Wr`%'m9K)ѕD@9*QJ9ɳG x屒S%VρHƋީa$2#΅攘M^"jcCT>d܋7)%E̷) D1G҈AYs:wYRy9OZƍJԣ9 I'?RL}3ԟ5vr{r:KU]X 6!N؉QI jHfЛ9eJsի BiℂI9|eXR,ֳhU)ׂ;{tȮr])Ե nv0ڝck'PcQ;=U}S~s6t.釋ɤ%cz] pu>vK65=UmހSR^1E ; n=_RͰN` OѓA{9*%O#Zyob@!à8Ld!5RIpB 4vksxĭl4'pB}*!CvrrJ2, ax9JUܒcŠwEmI{ 5Y"wRD.K_PpS6Dsy wBO`$)1/\c h'Q u4c<|[,A`A xbE . 5): Gdx%IRG! Pě.BjPG&UiSOe!O>oacE2E< J)iy3-7ٓLQջ^}*UiYNr hЦUb)?GFQ{\n)Y&I9P%4XE"eMnX vQb7]:Lխczܽ^Q>A% <,K;!#R;#]C=b2@'rޔlJ\.KmKᾤRJ03C55SL\S9;S=?͞-CMTEt͈ p "Lp!ÆB(q"Ŋ/b̨q#ǎ rq$ɒ&Oz r%˖._Œ)s&͚6s'O9{ *t(ѢFt)ӓJB*u*ժV>u+\ +v,ف^ˢz6-۶nM)2.ݤsͫw/۵|^ x0†c >`ŎC])[άy3Ɯ;c,z4鯞K=z55UN ;6ڶ5ξ 6޾ \Ə<ΟKn֯މS==D׻o ?>v/?w(V 2(W;F8CZa}j"!4Q8`A&TaC!F8bE1fԸcG9p8dI'=DeK/aƔ9fM UԹ'Ɯ=:hQGeDIMF:jU ^պ@V_;@e=m[onҹuջZ/FMUl"Dfƪ3"J1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu!,H*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JH*]ʴӧPJJիX 3ׯ`ÊK6*׳,˪]˶۷Jʝݻ!Q/߿xPDa]LVءNK(ءRȠ ¨Q3N&c7Xw;cd|CV$IBd}K=SB)aV֥{_&cngi@tXA .dC%NH`E5nѣ‹E$Y$Ð'UdٲaJ1eΤ M9uBO=%QhQI'UiBONU-fzskW2%rlY$Ϧesm[aƥ˳]sE߁;0‡&Vܖq㴏!<re˙5b|sgAK=iiuQf-puka=ۭmqwս︽㝅'IKF>zu_{V3_|WS_?Mi|jƿ`\ (,p4lPA A 03 P s;JBDI XTE=Qiq˱o4Gz|NHL!%k%2)/ *\ȰÇ#JH"3jȱG?II!O\ɲeÔ.cʜId͛8ssϟ,{JТHN<ӄLJ1*իX[Z֮`e~ KvزhIMvڶpþKgݻ"݋P/߿ waM-:HLrPA㠟C |WjSxvڶfXڲ˙7m<8׭+Bz֓bώt{)c0{Uw_=҅Gݽi_̲t [z!@i8Y{} FؗrQXJhaqr5Wosuуv8 ~*b'0jbyM4b.Z($G6ed6=d(Y M @2%>n6Y1[Ǜdh 4ДȚAsN@xzg}q fc8 P$KjfdKqZF$%YaijU**C奭i*X*kRFoD+e.ZxB%N(jܦ:nb8#vN.pǮgU e4. #+x:\ˁ!pT%@يg|ھ"Drq Vc6 Ofoh (&QnJK{eASYA 5 DU? ܮ77sԜE(&.9}:f䙉厶*H#vn#v4;&B 6GAb' }&!oz[ޠM'xcrtkwˀn> 6Z{')h˒|y<;9fJϱ{g_'z=B1ec/Q^BW<_O}_R#4S 8A !`1]~|ޏ'a;c}\&xjņ74WX@Q./<ڼdaI-Xxx%AފaHD=VBk9B8x+vP :,h „ 2l!Ĉ'RH"ƌKWt9uɆݶk4^ IphnxB^xڡ`x]w]^QUha0H@{>ԡIZMf$2ю!(aAŨbC`x8!QڔQY6~]d_\m9یw|2P+w'GCm9)IZ)$])UV-2ʛd&٠x6Z^զjEid 6:"ީi*/.1fY26X4Ij@bkb{rKцj ln=eo,SjU^ *`bŊ;, /e"] oH˧f0jn>[~, #_cZJ@-:{:i~YW܃@ w H=rQpzajwͅ/^*n{9Pb*| 7Ċt!B1\C-F )k&".?Ue8%H.[FD"Mq(hr|E g\!!RGRZt@Q] :CVjb&GE'}M96IAf,/$F d  հo$$5P=ڄv8s~F ,9YhR#b0^ gJ&B ]1 5t&0i-vs d92vFDČy)  ),(q2dK-\TEŅ8-K]\H4|UGRZ-%a +Qt +?ϥy4j.b'j8˂,.mPīн[NV*?+=x j+Ր5!f5UUՆp #+?J)'=o`QLQc3 "n W"مPlufQX=gA *L,b۷ Ս80ioL7M_PEE [VmS~ u@P|*S$rl+vNW7έ-tYRCQcov5-Ys=3.l,C%\ͺ3~>IKӛj XW0G%<= ,3p{YSװ\0,4ېrN)㘱uz1UC,bJX{?Riq̿kf14ElK<SGPB:37#Y2@UQ#uѵ(!8KӔWPmKIY;a-(+ʊ=0[O]Aj}֪`<e=K4VƖE[!M)th0֎zcMm[:޾;&o_pt+ߩ~P@>M3Z.S\~+&̇M/b&Ƒ ߍͲ]yVZOvk]Sw/-3^S RB\] %8$-(̝ۖmK=zY}~{r4N6Ye# 2PM{̥@)$Y,hoVкX3@1SKGAM~C e +}yJ G )])PlxpR;dH'*/yD!HE+nAzslzmg-.BG[L0 #c,cΈƴ]9u ݢ#1U_<"',᱌E-  gȅ #eBdlKF+J"ԑ8vj%c|W-TFsKͨI2l -eȷ[>2\/M)f%)r6I#j\JIIb4=IҡfAM:/y J7Gihfd+g;_su Lyfޓ*er`L3fEN?LE-!(9Ɇ(tY>QJqaLPuo9 L/:#55wet'H7#RNdI 0_P+v>3 yT#CTk(T}nլEY5m=Ss6P \*Wvi FA~+@ *\ȰÇ#JH"2jȱǏ CIɓ(SȲ:p`@F Pϟ/JѣH~ʴA2iAD&DA5ziRK6u*pSSVzhT[vUWcɖlZH'][/g& `"&91,uyvĎ5ͻ/Sp9wshcA6}jiԫYU6ۉ˾^/ŇqFR~mN{Ojvصw7{ɗ? <魢,|7n/8̂?yt&˯糎- LjP '0) % 33 ?2DQdzrq* yl*!ȇl,^=ݎrh ԩڨ۠۲(J͠L35t7SN"f|T[IHSd'Z5T؈-V=dTLt2i=_'DjzauZMJꪦ"*kȨCuqJ+gZ-]-Q[L"k,vn22*(v{oE.;h좛غм;!/B\7Ŗ:Rb@C+,,~qƒLpm}rC"Sr*s2b c6stAH3O(_j1'Ŏۨ.ĝ+˘R't՞&95_z!TgCefQmO >#^uyq,u_nw`*wד?8N;~(&:D[s9yn"`wNх38/UOjUMާ=a&ƼZ-zFm}%n.KrY7im/J۝yK- 9Nf8 M\qjG0E00;gJKpdR@5sG! _8H|pP!,HƌB|qe+A WN)U]/0p]j[r"dJ&U$|lQ6]tcEh#H@ RNѢ/OAyc 9+[LIRCuG+\_g3A]MclIޕFϔ`S $Xq9X*bp" 04T&gǬJ2CfQD-^ĘQF=~RH%MD`*]S#2męSN=}TPE34TiNK>UTU^ŚUaS]UXe͞EVװklV\uśh\}?X`…  ℊ?YdʐW>|fΝ=-Ts輣IFZjM^lڵmF+Xݻ}\xë7\r]t>ytխ_<{P۽>46tRG^zٿt^|=ƷO~ￎ@@-R(H*\ȰÇ#JHŋ3jȱǏ CIɓ(SR˗0cjdA͛8sɳϟ@ JhFF*͉tӧPJJիX*lW\KٳhӪv۞mʝKݻxG~ LW#^P1ǐ#KLʇ/c̹Ϡjw4ӨS^Zk_ÞMhiͻ Nȓ+_μ%УKسkνoË6Oӫ_Ͼ˟OϿ(h& 6`x8`A&TaC!F8bE1fԸcGA9dI'QTeK/aƔ9fM7qԹgO?:hQG&UiSOF:jUWfպkW_;lYgѦUm[oƕ;n]wջo_Հ;PK HA옼PBPBOEBPS/images/_manage_certs3.gifGIF89aߟwߟOߟwwߟwOwwwwwOwOOOOOOOOwOOOwO` w(/7>FMUl"Dfƪ3"J1`@wO^n}Ҍ"Df׈33GG\\pp)Rz"31J@`Ow^n}"Df3M"f+3<DMUh|:Wu3Pm33MMff3Mf"+3<DMUh:|Wu3"J1`@wO^n}Ҍ"Df̈ת33MMff:Wu3(P7mETbq3Mf3Uw--DD[[qq3&M3f@MYfs:WuȒׯ33MMff:Wu3M&f3@MYfs:Wu!,H*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJիXjʵׯ`ÊKٳhӪ]˶۷pʝKݻx˷߿ LÈA ǐ9 \Bʐ;P @s 8,cԜ=7PudMn`׾KOLx`̻?&iX5QI9"y8gu`cjhiCx*jUz&4)|~~橥B6Vv)7^y7ُ .*Bv&T>c)he ] +|~ܥQPŬ>cxfkDD&T_R +dZh:f/Kf}H2y k#kТ aMp묹u߷Bh=6A莶} <>LrB@т#0;ך-/ KsM`M!ߊ6}aF2dcvam}sA^릶؄Mvѷ ҭA]I88-}/y4p&p ?~^>GpQn̈"y{}EF~V!BTs β4>uyU8`A&(B!Ft( C-Bp (Ň ᅁ `ƙ\xG: |SЉK>ifKOF:jUWfպkW_ɔBܙ3"тiem%eM=87ƙwJ5B/n _!GQLQYt.2BE4+<K Cq >廐#cr lQ)+":0bQ ܲK)EB6çBI? TA+{猨 a LI΃*iQ4l' $TUYmUC=2>:Tl3bm.ڴ4MmP{U݄MעtUi9XyB44 ;ҲUOsLOHqB$c6~R{W_Iw51]O A>uIX:E8Y]Vt}9&2VVT^YyzXab^$UӲ矁ߙEHW%u`iNԛT6ςp:[.N[n[[B\ /O\o!\)1\9A]I/QO]You p "Lp!ÆB(q"Ŋ/b̨q#ǎ? )r$ɒ&OLr%˖._Œ)s&͚6o̩s'Ϟ> *t(ѢF"Mt)ӦNB*u*ժVbͪu+׮^ +v,ٲfϢMv-۶n+w.ݺvͫw/߾~,x0†#Nx1ƎC,y2ʖ/cάy3Ξ?-z4ҦONz5֮_Î-{6ڶoέ{7޾.|8Ə#O|9Ο@@ DPB >QD-^ĘQF=~RH%MDRJ-]SL5męSN=}TPEETRM>UTU^ŚUV]~VXe͞EVZmݾW\uśW^}X`… FXbƍ?Y2-_ƜYfΝ=ZhҥMFZj֡'fZlڵmƝ[nؽW\$p7#r2w!tR vr^?|xXǗW~zw^>'׷(~Ll@@ SpAQj"B @"Lp!ÆB(q"Ŋ/b̨q#G; )r$ɒ&OLreŏ,_Œ)s&͘.k̩s'Ϟ>S)t(Ѣ?Mt)ӦJ:*ujTTbͪUխ^ 5,ٲfvv-ۯj+w۹vw/߾3 ,x$#X81 ;,y/ɖWy3̜? z4餢Kz:52Wڶ[uݾ |8Lď6|9I̟v}:Fԯk}Cܿ#T~<Ϸ~۶=a???'gb& wC%k :aNJXb҅r!!8@ !DPB >QD-^ĘQF vRH%MDRʊYSL1]ęSN=}SPE5TRM"uUԨP^ŚUV[VXe͞EVZmzmiТ[pś`WX`c6䋘aƍM7cZֈfΝ7j 3L^KZjԝO6:luaƽݹ9 ܡpō?Mq˛:Wt4#z~gw 4O4}>E_cį@$P( B'!w sB?dhCD,D$DWlLE\ FPDE=Q;Y̑oWJ8`H B4IJw4ւS!UJ$XH( Dͱ$Kh05>'rS˃(χ}s8Bs ;B2PMT%,` t2"#?@!;#}T JѣH*]TͦP)ڱ̍"@(a$y1DXtjԷ<&u ݻxݻ.ߦ~Ksfe˱kX*Yv<,cb4ϠCM:nuE+tK) ̕ګOw|Գ 7qqh-)}9+&?NӸOËO^{`-u7:bƇ|9߀x!SUtP }PYg`C n (_WFe]|AEXb -C.Qhވ 8BxGЄ$H U&ߌHi@v7v%C+f(aAX6bBUAo>񗥏c|'{gQddv3BdGa禜iJ R%icL.U+Zgf|9V!jS gXhvd[)*zEZ1JgA j-D[b^BK++뮼G/Ծ|ۯOppC0^Z]Gƀ5LŜ WlP"+CE0̧Z*Ygΐ%uxS%PC5ziRBdSQY>5ijV[vEEa.[ٝhٶuZZ.RCv4|qbŋ7vrdɇ pL˗9w|w̟{~k:"jҫY-l-eMrvnݻG7H] yrA+?\+ǝWY:n;wuWj੧w>z.}k^fc/ ,J?<п(A%/¡ 5ܐC* 'q<K{P̋]|1#[FhuQ9 qʑ"w&$S2&"|E&aR7*]r,%6k*/SS2/3qs0D2|84+ݜOm O͓оL]F;AJ+JKK=]*մP2T@!B <0… :|`+Z1F7z#HG<2ʕ,[| ӢȘ4ά3gȒ:{ϡD=4@JW2m )Ϩ,J5֭\"ذd- Nlۺ}T-\rnkTy !^c >8Ō;~ 9iV8X˜;{s=G55լ[{T떲&9;#o$<9⠕eΫ[,j C:+5O~znӻe?>5Z`߀ j PManȡcR8=Hbw(E`.D4b:ٍpɨ8c; Y)F>"0I.9 eZI5rYeɁɗ9"jfpnΉ'vwچ_~ h}(gy*A9)ah9RznWY%ĉJ'BxaB 6t)VxcF 'nqcG 4yeJ+YtE1i>Ygΐ%uxS%PC5ziRBdSQY>5ijV[vEEa.[ٝhٶuZZ.RCv>Z.b 7v'c V|sf͛9wthiB^Z:dӫY^Z/쬪nh[vnݮq~9rw'Ϲ\+ΩW-*v뷛;Ʈ}{x7?^byգw>{{O~~eG0^ۏ@ I[cB( p%ܐÓ02DM쌴]LEbqEjdu\zqF4ܑ"ѭ S!|2G&'DE)ar,7%.U%/,1E3 M2M͠0$< ;%C?TB3tN\F,Eذ4RRjJ=.ӏB l @"Lp!ÆBrK,ozgo{Iϯl&kXQ(2)~ BaLEhbvFZ bD#"a&C=/bb2l-֘ S;c8 Y).YSM9a>%WUn^ԤcKfemjrGY#יs'dug|'Y_~E(FtB'MX#_:ߦ) @bA .dC FXE52ǍAr48I)UdKEƤpfM9CsM@}%ZQI UiSNyFeԤUYn%V%plYgwe[j";wk]J_ha)*6㞌\e̙5ogСEtJɥUfѱeϦ]vz_wn޿68ɕ/7q0+ձվ*ݽۏ'|y+|{i _b~/ۏ@;0d<pBp.0B ;p5+ ]DALp3G2cNE9 o=lG^rz3"1##t2&I J*+J@,,e K2'Sʤ̈TMlQ48us:DMGSH=McPA}e;Qt+"*\ȰÇ#JHb3jȱcƋ Iɓ(S\ɲˉ#_ʜISa̚8sΟ@ J@F&EiP$:Jի&bzR+ׯr ٳh]Mvڶpd 04 D(zCp a~缛x! Ĭjݸm?F+\+휓@ X({`꼋e6۪Y'm%qTK6|Db&B{ϙ='z+/Uα5$>5n5QD Q~WЀ!}Ga|]T6Y~yIu QyJ"M$ bjaEȣP>JM8b^b 9QKR 2D`܏ ɥN^~YSa䠑VLZNRmtf 'bFTf2gKdzHqE") QJ)XZ 鐟$h[y[6BNuk:jb^zEyy IYbtVDNFh*$BƐ_z҄)=m{FmR!JQJj!w#&6޺ BP"T/[mEQ׼Bڨ,:ӵۖqyRub&9P,ƕ!ȃ,r%ȡ/B&{9MLqXTDL#}Е6\Г$,n TA&^)bIe/ T*],u'rYuF%t⌯|6Uʙ:XcU:@m($*DϝSѺe@s3jSfRNT5RI{KO:^۶ż%-c+>/}/ԶUj+c/|'giXQ*B,Nak"bņzyao!H  }O#e;Yk{RYv֍/%<@3n$YǃF$`&8#F$9+⏅MY!ª# S PQCȨ<Ɍj&GŒg!c`e7apP(lrR"Ft&^cGF$ЫD:ΐ"Ԫ-}YȬ!"U2qQ&#CCT"3i$6':w"mdͫgv{a a9-rS.#:Mo7U=!KS.AtHd!67cr4-oٻoBЖ@21A <*3|2&2䡎|T 56!6$")&sl4wńϦ7KCY9nwhHtiⰱ˄"Wyڠ7q4013,C&ngELd9a~& /'L5LSeVB5*TvW հG\SL V9U 5YrTLp0"ӟ(R5DZ~r.,e$ꑱR_J|ҋO bA .dC%NX`E5n1E A$@A6@"|9$J X(r!K0,f0:h؀s%M*)Ҭeb=jU͔W*t j2M.đ&\XAÉ/crth[fnӴS;~.|` j֭-gܺ¾|SB6mZ@ΑB^zd׵o/;bag0m`>oY{y|YQ&0Lƣ Kϸ^2Th.<;hCC =*qĘfj#P,ƛ 3AL⪶d-F˴XQ„"ހ,L ӔDK/L4TsMd̄s6NyemItAfyfga9ey`m6q~hhpVgFU饅^iꖥ>jlk 1 „ 2l!Ĉ'RX"ƌ7rdž C,i$ʔ*Wlrȗ2gT&Μ+o'РB-*ЧѤI*m)INRjIXkGł-k,ZdӲ]-ܣYk.^u_s.ljV+ƒ'S2˘Vy3Ѕ?I Un+;;FLںwÍͻ-8rē4'ϧSzMF;N޳ϳovo9>~g=?|ZT F a x18axF aHz׆'p!J!)ڦX&(!1"v4R9f.ARtD2If>QdrTYeNaťpdi^BxaB 6tbD)V,XcF9vxcC!I4yeJ+Yt9qK3i*YgΕ7QhPChҤH6 ʔ$TSVzդT[OjWb5{Ki.\Q,Ƶ{ٺp p` 6|qbŊBKqcɓ)vqf͛9w|͹;G6}5gWnٺ,l]׶}6ܷ>[4oÉmxC'G\ytVS>uڵc]gw$o;_=_}Cӷ|ZO= m)"TnB 5.Ù:×ܐ= Q MtLżF\k/m.7Qk.S2}B?Y4C`!2Ap "9D(!G4ڸ P !S(ԵM;O ";Q` d3"2?@!K_muX,UuH^tZ\UIYju܁|c 5-z7m5"oTbU4N^s*Xu25]]5{,"*\ȰÇHa CBp0d D MHSĚ8sxsÞ> JѣH*]ʴ"ЦP)>e*+_<%ׂ!2":RKgcbl:5[m}Kݻx};w/ӾHMYb(` 6!Y-ȁAu ՌϠCyyRF/R206\֤GUW-m)ꝿ{ N񟼏 >4d :Deٰ>;@-+gӫ_:9{fIKNށ&`D N5Ib7~Vn $hbg#"E}U]F@e7x'.bC?(DqGZ$_&ԎLt#BuE[f`$qc.duI(#GbɔJN6ٔ~YD]|*tgoVE#C淤FuXh-*(Gqe禜^釘RҕWn[uӱ UaJkZ PuvWV礲qgU򪠭j*V Ɔt~fN]E &+ 5la%X ԝkZf 7|ܭkC $BAobn|;:lɣA(,s^.U7<$g,H/Gtz94^F'-ԤtO5\w=PvͩtmR2%yCj-o+wZ7\={7}w߈\8#x㔃6yRQfW9̡8קx D&TaC!,bE1fpF7vH'QTeK/aZÙ5q YRgρ7U9hQG&(TJMBt(TS' lYgѶڡ,H[PA8@-E:լ[~ tڽC+9ݸVKi?!L5x`nxym Εa&хC[.cK*cڈ#BwcdAXN%$IrQZv$M^dlM1-ez)Yb雙eg`Ixp馆wVruޞ|^uu> iYٜ^c.~@bA .dC FXE52ǍAr48I)UdKEƤpfM9CsM@}%ZQI UiSNyFeԤUYn%V%plYgwe[j";wk]J_ha)*6㞌J\2 3W3a$]iԩUfkإZϹu͵ _JqL\yEQG^p揩_'{zvݮG}bϷ8~=?rc@ O )TAaϨ ū(#pë$Coq C4Ĉ.jZtEcdm6^REkD0GFFyr# "u*qH&9L2'Ҳ#ilJ'dkJ丌iI,$K RǖsM,KM4=M:ǃ3M75Zx"~~]>`d R8{/YuSˍh+&T"Mc3Xco!;g.$L:XbBrtNe|LDeV [d^heU` F&g*'&_hjf&YDgjftflzs|rgehlJ6ǨBݤzar揕 *TvZc D&TaC!,bE1fpF7vH'QTeK/aZÙ5q YRgρ7U9hQG&(TJM:SVfպkWX^±e!݉m[oPܭu*5o_;kwpࣅ"pcǏ{2n+rMh/7\sg7-8tiӧQVukׯa˹ϷqNګl߿>4u'W<"oϡkzub_׾fv?wѧ]}Ǘ|׿d~ l0#%B(PC2C!PD:B<Ul17]il+ґG}QJ L+$܏&l(囒+˘0,s$"*\ȰÇ#JHŋ3jQb CIɓ(S\Y#˗0cʜI3˚8sɳϔ7 JϠF*]ʴRNJ*իXjjuׯ`Cv KٳǢ]ڶpvݻ>˷L~  xÈ#N̸Ŏ#K ye/k 63p=M:ҨNͺծc3-oV{&iS8㾍#_NR9笝CQ:뚭cP;nO7ţ߮~C/~Xə XAG D .P >K^!NUnX"xxb&a0\+b͈F@ !DPB >ذD-^,QF=~RHIDyƋ  `)=PfÕ/8INEhґ,>UTTUfc? (BAZ,KD RlkV\X0]}"nЮv`ܬoC 5K'Yި:h;2ÞdQ'L| cZӻIp;yC`} [X\{7 ѽɋl]!uK.5՟|~/&N@${ |#쾥sO 4‡$D/**Í[͡wsHl #QD -cģf PB,(O$NȊ$r;ÒR::˄Ϻ.29l!dE$i՘ :*d -6Bë&2oq Ǡ(d$53-65=jm9$4Q0ԋt"lHчNOxmIԥHSO7T4QbG+EȲ:|m=G.^]W@HVvՅ7t`6(6D}̀3jE-)C:E)ȱJDVSRXL6@VHdT(كZ<e L҇C=_ČS z Z:̍ehS_%gG˵f f60B;K9Z}W֗!7ju!Jvg9ӚQrr/egy矟";]:YU1W o+lVDG)o zG~yGߛFwnq|۝r%1r8܎XPDx9^7B~~ ijEt~K]@F:Ϻ8XFXq'Tn ?v7N C#3Q1mJQz@RDM{ןJ{Up^!R50{ Q@$BL e(V ;#l$,q!KCPh!+Կ]!k"4GbYwdbC@&TX?I| IF,$|]%%uq$';J7rM#yiI|?ILá0yYFX頻F.ΑW1sxE*ӎTM%^SCXT>2\zD cwA׾%)f.7KQ@ZhO0ȧtsM4 @-2 nh44 :9(DA--Zɭ  &IK*S1*%%LQGZE<!;>>r 8)QqRJu`&?Ndr3ۻ?+v=8cotAYG_ .`>aNHaoXW(n_s*ab*b.cL8`A&TaC!F8bE1fԸcǃ_9$WQT9L򥰓CYkeO?%|В7&UiSOF:jUWfպkW_;lYgѦUm[oƕ;u&Q^+Hia`uW_a"UxqǑ'WysϡG>zսދ.:oOԕN2|%W}{Ǘ?~}׏{+#ۯ^"IM@[!P ) 1P 90:%,J6HlQiqQyǹKDb""0R)+RK p "Lp!ÆB(q"Ŋ/b̨q#ǎL RW)ǖ._´EH]Q,s'ϞAҤe'ѢF"Mt)ӦNB*u*ժVbͪu+׮^ +v,ٲfϢMv-۶qd)`ⅸ&鎴wpA"Nx1ƎC,y2ʖ/cάy3Ξ?q/M^I5Mia쉰c{kcX4ΟC.}:֯cϮ};޿Ws ܑ5q#Wl^ɔTL-_C' EVBW!rQH%(6_`wW'+آ/3آ#EX JTa=rm[}*W؆#]_I"U$_C$p = Є&I__7D|MئosYw♧{BAhZD_c|jhl6T0%K&hF5hv% > *FEimJЦ򙫮ګ[luZا#Z`,l*䨕DjiAi%-*$B:**JK~cn jJ&ۯ\0W8`A&TaC!F8bE1fԸcG[ a"kUdK/CTf͗^52fOXΖ8=i҄4}ljԚ2 VQ+@'8k֮iU]-鉙nS dHTNU٠BkF3Y[,h „ 2l!Ĉ'Rh"ƌ7r!bEH~@^?EfJqYpK+#V Ja˗JvLX4(Ԩ1 bUW&M9+Ȝg¬xA*riB!.|*ªx/.l0Ċ3n1Ȓ'Sl2̚7s3ТG.m4ԋ,[7(݅'2}8[A)J hA!: ܠ؃oGm>B"yG}+ʔv}lH nlڡL` J]5? 8 x * : Jzu ]| L}HssgRv"]G{}\k D3J|5xZzo^&*T"n:$QJ9%UZy%Yj%]z%aIJrW$Z շVG-NT&qHчA b#C!}6#X5'KhwdxFwA:&Zz)j)z):*\!Bkܤ1yCpzgշUy!8h"Dޡb(w2˨9:kZ{-j-z-;.LzlMҹ'if볕;AƻVA[fBTq;1[|1k1{1~/:K-Fp VUнG:E:+pc!,\K sM;4QK=5U[])@$XA .dC%NXE5n!E$Y$I^ ?c1elIp `(z7R˃+GX4@œt&QBEBȓVG*EU$VRCR-(ل^Cr5tQqΥ[]y_&\aĉ/fcȑ%O\e̙5oYZתFU=}Ήj"4q9 ^C[o !hG=`sfg .2gٵow'_yկg{Z7_WM~$͹@J2n " B.FZ!h3p *:xN>STqE[tEcqFkFsqGs0 P?$)L 9<4!,2JnH !RMtM8sN:N+}zL,jD"'=R#ECB:T32 MT%BCt81UXcuVZkV\suW^{u1UQ-TRG*HW]D]v4ErVYLtVO$ ́T3}ҁ"-Wvu]xw^z^|6TW̃Rn*T-ьjCr#rCd279-dSVye[veo( <0… :|1ĉ+Z1ƍ/n2$W '0k9c͛'sF2L@qУӨN,OԂI[֊W]O'ӂNEeh)Ͳ SN7޽| 8 >8Ō;~ 9ɔ+[9͜;{ :Ѥ ybXWLj]Ӣ=4|+PO6[X\-[۳ݸ0t Go(xp;|~uۻ?ۿ?`H`=UEiu1Vqv5]5`Iu8oMZ^"Ae ȕR>^B5BX.^h`>dBIdFdJ.dN> .rvo4@ρKZti8Ѝ=w%Fxa6Gyc%H%ץC|2#rRe> iNJi^iniC U]Wp:gKсڦ4% YhmRqj8IATBoF%Clkݠ\B[J1inm~ nKncrB{ҝ]箍9M/*&Fˑ`x q[B޹6bwBǮ*nL'1"Lr&r*r.+be˝@SG-oK!\oAkR4e1l.h/A;5CVLŲN<-URK0G6jvn wr$@$XA .dC%NXE5nH <!EEH^2ʅ[\$iL*W8u)3΃_#O⬵K pK2g,(ИFTE%ڇSQ6M(DFv_&\aĉ/fcȑ%O\e̙5ogСE&]iԩUK4+.ǫoFI֠]{ 4 w޴ 6uҹN;>QIOF%*=FYs5*Q\YEdЁf}H;(B%b]%f]w\r5\tUw]vu]x2[F{鄶E I:B׈ը_FeE(7Hتv$# uJydK6dSVye[vbݕBQkb1g6qXpT"hȺی+%ZMe9kak{l6l3 p "Lp!ÆB(q"Ŋ/b̨q#Lj_)֫LIa.SU˚!ki"&4UߤvX" 2ؠB8nQk"hSrء#X'ix6ۊ}77☣;أ?Cƅ_J9d$QDr_HK1SRYWb@@ DPB >QD-^ĘQF=~<%K {&uSL5m˛=}TPEETRM>UTU^ŚUV]~VXe*\@-iuuVܙ#[W^}X`… FXbƍ?ohT^e=O۲gҥMFZj֭][lڵm>Z-܃9+[8Z_}=\r͝?]tխ_Ǟ]{OʿNOn<şG^zݿ_|/z?$@D0AdAOzp* B 7C?1D( <0… :|1ĉ+Z1ƍ;z2/<2%Z"[| 3̏UT53Ν<{ 4СD=4ҥL:} 5ԩTZ5֭\z 6X$me96Z[ {6ܹtڽ7޽| 8 >8/S8Զ(J9͜;{ :ѤK>:լ[~ ;ٴk۾;ݼ{ <ċ?<̛;=ԫ[=ܻ{>˛?>ۻ0 <0… :|1ĉ+Z1ƍ;z2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{ 4СD=4ҥL:} 5ԩTZ5֭\z 6رd˚=6ڵlۺ} 7ܹtڽ7޽| 8 >8Ō;~ 9ɔ+[9͜;{ :ѤK>:լ[~ ;ٴk۾;ݼ{ <ċ? *t(ѢF"Mt)ӦNB*u*ժVbͪu+׮^ +v,ٲfϢMv-۶n+w.ݺvͫw/߾~,x0†#Nx1ƎC,y2ʖ/cάy3Ξ?-z4ҦONz5֮_Î-{6ڶoέ{7޾.|8Ə#O|9sH*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJիXjʵׯ`ÊKٳhӪ]˶۷pʝKݻx˷߿ LÈ+^̸ǐ#KL˘3k̹ϠCMӨS^ͺװc˞M۸sͻ Nȓ+_4,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gҬi&Μ:w'РB-j(ҤJ2m)ԨRRj*֬Zr+ذbǒ-k,ڴjײm-ܸrҭk.޼z/.l0Ċ3n1Ȓ'Sl2̚7s3ТG.m4ԪWn5زgӮm6ܺw7‡/n8ʗ3 0 <0… :|1ĉ+Z1ƍ;z2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{ 4СD=4ҥL:} 5ԩTZ5֭\z 6رd˚=6ڵlۺ} 7ܹtڽ7޽| 8 >8Ō;~ 9ɔ+[9͜;{ :ѤK>:լ[~ ;ٴk۾;ݼ{ <ċ? *t(ѢF"Mt)ӦNB*!V Zͪu+֭^v5Xˎ=,lJ6\uE^}Ӷ{U`~+pr v 2]v-ŬW3_~=XI7X ~l:rɳ+߾;ͽ;<ѵK>}<[F 䴩۶[n\p]ǎr;=~^ X^Et^{ w`| 9HTrء -8'+آ/3X7cO%أ?$< YG"K2٤OBSRUb[x%_cYgkN%o9w♧{٧Iu ZH(2ڨBRZYbZ@$XA .dC%NXE5nG!E$YI)UdK1eΤYM9uOA%ZQI.eSQN%UYnWaŎ%[Yiծe[qΥj]y_&\aĉ/fĻ%O\e̙5ogСE&4riԩUfkرeϦ]mOo'^qɕcݽsѥO^ͱ/@@ DPB >QD-^ĘQF=~RH%MDRJ-]SL5męSN=}TPE RM>UTU^ŚUV]~VXe͞EVZkݾW\uśW^}X`…5Xbƍ?Ydʕ-_ƜYfCwZhҥMFZj֭]slڵmƝ[n޽}\ÍG.xr͝?]t=[0 <0… :|1ĉ+Z1ƍp2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{ 4СD=4GJ:} 5ԩTdj5֭\z 6رd˚=6ڵlۺ%ܹtڽ2.޽| 8 >8$2~ 9S9͜;{ :ѤuZ.:KY~ ;ٴk۾;Ӻ{}7ċ?<̛v=§[=ܻ{:H*\ȰÇ#JHŋ3jxǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH~ӧPJJjIVjʵׯ`ÊKٳhӪ]˶[XʝKݻ,˷߿ LÈ+^LR/ǐ#K1˘3k̹ϠCMӨSװc˞M۸sͻJ־ Nȓ+_μgCNسkνH*\ȰÇ#JHŋ3jxǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJ#իXjʵׯ`ÊKٳhӪ]˶۷pʝK7պx˷߿ LÈ%M̸ǐ#KL˘3k̹/MӨS^ͺװc˞W4۸sͻ NkƓ+_μУKNuȯ;@@ DPB >QD-^ĘQF=~RH%MDRJ-]SL5męSN=}TPE RM>UTU^ŚUV]~VXe͞EVZkݾW\mśW^}X`… &ibƍ?dʕ-_ƜYfΝ=SrhҥM8j֭][lڵmU}[nts\pōG\y˝?ytխ_Ǟ]vN` 4xaB 6tbD)VxcF/dH#I4yeJ+YtfL3iִygN;yhPC5ziҏ6ujTSV-jV[vlXcɖ5{mZkٶuK[sֵ{e\{p` 6|qbŋIerdɓ8|sf͛9wthѣI\ujիvvlٳi׶}wu.oÉ7~yr˙77zt9O~{v۹w|H*\ȰÇ#JHŋ3jxǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH*]ʴӧPJJ#իXjʵׯ`ÊKٳhӪ]˶۷pʝK7պx˷߿ LÈ+^̸wKL˘3k̹ϠCMiҨS^ͺװc˞M۸5ͻ Nq+_μУKNaco0 <0… :|1ĉ+Z1ƍ;z2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{ 4СD=ZҥL:} 5ԩTZ5֭\z 6رd˚=6ڵJ׺} 7ܹtڽ7޽| 8 Wmk8Ō;~ 9ɔ+[9͜" :ѤK>:լ[~ شk۾;ݼ{ 8Ō;~ 9ɔ+[VH͜;{ :i渄K>:լ[:ٴk۾;ݼ{ QtoI?>}]ۻ?ۿ?ݲ`'`` .`>!}E`^X[na~b"@$XA .dC%NXE5nljDzYI)UdK1e8$M9uOA%ZQI.eSQNZUY&)VaŎ%[Wiծe[qΥ[Ϯw_&\᠃/fcȑ%O\b^˙5o9bϡE iԩUfkaϦ]6bӷu杛o'^xKǕ/g޼oѥ߅>uٵo4yw>yѯg{LJ0 <0… :|1ĉ+Z1ƍ;zl $$K<2ʕ,[| 3L"Gμ3Ν<{ 4СD=4ҥL:hԩTZ5VQ 6رd˖j6ڵlۺ} 7ܹt޽|{3S >(Č;~ 9ɔ+[z9͜;KtѤKom:լ[~ ;6Rвk۾&s `ċ?<+w3=zdIKܻ{>Ǜ?~hӻ^$ۿ8`A&TaC!F8bE1fԸ"'dI'QTeK/aƔ9sH4qԹgO?:hQG&UiSOcބ:jUWfպ5U\;lY_ͦUm[oƕ;n]Nջo_慊paÇ/%qcǏ!GQD-^ĘQƋ8~@G%MDRJ-]S̍#IęSN=}TPEETRM>UTU^ŚUk›RmnVXeO~5VZmݾW\uśW^}v`… |Xbƍ?Ydʕ-_ƜYOPoZϣMFZj֭][lŝ[ny\pō}\/l>@^'~Y۷un^/x͟'^=k/O})ti^~0@$к D H*\Ȱ[HHŋj=ȱǏ CLQ"(S\"˗0cʜI͛8sɳgO> JѣH*]ʴӧPJJիXʵׯ`VHDaӊoWjKݻx߿ LÈ+>uǐ b2ƓH nf|?MtЦS^ͺװc˞M1۸s`K;:𕨏+_pУKNν.u}wO1X/*O:s~Ͽ(CIdH4Bx^{`շ&afvi~(bwIH Jކ\M44va8zѭg׾{w?sѧWXE0"FDO`qo!< $o k &R 1< 9A QI,"LLQEr#C/@n▓ D}qAkdhFy@l WR)+R-K QR1W^KB$2ApO( :|(0j7ܓH>S8@P"2mJ+TI)K Mıɋ  ;8],(:OmϏ7d3>R>Ra5T,B #aK,MeLfViڧVے p "Lp!Æ  X/H/S4RT1#ǃ^iLjPnD%cH'%$dń#%<>52EINBu *ժR%Zͪu+׮^ +v,ٲfϢM6mƵn+w.ݺvͫw/߾~,x0†x1ƎCR#ʖ3B1c҇*4<%phYG0k8{̨͈9#T -Ə#O|8ΟC.}:֯cϮ};޿amR}ݡ9;*{ yn:1% C3g'cĉRbrء#X'y+"DyTAi7dЎ=DEChEr:v!OB%NJYWb[r٥_rChjbDg*| 򧞝 6@d`T;iQ)2VBRZbXfe0ƉS}& 92xlb[kJg5T ܣ얿 ["2۬^j8:թٟ @*F^k&+ӂKܳ[⛯@$XA .dPa#bED^9G!?RQb^lHkAI.2Ef"uyN `QH$e(FQNZUYnWaņ:Yiծe[qΥ[]y_K&\aJ0D M6Ѣ2ʌt"ETTSTU[uUXFcuV$V<˔Q# ^4RΣH&TĦ 5BJիXjʵׯ`ÊK6ԲhӪ]˶۷pʝKݻx˷߿/LÈ ztLe4D!jhу%bNAɟ0:g'7SF3Bd^m 7{ȓ+_μУKN-سkuR4)cKu65VXzbN+\-QP5evh]'LNUv 6-VhfvA ~($!чbf$7߀ghAHPWj=w?Hx52&P|STIXTVVf\v`)fC!i時i"R7L>^mI(!_k9gWP8% \^ eSXi饘6Qv駠*_BJꩨ":h⓬F9kOV( _J뮮Ṣv ԝ™ʕ:Umfiv+JK>A;JPF;SE78P@~J&RnbjeYע+rKgw\W@$XA .d#rĈ^%Lj6.#70RXҤG_TF kaǗ E.2%gNqdYQ$e:GNZUYnWaŎ%[6Diծe[qΥ[]y_]:aĉ/&U"tdM Ơ-,q'I1L-Q /6Xlko^qɕ/gsѥOku٥9rP6(Ant)((p˭!3@D@tA#pB +B 0C;P/0z/i Fl# 4*W\I AxG G!4H$TrI&tҪrJ*1"+ʯvJ!"sL2L4TsM6tM8sN^\Nˏ O@5OA 5PDUtQFuQ*cҦO"RN;nSOCuTRK5TTS ,h „ 2l!Ĉ'"a(r#Ȑ"#ʔ*W,$̘2gҬi&Μ:w˟B-j(ҤJ2m)ԨRRj*֬Zr+ذ]LAYK,ڟ%wl6hдrҭkϸx/.l0Ċ3nxy(u=2̚7ssG.mӪ~n5حWm6ܜi;‡m8MC8ҧkVn:vީsK;=/o^굞ouصӯ"F> (vx *с-` J8HZ^|EZ0Px|Z(Ѳohވ-"5R碍9F7#0cpVƜlYPvbIbtu QZy%}b9v)%ɍYߙmPuP 4xaB 6tbD)VxcF9vLdH#IIPG+YtfL3iִy'ǔ9yĝAZiͣI\jTSVjVXеfcɆmL/B {n\s-{wAup{6̓a/ٸ*cȓ)W,rNTfne ^"yyE$Yv7ö}wˏu\F&>sq˗'g.Ըκ׊<4Iϡ5|x_]Rٷ}|'c_et1?ít(Ae i-Pa:/ E4JMRoEZ<z=5;5dܨ:!"uRC i+&|!lOK#Kz$*  t2W[N(t鼈Œ 5P]iN׾'7%zT$5%G ,h „ 2l!Ĉ'Rh"ƌ7^!"G8#ʔ*Wl%̘2gҬiɛ:w3cΟBwjȣJi])ԨRMJjGXz* I])!YvdoG;Emȳ +U&^n1Ȓ'dL2f3C̹S=.m4jS\0[HBN[o/D'(|deE&O{wȿ}Ce0g <כ }wWʟO߽~a`TWH¼b)ԠvkqѲ`Y6a] A]E(҅u]q"n@#9cDM>Cy$M -|s"E+*'^ul#YP~yPڕ)Јн%yR5cKxm4 :fPzb" h&(JڣVzU]E+Т@R.]!}q!$ꨥꨯnN+ezߥA,*Kб:,(:{m-Nz'jIP t`f .pgj놻ڻl*Ky;B/9^]vecVbfO;SR`:a3[gMS:a?( <0… :|1ĉ+Z1ƍ;zl $<2JZ YˣII2'I)q 4K`t Q^| ҩTZ%x֭\z:0+رd,6bJbӺܹtڽ7.޽E8Z[Pj4W mB}4"i1vH9dCJeT灝!ּ0S yٴk۾YO?eR71^bfAy*E8(mdž}rsVr>Ǔ'T{׳?|u_^kzUN^XM)vP&P"Uǐ!!Xr1Tڄh v]tHb&~[ELpL#/1X(.bB#*ddUL6Yc}XOVeZҖ_]iW`Aja9J]K…x :&J5U8h 9 W zIJIeDzjꩦYd*kH ꖘNBF韈uP'Ij$mAvvUqܦ~ no Qjbh9{#bKo/X/Qpd ._wXNPZ,1Ajxm\ X%kp.`ͻ[ $"lB)8G4lt!tXL#jD:uV_ VW wfȭ! @ k{Ҍݕ&&6zcMq] m <"e,yj/-wGWj^j4瘏޲褚>ߩcUr7{j&76(]SwD|x8`A&TaC!F8bE1fԸ"'$.8YW/Yie#k)e/Mx2%#Zs͞*1é2-X*UQZoƕ;d[wBoGdoaÄ 'VqcǏ뎄<*b  Y2ܡ:BZC & vc׈9͐6`^ѣ#ď{kHdh@@k 6,CBC :07m1k%bFdQ3g RH|r"n-9{6j%m?^Ӊ|C@C+j2[PHM[N,O4;̓1%i162Q9"L&04.27FrG5N{> zS ӅeFŢ2HtNdN~rJ.rw- I=m62lhBɄlo_\ąϴlT)jrdI2qS 7:,|y3^9yvu܇!FU Ы (&DX)ބJM'c3b BdB Nh4_B/sU@*٪uUt FeԅVh*XԚk7k k>[n(#z0V'G^Uʅ VxʃX&v<>gf1\sΥNn.&h>"#X:t/IQ}%Li>{i%2uW~! ]h'g1?vo|E?7Ͻ/{&;ob:|A^48RJU/+ zLUn`mv? nPl[_^Bw+xX)DTdPtH JXFAD+fٮtLX% 4l GRyRC̏]dX-0~"F5q[cd#ܘ$107LE( hV0°71!36>~IINGqK‡ " eE!BXH3 +_+D9Shd:јkf9E 1xNs]آƷ)JJA7y!hGE_f֧{l-T:ǖ^Em`[s~ĺV,o~(p{̄W|qܙD+Z#Riٴ6i@=h92ߚҧNhh.{ʇYq}bIqx߶ł'^ wҚ'^z^W<8ڡ~{+zH'j%=󣓗[G7uJ QD-^ĘQF=6G]Em$34 dP@b # pA /0C mpC:M"DOD1EWLA?j²+)qh<* ;v:O"# @:.D! ґIz @̪**d 73s:,2s$gEC3B =41FŌ0/J+4SM?Tt;E$TSOE5UUK?@K4$4[22%군_Ltօ$lρ\:b!f21s/Q4[X^ r l%e9MpU{MTWh_L_~%x`>`RxVxa'bzCP/Y[ۍ(HʸMcw,aUU@9yŜs:捃g2phfiOD6j3_%z!Sz6;m.{mGt4离n-±%S_m=,&n^|~/_,h „ 2l!Ĉ'Rh"ƌ7^D"=,i$ʔ*Wl%̘2%H7weΠϤ?*mʓӨ/Jj*֬ZRbׯu-k,ڴjײm6"Yaҭk.^S:;7/ KX(ÿ*^x㯍#SlrɘBvw3ТG.-J~;n54496};ʗEܤ𬪟Sn:vS{ޞ;? { /=0z`ˇ~fzV=2Ǜ{1Nt"鏣SF88Ə#OΕ%<9ԫ7غ ;4 >ϳzÏ/@stMAͿwo9$D6}P&``"d_>5^`5#X'B%"+'Tb*H1ʘuxqR܌A*dK&CŤaix!= CAMI&Tel~fe~ȤACڙ{9'y}vF#'\<i:Z"t]HbکG_^@YP~QhӖ[p>˗{JPC*Щ:)"2ԧB퍚JQiniIizK.c}iۮeVB=aVG Co k grT>aF(f23#M%6#'2ܵh̎Όh-fnFt$[ h^qGgdYM%G {ª)EWkϊp],qGKT{@T'$_Bm=\w{%"}ݑ;tc.^]䗯P 4xaBpbD:%_= bYPdƄ^AXɒylc”_0&艐υ)6ujTSV:uiV[vlXcɖ5{mZkٶu.Zqֵ{mSlk_ /\qÉ7>{հWáo>lwłuT@P` ^~tbWC 4ɗ7}z;wZᏧ~J+"п/|BX.`(9:)$h15p "(,\A )hk"|Eʐ 2B[<$%j);z/@Z5CH+Keh#5'VW`M"~ jȔR*͜;{KGi 4C]jt)Rt3txzb[{ oGYe>9fS=ܻ=|^/<{V>Rd/?B<]H ?pЁBǍfAҁ8@m`rroh҉=xTg=8wHc6ވ#[3h#yDБJ.ɤC6PNIe5RTaAEt`q-m@_.5bAhAk>&+s1ng~ hk)(v>GhJ%R6NJzVjХni; Rˑ襂5a;f X۩%!*"taSavzJlƖ7채9Vc:)Jl =mNY[gRؠoih[A9Q[rS辫1~Kp9#:<)čJpS\(o̱_jGv/Wh{Ʌ+j[a.Alڭ'6 mFS'=&ҁJ'L_1Qku@@ DPa*`Ç^"E^=Q E$f)2@%%nii J2_` ̇Njt ɜ?S BG%>'U%RU-~VXe͞EVZmݾ7Wu5;!^R ] 6/bō?Y)_fΝ=˔>l'I?T-È YUI"ӏ=WvhZ!jFؔٻm*kv5@۽^xVGWZϷ~|7˷_~[?@/R0[ #p+8e! k80LHeI%,)F<9ZčjDнz2H!$,$o=<It J*2KԲ-+#[K1R9t|9 2LP\ /0ނid jEi4()")NTP?_ P4W©Q2!RM7S;%4TJ5T.S UV_54Wchh5,<46k$H7 vAUtTj%]!amDqbQXbBNWl57]u׽oUvKt_zY]}+_S+L~&+JYAT'HmXIH-Eφ{3bu( jVc< X F `WfeUAu9xTӚ;yӜc9ݝ/.{&z_eOr aalCQI+Ɖѷ7~a4貂6;m=E噵lnwQ[nƻi 3H&"`Jd!Wȱ#jHҡ._T٥$Z!EntrJ0J‘‘4993(ȘH*]ʴӧPrJիXjʵׯ`ÊKөfӪ]+%۷QKwܺx޾ L0ῆCE Ɛ#KLy.P9Vxf0 eC:/wˋ )Zԩ5kid_[qȓ+_\)c9 5;w޿O<0˟ONS2U_S9]ytR} zVhfX6]!qbV"JވbY%0JbXUTIH<\n HD&="du%%MaGCZIe6ni\hf=9tIv&!xJeSQاij L"Fc=(izpJ襜vz馆IhZIS" *9*jr0ث+,[LAfBkn*zP 4xaB 6t.(cF9vdHDXI+YtfL3iִygH9yTO?+5sIK)u0S3NzkV[{VUׇLL mZkٶ.srSϙ6  ϣHʴaѦP]>JիX未+EJÆJvx#x'eʝKݻxެ5߿ /aJ_5S#KL˘#^ϠrM1ӨS^]o%V۸s-x/]Ƽ NxA[&N.u4AYKNz1cνNSFNyg5<˟O>^sϿRZtT R`=(EH fa}1MPH!^h(\0.fa-GQވІ&j'Rm6REVi. \r%6"fEgߗ(4ibe\6%" IY'\)R|Q(Ft6"椔(Rf*楛H$dXNUݙG覦w*΍ ӊ2 D§{bHP Q6hRT*x CUP8`A&TaC!F8bE1fԸcG dI'QTeK/aƔPș7oԉ'N594H?&EJ)HMjUWfTkWS*M+ԬE xD{έۥYk8@b_- uq.nXt[~y{zͯ^{ܟ׿ P D В*IN!\ = 9P! =H * A"ڻ>;="+hZfKłP\FE҅E~,(܊;c ' (+ ܒ.CD1CrL\7MS0˴:Bshɚv #@s/|Q$^ B1 hHutQ uSDGe4ӟ*唽 T'DUVHs[qն6|MW6ֹ_uN*m3YbmVD^ O;I4THO b1DW4=JG >@MuObUƤRU҃ms[AÍVe NXBB0Ahհ(b9xxBk r & ρf||_ޖzdYe R^wlՠoY蔃Y]^e5jS)VhAc곯4{˰#YAO^nJ`W^CuhNZ1[Pmwӄ&S^'H*\ȰÇ#JHŋ3jxǏɓ(S\ɲ˗0cʜq$I8QܙO;m>hN*iiCN*իXjIuא#. W^]4X/]lrEH]ؤ){*L;/#6$,06+;WHgCMN^ͺװc +[_oCT+l.{xƓ+_|7V+ .eu5S+ao;|P扌EZ^mf_0CB0v 6Y׉&݃VhTaYK=Z$j8b*M0܆2H"m{ 7 {wPrE%x_~jهԣY!9Ґu]EYhZW.p)HEvθzfgm򩢠\"!a )fcS*d;_>tzTR:ЕzW%A ea jq-z뮼ZkAegPp{F+-HZ-AJŴ's*\6q& XTaM2T H[|.:wl-c2l_K RLg0|rLK.ށE۩kؤԞcNSwr7R.×ʴjl!L7l/(Sc1W5K`wYmRis)- "NLJbQ=MN dz10oco7M8`A&TaC!F8bE1fԸ"'dI'QTeK/aƔ9sH4qR3gOw(gќDK4T!RO[::jUW┚kȑ'FrZKaڠoEWmXvnE}v ḗGsgϟQtiӧQVWIHٜIƚ[wU޽>oEOe ؤ|`Z'8X/3abx؃~}EwN~ʶ@ -]ڏ|Ф% %Ì4'{" =, F!¦3QDEK((J!,r7%l|0';-4רH,D R1oے́<#\|H=r̽<\aV[ m WoSTs=-5[rdJwōQxW7ɃNh%6NPUwE=C; xؑ_\1nXޏ6+{A.&IJXKTUS^2"g> k2gPTbbYiwʷ NYb^[֠=ơNV p "Lp!ÆB(q"Ŋ/b̨qE?N #Ȓ&OLr%˖._Œ)sƑ$i4hsgΞ>SϢ9M:Ҧ-:*u*ժVqB5ȭ oz5EM^ڤ&D;Rm.6Zhwd-_ȷpoق3D,RA+ܗdUv4ҦO.55֮_ÎzlAz[RܹM5ċ#O|9}:<x%v\[-_H_A7%Owau@@7B!VIXbas>Xᄼ%!!r/ˆQt1bi*>h~!~Y{A=^6dP;\ "XA%dPyAINfePGئo6#sY wf8YQ64(x(*%Cez`z(䀝z8dB`9ީAǙM~PZ`JPVzt2T> -Rk^[Ԥa CZf6H^& xZ_% DkVۯ:g)[m q#+1ce!{ >`! kٻ$r%A!62; = sJ3KtN PO4"3DIEmZ]Phgyi{O8`A&TaC!F8bE1fԸ"'dI'QTeK/aƔ9sH4[ԉgς:m<ThQD&TiӜ#F:jUB^J1V7]h^L B/FzEMm+4ڽ4+paÇkkbǏ!GmG!TI)R[DMټ6TTP-QQOSWm$X= ,h „ 2l!Ĉ'Rh"ƌ7^D"G,i$ʔ*Wl%̘2gҬi&Μ:w'РBiaʣJ2})SRR} *VUr+ذbǒ-kƮjD-ܸ` K.޼z/`-l0Ċ3nqJܐe7s"T?.m4jWM15_*6ܺw5I‡/nx1#w˼9ҧSn:N n{/oQD-^ĘQƋ8~@G%MDRJ-]S̍#I\hS'N= SPEETRM>UTU^ŚUV]~=zkPe͞EVmKF\ȸuśW^}X`… ,j[č?\й#|YfΝ=ZhҥMF}ٲd]w2ֶ̱[n޽}~;pō}\r=~<̡R/~~>w?e?\[2ؠBRX@$XA .dC%NXE5nljDzYI)UdK1e8$G9i0͞A%ZQI.eSQNfUYnWDfYiծYVϑl)]y_\aĉO%\bȑ%O"ƔAbgСE&]sfөUf%j]Ϧ]ۯlm?Խo'^<(lɕ/g9TͥO2n˳WwE|>yϽ{nON}x}Ьko@TK>>#pB +/԰ H*\ȰÇ#JHŋ3jxǏɓ(S\ɲ˗0cʜq$I6s3aN= JѣH*]ʴӧPJJիXjʵׯ=ob ٳhӪmIϑkݻx˷߿ LÈU6ǐ#Cmpb -c̹ϠCMӨSװcuMP셖/ͻ NuuSسkν?7T>.z˟O㓗j>5{& @@ DPB >QD-^ĘQF=6G%MDRJ-]S&C#9S΂8kTPEETRM>Uԧ6^ŚUV]~gXe͞EOj V\uśW^}ZX`… 8bƍ++qȓ-_ƜYfΝ=;YhҥMU|Zjh+^lڵmƝ[wл}\tjōWַl͝?]t_Ǟ]K۽gs+9\͟G^=bݿ}ߟZ6s0@c p "Lp!ÆB(q"Ŋ/b̨qE?N #Ȓ&OLr%˖._Œ)sƑ$i9&O> *t(ѢF"Mt)ӦNB*ͩVbͪu+׮^cVj+ٲfϢMrڡ<ٶ+w.ݺvͫw/߾;,x0GNkx1Ǝ*~Hɖ/cάy3Ξ?7D z4ҦOK52֮_eݚreضoέ{7ZU.|8.|9K>|:֯c.U޿49<Ï[c4=4mX" X 2@$XA .dC%NXE5nljDzYI)UdK1e8$M+mOA%ZQI.eSQޔZUYn5(U6%[Y8Ŧs-[qΥ[]y[l_&\8_o /fq⑏,e̙5ogE&]4HQfu՛)|]mܹuoGL 5pɕ3<~yvѥO^uٵo-wlկg{y~p@ 4 p "Lp!ÆB(q"Ŋ/b̨qE?N #Ȓ&OLr%˖._Œ)sƑ$ihfΞ> *t(ѢF"Mt)ӦNB*u*ժVbͪu+W7*v,ٲf϶ VNk+w.ݺvͫw/߾~,Wn]v@kpċCL#%cάy3Ξ?ҦON2)EZT]V3kE.|8Ə#GN:9ΟC/;eb6Ϯ=Nr{ϣO~rÏ5IܱzӶGe_EU H(_|5BRX!KYr Hm%:"eE-rr97☣;ƣ%@@ DPB >QD-^ĘQF=6DžUEyj2K5M(F5}TPE,QJ>UTU^ŚUV]~VXEVZmݾѡ^ SLdg˝r KQ"?Ydʕ-_ƜYfvZhҥV8͔`댴a6zscǸ}\pōGur͝?~u9Z>kg>m˼CG^zݿ_uz|ߟ<,y[B;숿c0B 'B /P(2C?$Ry HP|C6dE1#OZӒ)f9XU`)di晇lsjeI Zӑ8TЕUg@LUِPOzuױg׾;ȉt 6|@<}?Mzy\OAΖ%ꯠd38l!P ) 1P 9ÅC,AnsJO*+MsQSƋK$xDHFDrl'R)+R-bRAKGPZG4tEPȾ؜HL..ɿA -CMTEmG?5JoF> 43 zӠCӳ8<%DHaRUR[qU]yN^ Va=-J$5ʔS<T^%mHXvl -0UsMWuمv,h „ 2l!Ĉ'Rh"ƌ7r!>."u1˄UВEZ]@ypf̓<}BBʞ ohR)ɨRRj*֬E:+Xbǒ-k,ڴjײm-ܸrҭk.޼g/.l80WFȓqC1 N/sDA'&圐i,nqʆm6ܺw7‡ K8ʗ3o^6Ǥ' ˡd#>M]p(B-q;C;oﾸH㿯o>Z8 x AbQv/Mgx $AE$R'-w 5 )"`Dn5*8#5x#9W;#A h´L&iMiQP 9$PHci&m&e'uxiщHLK*!8Tf)鑨wZמ e*љz):*Y**ܩvm*;15aB Pա%٢V6jbEJ*UzPXu,Z{-نڪBP 4xaB 6tbD)VxcF/q"9V)ZHkM&i3ʢDKϟMykV[v,C!eXvlXkٶun\sֵ{o^{p`n6|qbŋ7v`ai5z1ҡ#CŤ0m =`ЧfM_C2dݻydE6~yr˙7wztө#^{v۹w_~oUSf)"Q)`hm dhQiUF ? dɥ+ @hC > })"%=EM :P-V]}1XepYmWjTU_^jKT#f}hUj( <0… :|1ĉ+Z1ƍp8H@ ʕ,[4ҥ̙4kڼ3N#I. 4(Ϡ"w=4ҥL:} 5ԩTZ5֭\n5رd˚=6mSb{jڹ-ʥ7^n >8Ō;~ y*Ȕ+[93^j :h@լ[~ ;ٴk۾;ݝI t̛;=ԫ[sػ{;LA?>ۻ?7?lɟ`H`` RWV-aIana~@$XA .dC%NXE5nljDzYI)UdK1e8A9uIOA%ZQI.eSQNZUYnץ7[Yiպ$۝kΥ[]y_b&\aĉ-UcL[9gd̙5ogСES]iԩNV벬Xmܹuo'^ܸgǕ/gNydћO^uٵ3wM1&_<ѥg{峝_}4p@ 4ȺCpAH*\ȰÇ#JHŋ3jȱdžBHɓ(S\ɲ˗0cd(r8srϟ@ JѣH*]ʴӧPJJըͪXjʵׯ`a^Z3ٳhӪ]˲lpeKݻx˷߿+È+.JŐ#Kp)k̹ϠCMdӨS^1Ǭc˞29iͻ zȓ,.У'M}سkνw̿8Otx˫_{˟OCϿS߀%`& 66P 4xaB 6tbD)VxcF/q"A4yeJ+YtfL37$IgN;yhPC5ziRK6u4MSVzkV[^lXcɖulZkٶun\sֵT]{h^h6|R‰7vrdɓ)WLSe͛9w,13ޑI6viիYvvl^g׶}wMSx7~yrufzt~{ٹw|xɗ7ٷWo}|׷w$XA .dC%NXE5nljDzYI)UdK1e8$M9uOA%ZQI.eSQNZUY&)VaŎ%[Wiծe[qΥ[]yWoרh&\ذQ/fcȑ%O\e̙5 5fСEouٵo4yw>yѯg{LJ0 <0… :|1ĉ+Z1ƍ;zl $$K<2ʕ,[| 3L"Gμ3Ν<{ 4СD=4ҥL:hԩTZ5֭kr 6رd5z-6ڵlۺ} 7ܹt뮌j7޽|{, )Ō;~ 9ɔ⭌9͜& :詟G>:լ[yٴkݴݼk <ċ?7̛/VJ=ܻ{O 䃆/J?M/` 4xaB 6tbD)VxcF/q"A4yeJ+YtfL37$IgN;yhPC5ziRK6u4MSVzkV[^lXcɖulZkٶun\sֵT]{h^h6|R‰7vrdɓ)WLSe͛9w,13ޑI6viիYvvl^g׶}wMSx7~yrufzt~{ٹw|xb7}ꭧw~p{׷ p "Lp!ÆB(q"Ŋ/b̨qE?N #Ȓ&OLr%˖._Œ)sƑ$i̩s'Ϟ> *t(ѢF"Mt)ӦNƼ u*ժVbͪukԫ6 +v,ٲ.Mv-۶n+w.ݺvͫw/߾~Czw0†=x1ƎC,y2ʖ/cάԩ7-:ѦONz5֮_Î-{PKέ{wAܼ.|8Ə#O|@O}3.=/֯cϮ};޿i-~=Ï/6,h „ 2l!Ĉ'Rh"ƌ7^D"=,i$ʔ*Wl%̘2gnI&Μ:w'РB-j(ҤJ2mi̛PRj*֬Zrmi+ذbǒ-{ٴjײm-ܸrҭkԻz/`6GF,aăay>vXʖ/?4GZUx3.6EͰ ~E6k9uks)iEeH\,xPNx1Ǝ"~,y2ȔZ標;-zϤut-_yYZv޻_Ftm,A/F-&ldGOX{Hu3ή}ՀSs/~<9OۻG7X?MWM¼b)tujpR`I 6t!] )h݆-8R]\p"r埊/81x~=R#CߏE>$$Q,n'#RT"9tx@ NyPP.ݓTWdu]ni%o aJYw.y${(Z@tI":.B6WQi*$悺,7f|EZVZݥR9ꥸu܇¨ks*PlZľyIY{@b qdie~ @d-Mzb"'ik2i/|k _%,p s8WvԡY -҂:j8Bb&gZ"~["h@$XA .dC%NXE5nljDzYI)UdK1e8$M9u)fO8%*shQ,&eSQ_.ZHYu~bWaEBkUlzeW z ڑq۶ ߑh\uwx#k\e9o^gСEܙiEMnuk]m i޹whb aȓl/\#3>1D.29Ya`{ko[}?h$$06a*0At0(B yB8 m ګN#S:"ZE:toJ<:ܰB{ *G"4!TRAI')ʌJ,a2K$*:P8! ‘L=b31Ns/HLhE4PD!2QFuEH('tKK4M3*Cq̵>,KÈFmhN<bOօnsL }HOP5@RUvYKe7L?riJQ=Yn96mbҩg|,NEի2ӡ9q=w;; us=zMhNsx`%`48М]‡Osf)f,#Pc9=s|%=b/NMwSU p "Lp!ÆB(q"Ŋ/b̨q#ǎ #ɒ&OLr%˖._Œ)ȑ3o̩c͐k :Т {H(SKB*u*ժ-Z*ւIW"e'_anߺEpHZk )`[z5/`}"lb LY+ʖ/c Ξ?-3ѦOW|T$j[5lkέ{ۼqթۢUjux8yC9Yq VZi|=h=(<>78??1ןGE k 2ؠ X j6\JX]1$^z e7b YM.v$du@! u|}'?iYG"9I2\!dBQKJyeYr%jTz9FY8CtA.r24'bd"r=܎a"ieR6BiUJxQe]:ѦY~Z%^Z&u* Ċ'ʩ"xhA˹Рu @)cy޴k2-Aָ[udג+H$} S.v|;Ds֙P;P4-o 3LӐ[6 ;5*V1Z\r"2K wKvkO1k\ao=-GB@>gP 4xaB 6tbD)VxcF/q"A4yeJ+YtfL37$IgN;SӧC<Z)CK6<˧QVzk֜Svի- <&~SW-6rf\_ؤewauWaZ$аH a66lhѣIz4XӫYvvle׶ѬY#oݻfnExr˙GDޜsU βaEE]$/}s2j" @?Gg;  <M|%t -<κj“80C C>,U3jѪQ qlKh@ /t KHo H~JG̯Z12<͇LM ijC|QN0߬q N=35%HPdΟPJ Bo" 2~ҒJ$Ⱦjr |Q@=<HIXW\} D$Wb3Lc,hAUji$g-M!jֽμM%)cJs}bG+s\$UWR݁]y=ᢸJۄ~bBoh63fo1N)Z4y9)c5a.Nq.065ĺF uͬ\z 6ؚ#ǚ5Y5ڵj5V/nRE]y{ M^ x$W аPa ͜;{l$[G>:լ[} ;ٴkmڶkq.;ǖ.ޙL-^V\٢䑔+yNȼqux{rGguۿR4`1G`Pz`. pNHag!MnkD^E_L\bc8чEv'dވc\w:dB'F6՛GIIMFIe?Ni%FX[#ڴ^bIfjBJi4NNEZf:!Ujj' Z6xJk9k*Urj ;* l&W)ez7)@@ DPB >QD-^ĘQF=6G%MDRJ-]S&C#gęSǚ=}N3ERB&hTU^ŚT]'rj&KeMeJZhݾW\u%W^}"W`f. L8ib VUƓ-_GZsND23(PN_}*u*ժVmu+S\lײfϢMv-۶&æv.ݺv*7/߾zկսkhŌC,;+f˞?-z嶘INzuӬ_g]5lWx6ݼ.зĩv8ΟCG<֯c~<;wdnzpٺɋ==N׷yvWL X]-8P=Xat[Qءi((->G/6Gc_2Fb6#: #Ti裑G"[X yD_#R-IdX>$y[$_^Wo~P 4xaB 6tbD)VxcF/q"A2"R/D*fL3i< eM;ys$ɟC5zdPK*eԨSS{JzkV[Nůa %{mZkٶunDlҜ@+,liռ`^ vcɓFe#5thѣ!~&tعYvvlWM W;# ̽7K{/\.gcߦ^uҵW|xb}kmٷw>zi +o'z/?2j?Kl0! ) 5 EQ D3ސj 2#ӍA;K rB"-4B$\Id&*Ǔϳ bDJli@zdn0ߊR#dM|o6԰>2,rF@ B/:S#HjIëATHL-TANR( <0… :|1ĉ+Z1ƍp8H nɫʊ'Z 3̏SЊy@J_ϙD=r$IL:} ҨTj5kUZ65رd˚= Zi׺} 7ܹtڽRmW a˗ / X߇B(.##lX`dEZ6 kФKm,ԪGٴkCm{ܼ{ 2{ ?<׳^*?}g쯚H`-&v" E̕HdUEU(e!a=O9*C)T6RU ֏@{ w dHLΥ_RNIeV#Dч0Ћ:؊2&<09 r  R*ِlJDHh06zehYFJC*yii)F$fiFEꩮ k:*B5`.u *Axq'">yа٦f>ke"'nDtkaVU 3{ Dl k/{LpFFY(!$ Mf4 }Yi,g"9ʖ& C o0Fj,&8d:Ao>;iCRP 4xaB 6tbD)VxcF9v@H N F*v eB/Ԃdʌ&k2 Sbx4(%B"c"sӦW4yQ i4֮_I5{mZ/նun\ε{H{0޿ q⊉ظaɓ|c GnthѣI6}hXR q'֋Bg/ !R?[>8A־ѹE[g:SwO{x]yKg>/d3X>|7< <:n5b i*hJΧ.zJ7L!D0*tBE: ;z9~2J+bhFj1= $!*#L.$$ I"\G,M[02< Ӷ)0NXdF7M'xӡ6!8lNSNܐ&L<=s5)t3K1}HM9S: u+45PMLAmTcZm\U`(Qs+;RNd<a*4Crq_/OۂյQ=W^LuٕUiJUQ0su{ fR`ڵhuHZmhC"}#80(XF{h\ź18 ڑ僻Xfi[su}[znh.馝~?^hOJ8nyQGFَ&XCE[ξg;f՛"ZJSC|S¡whSU6nr p "Lp!ÆB(q"Ŋ/b̨qE?N #H_UrJʊ]Djx@[{u NYt3'Ɨb2ԡx#.,Un$׮^ +ӱfϢMvmIJlU6.ݺͻ޾~%B ,$+Nw1|C8rB”/cάy3Ξ?kd7lI(҅Jmܙxȭ Z&ʥ YYU[NxϷyÏ/>/＝VWMeO fB`R1dTT GUe}r8~!5"%w"[&בx-r" X~7أ?$F;FD=8C7X`MA)4BYeirt&&Cqʹ wujF'Z"ՠ̭KQ~W*ړYL/aU YT& ^Hj~(꾹(6:B'cCk]J,\ 2 =Q_F"*CPFTbj%jMfO2I*a{gu[e,VoV3ܰpc>m>$N6-Fr)n\.A.-E .&1I36Ç9XĂɌb{ |@@ DPB >QD-^ĘQƋ8~@Ǐ]DIp ZM<n Ɨ1SsŞ2iḊJ%ϓ?^ŚUV GVXe"zVZ#پ m\eśW bW`w hbƍ?Ydʕ8JWs̚7n>}5hgNT4àO-~ye޽k\c7~mrș?]OV]vݽod"{bQ34WFSM_z7h&$ *V**0:/<+oAkAP+B 7Ì4P#C$DOD1EƋlD+$borOM$K͢1!rj$'"S1\J2!,ԒB.EK1ǜnK22L5dM7c0/JP)61MO5!]D6BYjI77S$N?*1E%T1M5UU;sՂPu5VYg8k'3"/_IсQ^G#E26I}dXK0T$ BXmg+X+e2RbRzն]a#=Zu^6_+_{_VF8au4b]` ݑv\x%vg֠p9[,fVށF!)q#&+]J$xg{6.h&i{( <0… :|1ĉ+Z1ƍ;zl $[B2"E {U񋼖"u <jϡD=tbˤL:} ҨTNլ\n 6رdfj6mEj l 7ܹtڽ7^"5@k]&8پ;qȒ'3\2͜;{mߊ>:լ[&0يeӾ6݄u7‡/׳w>!K־׊ES 4`.~ `x7w>!bV~b"6]]b'Rbu1N7c65zuc>btdFvb}GF$rI d6dQ)ɣ^P 4xaB 6tbD)VxcF/q"A4yeJ+YtfL37$&M;y\gН@qz!QK[*ejTStZkHlXcɖ5{-śeun\sUks-]{%o_M&,aŋ3Nܘcx sf͛9w|rXɟI6}hEvU댱-;muuop˙7w~6yϩW~z׹W=vo~[=}|G~~ת>o@p<4|p5!M‡'ܐ=D ?q Q4QME sYA1Fq op*<b$73R%$4(l,rF,G-ń ,h „ 2l!Ĉ'Rh"ƌ7^D"=,i$ʔ*Wl%̘2gnI͜:m'Е<9Τ#2E*)TGRj*֬FjڑS;cj,ڴjײmmIJk­k.޼zE(-\b Dǒ'S,0O*VJ63ТG.m\On`̝îu폲g'o/n w֩xsz:oŽ;ŰO-|/\˯o)ڻK9h[jiw :Ray zR!meeyU(Ru$"ܹb5X ]+xe;~#xDnd/~1E-"9%UםVj`%a9&eIG&m\Z٩&y |˜@@ DPB >QD-^ĘQƋ8~@G%MDRJ-]S̍#=ęSN=}TPEETң4>]h3SU^M UցR~VXe5z5Tmݾm ^A]}X`€I:bƍ?#\ʕ-_ƜYQɈ7gţMFZ+Z}C{%VWk޽}\AÍG\͝?}ҭC^]dvݽC-u9Yky6y_|ǟ_^P쨴@TAUcA òb t=80DG$JD1E[c _(Bc:jչ:lgS=5l%qnċ+ ngpK]N.rH]'Hl<ݙZƋRW5v{޷=YsF_H`Y. ~`=x:gnȡEvQ `z{Qyv w{EVd(}.**cA8U@.2#N>9}eV^%Mj[^ysVR)f~Ǽߤ}x`B"h DwA]xqR^HѱquBǡH!&$]eu98#5e ڸ#=AY!ɠK:$iMB ёSfyvza iܗ "c@C['Qh:yU' ʛʤH&X䣍J:}6)o ܝyWfBu*f:vj]WPeB2V+ {" *GZUx3+ׄ]l ֫)`ERHZ~ڳiy= nĸ6v ,x0 jx1ƎC82@'[f9fn,z4C։*Ԯn5ڶon-3޾:8qË<<9-;.}@+Zoz*6r/~YO~=u?oۯ.??E~`Py5 2L6RX!QY!mh_}#&&GN_[*(7RX# c^;#2IE~0- Ye^fCb:DfCf2Bj&B]f`iI'YyIPi*w:z1ڨBRZxrک ZbUJQl#G8`A&TaC!F8bE1fԸ"'9RC'MRG-KD)$D6[Ts˜<{2P5},zsRLL*5jЅFZ)V_;lYUm[oƕKl]_ջo_w:U[?{{yѧW|{ǟ~7eHa P ,@:9j8c0 [0C DMA>0D#;(Lq%lEJt0Ō;~ 9ɔ+[k9͜;U9YA>:լ[~ 3ٴkFlݼs <ċzh˛Jۻ;|H*\ȰÇ#JHŋ3jxǏɓ(S\ɲ˗0cʜq$I8sɳϟ@ JѣH*]ʴӧ1oBJիXjM`ÊK˯fӪ]˶۷pʝK]R˷߿@BE ÈN̸ǐ#KLe/k̹gLiO^ͺװc:۸n:Nȓ+_s7У[vxνËK}蓖Wo=ßOϏ` 4xaB 6tbD)VxcF/q"A4yeJ+YtfL37$IgN;yhPC5ziRK6u4MSVzkV[^lXcɖulZkٶun\sֵT]{h^h6|R‰7vrdɓ)WLSe͛9w,13ޑI6viիYvvl^g׶}wMSx7~yr˙7w:LG~ou۹w|xɗ=]hً~|׷9,h „ 2l!Ĉ'Rh"ƌ7^D"=,i$ʔ*Wl%̘2gnI&Μ:w'РB-j(ҤJ2m)ԨRRj*֬Zޔjs+ذbǒ-{ٴjײm-ܸrҭk.޼zkT~.lبÊ3n1Ȓ'Sl2̚}x3Т~m4ԪWnZiײgӮܺw7‡/neʗ3o^ҷBn:ڷs_;CWo׳o=@@ DPB >QD-^ĘQF=6G%MDRJ-]S&C#gęSN=}TPEETRMNTTU^ŚU֎5~VXEVZmݾW\uWFW^}=x`… |Xbƍ?Yd VƜYf/;MYhSCFZj֭]slڵm>9iܽ}[pōGܣn͝?W\ipխ׭)vݽv͟I~HOϮ|Y~H*\ȰÇ#JHŋ3jxǏɓ(S\ɲ˗0cʜqM4sɳϟ@ JѣH*]ʴӧP]JիXjUԪ6KٳRoD˶۷pʝKݻx&߿ 7j+^TcƐ#KL˘3kϠCc, ӨS=װc˞MNIͻsMq~УKN$سk|}i/-ӫ_Ͼ=˟pS%/p(_@@ DPB >QD-^ĘQƋ8~@G%MDRJ-]S̍#I"N=}TPEETRM>UTU^ŚUVUozUXe͞uiaNhݾW\uśW^}XpTFXb Xdʕ-_ƜYfΝ=ZSFZӏ!^[lڵmƝ[n޽}oō u͝?]tխ_~ٽG}*k͟G^zݿqrKp}0@@H*\ȰÇ#JHŋ3jȱdžBHɓ(S\ɲ˗0cd(rŚ8gɳϟ@ JѣH*]ʴӧPڌJիXjʵ+˚^ÊKْ`3L{۷pʝKݻx8u߿ L!ˆ+^0Ƶ"KL˘3k޼/ϠC1ӨSw5gհc˞M۸5ͻߖY' o 9УKNֳkS:{սߙ=Ͼ:Q;MO8](M~& 6^> @$XA .dC%NXE5nljDzp a*V $K%eΤYM9uٓH6 QI.eSQNZUYngQaŎ%[Yi xjU"OǺw_ns aĉ/fcȑ%Oʖe̙5o\ֲ9YE\yQwf58 |]mܹuo'^q¹ƶ W/ExO#^ݺ@g+w'_>*wկg}4G6\c?x~p@ 4TpA|2rr3PoCCqDK4qOTqEJѪAB[ZԱ=$lG rH"dE#<,h „ 2l!Ĉ'Rh"ƌ7^D"=DEZOj ZT%0QHS͒B-j(ҤJ2m*t$IRj*֬Zr+ذbǒ-k,ڴjײm0۸rҭk.޼]ʅtH^Pu3Oj'bl2!G~Y3ТG.m4ԪWn]زgӮm-l~ gz.ʗ98ҧSn:ڷ;nOng~? 8 xxQ|Q"x!tqz!!8"%x")hkmXRzyHb4c/#1HV= 9$Ey$I*$֋ 9E,CH=]d%h$$FVay&i&mP 4xaB 6tbD)VxcF/q"A"RW*(˔2KִygN;yhϑ$VzhRK6ujTSVzkV[vlXcɖ5{mZNse^%<r-p7@޽s6|qboerdɓ)W|sf͛9wthѣI_n;qM/b\ @ث'Ъ:lKpjG7~yr˙7wzѩW~q 8E$4' G>׷~k ^"KB 5ܐ=!OM<ū.T)z_WzwӳS|yѧWiԩ9jرeϦ]m}q7fֿ'>0xkŕ/gsQuG^%_ޝqɽ)'_yg=N_3/@ ( <0… :|1ĉ+Z1ƍp8H K<2ʕ,[| 3̙G͝7s 4СD=4ҥL:} 5ԣ=Z5֭\z Zժͯd˚=6-αjd6ܹtڽ7޽|V 7 N X*Ì;~hS~ ;n+;ݼ{6ċ)̛;_ԫ[=ɷ{t5Û??ۻ?|ۿV;qG``է`@@ DPB >QD-^ĘQƋ8~@G%MDRJ-]S̍#Ię3M:}TPEETRM>UjƛS^ŚUV]ƬjWe͞E%Omݾm[uśW^}7l`… F8`c?YX-LnfΝ=ZhҥMFZZ[˵k<[n޽}\pōfq͝s?Ǟ]vݽ^;ɡ.'^=hԩ^|ǟ_~?E?Ī=lC->dA0B #( <0… :|1ĉ+Z1ƍp8H K<2ʕ,[| 3̙G `3ΝԬ[~ 0شk۶yۙy <ċ̛Þ< g+3ܻ{>>]˛?:+C.ۿ?zH`Vq`>~EH!B8`A&TaC!F8bE1fԸcG dI'QTeK/aƔPH5qisfOw9hQG&UiSOF:jU/^պkW_2՚cѦUm[goӠuջo_Y3n}>xqǑysϑ.zu#R7Ȼ7tN?|y'W=v#?#o~ PKo!x/9 !P 90= H*\ȰÇ#JHŋ3jxǏɓ(S\ɲ˗0cʜq$I6s4s$͟@ѣH*]ʴӧPJJիXʵׯ`ÊKVkXeӪ]˶۟hyp۩v˷߿ Lխ+^̸c}Lg}>KTP,MӨS^m82װc˞5dʹs]xrCζ -3ȓ+_μsKNzU}[νE8Q}ӫ_Ͼ=G˟>^ >NM~h& 6}R%BQ4sV ($P 4xaB 6tbD)VxcF/q"A4yeJ+YtfL37$ѦȎ9GS!Ϟ@5ziRK6ujTSVzkV[vlXon9mZkٶuy6PBuJ]{p` 6|qbŋ#Λncɓ)W,W"t-thѣI6}ujիYv 1ȯi׶wv撟oxpÉ7~yr˙}5wsө\7չw|x@7}zշw/=翷~O @n|%4ο -L,h „ 2l!Ĉ'Rh"ƌ7r!>,i$ʔ*Wl%̘29a͜7w$fϠB-j(ҤJ2m)ԨRI*֬Zr+X@Ò-k,ڴ$.)Rm[Vҭk.޼z¹.l02n1Ȓ'Sl2̚7s3ТG.mSƊz5?W˔m6jںw7p^.n8Ko9ҧSnz娪k܎;۷=/{T ֘P:#({yOgYS˒QJؔUZy%d8%[`~)fHYYe\U}mZ-gRfHdP 4xaB 6tbD)VxcF/dH#I4yeJ+YtfLh֬)gN6yzO15Q3o.ujTS[&zuU}nUYgXcky5 ^un\$ε{o^{]:UQ~Zᦉ /frdOYk] L4^nI-iիYvlٳi9JfJwMb&~yÕ456Fus`kVɗ7)=C3p}8l']("Ц`zj2%j - rO8?CpJ PEN6hR"lŋq}1+ "%0C$az>&s>(=)/v B*Bg<@R̔B i.H*\ȰÇ#JHŋ3jxǏ CIɓ(S\ɲ˗0c$M3sx'GoS(ѣ."]R)ӧPJJuӪX%^Z#ה]zEͱ E7kE{-)kkeM_ LpQÈ+^̸ǐ9d6\)ΞyӨS,z&֌e1م}/(^M0M|D0n!~yqԣνbËOyǗϿLoѧV/2}_#RU$+xB Rǖ[-`[Mt mhWB RarDaAF܀,x.(4{6f6YEkg_$EPF&$iB.YND'RMYbM@ byPU.ei I`ntRcxȧA~:#DHY(F蟌6ѢKBhD֤]D)@Xӈ]zsTV_*tu)m*jt뤸JE k {$|JF2 N: euZykYе50~(A٦ؾ׷䊫Z+j@nkj\"ܕ«!'9B\W|3bkyvh̡E<)ʥMF:jՕOfSkB]O~lY5u!ҳV*7i2(g܄t{M [0Ͷ [/o < Kݪ=4ϳlMOym!X≹ *ڂ\Iw yIaj$7sOI؅-|-T!α}{a ,h „ 2l!Ĉ'Rh"ƌ7^#Ȑ"G,i$ʔ*Wl%̘2Ei̜:›;JhО"mӨRRju%ԫZ%fZ#VH^5-ܛIú5tk3X^ Lo=&D/Snj2̚3ТG.m%^FUװ7({۸w훡9k휲6*7;D\BWf-kV/(}m[xJ{q\X8o>犼XNDqa4 JHۃ`U]ZN5C屇vŜ@X9T"thO/6tcO%A 9$WDy$I*9!KRa$p ESR[ze]ih3'#դA1Qs5T d6is$c*ig2(J:i@Q:QYӥ\itO~)Abz*rZ(I$bD ygB%&Zsp"T(zr0Ikgs,hF;-Z;Zf)j}^{掩.Q$K% v6ti`k߁'1K滧0B<1[Ln1Ovn|8B$_|U$2K Q3䫾/$a7t=Fٜ{P 4xaB 6tbD)VxcF/dH#I4yeJ+YtfL0ԴisfN7yMCg %zO5ETSSVzLYRՠǕKf_ԕpMa)7i]؅܃vmUx67$\Ӱ@6rX_kthѣ%}ujիYvtY9:쫹us!T7~yŕdt߷QN.Ls;x/c1S|mZ|WM o\|P$ h qiB˰B01 M5Jq7: [+0@o{4(*Ҽ [pwҳQ,"0SL L 2M?|MXi21>5QC ɲ '}JMgǸ5Ho eC( <0… :|1ĉ+Z1ƍp2ȑ$K<2ʕ,[| 3̙ ؼyN8{ 4͝Dc =4ҥL:}4΢T]N5֭\b5,Fd˚=*8E^O] 0Zkᖤxޤ^xf*,@݊9͜v :ѤK>a$.eٵٴk7;'ݼ{ VċGaߌ^克"؝CBG$:B> ?|ۿ?onZu\xԀ0`>`({8}WS@qOirp}hC؄2HcDՈc:ccFYхFI dN!Ie!NIe^~ fbI&@YPhJ%` qIgY&aݘқ<Jhh)gilA*&^J`j:KIvJjj_Ci~裵+vkU|4+ٹF8`A&TaC!F8bE1fԸcGA9dI'QTeK/aƌ f͚2q˝=*9hџUZ2ROF:eSW#ZJJ_n}eZbѦUm[oƕ;n]w7VJ̈́Dqclj?imW KEM]A=tiӧQVƽ3FQvja֞n߿#.Jx6y1>:lձg׾_P|iC~z離w/o)| ,A L ; O90,D Kۻ?uʷ7_:l`ߑǞ . z 6aNsן~8ʼn&|b.}(!r"0XٸBP 4xaB 6tbD)VxcF/dH#I4yeJ+YtfL3ip'Κ;OCY %zԤQK6u*IQBZkV[vlXŖ5{mZkٶ[W[׮NKھc&|qbŋ7&Jqdɓ)W|y#\Ä7cgK&}bө%fvlٳ_C}wnݻik5o]!q˙TysөWu۹wN[sm7뫫}}|^~=m A |QO -CKl:dCB̐DnDJ\%H*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cT M3aΞ@Y JТH*]ʴiʣNJ* Xjʵׯ`ÊKٳhӪ]K[ *w.]v˷_{È+^̸ǐ#KL2H<23g?g -iƤOOL԰װc˞M۸sΊy3[ֻ.7qÏ?-ds=N9سkνw9:nV~5揽CoOӸw9Ͽ(_Y͖ m 7UiDV la (t#h("8Z֢j/cVa>cތ(dN8`A&TaC!F8bE1fԸ"A9dI'QTeK/aƔ9H7qI2N1{2P(U4aNO=R:fGOf:0VRu~UUlYgѦUm[ɾ;n]wջ!U]XpXK|+XƉ>6X1d4-{sgϟAttiӧQV߹Y[d&gf*97\U-mom|ysϡ]zuױg:Uzr=\ Pz<O~ P@\c>,/мs6, A*A E,Qt@p^.5p"ođFfGHQ!/"LR%[Ѭ2:)RD #mB|C l.d ,h „ 2l!Ĉ'Rh"ƌ7^#Ȑ"G,i$ʔ*Wl%̘2g҄ &N5)3fϟB]jeѣJiRPI*ӬZDubׯ=-k,ڴjײm!ٷrҭk.޼zZ6,ߡ Jxyjǐ+NLyq/s3Тnm4ԪW&xkc˞mIڸKoVLK#o9rKn:ڗO|oyé;\xzϏo>K? XkJ7ށ%ނy'*5݅j!~֟!8"%7av,^碉QٌImi#=#}9$EZ?ݒ5 ݓ$>эMyc*%]FP 4xaB 6tbD)VxcF/dH#I4yeJ+YtfL3iLgΜ6 OCY %zԤQKԩ4Slz+YBlXcɖ5{mZ=un\sֵ{dU?oӾm&y 1Lȑ)W|sfbnthѣI[ۙTN5Fرi=۶DHQxpÉ7~yrZܽѕS~Kȷ|xhɗ7}z^篷o1 ~Dѷ|ہ% -Hۃn58!g!jl~al vhy$rxbe"¦P(@$XA .dC%NXE5nG!E$YI)UdK1eΤY$9s~ig̞"=$0hQ(&eSQW.ZU"UCZWaŎ%[6Viծe[q~Yw#ֹHbܙg_M&\e&X%Ző%O\ٲbȗ5ogСe찴軎3E]tժaϦumM뾋oWcs(џF=eҥNB*uʦT ݙ(W^ +v,ٲfv-۶n+w.ݹ\q6Zw^w7#N\װbx2ʖ/cάRΞ?-z4i-}qȒUd ;ٶog{.|89O|9 Fڿ_ϞNݷ޿5rׁ_y^/~ϯvZ{~>'C)Ńw颠bTrء؄EƠs*آp,2g0Z3;أ?HcraOfNr$)wSXPP 4xaB 6tbD)VxcF9vdH#I4yeJ+YtfL3ip'9klɳ`NCy4!PKI*ejTStZ+ī;v@V_y5KXkٶun\sֵ{o^{xoTg qa7vX/c0 vB/p {qPZ36}ujիYvvl|ζeݻyQ۷o7~yA ztӗsܒs*9b|xɗ7}zH~|~~K%J썣pe"rJ˿|% -K8 ܐ{ E)r҅"omѤpܑ})I"$PD!\<%#(Ųnꎢp.Q/2t>K43NtOM0[<ņԓ4B Kһ4AkTE)H*\ȰÇ#JHŋ3jxǏ CIɓ(S\ɲ˗0cʜI͎r2N> J4(ϣ "]zR)ӧPJJӪX#^ Pן+=fE%(WL Ky_>,.l-*סx_u5 @ZUo㎝Lb̹ϠCM4ϭڸWF*{۸s{j׭[}0 Z>o2t.XϟAqtiӧQVukׯfTVEƝTn߿'[8M ~UxA/G|бOZ%.wOKz{Nx1sʬ ,( LPl! s (Lh AڐA 1Eĉ0,j8[  UQI-T|3:B3SZYi-H6o=UXtG= Eh$|OOS1ĞIDo$ځ%vZp-se-W02tr^{_*Gcj/bz[?fO`C_҇[KEbq=YI.|Mw8)TYKM9AQϫt㡪w(x=g)XʏɚzПM ,h „ 2l!Ĉ'Rh"ƌ7^#Ȑ"G,i$ʔ*Wl%̘2gҬi#7w̩'P>=-zrѤJ2mϧR)"je^12eh_ -kO] C ׃l:3>>ԛ@.3X&-jRl2fD3s3ТG.meKS^런gӮm 7sWެupqd7`(0qR9Yъ<׳o=ӯo!$?T8  ğ!8oy%CTAסpuC\> ! &$"D] 5x#9#= ѐG*NI29L5*EVur5gIȥXЃ9qVs %xX~W9QPtQ䥊g>y'y'}eQ2)蓄.i(*jG6Ԕ 6fZmW)8jRePPXc heD*㞢:+z+=A㯹 c;[S*jbF~NؕCyզ -بú.;/h^6 S8#C( ?ץvf~6l.eYI"jBQD-^ĘQF=~RH%MDRJ-]SL/PSgK9wTPBETR$6*iT>~2.]zu0kϰ ,;pKZ `mz[\z ] Kp-bZo 7mBW-_ƜYD=ZhҥMFgSY#uzhlٵmMLT;,/qB.0?n>`%@u=T{酳;=axsWX>~/@$@D iA\AB /B 1Ұ[N?ƒ CD:\EΠK+ 8 "{*QGojO @$72K-K/C0sL2#42dt5(F *&<"}R;co ~L(P OH%3 =$Cq0t8G%ROE5UUWe9|XٜU[o=&\ u:osO4H !DFGb`ϭhj+oܵr57]ue]z1^wN\ ]"H'#[fv[֠K%F_dOF9e.]fgP,m6?jhg)Vܽnc2xa,RjٻFvh p "Lp!ÆB(q"Ŋ/b̨qE? )r$ɒ&OLr%˖._Œ)s&͚6;ys˜:yecТ'Mt)ӦN|*"ҩZOa,V°Cq Z^~kmh.Zt޼ ޻jB,y2X+cάy3Ξ?-ZhL>]:RԬ_Î-{7kGl[f'~ҖB9=DC >|rdwcϮ޿/~k/;ɈsҟX" 2ؠ9JMxf! exڇJ5݈'Hآ/c!rH6n;H0X=$]NOBKa^Sr9b ~hg)[i٦oNsYw♧v&Yh"ivե(E8`A&TaC!F8bE1fԸ"A9dI'QTeK/aƔ9fMԹgO?:hQG4fROF:(SWfպ@_kYg%n٩ m[oƕ;wGwջo_:paÆ=q㤉!G<٢c˗1礼rzq=ti Vukׯaƛv_ֽ;*n߿W=]~S+ϡG.0tױg׾{w[?|y7Iyწ~}׿mIb-LPl!P )P 9A QI,Q+YT,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gҬi&Μ:w'РB-jhMH2m)ԨRRj*֬Zr+ذbǒ-k,ڴj*]-ܸrҭk.޼z/.\Ċ3n1Ȓ'Sl2̚7s3ТGL4ԪWn5زǚm6ns7‡/n|ʗ39ҧSn:Ak0 <0… :|1ĉ+Z1ƍp2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{ 4СD=4GJ:} 5ԩTdj5֭\z 6رd˚=6ڵlۺ%ܹtڽ2.޽| 8 >8$2~ 9S9͜;{ :ѤuZ.:KY~ ;ٴk۾;Ӻ{}7ċ?<̛v=§[=ܻ{:H*\ȰÇ#JHŋ3jxǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@ JѣH~ӧPJJjIVjʵׯ`ÊKٳhӪ]˶۷pʝK]v˷߿ LÈ+^̸,BL˘3k̹ϠCMtYɦS^ͺװc˞M۸sD Nȓ+_7УKNسk 0 <0… :|1ĉ+Z1ƍp2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{ 4СD=4GJ:} 5ԩTZ5֭\z 6رd˚=6ڵl2m 7ܹtڽ7޽| 8 >l-Ō;~ 9ɔ+[9͜;{&ѤK>:լ[~ ;lǡg۾;ݼ{ <ā.<̛;=ԫ>n9,h „ 2l!Ĉ'Rh"ƌ7^#Ȑ"G,i$ʔ*Wl%̘2gҬi&Μ:w'РB-j(Ҥ=*m)ԨRRZլZr+ذbǒ-k,ڴjײm(ַrҭk.˸x/.l0Ċ1Ȓ'pL2̚7s3ТGi4ԪW/e5زgӮm6kO]/n8ʗ3on9s n:ڷs{ p "Lp!ÆB(q"Ŋ/b̨qE? )r$ɒ&OLr%˖._Œ)s&͚6o̩s'Ϟ> *t(ѢF"MѣҦNB*u*ժ%Zͪu+׮^ +v,ٲfϢMv-۶nb}+w.ݺvﲌw/߾~,x0†#Nx1IC,yrǔ/cάy3Ξ?-z4iKNzR֮_Î-{6ڶoέ{7޾e-|8Ə#O|9ΟC?<:֯cϮ};޿@@ DPB >QD-^ĘQƋ8~RH%MDRJ-]SL5męSN=}TPEETRM>UT^ŚUV]~VXe͞EVZmݾW\śW^}X`… FXbƍOXdʕ-_ƜYfΝ=vhҥMFZj֭][liƝ[n޽}\p]6\r͝?]tխE~9,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gҬi&Μ:w'РB-jhMH2m)ԨRRj*֬Zr+ذbǒ-k,ڴj*]-ܸrҭk.޼z/.\Ċ3nLȒ'Sl2̚7sy'ϢG. 2ԪWn5زg6ܺ7‡/n8r3oҧSn:ڷ]:,h „ 2l!Ĉ'Rh"ƌ7^#Ȑ"G,i$ʔ*Wl%̘2gҬi&Μ:w'РB-j(Ҥ=*m)ԨRRZլZr+ذbǒ-k,ڴjײm(ַrҭk.˸x/.l0Ċ1Ȓ'pL2̚7s3ТGi4ԪW/e5زgӮm6kO]/n8ʗ3on9s n:ڷs{ p "Lp!ÆB(q"Ŋ/b̨qE? )r$ɒ&OLr%˖._Œ)s&͚6o̩s'Ϟ> *t(ѢF"Mt)ӦNB*u*QTbͪu+׮^ +v,ٲfϢMv-۶n+w.Vͫw/߾~,x0†#Nx1Ǝ'},y2ʖ/cάy3Ξ?-z4iKNz5֮_Î-{6ڶox:7޾.|8Ə#OΟC.}:֯l}9,h „ 2l!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔ*Wl%̘2gҔ &Μ:w'РB-j(ҤJ2m)ԨRRj*֬Zr+ذb.ٴjײm-ܸrҭk.޼z/#-l0Ċ3n1Ȓ'Sl_7s3ТG.m4ԪWn2زgӮm6ܺw 4‡/n8ʗ3ohҧSn:ڷs :WǓ/o<׳o=|9ӯo? 8 x ͗ :8P~J8! FX!j!z!] 8"]X",@@ DPB >QD-^ĘQƋ8~RH%MDRJ-]SL5męSN=} @GEETR%6UTU^iV]~VXe͞EVڝCW\śW^6X`… FXn?Y_ɕ-_Ɯ!e͝=ZhҥMt|Zj-9[liƝ[n޽}N[p϶GxqǑ'Wy󺼝G5tױg׾{w |yw@@ DPB >QD-^ĘQF=~RH%MDRJ-]SL5męSN=}ZOEETҍC>UTU^ŚUV]~VXe͞E[UӴmݾw"[uśWJ{X`… FxZō?Ndʕ-_>(fΝ=ZhMFZ5Jͫ][dkٵmƝ[nޗܷpō;}\r͝?Nwtս&]ع^x]N7^=  p "Lp!ÆB(q"Ŋ/b̨qE? )r$ɒ&OLr%˖._Œ)s&͚6o̩s'Ϟ> #ТF"Mt)ӒDB*u*ժVbu4+׮^ +v,ٲfϢMvΡ[+w.ݎuͫw/_o,x0†#NxqLC,ʖ/c̐Ξ?-z4ҦO:>z5떜[Î-{6״oέ{7޾I-|gď#OظΟC.}:ԯc'<;{n.~<ϣ;4=@@ DPB >QD-^ĘQƋ8~RH%MDRJ-]SL5męSN=} @GEETRM>UTU^ @V]~VXe͞EV-ˡkݾW\uś7V}X`… FXbƍ?Yd-_ƜYfΝ=ZhҥMFoj֭][lڵmƝ[n.W\pōG\˝?]tխ_Ǟ]v͹O@@ DPB >QD-^ĘQF=~RH%MDRJ-]SL5męSN=}TPE RM>UTU^ŚUV]~VXe͞EVZkݾW\uśW^}X`…5Xbƍ?Ydʕ-_ƜYfCwZhҥMFZj[lڵa:ElZfm(ؽ[?nstխ~]vݽYxyOv-e_=֏=~0@D0A<iF9M8-^bB(m(pA#D( <0… :|1ĉ+Z1ƍp2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{>"СD= ֫Uu(QaKn!˧֫Xl:ױd˚=֬Ǵlۺ} 7ܹtˮ7޽| 8 Ō֊:ejՂ>FV(D gɜK>:Ԭ[~ ;6ղk۾;ݼ{KGuE :TADC&NG>O~/>ۻ_'W0 zܲC/`'` Y&`>aNhQfB9h!߅17H"o b*x.c2HLӍd5Id[-dJuN> eRN[}ThiYuTIe9@$XA .dC%NXE5nG!E$YI)Ud