Upload
others
View
2
Download
0
Embed Size (px)
Citation preview
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
Open XML Gateway
User Guide
Conventions
Typographic representation:
Screen text and KEYPAD
Texts appearing on the screen, key pads like e.g. system messages, menu titles, - texts, or
buttons are displayed as follows:
Example: Enter your name in the User field and click OK.
Files and folders
File and folder structures are marked as follows:
Example: Download the file doSpellingSuggestion.xml from the folder Examples.
Entries
User entries are displayed as follows:
Example: Enter login here.
Quotation
Quotations and references are displayed as follows:
Example: Further information can be found in chapter “Overview” on the following pages.
Weblinks
Web addresses and links are displayed as follows:
Example: http://www.corisecio.com
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
3
1 INTRODUCTION .............................................................................. 5
2 SYSTEM REQUIREMENTS .............................................................. 6
3 INSTALLATION ...................................... .......................................... 7
4 ADMINISTRATION .................................... ....................................... 8
4.1 Login ......................................................................................................................................... 8
4.2 Home ......................................................................................................................................... 9
4.3 Express .................................................................................................................................... 9
4.4 Advanced ................................................................................................................................. 9
4.5 Express mode ....................................................................................................................... 10
4.5.1 Level ..................................................................................................................................... 10
4.5.2 Config ................................................................................................................................... 11
4.5.2.1 Security Level Low................................................................................................................. 11
4.5.2.2 Security Level Medium .......................................................................................................... 11
4.5.2.3 Security Level High ................................................................................................................ 11
4.6 Advanced mode ................................................................................................................... 12
4.6.1 Entity .................................................................................................................................... 12
4.6.1.1 Consumer................................................................................................................................ 12
4.6.1.1.1 New ..................................................................................................................................... 12
4.6.1.1.2 Edit ...................................................................................................................................... 14
4.6.1.1.3 Delete .................................................................................................................................. 14
4.6.1.2 Provider ................................................................................................................................... 15
4.6.2 Policy ................................................................................................................................... 16
4.6.2.1 Activate Policy ........................................................................................................................ 17
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
4
4.6.2.2 Listener .................................................................................................................................... 17
4.6.2.3 Request ................................................................................................................................... 17
4.6.2.3.1 Applying new functions to the policy .............................................................................. 18
4.6.2.3.2 Removing Policy functions............................................................................................... 18
4.6.2.3.3 Changing the order in the Policy ..................................................................................... 18
4.6.2.3.4 Configuring the functions in the policy ........................................................................... 18
4.6.2.3.5 Displaying a description text for a function .................................................................... 18
4.6.2.3.6 Accepting the changes ..................................................................................................... 18
4.6.2.4 Response ................................................................................................................................ 19
4.6.2.5 Error ......................................................................................................................................... 19
4.6.3 Logging ................................................................................................................................ 20
4.6.4 Admin ................................................................................................................................... 21
4.6.4.1 Change Password ................................................................................................................. 21
4.6.4.2 External Access ..................................................................................................................... 21
4.6.4.2.1 API Keypair ............................................................................................................................. 21
4.6.4.2.2 WSDL-User Keypair .............................................................................................................. 21
4.6.4.2.3 Keypair Download .................................................................................................................. 22
5 LOG FILES ......................................... ............................................ 23
6 HELP & SUPPORT..................................... .................................... 24
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
5
1 Introduction
The CORISECIO Open XML Gateway provides companies the possibility to cost-effectively
and simply protect their Web Services. Nowadays, more and more applications communicate
via the internet and local networks because of the increased spreading of architectures like
SOA and Cloud Computing. Because of the network-based approach applications and data
are increasingly exposed to business critical threats. This e.g. includes, besides various se-
curity vulnerabilities, themes like data theft, XML-DOS or Multi-Layer attacks. These weak
points need to be protected efficiently.
CORISECIO – Open XML Gateway provides the following features:
• Policy-based SOAP messages processing
• Filtering, authentication and authorization for Web Services
• The gateway may be used as stand-alone component
• Enables use of cryptography for Web Services
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
6
2 System requirements
The statements regarding processor, working memory and hard disk storage may only be
seen as values for orientation as the requirement for system resources mainly depends on
the Open XML Gateway use. Reliable statements are only available by testing in your sys-
tem environment.
Processor Intel Pentium IV 2,4 GHz or more
Working storage 1024 MB or more
Free hard disk stor-
age
10 GB or more (amongst others for Logging)
Operating system • CentOS 6.0
Software • Java Software Development Kit 1.6
• Java Cryptography Extension (JCE) Unlimited Stren gth
Jurisdiction Policy
• Apache Tomcat 6.0.32
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
7
3 Installation
In the following deploying the Open XML Gateway in an Application Server is described. If
you are using the preconfigured Virtual Appliance, you may skip this chapter.
The Open XML Gateway is operated as Web application on the Application Server. If re-
quired, please kindly see your Application Server’s documentation.
For deploying in the Apache Tomcat rename the War-File so that the filename corresponds
with the required deployment path. Maintain the file extension. Copy the file to the Tomcat
webapps directory. If necessary, restart the Tomcat.
After deploying test the installation by starting the web application.
Enter the following text at your browser’s address line:
http://<hostname>:<port>/<filename without extension>
Example: If you have renamed the war file openxmlgateway.war and if your tomcat installa-
tion is running under localhost:8080, then the address to be entered is:
http://localhost:8080/openxmlgateway
You will be shown the Open XML Gateway login page.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
8
4 Administration
The configuration is done completely via the Open XML Gateway web interface.
4.1 Login
First you will have to login at the Open XML Gateway web interface. The password is prede-
fined as follows:
Password: secRT
Enter the password and click Ok. At correct entry the Open XML Gateway administration
page shows up.
The password may be changed after login to the system (see chapter 4.6.4.).
If you are logging-in for the first time, the data store will automatically be created in the Open
XML Gateway directory. Here the Open XML Gateway configuration is saved.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
9
4.2 Home
After login the Open XML Gateway start page is displayed. On the home page an over-
view of the menu items Express and Advanced as well as the services status is shown.
Here you may start and stop the service.
4.3 Express
By using the Express button you may switch the Open XML Gateway to the Express mode.
4.4 Advanced
By using the Advanced button you may switch the Open XML Gateway to the Advanced
mode.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
10
4.5 Express mode
In the Express mode all configuration steps are executed automatically.
4.5.1 Level
Under the menu item Level the solution’s security level can be set. At installation the security
level “Low ” is preset.
The following Security Levels are available:
• Low : At Security Level Low all messages incoming on Port 80 are checked against
an XML scheme for correctness and XXE attacks and forwarded to the configured
target address.
• Medium : At Security Level Medium the message sender has to authenticate using
SSL v3 (Client authentication). All incoming messages on Port 443 are tested against
an XML scheme for correctness as well as for XXE attacks and SQL/X-Query injec-
tions and forwarded to the configured target address. Also the XML well-formedness
is ensured.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
11
• High : At Security Level High the same features apply as at Security Level Medium.
Additionally, messages are tested for WSDL scanning attacks and Replay attacks.
Also requests are. Additionally a SAML Token is added to the request and it is en-
crypted and signed. The response delivered from the target system is decrypted and
the signature is verified.
Select the required Security Level and click Apply.
4.5.2 Config
Using Config you may configure the behavior of the solution. The provided parameters are
dependent on the selected security level.
4.5.2.1 Security Level Low
At Security Level Low the following configuration parameters are available:
• URL: Enter the XML scheme file URL, the messages will be validated against. If not
defined otherwise, all SOAP messages will be accepted. Also, you may define a file
here. The format to be used is file:///E:/directory/file.xsd.
• Endpoint : Enter the target address formatted like host:port, e.g. localhost:4711.
4.5.2.2 Security Level Medium
At Security Level Medium the following configuration parameters are available:
• URL: Enter the XML scheme file URL, the messages will be validated against. If not
defined otherwise, all SOAP messages will be accepted. Also, you may define a file
here. The format to be used is file:///E:/directory/file.xsd.
• Endpoint : Enter the target address formatted like host:port, e.g. localhost:4711.
• SSL Key Password : Here you define the password for the Consumer Keypair, used
for the SSL Client authentication.
• SSL Key Generate : Here you generate the Consumer’s SSL Keypair.
• SSL Key Download : Here you may download the Consumer’s root certificate and the
keypair.
4.5.2.3 Security Level High
At Security Level High the following configuration parameters are available:
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
12
• URL: Enter the XML scheme file URL, the messages will be validated against. If not
defined otherwise, all SOAP messages will be accepted. Also, you may define a file
here. The format to be used is file:///E:/directory/file.xsd.
• Endpoint : Enter the target address formatted like host:port, e.g. localhost:4711.
• SSL Key Password : Here you define the password for the Consumer’s Keypair,
used for the SSL Client authentication.
• SSL Key Generate : Here you generate the Consumer’s SSL Keypair.
• SSL Key Download : Here you may download the Consumer’s root certificate and the
keypair.
• Provider Certificate : Here you may download the provider certificate.
4.6 Advanced mode
In the Advanced mode you may detailed define the Open XML Gateway performance and
configuration.
4.6.1 Entity
Under Entity you may configure the Consumer and the Provider. Consumer are authorized
clients, the provider is the identity used for signing and SAML tokens.
4.6.1.1 Consumer
4.6.1.1.1 New
After clicking this link the form for generating consumers shows up:
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
13
Permitted entry values are:
Field Description Acceptance criteria
Name ID of the user to be created 4-50 characters accordant to the reg-
ular expression ([-]|[_]|[.]|[a-z]|[0-9])+,
unambiguously (no commas)
Keystore
Password
User password; an entry is possible
by clicking …
0-100 characters
Address Consumer address 0-60 characters
Description Consumer description 0-60 characters
When clicking the button, the data is sent and the new consumer created and a key pair is
generated if the acceptance criteria are fulfilled.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
14
4.6.1.1.2 Edit
By clicking Edit you may edit the selected user’s properties. The name cannot be edited. The
acceptance criteria are the same as at creating a consumer.
4.6.1.1.3 Delete
Via this link the selected consumers are deleted. The data is completely removed from the
database, issued certificates are revoked.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
15
4.6.1.2 Provider
Here you may change the provider information.
Permitted entry values are
Field Description Acceptance criteria
Name ID of the provider to be created 4-50 characters accordant the regular
expression ([-]|[_]|[.]|[a-z]|[0-9])+, un-
ambiguously (no commas)
Keystore
Password
Provider password; entry by clicking
… is possible
0-100 characters
Endpoint Hostname and Port, requests are for-
warded to.
Format: hostname:port
Trusted SSL The optional SSL provider certificate
is required if the endpoint is using an
Valid SSL certificate.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
16
SSL connection.
After having created resp. modified the provider, click Activate Policy .
4.6.2 Policy
With the Policy Editor, XML Gateway provides an option to arrange and configure security
functions available via adapters in a process logic. Thus, security functions may be realized
by the Workflow Engine without programming effort. To open the Policy Editor, click the
menu item Policy.
With the Policy Editor you may configure how incoming requests and the corresponding re-
plies will be tested resp. secured.
When clicking the symbol, the Editor appears and the current configuration is shown.
The entire sequence is displayed graphically. You will see areas for configuring the Listener ,
under Request the request processing, the response processing (Response ) and the error
handling (Error ).
On the Policy Editor main page there are buttons to be used for starting the configuration
pages.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
17
4.6.2.1 Activate Policy
This button is placed on the left side of the page. Clicking it results in persistent saving the
current configuration and activating and starting (or restarting) it. After successful start you
will be lead to the Advanced Mode overview page, displaying the Services status.
Please pay special attention to the fact that, without clicking Activate Policy on the Policy
Editor main page, all unsaved configuration changes are discarded, especially when leaving
the Policy Editor. When restarting the Policy Editor, it will be preset with the currently saved
setting.
4.6.2.2 Listener
Select Listener and click the Select button, to configure the Listener for the service. You will
be forwarded to another page, where the available Listeners are displayed as selection list
(the current configuration is selected by default).
Select the Listener from the list. Then click the Configure button.
You will be forwarded to the Listener configuration page.
According to selection you have several options – from the simple stating of a TCP/IP port to
configuring an SSL client authentication. Please kindly consult your product’s Modeling Ref-
erences regarding the varied configuration options.
Accept the required configuration by clicking Apply . You will be returned to Entry Point
Configuration .
Click the Apply button on the bottom of the page to accept the changes and to return to the
Policy Editor main page. The changes are accepted for the current session, but they are not
persistent and do not affect the service (to achieve this, please click Activate Policy on the
Policy Editor main page).
4.6.2.3 Request
Select Request and click the Select button, to configure the request processing.
You will be forwarded to the Request Configuration page.
On the left side you will see the currently configured Policy (Request Configuration list) and
on the right side all available functions.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
18
4.6.2.3.1 Applying new functions to the policy
Click the function in the list of available functions (Functions ) and click on the arrow point-
ing to the left. The function is added to the Policy at the end.
4.6.2.3.2 Removing Policy functions
Click the function in the Request Configuration list and then click the arrow pointing to the
right. The function is removed from the Policy.
4.6.2.3.3 Changing the order in the Policy
In the Request Configuration list click the function, the position of which in the process
order you would like to change. Then click the buttons resp. . Normally, the process
order is essential for the correct message processing.
4.6.2.3.4 Configuring the functions in the policy
In the Request Configuration list click the function you would like to configure and then
Configure .
A specific configuration page for the function appears.
Please consult your product’s Modeling References to learn more about the configuration
options.
Accept the changes on the configuration pages with Apply . You will be returned to the page
for the Request Configuration .
4.6.2.3.5 Displaying a description text for a function
In the Functions list, click the function you would like to learn more about. Then click the
Display Information button below the Functions list. In the Description text field fur-
ther information for the function are shown.
Alternatively you may consult the Modeling References.
4.6.2.3.6 Accepting the changes
Click the Apply button on the bottom of the page to accept the configuration changes.
Please kindly bear in mind, that the changes do not apply immediately, but after having been
confirmed again on the Policy Editor main page (see Fehler! Verweisquelle konnte nicht
gefunden werden. ).
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
19
4.6.2.4 Response
Select Response and click the Select button, to configure the process steps for the re-
sponse.
The functionality of page appearing then is mainly the same as of the Request Configura-
tion page (see paragraph 4.6.2.3). The difference is, that here the policy for processing the
response is configured here.
4.6.2.5 Error
Select Error and click the Select button, to configure the error page, which is sent if errors
occur during processing. You will be forwarded to a page where you may configure the error
text. Entry of HTML tags is possible here.
Accept the changes by clicking Apply .
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
20
4.6.3 Logging
Under Logging the recorded SOAP messages are shown.
In the fields From and To enter the required period of time and click Refresh . Under Log
Messages all logged messages are shown. The status shows the log reason, if it is an error
(red), a normally processed message (green) or a message, where a warning occurred dur-
ing processing (orange). Date is the log date, Message ID an internal Id and Source the
sender’s address.
Click an entry to have the details displayed. A description of the log-cause can be seen un-
der Message Details and under Message the message can be viewed.
By clicking a bar in the timeline you may focus the log entry view on this period of time.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
21
4.6.4 Admin
4.6.4.1 Change Password
Using Change Password changes the entry data for the Open XML Gateway.
4.6.4.2 External Access
Here you may configure the API, used for accessing the Open XML Gateway functions from
external applications.
4.6.4.2.1 API Keypair
As for an external accessing the Open XML Gateway an encrypted connection is required,
the API Keypair has to be used for encryption.
4.6.4.2.2 WSDL-User Keypair
For authenticating and authorizing the access to the WSDL API the WSDL-User Keypair is required.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
22
4.6.4.2.3 Keypair Download
SOAP messages sent to the WSDL API, first have to be signed with the private WSDL-User
key and then have to be encrypted with the WSDL-API Public Key. The Open XML Gate-
way responses are signed with the private key from the WSDL-API Keypair generated pre-
viously. The signature may be validated with the WSDL-API Public Key . The responses are
encrypted using the public WSDL-User key.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
23
5 Log files
The Open XML Gateway Log Files are located in the folder log of the web application’s
directory structure. In this folder there is a file named connector.[YYYY]-[MM]-[TT].log.
Here [YYYY] means the year, [MM] the month and [TT] the day, the log file was created at.
To open the log file, you will have to close the application first.
CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com
24
6 Help & Support
You have a problem or a question? Our Support Team will support you fast and professional-
ly.
Please kindly have the version information of your CORISECIO solution available. You can
find the data required by the Support Team in the Security Administration (RCP) under
Help > About via the button Plug-In Details . On the client systems you can obtain these
data via the appropriate About dialogs of the CORISECIO Runtime Components.
Please kindly state your CORISECIO customer name and your customer ID at each inquiry
which you may receive from us if necessary.