diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000000000000000000000000000000000000..49710c4382f543c150ac443607319cd1af687edc --- /dev/null +++ b/README.adoc @@ -0,0 +1,30 @@ +:toc: +:toc: left +:toclevels: 6 +:sectnums: +:sectnumlevels: 5 +:xrefstyle: full + +== OIOSI RASP Library for .NET + +[WARNING] +A security issue has been pointed out due to old versions of the Log4net component. +This issue requires a HotFix presented in *2.1.1 (Log4net Hotfix)*. The next stable version: *2.1.2* will have this issue adressed. + +[options="header"] +|=== +| Version | Branch | Release status | Description +| 3.0.0 | master_dev | _Ongoing development_ | +| _2.1.2_ | _master_ | _Announced_ | - Log4net component update to 2.0.12 +| 2.1.1 (Log4Net Hotfix) | master_2_1_1_hotfix | _Announced_ | +| *2.1.1 (Current)* | *master* | *released* | xref:doc/OIORASP_Library_DotNet-ReleaseNotes.adoc#rasp_2_1_1[RASP version 2.1.1] +4+| xref:doc/OIORASP_Library_DotNet-ReleaseNotes.adoc#what_is_changed[View section "What is changed" for earlier releases] +|=== + +include::doc/OIORASP_Library_DotNet-InstallationGuide.adoc[] + +include::doc/OIORASP_Library_DotNet-ReleaseNotes.adoc[] + +include::doc/OIORASP_Library_DotNet-ReleaseNotes-CacheOverview.adoc[] + +include::doc/OIORASP_Library_DotNet-Tutorials.adoc[] diff --git a/doc/OIORASP_Library_DotNet-InstallationGuide.adoc b/doc/OIORASP_Library_DotNet-InstallationGuide.adoc new file mode 100644 index 0000000000000000000000000000000000000000..73f1756a43a59c4a89748ffa1be6b145b6c45d2e --- /dev/null +++ b/doc/OIORASP_Library_DotNet-InstallationGuide.adoc @@ -0,0 +1,104 @@ +:toc: +:toc: left +:toclevels: 6 +:sectnums: +:sectnumlevels: 5 +:xrefstyle: full + +== Installation guide + +=== Introduction +The OIOSI RASP Library for .NET is a Microsoft .NET-based toolkit for implementation of RASP (Reliable Asynchronous Secure Profile) compliant business applications. + +*The current stable version is: 2.1.1* + +This document describes the steps needed before the RASP Library can be built and used. + +The library can be downloaded from https://digitaliser.dk/group/405467/resources (Compiled Library) or at directly https://rep.erst.dk/git/openebusiness/library/dotnet (Open source Git repository) + +=== System requirements + +In all cases the following is needed + +* Microsoft Windows 7 or newer, including the latest service packs +* Microsoft Internet Information Services 5.0 or later +* Microsoft Visual Studio 2012 +* Microsoft .Net 3.5 Framework +* Port 80, 8080 and 8008 (HTTP) outgoing open +* Port 389 (LDAP) outgoing port + +To host your own RASP HTTP service you will also need + +* Port 80, 8080 and 8008 (HTTP) ingoing open + +=== Install Package +The OIOSI RASP Library is distributed as a zip file, which should simply be unzipped into +any folder. + +Note that projects within the release pack cannot be moved from their internal paths relative +to each other. If so, library references must be updated. + +The zip-package contains: + +|=== +| lib | External libraries used by the OIOSI RASP Library +| samples | Sample projects +| src | he OIOSI RASP library source code +| test | nit and integration tests +| dk.gov.oiosi.library.sln | Visual Studio 2012 solution file +|=== + + +==== Certificate +New feature in RASP 2.2 is that each .dll is signed by a Software Publisher Certificate (SPC). +Digst has purchased a productive certificate that is used in the release cycle. +If you want to compile the code yourself (using the NAnt script), you must install the selfsigned certificate located in ‘certificates\SelfSigned\DigstSelfSignedSPC.pfx’. Alternative, you +can add your SPC thumbprint to the System Enviroment Variable with the key +’DigstSPCThumbprint’. + +==== NUnit (for running the NUnit sample test) +To run the NUnit test dll located in the test folder, NUnit needs to be installed locally on the +machine. When installed the framework can be used to run NUnit tests and develop tests in +Visual Studio. Follow the two simple steps to install NUnit: + +1. Download the newest install version of NUnit for .Net from www.nunit.org. +2. Install the downloaded file. +Now NUnit tests can be executed from NUnit which is located under +“start/all programs/NUnit.Net-version/NUnit.Net-version”. + +==== Test endpoints +Test endpoints can be found at the following location: + +http://digitaliser.dk/resource/555072 + +=== How to release Signed RASP .NET +Work has gone into make a signed release og RASP .Net. +However, we have the problem that the virtual build server can't reach the code Signing certificate on physical USB eToken. +Therefore, the only option so far, is release a signed version from a workstation. +These steps explain howto setup the workstation to release a signed version of RASP.Net. + +. Add (if not already exist) to windows Enviroment, the password to the certificate (yes, the key start with '-'): + Name -DigstSignToolPassword + Password not added to SVN. + + +. Add (if not already exist) to windows Enviroment, the key and Hash to the certificate (yes, the key start with '-'): + Name -DigstSPCThumbprint + VAlue 98642f19b787ec0386db8b52ce9e8ed4e49c + +. Install (if not already done) SAFENET DRIVERS: https://www.trustzone.com/standard-code-signing (step 1). + +. Find the svn revision number, and update the file './../NAnt.build.Distribute.Signed.bat', and set the correct build number (line 27). + +. Run the file './../NAnt.build.Distribute.Signed.bat'. + + +=== Verifying installation +To verify that the setup of the library has been done correctly it is recommended that one +compiles the RaspClientTests solution and, tries running one of the test projects such as +dk.gov.oiosi.test.request, or that the dk.gov.oiosi.test.nunit.library project is compiled and +run in NUnit. + +=== Uninstalling +Uninstalling the RASP Library is done by simply deleting the folders into which the library +was unzipped. diff --git a/doc/OIORASP_Library_DotNet-ReleaseNotes-CacheOverview.adoc b/doc/OIORASP_Library_DotNet-ReleaseNotes-CacheOverview.adoc new file mode 100644 index 0000000000000000000000000000000000000000..ce0c0b326d88a47970152ee4557340d00ede5378 --- /dev/null +++ b/doc/OIORASP_Library_DotNet-ReleaseNotes-CacheOverview.adoc @@ -0,0 +1,22 @@ +:toc: +:toc: left +:toclevels: 6 +:sectnums: +:sectnumlevels: 5 +:xrefstyle: full + +== Cache Overview +[format="csv", options="header", separator=";"] +|=== +Cache name;OIORASP 1.2.3.HotFix1;OIORASP 1.3.0;OIORASP 2.0;Proposition to change +LdapCertificateLookup/CertificateCache;TimedCache - 14 days;TimedCache, 24 hours validity, each 1 hour check for expiration;TimedCache, 24 hours validity, each 1 hour check for expiration;Limit maximum number of entries by some big value to avoid OutOfMemory, use LFU cache together with timed cache +OcspLookup;TimedCache - 1 hour;TimedCache, 1 hour validity, each 10 mins check for expiration ;TimedCache, 1 hour validity, each 10 mins check for expiration ;-- // --- +UddiLookupClient.getServiceCache;TimedCache - 24 hours;TimedCache, 1 hours validity, each 10 minutes check for expiration;TimedCache, 1 hours validity, each 10 minutes check for expiration;Critical! If we do not decrease it, NO changes in public UDDI can be visible to clients during 24 hours. +UddiLookupClient.getTModelCache;TimedCache - 24 hours;TimedCache, 24 hours validity, each 1 hour check for expiration;TimedCache, 24 hours validity, each 1 hour check for expiration;Barelly used at all, at least none in TrueLink subsystem uses it. +SchematronStore;QuantityCache - 2 path entries;LFU cache (max size 20), no expiration;LFU cache (max size 20), no expiration; +CrlCache;Unlimited hashtable for each CRL url, checks for expiration each time it is accessed, updates in the same thread where it was found that it is expired;LFU cache (max size 10), if failed to update - reattempt in 5 minutes by special scheduled job, which is started after each successful cache update depending on revocation next update date from CRL server;LFU cache (max size 10), if failed to update - reattempt in 5 minutes by special scheduled job, which is started after each successful cache update depending on revocation next update date from CRL server; +SchemaStoreCache;absent, Schema object is built each time when required;LFU cache (max size 20), no expiration;LFU cache (max size 20), no expiration; +MessageIdUnfinishedSignaturesCache;10 minutes;TimedCache, 1 hour validity, each 10 mins check for expiration ;TimedCache, 1 hour validity, each 10 mins check for expiration ; +SequenceIdUnfinishedSignaturesCache;10 minutes;TimedCache, 1 hour validity, each 10 mins check for expiration ;TimedCache, 1 hour validity, each 10 mins check for expiration ; +|=== +LFU: Least Frequently Used diff --git a/doc/OIORASP_Library_DotNet-ReleaseNotes.adoc b/doc/OIORASP_Library_DotNet-ReleaseNotes.adoc new file mode 100644 index 0000000000000000000000000000000000000000..e3b48019e0e5569e81c78b54e2f1009cbebfc1be --- /dev/null +++ b/doc/OIORASP_Library_DotNet-ReleaseNotes.adoc @@ -0,0 +1,504 @@ +:toc: +:toc: left +:toclevels: 6 +:sectnums: +:sectnumlevels: 5 +:xrefstyle: full + + +== Release notes +The OIOSI RASP Library for .Net is a .Net based toolkit for implementation of RASP business +applications. + +The distribution is part of the OIOSI work for exchanging business documents in a secure and +reliable way using the internet. See http://www.digst.dk/It-loesninger/NemHandel/Til-itudviklere for more information. + +The framework can be downloaded from https://digitaliser.dk/group/405467 + +=== Release content +This release comprises the following deliverables: + +* dk.gov.oiosi.library.sln – Main Visual Studio 2008 solution +Documentation: +* OIOSI RASP Library for .Net Release Notes.pdf (this document) +* OIOSI RASP Library for .Net Installation Guide.pdf +* OIOSI RASP Library for .Net Tutorials.pdf +* release-notes-2.1.0_HowToUpgrade.txt +* A number of detailed release-notes related to specific issues – named release-notes- +_.txt + +Samples + +* dk.gov.oiosi.samples.TestCertificate – Test certificates using RASP +* dk.gov.oiosi.samples.httpEndpointExample – Deployable test endpoint +* dk.gov.oiosi.samples.ClientExample – A client example that can send a document +* dk.gov.oiosi.samples.consolesClientExample – A console client, use to send a user +specific document + +For testing (as sub components of the RaspClientTests solution file): + +* dk.gov.oiosi.test.request – Sending test project +* dk.gov.oiosi.test.extendedRequest – Uddi, ldap and ocsp test project +* dk.gov.oiosi.test.nunit.library – Nunit test project +* dk.gov.oiosi.test.nunit.interop – Nunit interoperability test project +* dk.gov.oiosi.integration – Nunit integration tests + +Contributors to this release: + +* Jacob Lund Mogensen, mySupply ApS +* Peter Sone Koldkjær, mySupply ApS + +=== What is changed? +[NOTE] +In the following part of the document, some issue numbers are mentioned – these numbers are +internal numbers used by the Digitaliseringsstyrelsen (Danish Agency for Digitisation), so please ignore these as external +developer. + +[#rasp_2_1_1] +==== RASP version 2.1.1 +Main purposes of this release have been: + +* Make patch for NemHandel Referenceklient to avoid program stop on 2 Trust2408 root +certs in Windows cert. store. + +===== New features +_None_ + +===== Fixes +_None_ + +===== Changes +* Update CertificateLoader.GetCertificateFromStore to avoid +CertificateLoaderMultipleCertificatesFoundException() based on more than one found cert +(issue 1961). + +===== Removals +_None_ + +==== RASP version 2.1.0 +Main purposes of this release have been: +* Update code to enable PEPPOL BIS documents in Danish NemHandel. + +===== New features +* Support multiple schematron validations per document type. +* Send document, having a Sender part with other KeyType than the valid Danish receiver +KeyTypes. +* xPath parsing of values in RaspConfiguration has been updated, so it’s possible to set a +fixed value instead of an xpath – eg. string(‘EAN’). +* RaspConfiguration: It now possible to set an empty string as value for to +disable Schema validation for a single document type. +* Support schematron styling using XSLT version 2.0 (Peppol schematrons), by using IKWM +and Saxon. + +===== Fixes +* Minor memory improvement (release resource after use). + +===== Changes +* Minor restricting of internal functionality +* BouncyCastle.Crypto.dll has been updated from version 1.7 to version 1.8. +* dk.gov.oiosi.xml.dll has been removed, as it was not used. +* Add several new required libraries (IKWM and saxon) for the XSLT version 2.0 styling. + +===== Removals +* Functionality and classes that convert and KeyType to a specific Identifier implementation, +using the enum EndpointKeyTypeCode. +* Removed lesnikowskiMailProvider and some code around mail sending and receiving. +* Removed invalid and not used enum EndpointAddressTypeCode values. + +==== RASP version 2.0.2 +Main purposes of this patch release have been fixing smaller issues not related to functionality. + +===== New features +_None_ + +===== Fixes +* Spelling and divided text strings fixed. +* Minor exception error fixed in OcspConfig. +* Some invalid example files updated. + +===== Changes +* Unit tests depending on old UDDI Test setup, has been updated to depend on new NHR +Test setup. +* Schematron version 1.5 to project (2013.09.15) added to project +(http://digitaliser.dk/resource/2514884) +* Presentation style-sheets version 1.5 (2013.03.15) added to project +(http://digitaliser.dk/resource/2455502) +* dk.gov.oiosi.raspProfile.dll added to binary package. + +===== Removals +_None_ + +==== RASP version 2.0.1 +Main purposes of this patch release have been fixing a serious cache issue. + +The problem also persists in RASP version 1.3.0, but by intention, a patch is not released for RASP +1.3.0 because all NemHandel parties must upgrade to RASP 2.x.x latest June 2013. + +===== New features +_None_ + +===== Fixes +* Implementation of TimedCache had an error multiplying the cache time by 60. So a +CertificateCache with validityTimeInHours=24 cached the certificates for 60 days [1210]. + +===== Changes +_None_ + +===== Removals +_None_ + +==== RASP version 2.0.0 +Main purposes of this release have been: + +* Full support for Foces2 certificates. Foces1 is still supported in this version, BUT after +June 2013 DanID will no longer issue Foces1 certificates. Renewal of Foces1 certificates +will also not be possible after this date. + +The version number is changed to 2.0.0 to clearly indicate, that this version of RASP will not be +able to communicate with any RASP 1.x software where one of the parties communicating has +updated to Foces2. + +===== New features +_None_ +===== Fixes +* Error messages for invalid certificate (before activation or after expire) has been updated to +show certificate subject [1098]. + +===== Changes +* LDAP URL changed in RaspConfiguration.xml (/Host) to crtdir.certifikat.dk [1053]. +* RASP library identifies itself by platform and version number when making Uddi Inquiry +requests [1142]. +* Log4net library updated from version 1.2.10 to 1.2.11 [1168]. + +===== Removals +_None_ + +==== Cache Configuration (From version 1.3.0) +Possibility to configure caches (new functionality from RASP version 1.3.0) + +By default, after updating OIORASP library, cache configuration is changed. See "OIOSI RASP Library for Java Cache Overview 1.3.0.xlsx" for details. +The new cache configuration settings can be seen in the default RaspConfiguration file located in /dk.gov.oiosi/src/dk.gov.oiosi.resource/RaspConfiguration.xml. + +How to change cache configuration: + +1. The cache is configurated in the ConfigurationSection element (type =CacheConfig) as demostrated below: +[source, xml] + + + dk.gov.oiosi.common.cache.TimedCache + dk.gov.oiosi.RaspLibrary + + + validityTimeInHours + 1 + + + frequencyInMinutes + 10 + + + + ... + + + +2. Possible nested tags inside this section are: + - CertificateCache - The certificated downloaded from LDAP + - OcspLookupCache - A ocsp validation result (if the certificate has been revoked). + - UddiServiceCache - The registration downloaded from UDDI (NemHandelsRegisteret). + - UddiTModelCache - The special TModel key, that is used i UDDI. + - SchemaCache - The build xml schema + - SchematronCache - The build schematron + - CrlLookupCache - Cache crl lists (list over the certificates, that has been revoked). + - MessageIdUnfinishedSignaturesCache - Used in RASP communication + - SequenceIdUnfinishedSignaturesCache - Used in RASP communication + + +These tags should have sub-tags: + +ImplementationNamespaceClass - class name of the cache to use +ImplementationAssembly - not used in OIORASP java, optional +CacheConfigurationCollection - list of configuration parameters, which depend on cache implementation class. + + +Detailed description: + +In OIORASP 1.3.0 there are 4 configurable cache implementations: + +1) dk.gov.oiosi.common.cache.TimedCache - contains unlimited number of cached values, which are removed from cache with some expiration time. +Parameters: +validityTimeInHours or validityTimeInMinutes - integer with number of hours or minutes during which cache entry is considered as not expired +frequencyInHours or frequencyInMinutes - integer with number of hours or minutes to check expiration state of cached values. +Default values: +1 hour validity period and 10 minutes expiration check. +By default this cache is used for certificates, OCSP revocation and UDDI requests caching. + +2) dk.gov.oiosi.common.cache.LeastFrequentlyUsedQuantityCache - limited number of cached values, no expiration, least frequently used values are removed from cache if it is overloaded. +Parameters: +maxSize - integer with maximum number of cached entries. + +3) dk.gov.oiosi.common.cache.LeastRecentlyUsedQuantityCache - similar to LeastFrequentlyUsedQuantityCache, limited number of cached values, no expiration, but least recently used values are removed from cache if it is overloaded. +Parameters: +maxSize - integer with maximum number of cached entries. + +4) dk.gov.oiosi.common.cache.ZeroCache - cache nothing, no parameters. Primarily used in debugging and development + +==== RASP version 1.3.0 +Main purposes of this release have been: + +* Support for oces2 certificates. This release has prepared and tested code to handle these +new certificates. It will not be possible to start testing this in the general public before +DanID later in 2012 opens the last infrastructure components. DanID will sometime in +2013 stop issuing oces1 certificates and at that time, the RASP 1.3.0 (or newer) will be +mandatory in NemHandel. It will be announced when the date is set and notification will be +given at least 6 months in advance. +* Optimize performance. Caches have been made configurable, memory consumption have +been minimized, style-sheets are now pre-compiled, code is optimized – all to optimize the +throughput of communication. + +This release is fully compatible with RASP 1.2.1 and 1.2.3 when using oces1 certificates. +The 1.3.0 release is not a patch release, due to several breaking changes. + +In the provided Rasp Configuration file a number of default values for e.g. cache sizes have been +proposed. These are only default values, and can be changes by users as needed. +It is recommended to use the provided Rasp Configuration file as starting point. Please see the +details below for configuration. + +.Default values +[format="csv", options="header", separator=";"] +|=== +Cache name;OIORASP 1.2.3.HotFix1;OIORASP 1.3.0 +LdapCertificateLookup/CertificateCache;TimedCache - 14 days;TimedCache, 24 hours validity,each 1 hour check for expiration; +OcspLookup;TimedCache - 1 hour;TimedCache, 1 hour validity,each 10 mins check for expiration; +UddiLookupClient.getServiceCache; TimedCache - 24 hours; TimedCache, 10 hours validity, each 10 minutes check for expiration; +UddiLookupClient.getTModelCache;TimedCache - 24 hours;TimedCache, 24 hours validity, each 1 hour check for expiration; +SchematronStore;QuantityCache - 2 path entries;LFU cache (max size 20), no expiration; +CrlCache; Unlimited hashtable for each CRL url, checks for expiration each time it is accessed, updates in the same thread where it was found that it is expired;LFU cache (max size 10), if failed to update - reattempt in 5 minutes by special scheduled job, which is started after each successful cache update depending on revocation next update date from CRL server; +SchemaStoreCache;N/A - Schema object is built each time when required;Deleted from RaspConfiguration Test and Live + +|=== +===== New features +* Oces2 certificates are now supported. OIORASP 1.3.0 is prepared for DanID to start issuing +oces2 certificates. +* Schematron validation speed has been improved. +* New internal Rasp logger that can be used to get status information from inside the RASP. +Can be replaced by another logging implementation, by updating the configuration file. +* Configurable cache and improved implementation. +* Schema and schematron validation is moved before the sending process begins. +* Update OIOSIMessage, so the receiving document can be received as a test string, instead +of an XmlDocument (much faster processing, if the document is stored in e.g. database). +* Lots of logging has been added around the code base. + +===== Fixes +* Xpath for KreditNota made absolute [367] +* Profile validation error in test-code [579] +* Code reference to .NET 3.0 stuff fixed [598] +* Enable code to allow SE as sender type [613] +* Field ServiceType always empty in UddiLookupResponse [637] +* Error in EndpointAddress corrected [644] + +===== Changes +* http://discoverybackup.uddi.ehandel.gov.dk/registry/uddi/inquiry put in as default +backup [621] +* BouncyCastle and other libraries are updated to latest version. +* December 2012 schematron files (version 1.3) put in as default files [668] +* Schema is now placed correct, and loading of included schema, is also handled correct. +* Improved samples, that show how sending and receiving should be done. +* Use revocation CRL instead of OCSP. +* Rasp Request interface has changed. +* Implemented functionalities that can test certificates validity. +* Restructuring of source code for easy reading / debugging. +* Default location for schema and schematron files have changed, to get clearer file structure +(related to how e.g. Schematron updates are released [633] + +===== Removals +* Configuration of old VANS GW adapter removed from configuration files. + +=== How to release signed .NET RASP +Work has gone into make a signed release og RASP .NET. +However, we have the problem that the virtual build server can't reach the code Signing certificate on physical USB eToken. +Therefore, the only option so far, is release a signed version from a workstation. +These steps explain howto setup the workstation to release a signed version of RASP .NET. + +. Add (if not already exist) to windows Enviroment, the password to the certificate (yes, the key start with '-'): + Name -DigstSignToolPassword + Password not added to SVN. + + +. Add (if not already exist) to windows Enviroment, the key and Hash to the certificate (yes, the key start with '-'): + Name -DigstSPCThumbprint + VAlue 98642f19b787ec0386db8b52ce9e8ed4e49c + +. Install (if not already done) SAFENET DRIVERS: https://www.trustzone.com/standard-code-signing (step 1). + +. Find the svn revision number, and update the file './../NAnt.build.Distribute.Signed.bat', and set the correct build number (line 27). + +. Run the file './../NAnt.build.Distribute.Signed.bat'. + +=== How to upgrade to 2.2.0 +How to upgrade project from .NET 2.1.0 to version 2.2.0 + +This file should be seen as a guide for migrating own code to OIORASP library 2.2.0 + +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from https://digitaliser.dk/group/405467/resources + +2. Replace your old .dll files with the new .dll and .config files. + +That should be it..! + + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk + + +=== How to upgrade to 2.1.0 +How to upgrade project from .NET 2.0.X to version 2.1.0 + +This file should be seen as a guide for migrating own code to OIORASP library 2.1.0 +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from https://digitaliser.dk/group/405467/resources + +2. Replace your old .dll files with the new .dll and .config files. + Please note, there are several new files (IKVM and Saxon). + Remove the 'dk.gov.oiosi.xml.dll' file (it is not used). + +3. RaspConfiguration.xml must be updated! + See RaspConfiguration-update-2.1.0.pdf + +4. Code updates: + EndpointKeyTypeCode class has been removed. Now endpoint types is treated likes strings, so replace the class with 'string'. + enum EndpointAddressTypeCode has been cleaned for unusable values (https, email, ftp and other) + EndpointAddressSMTP.cs has been deleted. + + A lot of cleanup in the (default) endpoint service WCF configuration files. + See the test instances for how the configuration files could look, for more information. + + Important updates are: +4.1 The WCF binding for lookup in NemHandelRegisteret (NHR), must be present and is now named NHR_lookup (was just call basic before). + The client endpoint can be removed (was only used to point to the binding below). + + + + + + +4.2 + The Schematron Store Cache in RaspConfiguration.xml file must be updated from + dk.gov.oiosi.common.cache.QuantityCache`2[System.String,System.Xml.Xsl.XslCompiledTransform] + to + dk.gov.oiosi.common.cache.QuantityCache`2[System.String,dk.gov.oiosi.xml.schematron.CompiledXslt] + + + +That should be it..! + + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk + + +=== How to upgrade to 2.0.0 +How to upgrade project from Net 1.3.0 to version 2.0.0 + +This file should be seen as a guide for migrating own code to OIORASP library 2.0.0 +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from http://digitaliser.dk/group/405467/resources/type/150019 + +2. Replace your old .dll files with the new .dll and .config files + +3. Update your RaspConfiguration.xml file - remember to: + - adjust path to resources (schema + schematron files) + - change ConfigurationSection "LdapSettings": Host has changed to crtdir.certifikat.dk + - add Oces2 root certificate in ConfigurationSection "RootCertificateCollectionConfig" + +That should be it..! + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk + + +=== How to upgrade to 1.3.0 +How to upgrade project from Net 1.2.3 to version 1.3.0 + +This file should be seen as a guide for migrating own code to OIORASP library 1.3.0 +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from http://digitaliser.dk/group/405467/resources/type/150019 + +2. Replace your old .dll files with the new .dll and .config files - Note there exist more files in this release then in the old release + +3. Remove OcspClient2.dll and bccrypto-csharp-b02.dll from lib - Not used anymore. + +4. Update your RaspConfiguration.xml file - remember to adjust path to resources (schema + schematron files), as the path has benn changed. + +5. When a document is received though RASP OiosiMessage, a new method MessageAsString is provided to extract the document. Use this new method to take advantage of the improved processing speed, that has been implemented. + +6. Some classes/method is no longer static, and must in initialized. + +7. Log4Net har been implemented to be used by RASP .Net. Update the configuration fil log4net4Rasp.xml, to fit you needs. + +That should be it..! + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk + +=== Compatibility +This RASP 2.0.x release has been tested OK with RASP 1.2.1 and 1.2.3 for both Java and .NET +when running with Oces1 certificate at sender and receiver side. +Running with an Oces2 certificate, requires that both sender and receiver uses RASP 2.0.x. + +=== Known issues +Calling Abort() on the request may occasionally crash if one tries to update configuration or shut +down the application during sending. +This is due to a bug in the WCF WS-RM implementation that Microsoft has recognized. [as +reported: http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2189376&SiteID=1] + +Processing large sized documents will consume large size of RAM and CPU. The RASP library it +self should no longer be the obstacle for sending and handling large files – but the hardware must +be well equipped, as well as internet connection speed between sender and receiver + +=== Licenses +Some of the source code is licensed under the Mozilla Public License Version 1.1. The used license +is stated below. +Please check each source file for a license declaration as some source code is licensed on other +terms. + +[source] +/* + * The contents of this file are subject to the Mozilla Public + * License Version 1.1 (the "License"); you may not use this + * file except in compliance with the License. You may obtain + * a copy of the License at http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an + * "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express + * or implied. See the License for the specific language governing + * rights and limitations under the License. + * + * + * The Original Code is .NET RASP toolkit. + * + * The Initial Developer of the Original Code is Accenture and Avanade. + * Portions created by Accenture and Avanade are Copyright (C) 2009 + * Danish National IT and Telecom Agency (http://www.digst.dk). + * All Rights Reserved. + */ + +The NUnit distributed is not a product of DIGST. Following license is from the +originator. + + Portions Copyright © 2002-2007 Charlie Poole or Copyright © 2002-2004 James W. Newkirk, + Michael C. Two, Alexei A. Vorontsov or Copyright © 2000-2002 Philip A. Craig diff --git a/doc/OIORASP_Library_DotNet-Tutorials.adoc b/doc/OIORASP_Library_DotNet-Tutorials.adoc new file mode 100644 index 0000000000000000000000000000000000000000..476f6cd7275c8361685fa5907c509db1ddd3f8ce --- /dev/null +++ b/doc/OIORASP_Library_DotNet-Tutorials.adoc @@ -0,0 +1,943 @@ +:toc: +:toc: left +:toclevels: 6 +:sectnums: +:sectnumlevels: 5 +:xrefstyle: full + +== Tutorials + +=== OIOSI RASP Library for .NET 2.1.0 + +==== Introduction +The purpose of this document is to guide developers in creating an application using the +RASP library. The main components will be explained here, and example code showing how +to set them up will be given. +This document represents a high-level view of the main communication components. More +documentation is found + +* As comments in the code +* As stand-alone test applications +* As NUnit tests +* By seeing code used as part of other components + +Please visit http://www.digst.dk/It-loesninger/NemHandel for more information on the +OIOSI project. + +==== Overview of Lessons +The basics of the RASP Library will be explained through different lessons, each describing +one specific aspect of the API. +The lessons are + +* Configuring RASP and Windows Communication Foundation +* Sending documents +* Extended Requests (including UDDI, LDAP and OCSP/CRL lookups) +* Receiving documents +* The interceptors +* Hosting a HTTP service in IIS + +==== Prerequisites + +===== Resources +All common resources can be found in the resource project src/ dk.gov.oiosi.resource, and is +added (by link) to other project that need the resources. + +===== Sample documents +There are several sample documents used in the tests of the rasp library. They are located in +the src\dk.gov.oiosi.raspProfile\Resources\Documents directory. + +==== Sending Configuration - App.Config +Each test project has an App.Config application configuration file, and so should every +project that uses the RASP Library. +Most of the Windows Communication Foundation settings are done in App.Config, and this +section will briefly cover each important section in the configuration. +It is recommended that the main sections described here are copied from one of the test +projects, since the RASP Library is dependent on default settings (first and foremost the +OiosiHttpEndpoint, OiosiHttpEndpointBehavior, OiosiHttpEndpointBinding and +NHR_lookup). + +[#client_endpoint] +===== Client endpoint + + + +.App.Config sample 1 +[source, xml] + + ... + + + + + + ... + + +This sample shows a client endpoint, “OiosiHttpEndpoint”, using the attributes + +* name – Must be OiosiHttpEndpoint, as the name is hardcoded in RASP. +* address – Is retrieved from NemHandelsRegisteret, so can be left empty +* binding – Must be ‘customBinding’, as it described that we used a custom binding. +* bindingConfiguration – The name of the binding to use, described in the +customConfiguration see <>. +* contact – The contact describing the interface. +* behaviorConfiguration – The name of the behavior to use, described in <>. + +[#client_behavior] +===== Client behavior +The behavior configuration for sending. +.AppConfig sample 2 +[source, xml] + + ... + + + + + + + + + + + + + + + + + ... + + +The behavior name (‘OiosiHttpEndpointBehavior’) must match the defined name in <> + +[#client_binding] +===== Client binding +The binding configuration for sending. + +.App.Config sample 3 +[source, xml] + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +First there is a basicHttpBinding, that must be named NHR_lookup, that is used to perform +lookup in NemHandelsRegisteret. + +Second, must of theses configuration should not be changed. +Last, there must be a customBinding where the name (‘OiosiHttpEndpointBinding’) must +match the defined name in <>. + +==== Receiving Configuration - App.Config +Each test project has an App.Config application configuration file, and so should every +project that uses the RASP Library. + +Most of the Windows Communication Foundation settings are done in App.Config, and this +section will briefly cover each important section in the configuration. + +It is recommended that the main sections described here are copied from one of the test +projects, since the RASP Library is dependent on default settings (first and foremost the +OiosiHttpServer, OiosiHttpServerBehavior, OiosiHttpServerBinding). + +Note – This section describe how to setup a receiving endpoint on an IIS (IIS hosted). There +exist other ways of setting up receiving service (self-hosted), that will not be described here. + +[#server_services] +===== Server services + +.AppConfig sample 4 +[source, xml] + + ... + + + + + + +... + + +This sample shows a server endpoint using the attributes +Service + +* behaviorConfiguration – The name of the behavior to use, described in <>. +* name – Is the namespace and class that implement the communication interface. +Services +* name – Name of the endpoint – not importen. +* binding – Must be ‘customBinding’, as it described that we used a custom binding. +* bindingConfiguration – The name of the binding to use, described in the +customConfiguration <> +* contact – Represents service contract implemented by the endpoint, describing what +operations are supported and what SOAP actions they expect (and return). RASP +endpoints should implement dk.gov.oiosi.communication.client.IClientProxyContract +interface. + +[#server_behavior] +===== Server behavior +The behavior configuration for sending. +.App.Config sample 5 +[source, xml] + + ... + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +App.Config sample 6 shows an endpoint behavior. The behavior name +(OiosiHttpServerBehavior) must the name defined in <>. The behavior add the +signCustomHeaders and references a client certificate (and where to find it). As mentioned +before, this behaviour is referenced from a client endpoint. +The sender certificate and the server root certificate is checked using WCF extension, as this +give the possibility to create better error description back to the sender when something is +wrong. + +[NOTE] +==== +Oiosi RASP can use both Test and Live certificates, however most organisation +can’t use test certificates in testing. This is because of Nets port restrain in there +firewall protection the LDAR and OCSP/CRL servers. +==== + +For a hint on how to find the serial number and store location/name of your certificate check +the section named “Importing certificates” in the document “Rasp Library for .Net +Installation” + +The certificate configuration must match the location where the certificate is installed. In +this setup, the find value is the certificate serial number. + +[#server_binding] +===== Server binding +The server binding configuration. +.App.Config sample 6 + +[source, xml] + + ... + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +The name of the server binding (OiosiHttpServerBinding) must match the name of the +binding defined in <>. + +===== Configuring timeouts +There are several timout settings in the app.config. Some of the overall timeouts are +described here. + +* SendTimeout is the overall timeout for a communication, i.e. including all RM +messages back and forth between sender and receiver. +* Open- and CloseTimeout concerns the timeout of the creation of a connection from +the sender to the receiver, and nothing else. +* ReceiveTimeout is the timeout for a process waiting for a message within a session, +before deciding to time out the session. + +==== Lesson: dk.gov.oiosi.communication +The communication namespace holds the 3 main classes for communicating with web +services using the RASP stack. These are + +* Request: Allows the simplest form of request using the RASP stack using http +transport. Transport options (i.e. using RM, security, schema- and schematron +validation) can be configured in App.Config as described in the earlier section. + +===== Request +dk.gov.oiosi.communication.Request is the main class for making RASP service calls. + +For a concrete example of how to use the Request class, see the test project +dk.gov.oiosi.test.request. + +The sample below shows how to easily use Request to send an XML document to an http +endpoint through the use of the method GetResponse. The code should be fairly straight +forward. + +.Code sample 1 + +[source, csharp] +// Sends an xml document and receives a response +XmlDocument xdoc = new XmlDocument(); +Request raspReq = new Request(new Uri("http://myEndpoint")); +Response response; +try{ +raspReq.GetResponse(new OiosiMessage(xdoc), out response); +} +catch(RequestShutdownException e){ +// No need to do anything in particular if one +//isn’t concerned with a nice shutdown +// If the response variable is set, it’s good to use +// and your message has been acknowledged +} + +Calls can be made to http service, and Request automatically detects which type of service is +being called by looking at the scheme of the URI given. Http endpoint addresses MUST be +formatted http://address and is normally provided by NemHandelsRegisteret, and is +currently the only one supported. + +Code sample 1 give an URI as lone argument to the Rasp constructor, defining what +endpoint messages will be sent to. However, Request offers two more constructors, presented +in Code sample 2. + +.Code sample 2 +[source, csharp] +// Takes the name of an endpoint in App.Config +public Request(string endpointConfigurationName); +// Takes an endpoint, credentials and a sending policy +public Request(Uri endpointAddress, + Credentials credentials, + SendPolicy sendPolicy); + + The first constructor in Code sample 2 takes the name of an endpoint in the application +configuration file. See the file App.Config in the test dk.gov.oiosi.test.request for further +reference to how the configured endpoint (OiosiHttpEndpoint) describes the service which we +will call. + +An endpoint configuration is needed no matter what constructor is used. Unless the first +constructor in Code sample 2 is used, the endpoint configuration name must be +“OiosiHttpEndpoint”, and therefore should always be present in the App.Config file when +using the RASP Library. See the App.Config section for more information. + +The second constructor in Code sample 2 takes an endpoint URI, just like the ones used in +Code sample 1+2, but also takes programmatically set certificates (for sending and/or +receiving). These will override any certificates given in App.Config. + +===== Extended request +This section demonstrates the following in addition to making plain Request: + +* Gets identifiers from xml documents (e.g. EAN or OVT numbers) from documents +using configurable xpath expressions +* Performs a UDDI lookup using these parameters +* Retrieves an endpoint certificate from LDAP based on information returned from +UDDI +* Checks certificate revocation status against OCSP. + +[NOTE] +==== +Please note that the project has moved into the samples namespace and changed name +to “dk.gov.oiosi.samples.consoleClientExample”. +==== + +For a concrete example of how to use the Request class, see the test project +dk.gov.oiosi.test.requestTests. + +Code sample 3 shows how ExtendedRequest encapsulates all UDDI, OCSP, LDAP and +document searching to send an XML document to an http endpoint through the use of the +method GetResponse. + +.Code sample 3 +[source, csharp] +// 1. Get client certificate: +X509Certificate2 cert = CertificateLoader.GetCertificateFromStoreWithSSN( +"CVR:26769388-UID:1172691221366", +StoreLocation.CurrentUser, +StoreName.My +); +OcesX509Certificate clientCert = new OcesX509Certificate(cert); +// 2. Define send policy: +SendPolicy sendPolicy = new SendPolicy("*"); +// 3. Create request: +ExtendedRequest requestEx = new ExtendedRequest(clientCert, sendPolicy); +// 4. Create test message: +// 4.1 Load a test message from file: +XmlDocument xmlMsg = GetTestMessage(); +OiosiMessage msg = new OiosiMessage(xmlMsg); +// 5. Get response: +Response response; +try { +response = requestEx.GetResponse(msg); +} catch (Exception ex) { +txtResult.Text += "RequestExtended failed: " + ex.ToString(); +return; +} + +You can run the ExtendedRequest test sample by running the +dk.gov.oiosi.test.extendedRequest project application, see below. + +image::images\:rasp_extendedrequest.png[] + +The LDAP, OCSP and UDDI lookup components have both online and offline implementation +of their interfaces, see the RASP client tutorials on how to switch between these. + +You can choose which implementation to run by setting the corresponding factory +configuration in the configuration file, see below. + +You choose the implementation type by setting class + namespace + assembly name. The +factory then instantiates this type dynamically. You may supply your own implementation of +the OCSP, LDAP and UDDI interfaces. + +.Code sample 4 +[source, xml] + + +dk.gov.oiosi.security.revocation.ocsp.OcspLookup + + dk.gov.oiosi.library + + + +dk.gov.oiosi.security.Ldap.LdapCertificateLookup + + +dk.gov.oiosi.library + + + + +dk.gov.oiosi.uddi.UddiLookupClient + + +dk.gov.oiosi.library + + + +Code sample 5 uses OCSP for to check for revocation, while sample 6 use CRL lookup. + +.Code sample 5 +[source, xml] + + + dk.gov.oiosi.security.revocation.crl.CrlLookup + + dk.gov.oiosi.library + + + +dk.gov.oiosi.security.Ldap.LdapCertificateLookup + + +dk.gov.oiosi.library + + + + +dk.gov.oiosi.uddi.UddiLookupClient + + +dk.gov.oiosi.library + + + +The OCSP-server is by default read from the certificate. This can be overridden by having a +configuration in the OCSPconfig section: + +.Code sample 6 +[source, xml] + + 10000 + http://localhost/ + + +The configuration file also demonstrates how to configure RaspDocumentType configuration. +This configuration is associates the following information with the root element of an xml +document: + +* Validation schemas and schematron xslts +* Xpath expressions for finding e.g. an EAN number or other endpoint key types +* Associate a service and SOAP action with the document type + +Most of this configuration points forward to the RASP client which uses this library for +automatically sending business messages. + +You can see the RequestExtended class for an example on how to string the OCSP, LDAP, +UDDI, certificate checking and Request components together, either by using configuration +or programmatically. + + +====== The UDDI lookup +The UDDI lookup of the extended request requires the UDDI connection to be configured in +the app.config file, where it has its own HTTP binding. + +The parameters of the UDDI lookup may additionally use a process definition filter. By +setting the BusinessProcessDefinitionTModel and RoleIdentifier fields of the +LookupParameters object, the result from the query is filtered using these criteria. If null, +they are ignored. + +For more information on how to use the IUddiLookup interface have a look at <>. + +[#uddi_lookup] +==== Lesson: dk.gov.oiosi.uddi.IUddiLookupClient + +This section will have a short description on how to use the UddiLookupClient interface and +the LookupParameters class for different scenarios. + +There are several different kinds of lookup in that the interface IUddiLookupClient supports. +The interface only has one method and that is for lookup that take some parameters and +returns a list of responses. See + +[source, csharp] +/// +/// Translate interface for the ARS (Address Resolving Service) client. +/// +public interface IUddiLookupClient { +/// + /// Translate parametres + /// + /// + /// + List Lookup(LookupParameters parameters); +} + +The parameters that are used for the lookup can be different after what is searched for in the +UDDI. It seems like there are three major lookups that is needed by suppliers and these are; +first one is to find all that a specific identifier supports, second one is to find the endpoint to +a specific identifier and specific document type, finally the third one is to find the endpoint to +a specific identifier, specific document type and specific profile. + +First there is how to make a lookup that get all services for a specific identifier, then you +have to use the following constructor: + +[source, csharp] +public LookupParameters( + Identifier identifier, + List acceptedTransportProtocols) + +Where the identifier is given as the first parameter and the second parameter is what +transport protocols the client can support. + +Second lookup type takes three parameters; the first parameter is the identifier, the second +parameter is the service identifier in the UDDI and the third parameter is the accepted +transport protocols. The second parameter is a bit tricky to find but it is defined and found +on the UDDI. Se below for the method parameters: + +[source, csharp] +public LookupParameters( + Identifier identifier, + UddiId serviceId, + List acceptedTransportProtocols) + +Here the UDDIID on the portType tModel is used as the value in the parameter. The portType +can for an example correlate to a document type (invoice) in a process (billing). + +Third lookup type takes four parameters where the third parameter is different than the +other two lookup constructors. This parameter is a list of UddiId’s on the profiles that the +service must support. The method looks like the following: + +[source, csharp] +public LookupParameters( + Identifier identifier, + UddiId serviceId, + List profileIds, + List acceptedTransportProtocols) + +The lookup will accept a service as a result if just one of the profiles in the list is supported +by it. + +There are more constructors but they are not needed to send documents over the RASP +protocol, so they are not described here in this document. + +==== Lesson: dk.gov.oiosi.extension.wcf +The RASP library comes with several extensions to the .Net 3 Windows Communications +Foundation framework, that can all be found under the dk.gov.oiosi.extension.wcf and +dk.gov.oiosi.raspProfile.extension.wcf namespaces. + +These extensions come in the form of binding elements that are inserted into the +communication stack, where they intercept and handle the in- or outgoing message +according to their functionality. + +The extensions available in version 2.0 are + +.Interceptors +* The schema interceptor +* The schematron interceptor +* The signature validation proof generator +* The XSLT transformer +* The ubiquitous message property interceptor + +.Headers +* The party identifier headers + + +These stack elements are added in the App.Config file, but only after adding reference to +each of the elements configuration extension as seen in App.Config sample 7. + +Server and client side interceptors have been implemented in different manners because of +the different ways the two handles SOAP messages wherefore one has to make sure the +correct interceptor binding element has been selected. + +.App.Config sample 7 + +[source, xml] + + + + + + + + + + + + + + + + + + + + + + + + +===== Schema and schematron interceptors +The xml validators have the following settings + +* *ValidateRequest* - If true it will validate the xml on request. Default is true. +* *ValidateResponse* - If true it will validate the xml on response. Default is true. The +current configuration does not return any valid xml so this is disabled. +* *FaultOnRequestValidationException* - If true it will send soap fault to the client if +the validation fails. If false the message will continue up the stack and any validation +failure is added as a custom property to the message. Default is true. + + +===== Signature validation proof interceptor +The server side signature validation proof interceptor has the following options + +* *FaultOnRequestValidationException* - should a SOAP fault be sent on exceptions? Default is true. + +The client side signature validation proof interceptor has no options. + +Note that the ServerSignatureProof and ClientSignatureProof interceptors must be located +between the RM layer and the security layer as seen in *Error! Reference source not found*. + +===== XSLT Transformation interceptor +The XSLT transformation transforms the incoming XML, and has the following options + +* FaultOnTransformationException – should a SOAP fault be sent on exceptions? +* PropagateOriginalMessage – The original XML will be added as a message +property + +Note that the XSLT interceptor must be placed above the ReliableMessaging layer. + +===== Ubiquitous properties interceptor +The ubiquitous properties interceptor adds ubiquitous message properties to all messages +that pass it (as opposed to normal WCF Message properties), that will only be added to the +payload message. + +Ubiquitous properties are added to the OiosiMessage before sending, and need to be given a +unique string as an identifier, which later stack layers need to be familiar with if they would +like to read the property. + +[source, csharp] +OiosiMessage msg = new OiosiMessage(); +msg.UbiquitousProperties.Add("MyProperty", new object()); + +Note that the ubiquitous properties interceptor needs to be located under the +ReliableMessaging layer. + +===== SenderPartyIdentifier and ReceiverPartyIdentifier headers +In dk.gov.oiosi.raspProfile.communication.extension.wcf an additional interceptor can be +found, which is used to add the obligatory RASP SOAP headers and + . + +The value of the headers is configured by adding an PartyIdentifierSettings object as an +ubiquitous property to the message to be sent, as seen in the code below. The name of the +ubiquitous property must be the value found in the constant MessagePropertyKey on the +PartyIdentifierHeaderSettings class. + +[source, csharp] +OiosiMessage msg = new OiosiMessage(); +string key = PartyIdentifierHeaderSettings.MessagePropertyKey; +PartyIdentifierHeaderSettings partyIdentifierSetting = new PartyIdentifierHeaderSettings(senderID, receiverID); +msg.UbiquitousProperties[key] = partyIdentifierSetting; + +==== Lesson: Enabling tracing +Windows communication enables both Message level logging and internal system traces, +both which can be used with the RASP library. Furthermore the RASP library can add it’s +own internal system logs to the same (or a different) log file as WCF. Beware that when using +traces for the library on the Verbose tracing level the trace files will very quickly become very +large, so tracing at this level should only be enabled for advanced debugging. + +At the very top of all the App.Config files that are distributed with the RASP library source, +there should be a section called . This section has been disabled by +making it an xml comment, and to enable it again just remove the from before +and after it. + +When tracing has been enabled, two files (App_Traces.svclog and App_Messages.svclog) can +be viewed using the application SvcTraceViewer.exe that comes with the Windows SDK. +App_Traces will contain internal logs and App_Messages will contain all the SOAP messages +sent and/or received. + +===== Changing the trace settings +To change the tracing options it is recommended that the App.Config file is edited in the +Windows SDK application SvcConfigEditor.exe. + +image::images\rasp_clientappconfig.png[] + +In the configuration editor, under Diagnostics there will be two important sections; Listeners +and Sources. + +Under listeners you can add new trace listeners that will write to other files than the above +mentioned two. Under Sources you can add more sources (for example your own WCF +extensions) or change to what Listener the existing Sources will be written (if for example you +would like to separate RASP logs from WCF logs). It is also here where you can change on +what detail level to log. “Warning” is recommended to not clog the log files. + +==== Lesson: Configuration - RaspConfiguration.xml +This section briefly describes how to access the dynamic configuration file, which +supplements App.Config, RaspConfiguration.xml and change loaded library versions from +live to test versions. + +The RaspConfiguration.xml file is loaded using the class ConfigurationDocument. Default the +location and name of the configuration file is loaded from the programs main App.Config file, +or it should be set like this: + +[source, csharp] +ConfigurationDocument.ConfigFilePath = "RaspConfiguration.Live.xml"; + +[NOTE] +You must set the configuration before starting to use the RASP functionality. + +You can choose to use offline test stub versions of the LDAP, OCSP and UDDI libraries. This +is suitable for testing in offline environments or to fix some parameters of the test. + +You can set this in the factory configuration sections of the config. + +To do use test stubs do the following: + +* *LDAPLookupFactory* – change the implementation namespace class from +“dk.gov.oiosi.security.Ldap.LdapCertificateLookup” to +“dk.gov.oiosi.security.Ldap.LdapCertificateLookupTest”. +* *LdapLookupFactoryConfig* – change the implementation namespace class from +“dk.gov.oiosi.security.Ldap.LdapCertificateLookup” to +“dk.gov.oiosi.security.Ldap.LdapCertificateLookupTest”. +* *RevocationLookupFactoryConfig* – change the implementation namespace class +from “dk.gov.oiosi.security.revocation.ocsp.OcspLookup” to +“dk.gov.oiosi.security.revocation.ocsp.OcspLookupTest”. + +When you use the test stubs, you can configure the behaviour of each of them. You can do +this in the following sections: + +* LdapCertificateLookupTestConfig: Here you can configure a certificate that the LDAP +client should always return. +* OcspLookupTestConfig: Here you can set the response that the OCSP client always +will return in response to a question of certificate validity (true/false). +* UddiLookupClientTestConfig: Here you can statically configure an UDDI response, +regardless of lookup parameters. Parameters include the endpoint address and +certificate subject. + +==== Lesson: Setting up an IIS hosted RASP service +To host an HTTP endpoint it is recommended that this endpoint should be hosted by +Microsoft Internet Information Services (IIS). + +A test project in the sample code demonstrates how this could be done. In this project you +will find some code and a Web.Config file (which will act as a substitute for the App.Config +file while hosting our service in IIS). + +To get started, either publish the project directly into C:\Inetpub\wwwroot\ (assuming that +you have your Windows installation on the C drive), or publish another location and +manually install the application into the IIS. + +Then you should open the IIS manager (found under Start->Control Panel->Administrative +Tools, alternatively as a subsection of Start->Control Panel->Administrative Tools->Computer +Management). + +image::images\rasp_iis.png[] + +Under local computer\Web sites there should be a default web site with the folder +C:\Inetpub\wwwroot\ as it’s home directory. If there is no web sites please refer to Microsoft +help for setting a web site up. + +As a sub folder of this web site you should see the folder you just published called +RaspTestEndpoint. Right click on this folder and select Properties. + +image::images\rasp_interoptest2properties.png[] + +In the properties window, under the Directory tab push the Create button. + +image::images\rasp_interoptest2properties2.png[] + +In the properties window, under the ASP.NET tab, select Asp.Net version 2.0 + +image::images\rasp_interoptest2properties3.png[] + +Under the Directory Security tab, Authentication and access control, make sure anonymous +access is enabled. + +Now you should be able to see that your service is running by opening + +http://localhost/RaspTestEndpoint/OiosiOmniEndpoint.svc + +in a browser (such as Internet Explorer) . + + +===== Tips for solving common issues when hosting in IIS +If you have problems contacting the ISS service from outside, you may try and look into the +firewall settings. +If your endpoint is not working, you may try the following: + +* Go to the IIS application pool property window +* Select the “Identity” tab. +* Change the account to “local system” +If you do not want to elevate permission on the whole of application pool, you can try the +following. +* Creating a new application pool, where all web sites are running on the same .Net +version (v. 2.0) +* If that doesn’t work, perhaps the application pool doesn’t have rights to use the +certificate. Try: + +** Delete the certificate OiosiTestVOCES.pfx from the MMC window. +** Run the command line tool WinHttpCertCfg +(http://www.microsoft.com/downloads/details.aspx*familyid=c42e27 +ac-3409-40e9-8667-c748e422833f&displaylang=en) +** Re-install the certificate like: +>WinHttpCertCfg.exe –i NemHandelTest2.pfx –c LOCAL_MACHINE\MY –a +“NetworkService” –p Test1234 +(imports the pfx file to the personal store on local machine, for the +NetworkService account, using the password Test1234) +** Grant acces to the certificate for asp.net by running +>WinHttpCertCfg.exe –c LOCAL_MACHINE\MY –s “NemHandel Test 2” –g +–a “aspnet” +(where “NemHandel Test 2” is part of the subject string of the certificate you +just imported) +** In web.config, change the location of the certificate from “Root” to “My” store.+image::images\rasp_dotnetproperties.png[] +** In the IIS manager, right click on the application pool you’re running on (if it +is the default, you might want to create a new one) and make sure that under +the Identity tab the “Network service” security account is selected. diff --git a/doc/images/rasp_clientappconfig.png b/doc/images/rasp_clientappconfig.png new file mode 100644 index 0000000000000000000000000000000000000000..30f3f5619443bb43ddda23d320c91a74513a99e7 Binary files /dev/null and b/doc/images/rasp_clientappconfig.png differ diff --git a/doc/images/rasp_dotnetproperties.png b/doc/images/rasp_dotnetproperties.png new file mode 100644 index 0000000000000000000000000000000000000000..1f2ac72d762a9eeeaec319bf2cf7b80941e71f00 Binary files /dev/null and b/doc/images/rasp_dotnetproperties.png differ diff --git a/doc/images/rasp_extendedrequest.png b/doc/images/rasp_extendedrequest.png new file mode 100644 index 0000000000000000000000000000000000000000..f6fd55d1e3673f516cdc4e0495a4fc4d9fa9cf29 Binary files /dev/null and b/doc/images/rasp_extendedrequest.png differ diff --git a/doc/images/rasp_iis.png b/doc/images/rasp_iis.png new file mode 100644 index 0000000000000000000000000000000000000000..60871219b9a46350f07dff311326af6b7bd09ee7 Binary files /dev/null and b/doc/images/rasp_iis.png differ diff --git a/doc/images/rasp_interoptest2properties.png b/doc/images/rasp_interoptest2properties.png new file mode 100644 index 0000000000000000000000000000000000000000..14a3550591ac95f428ce668fd487660ff07a3dd1 Binary files /dev/null and b/doc/images/rasp_interoptest2properties.png differ diff --git a/doc/images/rasp_interoptest2properties2.png b/doc/images/rasp_interoptest2properties2.png new file mode 100644 index 0000000000000000000000000000000000000000..f762c87d89c43633324414ca6c1b5718aeb7e8c9 Binary files /dev/null and b/doc/images/rasp_interoptest2properties2.png differ diff --git a/doc/images/rasp_interoptest2properties3.png b/doc/images/rasp_interoptest2properties3.png new file mode 100644 index 0000000000000000000000000000000000000000..5d177a4ce43d5d309185a12c029f0e9bcd08a0be Binary files /dev/null and b/doc/images/rasp_interoptest2properties3.png differ diff --git a/doc/Howto Release Signed .Net RASP.txt b/doc/old/Howto Release Signed .Net RASP.txt similarity index 98% rename from doc/Howto Release Signed .Net RASP.txt rename to doc/old/Howto Release Signed .Net RASP.txt index 2282ac6090e50732127e98df415dc1493e7decc0..4320c4d6dd1b852715655a616af4e4d0b2424ea1 100644 --- a/doc/Howto Release Signed .Net RASP.txt +++ b/doc/old/Howto Release Signed .Net RASP.txt @@ -1,19 +1,19 @@ -Work has gone into make a signed release og RASP .Net. -However, we have the problem that the virtual build server can't reach the code Signing certificate on physical USB eToken. -Therefore, the only option so far, is release a signed version from a workstation. -These steps explain howto setup the workstation to release a signed version of RASP.Net. - -1) Add (if not already exist) to windows Enviroment, the password to the certificate (yes, the key start with '-'): - Name -DigstSignToolPassword - Password not added to SVN. - - -2) Add (if not already exist) to windows Enviroment, the key and Hash to the certificate (yes, the key start with '-'): - Name -DigstSPCThumbprint - VAlue 98642f19b787ec0386db8b52ce9e8ed4e49c - -3) Install (if not already done) SAFENET DRIVERS: https://www.trustzone.com/standard-code-signing (step 1). - -4) Find the svn revision number, and update the file './../NAnt.build.Distribute.Signed.bat', and set the correct build number (line 27). - +Work has gone into make a signed release og RASP .Net. +However, we have the problem that the virtual build server can't reach the code Signing certificate on physical USB eToken. +Therefore, the only option so far, is release a signed version from a workstation. +These steps explain howto setup the workstation to release a signed version of RASP.Net. + +1) Add (if not already exist) to windows Enviroment, the password to the certificate (yes, the key start with '-'): + Name -DigstSignToolPassword + Password not added to SVN. + + +2) Add (if not already exist) to windows Enviroment, the key and Hash to the certificate (yes, the key start with '-'): + Name -DigstSPCThumbprint + VAlue 98642f19b787ec0386db8b52ce9e8ed4e49c + +3) Install (if not already done) SAFENET DRIVERS: https://www.trustzone.com/standard-code-signing (step 1). + +4) Find the svn revision number, and update the file './../NAnt.build.Distribute.Signed.bat', and set the correct build number (line 27). + 5) Run the file './../NAnt.build.Distribute.Signed.bat'. \ No newline at end of file diff --git a/doc/old/OIOSI RASP Library for .Net Cache Overview.csv b/doc/old/OIOSI RASP Library for .Net Cache Overview.csv new file mode 100644 index 0000000000000000000000000000000000000000..0dfec2f4f7cdd9afc5bea5e13a199c04f947fa0a --- /dev/null +++ b/doc/old/OIOSI RASP Library for .Net Cache Overview.csv @@ -0,0 +1,15 @@ +;Cache configuration comparison;;; +;;;; +Cache name;OIORASP 1.2.3.HotFix1;OIORASP 1.3.0;OIORASP 2.0;Proposition to change +LdapCertificateLookup/CertificateCache;TimedCache - 14 days;TimedCache, 24 hours validity, each 1 hour check for expiration;TimedCache, 24 hours validity, each 1 hour check for expiration;Limit maximum number of entries by some big value to avoid OutOfMemory, use LFU cache together with timed cache +OcspLookup;TimedCache - 1 hour;TimedCache, 1 hour validity, each 10 mins check for expiration ;TimedCache, 1 hour validity, each 10 mins check for expiration ;-- // --- +UddiLookupClient.getServiceCache;TimedCache - 24 hours;TimedCache, 1 hours validity, each 10 minutes check for expiration;TimedCache, 1 hours validity, each 10 minutes check for expiration;Critical! If we do not decrease it, NO changes in public UDDI can be visible to clients during 24 hours. +UddiLookupClient.getTModelCache;TimedCache - 24 hours;TimedCache, 24 hours validity, each 1 hour check for expiration;TimedCache, 24 hours validity, each 1 hour check for expiration;Barelly used at all, at least none in TrueLink subsystem uses it. +SchematronStore;QuantityCache - 2 path entries;LFU cache (max size 20), no expiration;LFU cache (max size 20), no expiration; +CrlCache;Unlimited hashtable for each CRL url, checks for expiration each time it is accessed, updates in the same thread where it was found that it is expired;LFU cache (max size 10), if failed to update - reattempt in 5 minutes by special scheduled job, which is started after each successful cache update depending on revocation next update date from CRL server;LFU cache (max size 10), if failed to update - reattempt in 5 minutes by special scheduled job, which is started after each successful cache update depending on revocation next update date from CRL server; +SchemaStoreCache;absent, Schema object is built each time when required;LFU cache (max size 20), no expiration;LFU cache (max size 20), no expiration; +MessageIdUnfinishedSignaturesCache;10 minutes;TimedCache, 1 hour validity, each 10 mins check for expiration ;TimedCache, 1 hour validity, each 10 mins check for expiration ; +SequenceIdUnfinishedSignaturesCache;10 minutes;TimedCache, 1 hour validity, each 10 mins check for expiration ;TimedCache, 1 hour validity, each 10 mins check for expiration ; +;;;; +;;;; +LFU: Least Frequently Used;;;; diff --git a/doc/OIOSI RASP Library for .Net Cache Overview.xlsx b/doc/old/OIOSI RASP Library for .Net Cache Overview.xlsx similarity index 100% rename from doc/OIOSI RASP Library for .Net Cache Overview.xlsx rename to doc/old/OIOSI RASP Library for .Net Cache Overview.xlsx diff --git a/doc/OIOSI RASP Library for .Net Installation Guide.docx b/doc/old/OIOSI RASP Library for .Net Installation Guide.docx similarity index 100% rename from doc/OIOSI RASP Library for .Net Installation Guide.docx rename to doc/old/OIOSI RASP Library for .Net Installation Guide.docx diff --git a/doc/OIOSI RASP Library for .Net Installation Guide.pdf b/doc/old/OIOSI RASP Library for .Net Installation Guide.pdf similarity index 100% rename from doc/OIOSI RASP Library for .Net Installation Guide.pdf rename to doc/old/OIOSI RASP Library for .Net Installation Guide.pdf diff --git a/doc/OIOSI RASP Library for .Net Release Notes.docx b/doc/old/OIOSI RASP Library for .Net Release Notes.docx similarity index 100% rename from doc/OIOSI RASP Library for .Net Release Notes.docx rename to doc/old/OIOSI RASP Library for .Net Release Notes.docx diff --git a/doc/OIOSI RASP Library for .Net Release Notes.pdf b/doc/old/OIOSI RASP Library for .Net Release Notes.pdf similarity index 100% rename from doc/OIOSI RASP Library for .Net Release Notes.pdf rename to doc/old/OIOSI RASP Library for .Net Release Notes.pdf diff --git a/doc/OIOSI RASP Library for .Net Tutorials.docx b/doc/old/OIOSI RASP Library for .Net Tutorials.docx similarity index 100% rename from doc/OIOSI RASP Library for .Net Tutorials.docx rename to doc/old/OIOSI RASP Library for .Net Tutorials.docx diff --git a/doc/OIOSI RASP Library for .Net Tutorials.pdf b/doc/old/OIOSI RASP Library for .Net Tutorials.pdf similarity index 100% rename from doc/OIOSI RASP Library for .Net Tutorials.pdf rename to doc/old/OIOSI RASP Library for .Net Tutorials.pdf diff --git a/doc/release-notes-1.3.0_HowToUpgrade.txt b/doc/old/release-notes-1.3.0_HowToUpgrade.txt similarity index 97% rename from doc/release-notes-1.3.0_HowToUpgrade.txt rename to doc/old/release-notes-1.3.0_HowToUpgrade.txt index aab31351911cc6a60c6adcf8d0933637e93b647d..05f923f4f7bedfdcd415b79a6e9a7dbf05367fd6 100644 --- a/doc/release-notes-1.3.0_HowToUpgrade.txt +++ b/doc/old/release-notes-1.3.0_HowToUpgrade.txt @@ -1,26 +1,25 @@ -How to upgrade project from Net 1.2.3 to version 1.3.0 - -This file should be seen as a guide for migrating own code to OIORASP library 1.3.0 -The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! - -Steps ------ - -1. Download new release from http://digitaliser.dk/group/405467/resources/type/150019 - -2. Replace your old .dll files with the new .dll and .config files - Note there exist more files in this release then in the old release - -3. Remove OcspClient2.dll and bccrypto-csharp-b02.dll from lib - Not used anymore. - -4. Update your RaspConfiguration.xml file - remember to adjust path to resources (schema + schematron files), as the path has benn changed. - -5. When a document is received though RASP OiosiMessage, a new method MessageAsString is provided to extract the document. Use this new method to take advantage of the improved processing speed, that has been implemented. - -6. Some classes/method is no longer static, and must in initialized. - -7. Log4Net har been implemented to be used by RASP .Net. Update the configuration fil log4net4Rasp.xml, to fit you needs. - -That should be it..! - -It you meet problems, that should be included in this guide, please post your comments to the following email address: - support@nemhandel.dk +How to upgrade project from Net 1.2.3 to version 1.3.0 + +This file should be seen as a guide for migrating own code to OIORASP library 1.3.0 +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from http://digitaliser.dk/group/405467/resources/type/150019 + +2. Replace your old .dll files with the new .dll and .config files - Note there exist more files in this release then in the old release + +3. Remove OcspClient2.dll and bccrypto-csharp-b02.dll from lib - Not used anymore. + +4. Update your RaspConfiguration.xml file - remember to adjust path to resources (schema + schematron files), as the path has benn changed. + +5. When a document is received though RASP OiosiMessage, a new method MessageAsString is provided to extract the document. Use this new method to take advantage of the improved processing speed, that has been implemented. + +6. Some classes/method is no longer static, and must in initialized. + +7. Log4Net har been implemented to be used by RASP .Net. Update the configuration fil log4net4Rasp.xml, to fit you needs. + +That should be it..! + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk diff --git a/doc/release-notes-2.0.0_HowToUpgrade.txt b/doc/old/release-notes-2.0.0_HowToUpgrade.txt similarity index 97% rename from doc/release-notes-2.0.0_HowToUpgrade.txt rename to doc/old/release-notes-2.0.0_HowToUpgrade.txt index 60a5da6b841af4138edfdd07d614b425eac53ae0..21c222b94d5de4292253cb36408918340a544a67 100644 --- a/doc/release-notes-2.0.0_HowToUpgrade.txt +++ b/doc/old/release-notes-2.0.0_HowToUpgrade.txt @@ -1,21 +1,20 @@ -How to upgrade project from Net 1.3.0 to version 2.0.0 - -This file should be seen as a guide for migrating own code to OIORASP library 2.0.0 -The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! - -Steps ------ - -1. Download new release from http://digitaliser.dk/group/405467/resources/type/150019 - -2. Replace your old .dll files with the new .dll and .config files - -3. Update your RaspConfiguration.xml file - remember to: - - adjust path to resources (schema + schematron files) - - change ConfigurationSection "LdapSettings": Host has changed to crtdir.certifikat.dk - - add Oces2 root certificate in ConfigurationSection "RootCertificateCollectionConfig" - -That should be it..! - -It you meet problems, that should be included in this guide, please post your comments to the following email address: - support@nemhandel.dk +How to upgrade project from Net 1.3.0 to version 2.0.0 + +This file should be seen as a guide for migrating own code to OIORASP library 2.0.0 +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from http://digitaliser.dk/group/405467/resources/type/150019 + +2. Replace your old .dll files with the new .dll and .config files + +3. Update your RaspConfiguration.xml file - remember to: + - adjust path to resources (schema + schematron files) + - change ConfigurationSection "LdapSettings": Host has changed to crtdir.certifikat.dk + - add Oces2 root certificate in ConfigurationSection "RootCertificateCollectionConfig" + +That should be it..! + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk diff --git a/doc/release-notes-2.1.0_HowToUpgrade.txt b/doc/old/release-notes-2.1.0_HowToUpgrade.txt similarity index 96% rename from doc/release-notes-2.1.0_HowToUpgrade.txt rename to doc/old/release-notes-2.1.0_HowToUpgrade.txt index 0c0376dc12dea79167e70455b62c6542eb2468c8..da63cd1d55e5f6ab3b0ca08d4bfc30e5449e01e9 100644 --- a/doc/release-notes-2.1.0_HowToUpgrade.txt +++ b/doc/old/release-notes-2.1.0_HowToUpgrade.txt @@ -1,47 +1,46 @@ -How to upgrade project from .NET 2.0.X to version 2.1.0 - -This file should be seen as a guide for migrating own code to OIORASP library 2.1.0 -The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! - -Steps ------ - -1. Download new release from https://digitaliser.dk/group/405467/resources - -2. Replace your old .dll files with the new .dll and .config files. - Please note, there are several new files (IKVM and Saxon). - Remove the 'dk.gov.oiosi.xml.dll' file (it is not used). - -3. RaspConfiguration.xml must be updated! - See RaspConfiguration-update-2.1.0.pdf - -4. Code updates: - EndpointKeyTypeCode class has been removed. Now endpoint types is treated likes strings, so replace the class with 'string'. - enum EndpointAddressTypeCode has been cleaned for unusable values (https, email, ftp and other) - EndpointAddressSMTP.cs has been deleted. - - A lot of cleanup in the (default) endpoint service WCF configuration files. - See the test instances for how the configuration files could look, for more information. - - Important updates are: -4.1 The WCF binding for lookup in NemHandelRegisteret (NHR), must be present and is now named NHR_lookup (was just call basic before). - The client endpoint can be removed (was only used to point to the binding below). - - - - - - -4.2 - The Schematron Store Cache in RaspConfiguration.xml file must be updated from - dk.gov.oiosi.common.cache.QuantityCache`2[System.String,System.Xml.Xsl.XslCompiledTransform] - to - dk.gov.oiosi.common.cache.QuantityCache`2[System.String,dk.gov.oiosi.xml.schematron.CompiledXslt] - - - -That should be it..! - - -It you meet problems, that should be included in this guide, please post your comments to the following email address: - support@nemhandel.dk +How to upgrade project from .NET 2.0.X to version 2.1.0 + +This file should be seen as a guide for migrating own code to OIORASP library 2.1.0 +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from https://digitaliser.dk/group/405467/resources + +2. Replace your old .dll files with the new .dll and .config files. + Please note, there are several new files (IKVM and Saxon). + Remove the 'dk.gov.oiosi.xml.dll' file (it is not used). + +3. RaspConfiguration.xml must be updated! + See RaspConfiguration-update-2.1.0.pdf + +4. Code updates: + EndpointKeyTypeCode class has been removed. Now endpoint types is treated likes strings, so replace the class with 'string'. + enum EndpointAddressTypeCode has been cleaned for unusable values (https, email, ftp and other) + EndpointAddressSMTP.cs has been deleted. + + A lot of cleanup in the (default) endpoint service WCF configuration files. + See the test instances for how the configuration files could look, for more information. + + Important updates are: +4.1 The WCF binding for lookup in NemHandelRegisteret (NHR), must be present and is now named NHR_lookup (was just call basic before). + The client endpoint can be removed (was only used to point to the binding below). + + + + + + +4.2 + The Schematron Store Cache in RaspConfiguration.xml file must be updated from + dk.gov.oiosi.common.cache.QuantityCache`2[System.String,System.Xml.Xsl.XslCompiledTransform] + to + dk.gov.oiosi.common.cache.QuantityCache`2[System.String,dk.gov.oiosi.xml.schematron.CompiledXslt] + + + +That should be it..! + + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk diff --git a/doc/release-notes-2.2.0_HowToUpgrade.txt b/doc/old/release-notes-2.2.0_HowToUpgrade.txt similarity index 96% rename from doc/release-notes-2.2.0_HowToUpgrade.txt rename to doc/old/release-notes-2.2.0_HowToUpgrade.txt index 873752911d50cb2e0bcbf78ca9598e822726e239..804d136e8f4f2517ff26c10aaf9102f8f212551c 100644 --- a/doc/release-notes-2.2.0_HowToUpgrade.txt +++ b/doc/old/release-notes-2.2.0_HowToUpgrade.txt @@ -1,20 +1,19 @@ -How to upgrade project from .NET 2.1.0 to version 2.2.0 - -This file should be seen as a guide for migrating own code to OIORASP library 2.2.0 - -The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! - -Steps ------ - -1. Download new release from https://digitaliser.dk/group/405467/resources - -2. Replace your old .dll files with the new .dll and .config files. - - - -That should be it..! - - -It you meet problems, that should be included in this guide, please post your comments to the following email address: - support@nemhandel.dk +How to upgrade project from .NET 2.1.0 to version 2.2.0 + +This file should be seen as a guide for migrating own code to OIORASP library 2.2.0 + +The guide might not be 100% accurate, depending on your use of the library! Some steps might be unnecessary in your setup, and others might be as detailed as need in your setup! + +Steps + +1. Download new release from https://digitaliser.dk/group/405467/resources + +2. Replace your old .dll files with the new .dll and .config files. + + + +That should be it..! + + +It you meet problems, that should be included in this guide, please post your comments to the following email address: + support@nemhandel.dk diff --git a/doc/release-notes-CacheConfiguration.txt b/doc/old/release-notes-CacheConfiguration.txt similarity index 98% rename from doc/release-notes-CacheConfiguration.txt rename to doc/old/release-notes-CacheConfiguration.txt index 68463f268eba3d6906e020d927285481ea155abf..7ae8737a6514c02a404ee185f6bbcd48afafe28e 100644 --- a/doc/release-notes-CacheConfiguration.txt +++ b/doc/old/release-notes-CacheConfiguration.txt @@ -1,68 +1,68 @@ -Possibility to configure caches (new functionality from RASP version 1.3.0) - -By default, after updating OIORASP library, cache configuration is changed. See "OIOSI RASP Library for Java Cache Overview 1.3.0.xlsx" for details. -The new cache configuration settings can be seen in the default RaspConfiguration file located in /dk.gov.oiosi/src/dk.gov.oiosi.resource/RaspConfiguration.xml. - -How to change cache configuration: - -1. The cache is configurated in the ConfigurationSection element (type =CacheConfig) as demostrated below: - - - - dk.gov.oiosi.common.cache.TimedCache - dk.gov.oiosi.RaspLibrary - - - validityTimeInHours - 1 - - - frequencyInMinutes - 10 - - - - ... - - - -2. Possible nested tags inside this section are: - - CertificateCache - The certificated downloaded from LDAP - - OcspLookupCache - A ocsp validation result (if the certificate has been revoked). - - UddiServiceCache - The registration downloaded from UDDI (NemHandelsRegisteret). - - UddiTModelCache - The special TModel key, that is used i UDDI. - - SchemaCache - The build xml schema - - SchematronCache - The build schematron - - CrlLookupCache - Cache crl lists (list over the certificates, that has been revoked). - - MessageIdUnfinishedSignaturesCache - Used in RASP communication - - SequenceIdUnfinishedSignaturesCache - Used in RASP communication - - -These tags should have sub-tags: - -ImplementationNamespaceClass - class name of the cache to use -ImplementationAssembly - not used in OIORASP java, optional -CacheConfigurationCollection - list of configuration parameters, which depend on cache implementation class. - - -Detailed description: - -In OIORASP 1.3.0 there are 4 configurable cache implementations: - -1) dk.gov.oiosi.common.cache.TimedCache - contains unlimited number of cached values, which are removed from cache with some expiration time. -Parameters: -validityTimeInHours or validityTimeInMinutes - integer with number of hours or minutes during which cache entry is considered as not expired -frequencyInHours or frequencyInMinutes - integer with number of hours or minutes to check expiration state of cached values. -Default values: -1 hour validity period and 10 minutes expiration check. -By default this cache is used for certificates, OCSP revocation and UDDI requests caching. - -2) dk.gov.oiosi.common.cache.LeastFrequentlyUsedQuantityCache - limited number of cached values, no expiration, least frequently used values are removed from cache if it is overloaded. -Parameters: -maxSize - integer with maximum number of cached entries. - -3) dk.gov.oiosi.common.cache.LeastRecentlyUsedQuantityCache - similar to LeastFrequentlyUsedQuantityCache, limited number of cached values, no expiration, but least recently used values are removed from cache if it is overloaded. -Parameters: -maxSize - integer with maximum number of cached entries. - +Possibility to configure caches (new functionality from RASP version 1.3.0) + +By default, after updating OIORASP library, cache configuration is changed. See "OIOSI RASP Library for Java Cache Overview 1.3.0.xlsx" for details. +The new cache configuration settings can be seen in the default RaspConfiguration file located in /dk.gov.oiosi/src/dk.gov.oiosi.resource/RaspConfiguration.xml. + +How to change cache configuration: + +1. The cache is configurated in the ConfigurationSection element (type =CacheConfig) as demostrated below: + + + + dk.gov.oiosi.common.cache.TimedCache + dk.gov.oiosi.RaspLibrary + + + validityTimeInHours + 1 + + + frequencyInMinutes + 10 + + + + ... + + + +2. Possible nested tags inside this section are: + - CertificateCache - The certificated downloaded from LDAP + - OcspLookupCache - A ocsp validation result (if the certificate has been revoked). + - UddiServiceCache - The registration downloaded from UDDI (NemHandelsRegisteret). + - UddiTModelCache - The special TModel key, that is used i UDDI. + - SchemaCache - The build xml schema + - SchematronCache - The build schematron + - CrlLookupCache - Cache crl lists (list over the certificates, that has been revoked). + - MessageIdUnfinishedSignaturesCache - Used in RASP communication + - SequenceIdUnfinishedSignaturesCache - Used in RASP communication + + +These tags should have sub-tags: + +ImplementationNamespaceClass - class name of the cache to use +ImplementationAssembly - not used in OIORASP java, optional +CacheConfigurationCollection - list of configuration parameters, which depend on cache implementation class. + + +Detailed description: + +In OIORASP 1.3.0 there are 4 configurable cache implementations: + +1) dk.gov.oiosi.common.cache.TimedCache - contains unlimited number of cached values, which are removed from cache with some expiration time. +Parameters: +validityTimeInHours or validityTimeInMinutes - integer with number of hours or minutes during which cache entry is considered as not expired +frequencyInHours or frequencyInMinutes - integer with number of hours or minutes to check expiration state of cached values. +Default values: +1 hour validity period and 10 minutes expiration check. +By default this cache is used for certificates, OCSP revocation and UDDI requests caching. + +2) dk.gov.oiosi.common.cache.LeastFrequentlyUsedQuantityCache - limited number of cached values, no expiration, least frequently used values are removed from cache if it is overloaded. +Parameters: +maxSize - integer with maximum number of cached entries. + +3) dk.gov.oiosi.common.cache.LeastRecentlyUsedQuantityCache - similar to LeastFrequentlyUsedQuantityCache, limited number of cached values, no expiration, but least recently used values are removed from cache if it is overloaded. +Parameters: +maxSize - integer with maximum number of cached entries. + 4) dk.gov.oiosi.common.cache.ZeroCache - cache nothing, no parameters. Primarily used in debugging and development \ No newline at end of file diff --git a/test/dk.gov.oiosi.test.unit/security/revocation/OcspLookupTest.cs b/test/dk.gov.oiosi.test.unit/security/revocation/OcspLookupTest.cs index 52dc69a347f006f7ac1400ed4c281bad9716727a..3a751680e8aeaf9e2508035a3b5df94c16a25672 100644 --- a/test/dk.gov.oiosi.test.unit/security/revocation/OcspLookupTest.cs +++ b/test/dk.gov.oiosi.test.unit/security/revocation/OcspLookupTest.cs @@ -120,6 +120,7 @@ namespace dk.gov.oiosi.test.unit.security.revocation } [Test] + [Ignore("Ignore a test")] public void LookupTestRevokedFoces2() { try diff --git a/test/dk.gov.oiosi.test.unit/uddi/UddiLookupClientTest.cs b/test/dk.gov.oiosi.test.unit/uddi/UddiLookupClientTest.cs index d6fb1c839d5c64d5c0345eccddc43f8051bea7fa..956e8e5e728d2e8a24fb4fdee7fb4207fa2fb6e0 100644 --- a/test/dk.gov.oiosi.test.unit/uddi/UddiLookupClientTest.cs +++ b/test/dk.gov.oiosi.test.unit/uddi/UddiLookupClientTest.cs @@ -87,7 +87,9 @@ namespace dk.gov.oiosi.test.integration.uddi { Assert.Greater(lookupResponses.Count, 0); - var expectedCertificateSubjectString = "OID.2.5.4.5=CVR:34051178-FID:55310689 + CN=Digst Demo Endpoint Foces2 (funktionscertifikat), O=Digitaliseringsstyrelsen // CVR:34051178, C=DK"; + var expectedCertificateSubjectString = "OID.2.5.4.5=CVR:10150817-FID:73995930 + CN=demo.nemhandel.dk_modtager_2020 (funktionscertifikat), O=Erhvervsstyrelsen // CVR:10150817, C=DK"; + //var expectedCertificateSubjectString = "OID.2.5.4.5=CVR:34051178-FID:55310689 + CN=Digst Demo Endpoint Foces2 (funktionscertifikat), O=Digitaliseringsstyrelsen // CVR:34051178, C=DK"; + var actualCertificateSubjectString = lookupResponses[0].CertificateSubjectSerialNumber.SubjectString; Assert.AreEqual(expectedCertificateSubjectString, actualCertificateSubjectString); }