Merge branch 'release/20.0.0'

CHANGELOG.md

@@ -6,6 +6,20 @@ All notable changes to this project are documented in this file following the [K
 - Issues reported on [OW2's GitLab](https://gitlab.ow2.org/authzforce/core/issues) are referenced in the form of `[GL-N]`, where N is the issue number.
 
 
+## 20.0.0
+### Added
+- New feature: XPath variables in AttributeSelectors' and `xPathExpression` `AttributeValues`s' XPath expressions can now be defined by XACML VariableDefinitions (variable name used as XACML VariableId), which means XACML Variables can be used as XPath variables there.
+
+### Changed
+- Upgraded dependency `authzforce-ce-core-pdp-api` to 21.1.1
+
+ - Changed Datatype extension interface (`AttributeValueFactory`) in support of the new feature above:
+
+ - `getInstance(...)` `XPathCompiler` parameter replaced with `Optional<XPathCompilerProxy>`, where XPathCompilerProxy is a immutable version of `XPathCompiler` class with extra methods; the parameter is optional because XPath support may be disabled by PDP configuration or missing Policy(Set)Defaults/XPathVersion in XACML Policy(Set)
+ - `Datatype` interface: added `ItemType getXPathItemType()` method used to declare Variable types on Saxon XPath evaluator when compiling XPath expressions with variables
+ - `AttributeValue` must now implement `getXdmItem()` to return a XPath-compatible (XDM) value to be used as variables in XPath expressions, in order to support the new Feature mentioned above.
+
+
 ## 19.0.0
 ### Changed
 - Parent project `authzforce-ce-parent` upgraded to 8.2.0: upgraded following dependencies:
@@ -43,7 +57,7 @@ All notable changes to this project are documented in this file following the [K
 - [GH-62]: Refactored the provisioning of standard environment attributes `current-dateTime`, `current-date` and `current-time`:
  - Now implemented by a new built-in AttributeProvider (`StandardEnvironmentAttributeProvider` class) which can be customized (to override or not the request values) in the PDP configuration with an `attributeProvider` of type `StdEnvAttributeProviderDescriptor`.
 - `authzforce-ce-core-pdp-testutils` module: upgraded jongo dependency to 1.5.0, mongo-java-driver to 3.12.10
-- `authzforce-ce-core-pdp-cli` module: upgraded picocli to 4.6.2, testng to 7.5
+- `authzforce-ce-core-pdp-cli` module: upgraded picocli to 4.6.2, testng to 6.14.3
 - `authzforce-ce-parent` upgraded to 8.1.0
 
 ### Added

CONTRIBUTING.md

@@ -23,24 +23,25 @@ You may build the project and generate the JAR as follows from your local copy o
 Note that you must use Java 8 to run Maven when building the project.
 
 ### Dependency management
-1. No SNAPSHOT dependencies on "develop" and obviously "master" branches
+No SNAPSHOT dependencies allowed on "develop" and "master" branches.
 
 ### Releasing
 1. From the develop branch, prepare a release (example using an HTTP proxy):
 <pre><code>
  $ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=80 jgitflow:release-start
 </code></pre>
 1. Update the CHANGELOG according to keepachangelog.com.
-1. To perform the release (example using an HTTP proxy):
-<pre><code>
+2. To perform the release (example using an HTTP proxy):
+ <pre><code>
  $ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=80 jgitflow:release-finish
-</code></pre>
+ </code></pre>
  If, after deployment, the command does not succeed because of some issue with the branches. Fix the issue, then re-run the same command but with 'noDeploy' option set to true to avoid re-deployment:
-<pre><code>
+ <pre><code>
  $ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=80 -DnoDeploy=true jgitflow:release-finish
-</code></pre>
-1. Connect and log in to the OSS Nexus Repository Manager: https://oss.sonatype.org/
-1. Go to Staging Profiles and select the pending repository authzforce-*... you just uploaded with `jgitflow:release-finish`
-1. Click the Release button to release to Maven Central.
-
-More info on jgitflow: https://jgitflow.bitbucket.org/
+ </code></pre>
+ More info on jgitflow: https://jgitflow.bitbucket.org/
+3. Connect and log in to the OSS Nexus Repository Manager: https://oss.sonatype.org/
+4. Go to Staging Profiles and select the pending repository authzforce-*... you just uploaded with `jgitflow:release-finish`
+5. Click the Release button to release to Maven Central.
+6. Create a new Release on GitHub (copy-paste the description from previous releases and update the versions)
+7. If the [PDP configuration XSD](pdp-engine/src/main/resources/pdp.xsd) has changed with the new release, publish the new schema document in HTML form on https://authzforce.github.io (example for XSD version 8.1) by following the instructions here: https://github.com/authzforce/authzforce.github.io#generating-documentation-for-pdp-configuration-xsd .

MIGRATION.md

@@ -3,7 +3,7 @@
 ```shell
 $ PDP_XML_FILE="pdp.xml"
 $ mv $PDP_XML_FILE{,.old}
-$ java -jar ~/.m2/repository/net/sf/saxon/Saxon-HE/10.3/Saxon-HE-10.3.jar -xsl:migration/pdp-xsd-v7.xsl -s:$PDP_XML_FILE.old -o:$PDP_XML_FILE
+$ java -jar Saxon-HE-10.3.jar -xsl:migration/pdp-xsd-v7.xsl -s:$PDP_XML_FILE.old -o:$PDP_XML_FILE
 ```
 
 ## Migration from version 16.x to 17.x

README.md

@@ -28,7 +28,9 @@ AuthzForce Core may be used in the following ways:
  * [XACML v3.0 - Multiple Decision Profile Version 1.0 - Requests for a combined decision](https://docs.oasis-open.org/xacml/3.0/xacml-3.0-multiple-v1-spec-cd-03-en.html#_Toc260837890) (`urn:oasis:names:tc:xacml:3.0:profile:multiple:combined-decision`). 
 
  *For further details on what is actually supported regarding the XACML specifications, please refer to the conformance tests [README](pdp-testutils/src/test/resources/conformance/xacml-3.0-from-2.0-ct/README.md).*
-* [GeoXACML](https://portal.opengeospatial.org/files/?artifact_id=42734) (Open Geospatial Consortium) support: see [this AuthzForce extension from SecureDimensions](https://github.com/securedimensions/authzforce-geoxacml-basic).
+* Enhancements to the XACML standard:
+ * [GeoXACML](https://portal.opengeospatial.org/files/?artifact_id=42734) (Open Geospatial Consortium) support: see [this AuthzForce extension from SecureDimensions](https://github.com/securedimensions/authzforce-geoxacml-basic).
+ * Support `<VariableReference>` (indirectly) in `<Target>`/`<Match>` elements: this feature is a workaround for a limitation in XACML schema which does not allow Variables (`<VariableReference>`) in `Match` elements; i.e. the feature allows policy writers to use an equivalent of `<VariableReference>`s in `<Match>` elements (without changing the XACML schema) through a special kind of `<AttributeDesignator>` (specific `Category`, and `AttributeId` is used as `VariableId`). More details in the Usage section below. 
 * Interfaces: 
  * Java API: basically a library for instantiating and using a PDP engine from your Java (or any Java-compatible) code;
  * CLI (Command-Line Interface): basically an executable that you can run from the command-line to test the engine;
@@ -58,6 +60,17 @@ AuthzForce Core may be used in the following ways:
 
 
 ## Limitations
+
+### XACML 2.0 support and migrating to XACML 3.0
+As mentioned in the Features section, we do not support XACML 2.0 but only XACML 3.0, and we strongly recommend you migrate to XACML 3.0 as XACML 2.0 has become obsolete. In order to help you in the migration from XACML 2.0 to 3.0, we provide a way to migrate all your XACML 2.0 policies to XACML 3.0 automatically by applying the XSLT stylesheets in the [migration](migration folder). First download the stylesheets `xacml2To3Policy.xsl` and `xacml3-policy-c14n.xsl` from that folder, then apply them to your XACML 2.0 policy files using any XSLT engine supporting XSLT 2.0. For example, using [SAXON-HE 9.x or later](https://www.saxonica.com/download/java.xml), you may do it as follows:
+
+```shell
+$ XACML_20_POLICY_FILE="policy.xml"
+$ java -jar /path/to/Saxon-HE-10.3.jar -xsl:xacml2To3Policy.xsl -s:$XACML_20_POLICY_FILE -o:/tmp/${XACML_20_POLICY_FILE}.new
+$ java -jar /path/to/Saxon-HE-10.3.jar -xsl:xacml3-policy-c14n.xsl -s:/tmp/${XACML_20_POLICY_FILE}.new -o:$XACML_20_POLICY_FILE.new
+```
+
+### Optional XACML 3.0 features
 The following optional features from [XACML v3.0 Core standard](https://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html) are not supported:
 * Elements `AttributesReferences`, `MultiRequests` and `RequestReference`;
 * Functions `urn:oasis:names:tc:xacml:3.0:function:xpath-node-equal`, `urn:oasis:names:tc:xacml:3.0:function:xpath-node-match` and `urn:oasis:names:tc:xacml:3.0:function:access-permitted`;
@@ -224,6 +237,26 @@ Our PDP implementation uses SLF4J for logging, so you can use any SLF4J implemen
 For an example of using an AuthzForce PDP engine in a real-life use case, please refer to the JUnit test class [EmbeddedPdpBasedAuthzInterceptorTest](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptorTest.java) and the Apache CXF authorization interceptor [EmbeddedPdpBasedAuthzInterceptor](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptor.java). The test class runs a test similar to @coheigea's [XACML 3.0 Authorization Interceptor test](https://github.com/coheigea/testcases/blob/master/apache/cxf/cxf-sts-xacml/src/test/java/org/apache/coheigea/cxf/sts/xacml/authorization/xacml3/XACML3AuthorizationTest.java) but using AuthzForce as PDP engine instead of OpenAZ. In this test, a web service client requests an Apache-CXF-based web service with a SAML token as credentials (previously issued by a Security Token Service upon successful client authentication) that contains the user ID and roles. Each request is intercepted on the web service side by a [EmbeddedPdpBasedAuthzInterceptor](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptor.java) that plays the role of PEP (Policy Enforcement Point in XACML jargon), i.e. it extracts the various authorization attributes (user ID and roles, web service name, operation...) and requests a decision from a local PDP with these attributes, then enforces the PDP's decision, i.e. forwards the request to the web service implementation if the decision is Permit, else rejects it.
 For more information, see the Javadoc of [EmbeddedPdpBasedAuthzInterceptorTest](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptorTest.java).
 
+### Providing current-dateTime, current-date and current-time attributes
+By default, the PDP provides the standard environment attributes specified in XACML 3.0 Core specification §10.2.5 (current-time, current-date and current-dateTime) only if they are not provided in the request (from the PEP). This behavior is compliant with XACML 3.0 standard which says (§10.2.5): 
+>If
+ values for these
+ attributes are not present in
+ the decision request,
+ then their
+ values MUST be supplied
+ by the
+ context
+ handler.
+
+Note that it does **not** say *if and only if*, therefore it is also possible and XACML-compliant to make the PDP use its own current-* values (current-time, etc.) all the time, regardless of the request values. This option is referred to as the *override mode*, and it is particularly useful when you do not trust the PEPs (requesters) to provide their own current date/time. You can enable this override mode by configuring an `attributeProvider` of type `StdEnvAttributeProviderDescriptor` with `<override>true</override>` in the PDP configuration, as you can see in [this example (link)](pdp-testutils/src/test/resources/custom/StdEnvAttributeProvider.PDP_ONLY/pdp.xml). More information in the [PDP configuration schema](pdp-engine/src/main/resources/pdp.xsd) ( [HTML form - select the *tns:pdp* element](https://authzforce.github.io/pdp.xsd/8.1) ).
+
+### Using Variables (VariableReference) in Target/Match
+In XACML policies (Policy or PolicySet), as defined by the XACML schema, a `<Match>` may only include an `AttributeValue` and an `AttributeDesignator` or `AttributeSelector`; `VariableReference`s are not allowed, which makes it a limitation when you want to match a Variable (from a `VariableDefinition`) in a `Target`. AuthzForce provides a XACML-compliant workaround for this, which consists in enabling a `XacmlVariableBasedAttributeProvider` with a defined Category (see the [PDP configuration XSD](pdp-engine/src/main/resources/pdp.xsd) ( [HTML form - select the *tns:pdp* element](https://authzforce.github.io/pdp.xsd/8.1) for the default Category). As a result, any `<AttributeDesignator>` in that Category is handled like a `VariableReference`, with the `AttributeId` used as `VariableId`.
+
+The configuration of the `XacmlVariableBasedAttributeProvider` in the PDP is shown in [this example (link)](pdp-testutils/src/test/resources/custom/XacmlVarBasedAttributeProvider/pdp.xml) (`attributeProvider` of type `XacmlVarBasedAttributeProviderDescriptor`), applied to some Category `urn:ow2:authzforce:attribute-category:vars`. Then in the [this policy sample (link)](pdp-testutils/src/test/resources/custom/XacmlVarBasedAttributeProvider/policies/policy.xml), you can see an `<AttributeDesignator Category="urn:ow2:authzforce:attribute-category:vars" AttributeId="var1" .../>` which will be handled like `<VariableReference VariableId="var1"/>`.
+
+
 ## Extensions
 Experimental features (see [Features](#Features) section) are provided as extensions. If you want to use them, you need to use this Maven dependency (which depends on the `authzforce-ce-core-pdp-engine` already) instead:
 * groupId: `org.ow2.authzforce`;
@@ -237,6 +270,26 @@ If you are using the Java API with extensions configured by XML (Policy Provider
 1. *extensionXsdLocation*: location of the PDP extensions schema file: contains imports of namespaces corresponding to XML schemas of all XML-schema-defined PDP extensions to be used in the configuration file. Used for validation of PDP extensions configuration. The actual schema locations are resolved by the XML catalog parameter. You may use the [pdp-ext.xsd](pdp-testutils/src/test/resources/pdp-ext.xsd) in the sources as an example.
 
 
+## Integration with other Security Policy models, languages, formats, etc.
+### SPIF (Security Policy Information File)
+A SPIF (Security Policy Information File) defines a security labeling policy in a XML document (based on the [SPIF XML schema](spif-utils/spif.xsd)). More info on the [Open XML SPIF website](https://www.xmlspif.org/).
+
+[NATO ADatP-4774.1](https://nso.nato.int/nso/nsdd/main/standards/srd-details/222/EN) - related to [STANAG 4774](https://nso.nato.int/nso/nsdd/main/standards/stanag-details/8612/EN) - gives implementation guidance on how to generate a XACML policy from a SPIF, including an example of XSLT stylesheet. Considering the latest XACML 3.0 enhancements, AuthzForce optimizations and our aim to differentiate a READ from a WRITE action in accordance to the Bell-Lapadula model, we made a few improvements to the stylesheet and made it available in the [spif-utils](spif-utils) folder in two versions:
+
+- `spif2xacml-for-xpath-1.0.xsl`: SPIF-to-XACML policy transformation XSLT using XPath 1.0, more verbose and less efficient than the XPath 2.0 version below, available mostly for historical reasons (no longer maintained except bug fixing).
+- `spif2xacml-for-xpath-2.0.xsl`: SPIF-to-XACML policy transformation XSLT using XPath 2.0 features (not available in 1.0), with the option to enable AuthzForce optimizations (XSLT parameter `authzforce_optimized`) for further enhancements. Disable this option if you want strict XACML 3.0 compliance (less optimized).
+
+For example, you may generate the XACML policy from the sample [ACME SPIF](spif-utils/ACME-SPIF-example.xml) (from ADatP-4774.1) using XSLT engine of [SAXON-HE 9.x or later](https://www.saxonica.com/download/java.xml) on the command line as follows
+
+```shell
+$ java -jar Saxon-HE-10.3.jar -xsl:spif-utils/spif2xacml-for-xpath-2.0.xsl -s:spif-utils/ACME-SPIF-example.xml -o:/tmp/ACME-XACML-policy.xml
+```
+
+Same example but without AuthzForce optimizations:
+```shell
+$ java -jar Saxon-HE-10.3.jar authzforce_optimized=false -xsl:spif-utils/spif2xacml-for-xpath-2.0.xsl -s:spif-utils/ACME-SPIF-example.xml -o:/tmp/ACME-XACML-policy.xml
+```
+
 ## Support
 
 You should use [AuthzForce users' mailing list](https://mail.ow2.org/wws/info/authzforce-users) as first contact for any communication about AuthzForce: question, feature request, notification, potential issue (unconfirmed), etc.

migration/pdp-xsd-v7.xsl

@@ -1,10 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- Copyright (C) 2012-2016 Thales Services SAS. This file is part of AuthzForce CE. AuthzForce CE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public 
- License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. AuthzForce CE is distributed in the hope that it will be useful, but WITHOUT 
- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General 
- Public License along with AuthzForce CE. If not, see <https://www.gnu.org/licenses/>. -->
-<!-- PDP configuration upgrade XSL Sheet: parent folder name indicates the version from which you can upgrade to the current one. -->
-<!-- To be used with Saxon XSLT processor. -->
+<!-- Copyright (C) 2022 THALES. This file is part of AuthZForce CE. Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License. -->
+<!-- PDP configuration upgrade XSL Sheet, from schema v7 to current version. -->
+<!-- Tested with Saxon XSLT processor. -->
 <!-- Author: Cyril DANGERVILLE. -->
 <xsl:stylesheet version="2.0" xmlns:xsl="https://www.w3.org/1999/XSL/Transform"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"