idnits 2.17.1 draft-ietf-supa-generic-policy-info-model-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 21, 2016) is 2864 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group J. Strassner 2 Internet Draft Huawei Technologies 3 Intended status: Standard Track J. Halpern 4 Expires: December 21, 2016 Ericsson 5 June 21, 2016 7 Generic Policy Information Model for 8 Simplified Use of Policy Abstractions (SUPA) 9 draft-ietf-supa-generic-policy-info-model-00 11 Abstract 13 This document defines an information model for representing 14 policies using a common extensible framework that is independent 15 of language, protocol, repository. It is also independent of the 16 level of abstraction of the content and meaning of a policy. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current 26 Internet-Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six 29 months and may be updated, replaced, or obsoleted by other 30 documents at any time. It is inappropriate to use Internet-Drafts 31 as reference material or to cite them other than as "work in 32 progress." 34 This Internet-Draft will expire on December 21, 2016. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with 46 respect to this document. Code Components extracted from this 47 document must include Simplified BSD License text as described in 48 Section 4.e of the Trust Legal Provisions and are provided 49 without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Overview ....................................................... 9 54 1.1. Introduction .............................................. 9 55 1.2. Changes Since Version -03 ................................ 11 56 2. Conventions Used in This Document ............................. 11 57 3. Terminology ................................................... 12 58 3.1. Acronyms .................................................. 12 59 3.2. Definitions ............................................... 12 60 3.2.1. Core Terminology ..................................... 12 61 3.2.1.1. Information Model .............................. 12 62 3.2.1.2. Data Model ..................................... 13 63 3.2.1.3. Abstract Class ................................. 13 64 3.2.1.4. Concrete Class ................................. 13 65 3.2.1.5. Container ...................................... 13 66 3.2.1.6. PolicyContainer ................................ 13 67 3.2.2. Policy Terminology ................................... 14 68 3.2.2.1. SUPAPolicyObject ............................... 14 69 3.2.2.2. SUPAPolicy ..................................... 14 70 3.2.2.3. SUPAPolicyClause ............................... 14 71 3.2.2.4. SUPAECAPolicyRule .............................. 14 72 3.2.2.5. SUPAMetadata ................................... 15 73 3.2.2.6. SUPAPolicyTarget ............................... 15 74 3.2.2.7. SUPAPolicySource ............................... 15 75 3.2.3. Modeling Terminology ................................. 16 76 3.2.3.1. Inheritance .................................... 16 77 3.2.3.2. Relationship ................................... 16 78 3.2.3.3. Association .................................... 16 79 3.2.3.4. Aggregation .................................... 16 80 3.2.3.5. Composition .................................... 17 81 3.2.3.6. Association Class .............................. 17 82 3.2.3.7. Multiplicity ................................... 17 83 3.2.3.8. Navigability ................................... 17 84 3.3. Symbology ................................................ 18 85 3.3.1. Inheritance ......................................... 18 86 3.3.2. Association ......................................... 18 87 3.3.3. Aggregation ......................................... 19 88 3.3.4. Composition ......................................... 19 89 3.3.5. Association Class ................................... 19 90 3.3.6. Abstract vs. Concrete Classes ....................... 20 91 4. Policy Abstraction Architecture ............................... 21 92 4.1. Motivation ............................................... 22 93 4.2. SUPA Approach ............................................ 23 95 Table of Contents (continued) 97 4.3. SUPA Generic Policy Information Model Overview............ 23 98 4.3.1. SUPAPolicyObject .................................... 25 99 4.3.2. SUPAPolicyStructure ................................. 26 100 4.3.3. SUPAPolicyComponentStructure ........................ 26 101 4.3.4. SUPAPolicyClause .................................... 27 102 4.3.5. SUPAPolicyComponentDecorator ........................ 27 103 4.3.6. SUPAPolicyTarget .................................... 28 104 4.3.7. SUPAPolicySource .................................... 28 105 4.4. The Design of the GPIM ................................... 28 106 4.4.1. Structure of Policies ............................... 29 107 4.4.2. Representing an ECA Policy Rule ..................... 30 108 4.4.3. Creating SUPA Policy Clauses ........................ 33 109 4.4.4. Creating SUPAPolicyClauses .......................... 36 110 4.4.5. SUPAPolicySources ................................... 37 111 4.4.6. SUPAPolicyTargets ................................... 39 112 4.4.7. SUPAPolicyMetadata .................................. 39 113 4.4.7.1. Motivation ..................................... 39 114 4.4.7.2. Design Approach ................................ 40 115 4.4.7.2.1. Policies and Actors ....................... 42 116 4.4.7.2.2. Deployment vs. Execution of Policies ...... 43 117 4.4.7.2.3. Using SUPAMetadata for Policy Deployment 118 and Execution ............................. 43 119 4.4.7.3. Structure of SUPAPolicyMetadata ................ 44 120 4.5. Advanced Features ........................................ 47 121 4.5.1. Policy Grouping ..................................... 47 122 4.5.2. Policy Rule Nesting ................................. 47 123 5. GPIM Model ..................................................... 48 124 5.1. Overview .................................................. 48 125 5.2. The Abstract Class "SUPAPolicyObject" ..................... 49 126 5.2.1. SUPAPolicyObject Attributes .......................... 50 127 5.2.1.1. Object Identifiers ............................. 50 128 5.2.1.2. The Attribute "supaPolObjIDContent" ............. 51 129 5.2.1.3. The Attribute "supaPolObjIDEncoding" ............ 51 130 5.2.1.4. The Attribute "supaPolicyDescription" ........... 51 131 5.2.1.5. The Attribute "supaPolicyName" .................. 51 132 5.2.2. SUPAPolicy Relationships ............................ 52 133 5.2.2.1. The Relationship "SUPAHasPolicyMetadata" ....... 52 134 5.2.2.2. The Association Class 135 "SUPAHasPolicyMetadataDetail" .................. 52 136 5.3. The Abstract Class "SUPAPolicyStructure" ................. 52 137 5.3.1. SUPAPolicyStructure Attributes ...................... 53 138 5.3.1.1. The Attribute "supaPolAdminStatus" ............. 53 139 5.3.1.2. The Attribute "supaPolContinuumLevel" .......... 53 140 5.3.1.3. The Attribute "supaPolDeployStatus" ............ 54 141 5.3.1.4. The Attribute "supaPolExecStatus" .............. 54 142 5.3.1.5. The Attribute "supaPolExecFailStrategy" ........ 54 144 Table of Contents (continued) 146 5.3.2. SUPAPolicyStructure Relationships ................... 55 147 5.3.2.1. The Aggregation "SUPAHasPolicySource" .......... 55 148 5.3.2.2. The Association Class 149 "SUPAHasPolicySourceDetail" .................... 55 150 5.3.2.2.1. The Attribute "supaPolSrcIsAuthenticated" . 55 151 5.3.2.2.2. The Attribute "supaPolSrcIsTrusted" ....... 56 152 5.3.2.3. The Aggregation "SUPAHasPolicyTarget" .......... 56 153 5.3.2.4. The Association Class 154 "SUPAHasPolicyTargetDetail" ................... 56 155 5.3.2.4.1. The Attribute "supaPolTgtIsAuthenticated" . 56 156 5.3.2.4.2. The Attribute "supaPolTgtIsEnabled" ....... 56 157 5.3.2.5. The Association "SUPAHasPolExecFailTakeAction" . 57 158 5.3.2.6. The Association Class 159 "SUPAHasPolExecFailTakeActionDetail" ........... 57 160 5.3.2.6.1. The Attribute 161 "supaPolExecFailTakeActionEncoding" ....... 57 162 5.3.2.6.2. The Attribute 163 "supaPolExecFailTakeActionName[1..n]" ..... 58 164 5.3.2.7. The Aggregation "SUPAHasPolicyClause" .......... 58 165 5.3.2.8. The Association Class 166 "SUPAHasPolicyClauseDetail" .................... 58 167 5.4. The Abstract Class "SUPAPolicyComponentStructure" ........ 59 168 5.4.1. SUPAPolicyComponentStructure Attributes ............. 59 169 5.4.2. SUPAPolicyComponentStructure Relationships .......... 59 170 5.5. The Abstract Class "SUPAPolicyClause" .................... 59 171 5.5.1. SUPAPolicyClause Attributes ......................... 60 172 5.5.1.1. The Attribute "supaPolClauseExecStatus" ........ 60 173 5.5.2. SUPAPolicyClause Relationships ...................... 61 174 5.6. The Concrete Class "SUPAEncodedClause" ................... 61 175 5.6.1. SUPAEncodedClause Attributes ........................ 61 176 5.6.1.1. The Attribute "supaEncodedClauseContent" ....... 61 177 5.6.1.2. The Attribute "supaEncodedClauseEncoding" ...... 61 178 5.6.1.3. The Attribute "supaEncodedClauseResponse" ...... 62 179 5.6.2. SUPAEncodedClause Relationships ..................... 62 180 5.7. The Abstract Class "SUPAPolicyComponentDecorator" ........ 62 181 5.7.1. The Decorator Pattern ............................... 63 182 5.7.2. SUPAPolicyComponentDecorator Attributes ............. 64 183 5.7.2.1. The Attribute "supaPolCompConstraintEncoding" .. 64 184 5.7.2.2. The Attribute "supaAPolCompConstraint[0..n]" ... 64 185 5.7.3. SUPAPolicyComponentDecorator Relationships .......... 65 186 5.7.3.1. The Aggregation 187 "SUPAHasDecoratedPolicyComponent" .............. 65 188 5.7.3.2. The Association Class 189 "SUPAHasDecoratedPolicyComponentDetail" ........ 65 190 5.7.3.2.1. The Attribute 191 "supaDecoratedConstraintEncoding" ......... 65 192 5.7.3.2.2. The Attribute 193 "supaDecoratedConstraint[0..n]" ........... 66 194 5.7.4. Illustration of Constraints in the Decorator Pattern 66 196 Table of Contents (continued) 198 5.8. The Abstract Class "SUPAPolicyTerm" ...................... 67 199 5.8.1. SUPAPolicyTerm Attributes ........................... 68 200 5.8.1.1. The Attribute "supaPolTermIsNegated" ........... 68 201 5.8.2. SUPAPolicyTerm Relationships ........................ 68 202 5.9. The Concrete Class "SUPAPolicyVariable" .................. 68 203 5.9.1. Problems with the RFC3460 Version of PolicyVariable . 69 204 5.9.2. SUPAPolicyVariable Attributes ....................... 69 205 5.9.2.1. The Attribute "supaPolVarName" ................. 69 206 5.9.3. SUPAPolicyVariable Relationships .................... 69 207 5.10. The Concrete Class "SUPAPolicyOperator" ................. 69 208 5.10.1. Problems with the RFC3460 Version .................. 70 209 5.10.2. SUPAPolicyOperator Attributes ...................... 70 210 5.10.2.1. The Attribute "supaPolOpType" ................. 70 211 5.10.3. SUPAPolicyOperator Relationships ................... 70 212 5.11. The Concrete Class "SUPAPolicyValue" .................... 71 213 5.11.1. Problems with the RFC3460 Version of PolicyValue ... 71 214 5.11.2. SUPAPolicyValue Attributes ......................... 71 215 5.11.2.1. The Attribute "supaPolValContent[0..n]" ....... 71 216 5.11.2.2. The Attribute "supaPolValEncoding" ............ 72 217 5.11.3. SUPAPolicyValue Relationships ...................... 72 218 5.12. The Concrete Class "SUPAGenericDecoratedComponent" ...... 72 219 5.12.1. SUPAGenericDecoratedComponent Attributes ........... 73 220 5.12.1.1. The Attribute 221 "supaVendorDecoratedCompContent[0..n]" ......... 73 222 5.12.1.2. The Attribute "supaVendorDecoratedCompEncoding" 73 223 5.12.2. SUPAGenericDecoratedComponent Relationships ........ 73 224 5.13. The Concrete Class "SUPAPolicyCollection" ............... 74 225 5.13.1. Motivation ......................................... 74 226 5.13.2. Solution ........................................... 74 227 5.13.3. SUPAPolicyCollection Attributes .................... 75 228 5.13.3.1. The Attribute "supaPolCollectionContent[0..n]" 75 229 5.13.3.2. The Attribute "supaPolCollectionEncoding" ..... 75 230 5.13.3.3. The Attribute "supaPolCollectionFunction" ..... 75 231 5.13.3.4. The Attribute "supaPolCollectionIsOrdered" .... 75 232 5.13.3.5. The Attribute "supaPolCollectionType" ......... 76 233 5.13.4. SUPAPolicyCollection Relationships ................. 77 234 5.14. The Concrete Class "SUPAPolicySource" ..................... 77 235 5.14.1. SUPAPolicySource Attributes ........................ 77 236 5.14.2. SUPAPolicySource Relationships ..................... 77 237 5.15. The Concrete Class "SUPAPolicyTarget" ................... 77 238 5.15.1. SUPAPolicyTarget Attributes ........................ 78 239 5.15.2. SUPAPolicyTarget Relationships ..................... 78 241 Table of Contents (continued) 243 5.16. The Abstract Class "SUPAPolicyMetadata" ................. 78 244 5.16.1. SUPAPolicyMetadata Attributes ...................... 79 245 5.16.1.1. The Attribute "supaPolMetadataDescription" .... 79 246 5.16.1.2. The Attribute "supaPolMetadataIDContent" ...... 79 247 5.16.1.3. The Attribute "supaPolMetadataIDEncoding" ..... 79 248 5.16.1.4. The Attribute "supaPolMetadataName" ........... 80 249 5.16.2. SUPAPolicyMetadata Relationships ................... 80 250 5.16.2.1. The Aggregation "SUPAHasPolicyMetadata" ....... 80 251 5.16.2.2. The Abstract Class 252 "SUPAHasPolicyMetadataDetail" ................. 80 253 5.16.2.2.1. The Attribute 254 "supaPolMetadataIsApplicable" ............ 80 255 5.16.2.2.2. The Attribute 256 "supaPolMetadataConstraintEncoding" ...... 81 257 5.16.2.2.3. The Attribute 258 "supaPolMetadataConstraint[0..n]" ........ 81 259 5.17. The Concrete Class "SUPAPolicyConcreteMetadata" ......... 81 260 5.17.1. SUPAPolicyConcreteMetadata Attributes .............. 82 261 5.17.2. SUPAPolicyConcreteMetadata Relationships ........... 82 262 5.18. The Abstract Class "SUPAPolicyMetadataDecorator" ........ 82 263 5.18.1. SUPAPolicyMetadataDecorator Attributes ............. 82 264 5.18.1.1. The Attribute "supaPolMDValidPeriodEnd" ....... 82 265 5.18.1.2. The Attribute "supaPolMDValidPeriodStart" ..... 82 266 5.18.2. SUPAPolicyMetadataDecorator Relationships .......... 82 267 5.18.2.1. The Aggregation "HasSUPAMetadataDecorator" .... 83 268 5.18.2.2. The Association Class 269 "HasSUPAMetadataDecoratorDetail" .............. 83 270 5.19. The Concrete Class "SUPAPolicyAccessMetadataDef" ........ 83 271 5.19.1. SUPAPolicyAccessMetadataDef Attributes ............. 84 272 5.19.1.1. The Attribute "supaAccessPrivilegeDef" ........ 84 273 5.19.1.2. The Attribute "supaAccessPrivilegeModelName" .. 84 274 5.19.1.3. The Attribute "supaAccessPrivilegeModelRef" ... 85 275 5.20. The Concrete Class "SUPAPolicyVersionMetadataDef" ....... 85 276 5.20.1. SUPAPolicyVersionMetadataDef Attributes ............ 85 277 5.20.1.1. The Attribute "supaVersionMajor" .............. 85 278 5.20.1.2. The Attribute "supaVersionMinor" .............. 86 279 5.20.1.3. The Attribute "supaVersionRelType" ............ 86 280 5.20.1.4. The Attribute "supaVersionTypeNum" ............ 86 281 6. SUPA ECAPolicyRule Information Model .......................... 87 282 6.1. Overview ................................................. 87 283 6.2. Constructing a SUPAECAPolicyRule ......................... 88 284 6.3. Working With SUPAECAPolicyRules .......................... 89 285 6.4. The Abstract Class "SUPAECAPolicyRule" ................... 91 286 6.4.1. SUPAECAPolicyRule Attributes ........................ 92 287 6.4.1.1. The Attribute "supaECAPolicyRulePriority" ...... 93 288 6.4.1.2. The Attribute "supaECAPolicyRuleStatus" ........ 93 289 6.4.2. SUPAECAPolicyRule Relationships ..................... 93 291 Table of Contents (continued) 293 6.5. The Concrete Class "SUPAECAPolicyRuleAtomic" ............. 93 294 6.5.1. SUPAECAPolicyRuleAtomic Attributes .................. 93 295 6.5.2. SUPAECAPolicyRuleAtomic Relationships ............... 93 296 6.6. The Concrete Class "SUPAECAPolicyRuleComposite" .......... 94 297 6.6.1. SUPAECAPolicyRuleComposite Attributes ............... 94 298 6.6.1.1. The Attribute "supaECAEvalStrategy" ............ 94 299 6.6.2. SUPAECAPolicyRuleComposite Relationships ............ 95 300 6.6.2.1. The Aggregation "SUPAHasECAPolicyRule" ......... 95 301 6.6.3. The Association Class "SUPAHasECAPolicyRuleDetail" .. 95 302 6.6.3.1. The Attribute "supaECAPolicyIsDefault" ......... 95 303 6.7. The Abstract Class "SUPABooleanClause" ................... 96 304 6.7.1. SUPABooleanClause Attributes ........................ 96 305 6.7.1.1. The Attribute "supaBoolClauseIsNegated" ........ 97 306 6.7.2. SUPABooleanClause Relationships ..................... 97 307 6.8. The Concrete Class "SUPABooleanClauseAtomic" ............. 97 308 6.8.1. SUPABooleanClauseAtomic Attributes .................. 97 309 6.8.2. SUPABooleanClauseAtomic Relationships ............... 97 310 6.9. The Concrete Class "SUPABooleanClauseComposite" .......... 97 311 6.9.1. SUPABooleanClauseComposite Attributes ................ 98 312 6.9.1.1. The Attribute "supaBoolClauseBindValue" ........ 98 313 6.9.1.2. The Attribute "supaBoolClauseIsCNF" ............ 98 314 6.9.2. SUPABooleanClauseComposite Relationships ............ 98 315 6.9.2.1. The Aggregation "SUPAHasBooleanClause" ......... 98 316 6.9.3. The Concrete Class "SUPAHasBooleanClauseDetail" ..... 99 317 6.9.3.1. SUPAHasBooleanClauseDetail Attributes .......... 99 318 6.10. The Abstract Class "SUPAECAComponent" ................... 99 319 6.10.1. SUPAECAComponent Attributes ........................ 99 320 6.10.1.1. The Attribute supaECACompIsTerm .............. 100 321 6.10.2. SUPAECAComponent Relationships .................... 100 322 6.11. The Concrete Class "SUPAPolicyEvent" ................... 100 323 6.11.1. SUPAPolicyEvent Attributes ........................ 100 324 6.11.1.1. The Attribute "supaPolicyEventIsPreProcessed" 100 325 6.11.1.2. The Attribute "supaPolicyEventIsSynthetic" ... 100 326 6.11.1.3. The Attribute "supaPolicyEventTopic[0..n]" ... 101 327 6.11.1.4. The Attribute "supaPolicyEventEncoding[1..n]" 101 328 6.11.1.5. The Attribute "supaPolicyEventData[1..n]" .... 101 329 6.11.2. SUPAPolicyEvent Relationships ..................... 101 330 6.12. The Concrete Class "SUPAPolicyCondition" ............... 102 331 6.12.1. SUPAPolicyCondition Attributes .................... 102 332 6.12.1.1. The Attribute "supaPolicyConditionData[1..n]" 102 333 6.12.1.2. The Attribute "supaPolicyConditionEncoding" .. 102 334 6.12.2. SUPAPolicyEvent Relationships ..................... 102 335 6.13. The Concrete Class "SUPAPolicyAction" .................. 103 336 6.13.1. SUPAPolicyAction Attributes ....................... 103 337 6.13.1.1. The Attribute "supaPolicyActionData[1..n]" ... 103 338 6.13.1.2. The Attribute "supaPolicyActionEncoding" ..... 104 339 6.13.2. SUPAPolicyAction Relationships .................... 104 341 7. Examples ...................................................... 104 342 8. Security Considerations ...................................... 104 343 9. IANA Considerations ........................................... 105 344 10. Contributors ................................................ 105 345 11. Acknowledgments ............................................. 105 346 12. References .................................................. 105 347 12.1. Normative References .................................... 105 348 12.2. Informative References ................................. 105 349 Authors' Addresses ............................................... 107 350 Appendix A. Brief Analyses of Previous Policy Work .............. 107 351 Appendix B. Mathematical Logic Terminology and Symbology ........ 114 352 Appendix C. SUPA Logic Statement Information Model .............. 114 353 1. Overview 355 This document defines an information model for representing 356 policies using a common extensible framework that is independent 357 of language, protocol, repository, and the level of abstraction of 358 the content and meaning of a policy. This enables a common set of 359 concepts defined in this information model to be mapped into 360 different representations of policy (e.g., procedural, imperative, 361 and declarative). It also enables different data models that use 362 different languages, protocols, and repositories to optimize 363 their usage. The definition of common policy concepts also 364 provides better interoperability by ensuring that each data 365 model can share a set of common concepts, independent of its 366 level of detail or the language, protocol, and/or repository 367 that it is using. It is also independent of the target data 368 model that will be generated. 370 This version of the information model focuses on defining one 371 type of policy rule: the event-condition-action (ECA) policy rule. 372 Accordingly, this document defines two sets of model elements: 374 1. A framework for defining the concept of policy, 375 independent of how policy is represented or used; this is 376 called the SUPA Generic Policy Information Model (GPIM) 377 2. A framework for defining a policy model that uses the 378 event-condition-action paradigm; this is called the SUPA 379 Eca Policy Rule Information Model (EPRIM), and extends 380 concepts from the GPIM. 382 The combination of the GPIM and the EPRIM provides an extensible 383 framework for defining policy that uses an event-condition-action 384 representation that is independent of data repository, data 385 definition language, query language, implementation language, and 386 protocol. 388 The Appendices describe how the structure of the GPIM defines a 389 set of generic concepts that enables other types of policies, such 390 as declarative (or "intent-based") policies, to be added later. 392 1.1. Introduction 394 Simplified Use of Policy Abstractions (SUPA) defines an interface 395 to a network management function that takes high-level, possibly 396 network-wide policies as input and creates element configuration 397 snippets as output. SUPA addresses the needs of operators and 398 application developers to represent multiple types of policy 399 rules, which vary in the level of abstraction, to suit the needs 400 of different actors [1], [10]. 402 Different constituencies of users would like to use languages that 403 use terminology and concepts that are familiar to each constituency. 404 Rather than require multiple software systems to be used for each 405 language, a common information model enables these different 406 languages to be mapped to terms in the information model. This 407 facilitiates the use of a single software system to generate data 408 models for each language. In the example shown in Figure 1 (which 409 is a simplified policy continuum [10]), each constituency needs 410 different grammars using different concepts and terminologies to 411 match their skill set. This is shown in Figure 1. A unified 412 information model is one way to build a consensual lexicon that 413 enables terms from one language to be mapped to terms of another 414 language. 416 +---------------------+ 417 +---------------+ \| High-level Policies | \+-------------+ 418 | Business User |----| Without Technical |----| Language #1 | 419 +---------------+ /| Terminology | /+-------------+ 420 +---------------------+ 422 +---------------------+ 423 +---------------+ \| Policies That Use | \+-------------+ 424 | Developer |----| Classes, Attributes,|----| Language #2 | 425 +---------------+ /| Relationships, ... | /+-------------+ 426 +---------------------+ 428 ... ... ... 430 +---------------------+ 431 +---------------+ \| Low-level Policies | \+-------------+ 432 | Admin |----| with Technology- |----| Language #n | 433 +---------------+ /| Specific Terms in a | /+-------------+ 434 | Specific Language | 435 +---------------------+ 437 Figure 1. Different Constituencies Need Different Policies 439 More importantly, an information model defines concepts in a 440 uniform way, enabling formal mapping processes to be developed to 441 translate the information model to a set of data models. This 442 simplifies the process of constructing software to automate the 443 policy management process. It also simplifies the language 444 generation process, though that is beyond the scope of this 445 document. 447 This common framework takes the form of an information model that 448 is divided into one high-level module and any number of lower- 449 level modules, where each lower-level module extends the concepts 450 of the single high-level module. Conceptually, a set of model 451 elements (e.g., classes, attributes, and relationships) are used 452 to define the Generic Policy Information Model (GPIM); this module 453 defines a common set of policy management concepts that are 454 independent of the type of policy (e.g., imperative, procedural, 455 declarative, or otherwise). Then, any number of additional modules 456 are derived from the GPIM; each additional module MUST extend the 457 GPIM to define a new type of policy rule by adding to the GPIM. 458 (Note: using extensions preserves the core interoperability, as 459 compared with modification of the base GPIM, which would adversely 460 compromise interoperability. 462 The SUPA Eca Policy Rule Information Model (EPRIM) extends the 463 GPIM to represent policy rules that use the Event-Condition-Action 464 (ECA) paradigm. (The Appendices describe the SUPA Logic Statement 465 Information Model (LSIM), which shows how to extend the GPIM to 466 represent a collection of statements that are either Propositional 467 Logic (PL) or First-Order Logic (FOL), respectively. Both of these 468 logics are types of declarative logic. Note that the LSIM is 469 currently out of scope. However, it is outlined as a set of 470 Appendices in this document to get feedback on its utility. 472 1.2. Changes Since Version -04 474 There are several changes in this version of this document 475 compared to the previous versions of this document. They are: 477 1) The SUPAVendorDecoratedComponent class has been renamed to 478 SUPAGenericDecoratedComponent, and its function has been 479 made more generic. 480 2) A number of clarifications have been made in response to 481 questions from the SUPA mailing list. 482 3) The multiplicity of all relationships have been fine-tuned 483 4) A **preliminary** YANG model [RFC6020] [RFC6991] has been 484 built from the GPIM; see [15]. 485 5) Various additional typos have been fixed. 487 2. Conventions Used in This Document 489 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 490 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 491 this document are to be interpreted as described in [RFC2119]. In 492 this document, these words will appear with that interpretation 493 only when in ALL CAPS. Lower case uses of these words are not to 494 be interpreted as carrying [RFC2119] significance. 496 3. Terminology 498 This section defines acronyms, terms, and symbology used in the 499 rest of this document. 501 3.1. Acronyms 503 CLI Command Line Interface 504 CRUD Create, Read, Update, Delete 505 CNF Conjunctive Normal Form 506 DNF Disjunctive Normal Form 507 ECA Event-Condition-Action 508 EPRIM (SUPA) ECA Policy Rule Information Model 509 GPIM (SUPA) Generic Policy Information Model 510 OAM&P Operations, Administration, Management, and Provisioning 511 OID Object IDentifier 512 SUPA Simplified Use of Policy Abstractions 513 TMF TeleManagent Forum (TM Forum) 514 UML Unified Modeling Language 515 URI Uniform Resource Identifier 516 YANG A data definition language for use with NETCONF 517 ZOOM Zero-touch Orchestration, Operations, and Management 518 (a TMF project that also works on information models) 520 3.2. Definitions 522 This section defines the terminology that is used in this document. 524 3.2.1. Core Terminology 526 The following subsections define the terms "information model" and 527 "data model", as well as "container" and "policy container". 529 3.2.1.1. Information Model 531 An information model is a representation of concepts of interest 532 to an environment in a form that is independent of data repository, 533 data definition language, query language, implementation language, 534 and protocol. 536 Note: this definition is more specific than that of [RFC3198], so 537 as to focus on the properties of information models. That definition 538 was: "An abstraction and representation of the entities in a managed 539 environmentl, their properties, attributes and operations, and the 540 way that they relate to each other. It is independent of any 541 specific repository, software usage, protocol, or platform." 543 3.2.1.2. Data Model 545 A data model is a representation of concepts of interest to an 546 environment in a form that is dependent on data repository, data 547 definition language, query language, implementation language, and 548 protocol (typically, but not necessarily, all three). 550 Note: this definition is more specific than that of [RFC3198], so 551 as to focus on the properties of data models that are generated 552 from information models. That definition was: "A mapping of the 553 contents of an information model into a form that is specific to a 554 particular type of data store or repository." 556 3.2.1.3. Abstract Class 558 An abstract class is a class that cannot be directly instantiated. 559 It MAY have abstract or concrete subclasses. It is denoted with a 560 capital A near the top-left side of the class. 562 3.2.1.4. Concrete Class 564 A concrete class is a class that can be directly instantiated. Note 565 that classes are either abstract or concrete. In addition, once a 566 class has been defined as concrete in the hierarchy, all of its 567 subclasses MUST also be concrete. It is denoted with a capital C 568 near the top-left side of the class. 570 3.2.1.5. Container 572 A container is an object whose instances may contain zero or more 573 additional objects, including container objects. A container 574 provides storage, query, and retrieval of its contained objects 575 in a well-known, organized way. 577 3.2.1.6. PolicyContainer 579 In this document, a PolicyContainer is a special type of container 580 that provides at least the following three functions: 581 1. It uses metadata to define how its content is interpreted 582 2. It separates the content of the policy from the 583 representation of the policy 584 3. It provides a convenient control point for OAMP operations 585 The combination of these three functions enables a PolicyContainer 586 to define the behavior of how its constituent components will be 587 accessed, queried, stored, retrieved, and how they operate. 589 This document does NOT define a specific data type to implementation 590 a PolicyContainer, as many different types of data types can be 591 used. However, the data type chosen SHOULD NOT allow duplicate 592 members in the PolicyContainer. In addition, order is irrelevant, 593 since priority will override any initial order of the members of 594 this PolicyContainer. 596 3.2.2. Policy Terminology 598 The following terms define different policy concepts used in the 599 SUPA Generic Policy Information Model (GPIM). Note that the 600 prefix "SUPA" is used for all classes and relationships defined 601 in this model to ensure name uniqueness. Similarly, the prefix 602 "supa" is defined for all SUPA class attributes. 604 3.2.2.1. SUPAPolicyObject 606 A SUPAPolicyObject is the root of the GPIM class hierarchy. It is 607 an abstract class that all classes inherit from, except the 608 SUPAPolicyMetadata class. 610 3.2.2.2. SUPAPolicy 612 A SUPAPolicy is, in this version of this document, an ECA policy 613 rule that is a type of PolicyContainer. The PolicyContainer MUST 614 contain an ECA policy rule, SHOULD contain one or more 615 SUPAPolicyMetadata objects, and MAY contain other elements that 616 define the semantics of the policy rule. Policies are generically 617 defined as a means to monitor and control the changing and/or 618 maintaining of the state of one or more managed objects [1]. In 619 this context, "manage" means that at least create, read, query (a 620 more complex operation than read that may involve pre- and/or post- 621 processing of the results of the operation), update, and delete 622 functions are supported. 624 3.2.2.3. SUPAPolicyClause 626 A SUPAPolicyClause is an abstract class. Its subclasses define 627 different types of clauses that are used to create the content 628 for different types of SUPAPolicies. 630 For example, the SUPABooleanClause subclass models the content 631 of a SUPAPolicy as a Boolean clause, where each Boolean clause 632 is made up of a set of reusable objects. In contrast, a 633 SUPAEncodedClause encodes the entire clause as a set of 634 attributes. All types of SUPAPolicies MUST use one or more 635 SUPAPolicyClauses to construct a SUPAPolicy. 637 3.2.2.4. SUPAECAPolicyRule 639 An Event-Condition-Action (ECA) Policy (SUPAECAPolicyRule) is an 640 abstract class that is a type of PolicyContainer. It represents 641 a policy rule as a three-tuple, consisting of an event, a 642 condition, and an action clause. In an information model, this 643 takes the form of three different aggregations, one for each 644 clause. Each clause MUST be represented by at least one 645 SUPAPolicyClause. Optionally, the SUPAECAPolicyRule MAY contain 646 zero or more SUPAPolicySources, zero or more SUPAPolicyTargets, 647 and zero or more SUPAPolicyMetadata objects. 649 3.2.2.5. SUPAMetadata 651 Metadata is, literally, data about data. SUPAMetadata is an 652 abstract class that contains prescriptive and/or descriptive 653 information about the object(s) to which it is attached. While 654 metadata can be attached to any information model element, this 655 document only considers metadata attached to classes and 656 relationships. 658 When defined in an information model, each instance of the 659 SUPAMetadata class MUST have its own aggregation relationship 660 with the set of objects that it applies to. However, a data model 661 MAY map these definitions to a more efficient form (e.g., 662 flattening the object instances into a single object instance). 664 3.2.2.6. SUPAPolicyTarget 666 SUPAPolicyTarget is an abstract class that defines a set of 667 managed objects that may be affected by the actions of a 668 SUPAPolicyClause. A SUPAPolicyTarget may use one or more 669 mechanisms to identify the set of managed objects that it 670 affects; examples include OIDs and URIs. 672 When defined in an information model, each instance of the 673 SUPAPolicyTarget class MUST have its own aggregation 674 relationship with each SUPAPolicy that uses it. However, a 675 data model MAY map these definitions to a more efficient form 676 (e.g., flattening the SUPAPolicyTarget, SUPAMetadata, and 677 SUPAPolicy object instances into a single object instance). 679 3.2.2.7. SUPAPolicySource 681 SUPAPolicySource is an abstract class that defines a set of 682 managed objects that authored this SUPAPolicyClause. This is 683 required for auditability. A SUPAPolicySource may use one or more 684 mechanisms to identify the set of managed objects that authored it; 685 examples include OIDs and URIs. Specifically, policy CRUD MUST be 686 subject to authentication and authorization, and MUST be auditable. 687 Note that the mechanisms for doing these three operations are 688 currently not included, and are for further discussion. 690 When defined in an information model, each instance of the 691 SUPAPolicySource class MUST have its own aggregation relationship 692 with each SUPAPolicy that uses it. However, a data model MAY map 693 these definitions to a more efficient form (e.g., flattening the 694 SUPAPolicySource, SUPAMetadata, and SUPAPolicy object instances 695 into a single object instance). 697 3.2.3. Modeling Terminology 699 The following terms define different types of relationships used 700 in the information models of the SUPA Generic Policy Information 701 Model (GPIM). 703 3.2.3.1. Inheritance 705 Inheritance makes an entity at a lower level of abstraction (e.g., 706 the subclass) a type of an entity at a higher level of abstraction 707 (e.g., the superclass). Any attributes and relationships that are 708 defined for the superclass are also defined for the subclass. 709 However, a subclass does NOT change the characteristics or behavior 710 of the attributes or relationships of the superclass that it 711 inherits from. Formally, this is called the Liskov Substitution 712 Principle [7]. This principle is one of the key characteristics 713 that is NOT followed in [4], [6], [RFC3060], and [RFC3460]. 715 A subclass MAY add new attributes and relationships that refine 716 the characteristics and/or behavior of it compared to its 717 superclass. A subclass MUST NOT change inherited attributes or 718 relationships. 720 3.2.3.2. Relationship 722 A relationship is a generic term that represents how a first set 723 of entities interact with a second set of entities. A recursive 724 relationship sets the first and second entity to the same entity. 725 There are three basic types of relationships, as defined in the 726 subsections below: associations, aggregations, and compositions. 728 A subclass MUST NOT change the multiplicity (see section 3.2.3.7) 729 of a relationship that it inherits. A subclass MUST NOT change any 730 attributes of a relation that it inherits that is realized using 731 an association class (see section 3.2.3.6). 733 3.2.3.3. Association 735 An association represents a generic dependency between a first 736 and a second set of entities. In an information model, an 737 association MAY be represented as a class. 739 3.2.3.4. Aggregation 741 An aggregation is a stronger type (i.e., more restricted 742 semantically) of association, and represents a whole-part 743 dependency between a first and a second set of entities. Three 744 objects are defined by an aggregation: the first entity, the 745 second entity, and a new third entity that represents the 746 combination of the first and second entities. 748 The entity owning the aggregation is referred to as the 749 "aggregate", and the entity that is aggregated is referred to as 750 the "part". In an information model, an aggregation MAY be 751 represented as a class. 753 3.2.3.5. Composition 755 A composition is a stronger type (i.e., more restricted 756 semantically) of aggregation, and represents a whole-part 757 dependency with two important behaviors. First, an instance of the 758 part is included in at most one instance of the aggregate at a 759 time. Second, any action performed on the composite entity (i.e., 760 the aggregate) is propagated to its constituent part objects. 761 For example, if the composite entity is deleted, then all of its 762 constituent part entities are also deleted. This is not true of 763 aggregations or associations - in both, only the entity being 764 deleted is actually removed, and the other entities are unaffected. 765 In an information model, a composition MAY be represented as 766 a class. 768 3.2.3.6. Association Class 770 A relationship may be implemented as an association class. This is 771 used to define the relationship as having its own set of features. 772 More specifically, if the relationship is implemented as an 773 association class, then the attributes of the association class, as 774 well as other relationships that the association class participates 775 in, may be used to define the semantics of the relationship. If the 776 relationship is not implemented as an association class, then no 777 additional semantics (beyond those defined by the type of the 778 relationship) are expressed by the relationship. 780 3.2.3.7. Multiplicity 782 A specification of the range of allowable cardinalities that a set 783 of entities may assume. This is always a pair of ranges, such as 784 1 - 1 or 0..n - 2..5. 786 3.2.3.8. Navigability 788 A relationship may have a restriction on the ability of an object 789 at one end of the relationship to access the object at the other 790 end of the relationship. This document defines two choices: 792 1. Each object is navigable by the other, which is indicated 793 by NOT providing any additional symbology, or 795 2. An object A can navigate to object B, but object B cannot 796 navigate to object A. This is indicated by an open-headed 797 arrow pointing to the object that cannot navigate to the 798 other object. In this example, the arrow would be pointing 799 at object B. 801 Examples of navigability are: 803 +---------+ 3..4 +---------+ 804 | | 1..2 \| | 805 | Class A |--------------| Class B | 806 | | /| | 807 +---------+ +---------+ 809 This is an association. Class A can navigate to Class B, but Class 810 B cannot navigate to Class A. This is a mandatory association, 811 since none of the multiplicities contain a '0'. This association 812 reads as follows: 814 Class A depends on 3 to 4 instances of Class B, and 815 Class B depends on 1 to 2 instances of Class A. 817 3.3. Symbology 819 The following symbology is used in this document: 821 3.3.1. Inheritance 823 Inheritance: a subclass inherits the attributes and relationships 824 of its superclass, as shown below: 826 +------------+ 827 | Superclass | 828 +------+-----+ 829 / \ 830 I 831 I 832 I 833 +------+-----+ 834 | Subclass | 835 +------------+ 837 3.3.2. Association 839 Association: Class B depends on Class A, as shown below: 841 +---------+ +---------+ 842 +---------+ +---------+ | | \| | 843 | Class A |------| Class B | | Class A |------| Class B | 844 +---------+ +---------+ | | /| | 845 +---------+ +---------+ 847 association with no association with 848 navigability restrictions navigability restrictions 850 3.3.3. Aggregation 852 Aggregation: Class B is the part, Class A is the aggregate, 853 as shown below: 855 +---------+ +---------+ +---------+ 856 | |/ \ +---------+ | |/ \ \| | 857 | Class A | A ---| Class B | | Class A | A ------| Class B | 858 | |\ / +---------+ | |\ / /| | 859 +---------+ +---------+ +---------+ 861 aggregation with no aggregation with 862 navigability restrictions navigability restrictions 864 3.3.4. Composition 866 Composition: Class B is the part, Class A is the composite, 867 as shown below: 869 +---------+ +---------+ +---------+ 870 | |/ \ +---------+ | |/ \ \| | 871 | Class A | C ---| Class B | | Class A | C ------| Class B | 872 | |\ / +---------+ | |\ / /| | 873 +---------+ +---------+ +---------+ 875 composition with no composition with 876 navigability restrictions navigability restrictions 878 3.3.5. Association Class 880 Association Class: Class C is the association class implementing 881 the relationship D between classes A and B 882 +---------+ +---------+ 883 | Class A |----+-----| Class B | 884 +---------+ ^ +---------+ 885 | 886 | 887 +----------+----------+ 888 | Association Class C | 889 +---------------------+ 891 3.3.6. Abstract vs. Concrete Classes 893 In UML, abstract classes are denoted with their name in italics. 894 For this draft, a capital 'A' will be placed at either the top 895 left or right corner of the class to signify that the class is 896 abstract. Similarly, a captial 'C' will be placed in the same 897 location to represent a concrete class. This is shown below. 899 A C 900 +---------+ +---------+ 901 | Class A | | Class B | 902 +---------+ +---------+ 904 An Abstract Class A Concrete Class 906 4. Policy Abstraction Architecture 908 This section describes the motivation for the policy abstractions 909 that are used in SUPA. The following abstractions are provided: 911 o The GPIM defines a technology-neutral information model that 912 can express the concept of Policy. 913 o All classes, except for SUPAPolicyMetadata, inherit from 914 SUPAPolicyObject, or one of its subclasses 915 o SUPAPolicyObject and SUPAPolicyMetadata are designed to 916 inherit from classes in another model; the GPIM does not 917 define an "all-encompassing" model. 918 o This version of this document restricts the expression of 919 Policy to a set of event-condition-action clauses. 920 o Each clause is defined as a Boolean expression, and is a 921 reusable object 922 o Clauses may be combined to form more complex Boolean 923 expressions 924 o The purpose of the GPIM is to enable different policies that 925 have fundamentally different representations to share common 926 model elements. Policy statmeents, which are implemented as 927 instances of the SUPAPolicyClause class, separates the content 928 of a Policy from its representation. This is supported by: 929 o All policy rules (of which SUPAECAPolicyRule is the 930 first example of a concrete class) are derived from 931 the SUPAPolicyStructure class. 932 o All objects that are components of policy rules are 933 derived from the SUPAPolicyComponentStructure class. 934 o A SUPAPolicy MUST contain at least one SUPAPolicyClause. 935 o A SUPAPolicy MAY specify one or more SUPAPolicyTarget, 936 SUPAPolicySource, and SUPAPolicyMetadata objects to 937 augment the semantics of the SUPAPolicy 938 o A SUPAPolicyClause has two subclasses: 939 o A SUPABooleanClause, which is used to build 940 SUPAECAPolicyRules from reusable objects. 941 o A SUPAEncodedClause, which is used for using 942 attributes instead of objects to construct a 943 SUPAECAPolicyRule. 944 o A SUPAECAPolicyRule defines the set of events and conditions 945 that are responsible for executing its actions; it MUST have 946 at least one event clause, at least one condition clause, and 947 at least one action clause. 948 o The action(s) of a SUPAECAPolicyRule are ONLY executed 949 if both the event and condition clauses evaluate to TRUE 950 o A SUPAPolicyAction MAY invoke another SUPAECAPolicyRule 951 (see section 6.13). 952 o SUPAMetadata MAY be defined for any SUPAPolicyObject class. 953 o SUPAMetadata MAY be prescriptive and/or descriptive in nature. 955 Please see the Appendices for experimental definitions of 956 declarative policies. Note that they also are derived from the 957 GPIM, and extend (but do not change) the above abstractions. 959 4.1. Motivation 961 The power of policy management is its applicability to many 962 different types of systems. There are many different actors that 963 can use a policy management system, including end-users, operators, 964 application developers, and administrators. Each of these 965 constituencies have different concepts and skills, and use 966 different terminology. For example, an operator may want to express 967 an operational rule that states that only Platinum and Gold users 968 can use streaming multimedia applications. As a second example, a 969 network administrator may want to define a more concrete policy 970 rule that looks at the number of dropped packets and, if that 971 number exceeds a programmable threshold, changes the queuing and 972 dropping algorithms used. 974 SUPA may be used to define other types of policies, such as for 975 systems and operations management; an example is: "All routers and 976 switches must have password login disabled". See section 3 of [8] 977 for additional declarative and ECA policy examples. 979 All of the above examples are commonly referred to as "policy 980 rules", but they take very different forms, since they are at very 981 different levels of abstraction and typically authored by 982 different actors. The first was very abstract, and did not contain 983 any technology-specific terms, while the second was more concrete, 984 and likely used technical terms of a general (e.g., IP address 985 range, port numbers) as well as a vendor-specific nature (e.g., 986 specific queuing, dropping, and/or scheduling algorithms 987 implemented in a particular device). The third restricted the type 988 of login that was permissible for certain types of devices in the 989 environment. 991 Note that the first two policy rules could directly affect each 992 other. For example, Gold and Platinum users might need different 993 device configurations to give the proper QoS markings to their 994 streaming multimedia traffic. This is very difficult to do if a 995 common policy model does not exist, especially if the two policies 996 are authored by different actors that use different terminology 997 and have different skill sets. More importantly, the users of 998 these two policies likely have different job responsibilities. 999 They may have no idea of the concepts used in each policy. Yet, 1000 their policies need to interact in order for the business to 1001 provide the desired service. This again underscores the need for 1002 a common policy framework. 1004 Certain types of policy rules (e.g., ECA) may express actions, or 1005 other types of operations, that contradict each other. SUPA 1006 provides a rich object model that can be used to support language 1007 definitions that can find and resolve such problems. 1009 4.2. SUPA Approach 1011 The purpose of the SUPA Generic Policy Information Model (GPIM) is 1012 to define a common framework for expressing policies at different 1013 levels of abstraction. SUPA uses the GPIM as a common vocabulary 1014 for representing policy concepts that are independent of language, 1015 protocol, repository, and level of abstraction. This enables 1016 different actors to author and use policies at different levels of 1017 abstraction. This forms a policy continuum [1] [2], where more 1018 abstract policies can be translated into more concrete policies, 1019 and vice-versa. 1021 Most systems define the notion of a policy as a single entity. 1022 This assumes that all users of policy have the same terminology, 1023 and use policy at the same level of abstraction. This is rarely, 1024 if ever, true in modern systems. The policy continuum defines a 1025 set of views (much like RM-ODP's viewpoints [9]) that are each 1026 optimized for a user playing a specific role. SUPA defines the 1027 GPIM as a standard vocabulary and set of concepts that enable 1028 different actors to use different formulations of policy. This 1029 corresponds to the different levels in the policy continuum, and 1030 as such, can make use of previous experience in this area. 1032 It may be necessary to translate a Policy from a general to a more 1033 specific form (while keeping the abstraction level the same). For 1034 example, the declarative policy "Every network attached to a VM 1035 must be a private network owned by someone in the same group as 1036 the owner of the VM" may be translated to more formal form (e.g., 1037 Datalog (as in OpenStack Congress). It may also be necessary to 1038 translate a Policy to a different level of abstraction. For 1039 example, the previous Policy may need to be translated to a form 1040 that network devices can process directly. This requires a common 1041 framework for expressing policies that is independent of the level 1042 of abstraction that a Policy uses. 1044 4.3. SUPA Generic Policy Information Model Overview 1046 Figure 2 illustrates the approach for representing policy rules 1047 in SUPA. The top two layers are defined in this document; the 1048 bottom layer (Data Models) are defined in separate documents. 1049 Conceptually, the GPIM defines a set of objects that define the 1050 key elements of a Policy independent of how it is represented or 1051 its content. As will be shown, there is a significant difference 1052 between SUPAECAPolicyRules (see Section 6) and other types of 1053 policies (see Section 7). In principle, other types of SUPAPolicies 1054 could be defined, but the current charter is restricted to using 1055 only event-condition-action SUPAPolicies as exemplars. 1057 Note: the GPIM MAY be used without the EPRIM. However, in order to 1058 use the EPRIM, the GPIM MUST also be used. 1060 +----------------------------------------------+ 1061 | SUPA Generic Policy Information Model (GPIM) | 1062 +----------------------+-----------------------+ 1063 / \ 1064 | 1065 | 1066 +-----------------+--------------+ 1067 | | 1068 | | 1069 +-----------+---------------+ +-------------+-------------+ 1070 | SUPAECAPolicyRule | | Other Policy Models that | 1071 | Information Model (EPRIM) | | are Derived from the GPIM | 1072 +-----------+---------------+ +-------------+-------------+ 1073 / \ / \ 1074 | | 1075 | | 1076 +-----------+-----------+ +-----------+------------+ 1077 | ECAPolicyRule | | Other Types of | 1078 | Data Model | | Data Models | 1079 +-----------------------+ +------------------------+ 1081 Figure 2. Overview of SUPA Policy Rule Abstractions 1083 This draft defines the GPIM and EPRIM. Note that there is only 1084 ONE GPIM and ONE EPRIM. While both can be extended, it is 1085 important to limit the number of information models to one, in 1086 order to avoid defining conflicting concepts at this high a 1087 level of abstraction. Similarly, if the GPIM and EPRIM are part 1088 of another information model, then they should collectively 1089 still define a single information model. The GPIM defines the 1090 following concepts: 1092 o A class defining the top of the GPIM class hierarchy, called 1093 SUPAPolicyObject 1094 o Four subclasses of SUPAPolicyObject, representing: 1095 o the top of the PolicyRule hierarchy, called 1096 SUPAPolicyStructure 1097 o the top of the PolicyRule component hierarchy, called 1098 SUPAPolicyComponentStructure 1099 o PolicySource 1100 o PolicyTarget 1102 The SUPAPolicyStructure class is the superclass for all types of 1103 Policies (e.g., imperative, declarative, and others). This 1104 document is currently limited to imperative (e.g., ECA) policies. 1105 However, care has been taken to ensure that the attributes and 1106 relationships of the SUPAPolicyStructure class are extensible, 1107 and can be used for more types of policies than just ECA policies. 1109 This yields the following high-level structure: 1111 A 1112 +------------------+ 1113 | SUPAPolicyObject | 1114 +--------+---------+ 1115 / \ 1116 I 1117 I 1118 +----------------+--------------------+ 1119 I I I 1120 A I I A I 1121 +--------+------------+ I +------------+-----------------+ 1122 | SUPAPolicyStructure | I | SUPAPolicyComponentStructure | 1123 +----+----------------+ I +------------+-----------------+ 1124 / \ I / \ 1125 I +--------+----+ I 1126 I I I I 1127 I C I I I 1128 I +-------+----------+ I I 1129 I | SUPAPolicySource | I I 1130 I +------------------+ I I 1131 I I I 1132 I +-------------+ I 1133 I I I 1134 I C I +-----+-------+ 1135 I +-------+----------+ I I 1136 I | SUPAPolicyTarget | A I I 1137 I +------------------+ +--------+---------+ I 1138 A I | SUPAPolicyClause | I 1139 +-----+------------+ +------------------+ I 1140 | SUPAECAPolicyRule| I 1141 +------------------+ A I 1142 +--------------------+---------+ 1143 | SUPAPolicyComponentDecorator | 1144 +------------------------------+ 1146 Figure 3. Functional View of the Top-Level GPIM 1148 Note that all classes except the SUPAPolicySource and the 1149 SUPAPolicyTarget classes are defined as abstract. This provides 1150 more freedom for the data modeler in implementing the data model. 1151 For example, if the data model uses an object-oriented language, 1152 such as Java, then the above structure enables all of the abstract 1153 classes to be collapsed to a single concrete class. If this is 1154 done, attributes as well as relationships are inherited. 1156 4.3.1. SUPAPolicyObject 1158 A SUPAPolicyObject serves as a single root of the SUPA system 1159 (i.e., all other classes in the model are subclasses of the 1160 SUPAPolicyObject class). This simplifes code generation and 1161 reusability. It also enables SUPAPolicyMetadata objects to be 1162 attached to any appropriate subclass of SUPAPolicyObject. 1164 4.3.2. SUPAPolicyStructure 1166 SUPAPolicyStructure is an abstract superclass that is the base 1167 class for defining different types of policies (however, in this 1168 version of this document, only ECA policy rules are modeled). It 1169 serves as a convenient aggregation point to define atomic (i.e., 1170 individual policies that can be used independently) and composite 1171 (i.e., hierarchies of policies) SUPAPolicies; it also enables 1172 PolicySources and/or PolicyTargets to be associated with a given 1173 set of Policies. 1175 SUPAPolicies are defined as either a stand-alone PolicyContainer 1176 or a hierarchy of PolicyContainers. A PolicyContainer specifies 1177 the structure, content, and optionally, source, target, and 1178 metadata information for a SUPAPolicy. This is implemented by the 1179 subclasses of SUPAPolicyStructure. For example, the composite 1180 pattern is used to create two subclasses of the SUPAECAPolicyRule 1181 class; SUPAECAPolicyRuleAtomic is used for stand-alone policies, 1182 and SUPAECAPolicyRuleComposite is used to build hierarchies of 1183 policies. 1185 This document defines a SUPAPolicy as an ECA Policy Rule, though 1186 the GPIM enables other types of policies to be defined and used 1187 with an ECA policy rule. The GPIM model is used in [2] and [5], 1188 along with extensions that allow [2] and [5] to define multiple 1189 types of policies that are derived from the GPIM. They also allow 1190 different combinations of different types of policy rules to be 1191 used with each other. Most previous work cannot define different 1192 types of policy rules; please see Appendix A for a comparison to 1193 previous work. 1195 4.3.3. SUPAPolicyComponentStructure 1197 SUPAPolicyComponentStructure is an abstract superclass that is the 1198 base class for defining components of different types of policies. 1199 SUPAPolicyStructure subclasses define the structure of a policy, 1200 while SUPAPolicyComponentStructure subclasses define the content 1201 that is contained in the structure of a policy. For example, a 1202 SUPAECAPolicyRule is an imperative policy rule, and defines its 1203 structure; its event, condition, and action clauses are populated 1204 by SUPAPolicyComponentStructure subclasses. The strength of this 1205 design is that different types of policies (e.g., imperative and 1206 declarative policies) can be represented using a common set of 1207 policy components. 1209 Please see Appendix for a comparison to previous work. 1211 4.3.4. SUPAPolicyClause 1213 All policies derived from the GPIM are made up of one or more 1214 SUPAPolicyClauses, which define the content of the Policy. 1215 This enables a Policy of one type (e.g., ECA) to invoke Policies 1216 of the same or different types. SUPAPolicyClause is an abstract 1217 class, and serves as a convenient aggregation point for assembling 1218 other objects that make up a SUPAPolicyClause. 1220 The GPIM defines a single concrete subclass of SUPAPolicyClause, 1221 called SUPAEncodedClause. This is a generic clause, and can be 1222 used by any type of Policy in a stand-alone fashion. It can also 1223 be used in conjunction with other SUPAPolicyClauses. The EPRIM 1224 also defines a subclass of SUPAPolicyClause; see section 6.7). 1226 The structure of the GPIM is meant to provide an extensible 1227 framework for defining different types of policies. This is 1228 demonstrated by the EPRIM (see section 6) and the LSIM (see the 1229 Appendices) that each define new subclasses of SUPAPolicyClause 1230 (i.e., SUPABooleanClause and SUPALogicClause, respectively) 1231 without defining new classes that have no GPIM superclass. 1233 A SUPAPolicyClause is defined as an object. Therefore, clauses and 1234 sets of clauses are objects, which promotes reusability. 1236 4.3.5. SUPAPolicyComponentDecorator 1238 One of the problems in building a policy model is the tendency to 1239 have a multitude of classes, and hence object instances, to 1240 represent different combinations of policy events, conditions, and 1241 actions. This can lead to class and/or relationship explosion. 1242 Please see Appendix A for a comparison to previous work. 1244 SUPAPolicyClauses are constructed using the Decorator Pattern 1245 [11]. This is a design pattern that enables behavior to be 1246 selectively added to an individual object, either statically or 1247 dynamically, without affecting the behavior of other objects from 1248 the same class. The decorator pattern uses composition, instead of 1249 inheritance, to avoid class and relationship explosion. The 1250 decorator pattern also enable new objects to be composed from 1251 parts or all of existing objects without affecting the existing 1252 objects. 1254 This enables the resulting SUPAPolicyClause to be constructed 1255 completely from objects in the SUPA information model. This 1256 facilitates the construction of policies at runtime by a machine. 1257 This is also true of [2] and [5]; however, this is NOT true of 1258 most other models. Please see Appendix A for a comparison to 1259 previous work. 1261 SUPAPolicyComponentDecorator defines four types of objects that 1262 can be used to form a SUPAPolicyClause. Each object may be used 1263 with all other objects, if desired. The first three are defined 1264 in the GPIM, with the last defined in the EPRIM. The objects are: 1266 o SUPAPolicyTerm, which enables a clause to be defined in a 1267 canonical {variable, operator, value} form 1268 o SUPAGenericDecoratedComponent, which enabled a custom object 1269 to be defined and then used in a SUPAPolicyClause 1270 o SUPAPolicyCollection, which enables a collection of objects 1271 to be gathered together and associated with all or a portion 1272 of a SUPAPolicyClause 1273 o SUPAECAComponent, which defines Events, Conditions, and 1274 Actions as reusable objects 1276 This approach facilitates the machine-driven construction of 1277 policies. Note that this is completely optional; policies do not 1278 have to use these constructs. 1280 4.3.6. SUPAPolicyTarget 1282 A SUPAPolicyTarget is a set of managed entities that a SUPAPolicy 1283 is applied to. A managed entity can only be designated a 1284 SUPAPolicyTarget if it can process actions from a SUPAPolicy. 1286 A managed object may not be in a state that enables management 1287 operations to be performed on it. Furthermore, the policy-based 1288 management system SHOULD ensure that the management entity 1289 performing the management operations has the proper permissions to 1290 perform the management operations. The design of the 1291 SUPAPolicyTarget addresses both of these criteria. 1293 4.3.7. SUPAPolicySource 1295 A SUPAPolicySource is a set of managed entities that authored, or 1296 are otherwise responsible for, this SUPAPolicy. Note that a 1297 SUPAPolicySource does NOT evaluate or execute SUPAPolicies. Its 1298 primary use is for auditability and the implementation of deontic 1299 and/or alethic logic. 1301 4.4. The Design of the GPIM 1303 This section describes the overall design of the GPIM. 1305 The GPIM defines a policy as a type of PolicyContainer. For this 1306 version, only ECA Policy Rules will be described. However, it 1307 should be noted that the mechanism described is applicable to 1308 other types of policies (e.g., declarative) as well. 1310 4.4.1. Structure of Policies 1312 Recall that a PolicyContainer was defined as a special type of 1313 container that provides at least the following three functions: 1315 1. It uses metadata to define how its content is described 1316 and/or prescribed 1317 2. It separates the content of the policy from the 1318 representation of the policy 1319 3. It provides a convenient control point for OAMP operations. 1321 The first requirement is provided by the ability for any subclass 1322 of Policy (the root of the information model) to aggregate one or 1323 more concrete instances of a SUPAPolicyMetadata class. This is 1324 explained in detail in section 5.2.2. 1326 The second requirement is met by representing an ECA Policy as 1327 having two parts: (1) a rule part and (2) components that make up 1328 the rule. Since functional and declarative policies are not, 1329 strictly speaking, "rules", the former is named PolicyStructure, 1330 while the latter is named PolicyComponentStructure. 1332 The third requirement is met by the concrete subclasses of 1333 PolicyStructure. Since they are PolicyContainers, they are made 1334 up of the SUPAECAPolicyRule, its commponents, and any metadata 1335 that applies to the PolicyContainer, the SUPAECAPolicyRule, and.or 1336 any components of the SUPAECAPolicyRule. This provides optional 1337 low-level control over any part of the SUPAECAPolicyRule. 1339 The above requirements result in the design shown in Figure 4. 1341 A SUPAHasPolicyMetadata A 1342 +------------------+/ \ \+--------------------+ 1343 | SUPAPolicyObject + A -----------------------+ SUPAPolicyMetadata | 1344 +---------+--------+\ / /+--------------------+ 1345 / \ 0..n 0..n 1346 I 1347 I 1348 +------+------------------------------------+ 1349 I I 1350 A I A I 1351 +--------+------------+ +------------------+-----------+ 1352 | SUPAPolicyStructure | | SUPAPolicyComponentStructure | 1353 +--------+------------+ +-------------+----------------+ 1354 / \ / \ 1355 I I 1356 I I 1357 (subclasses representing (subclasses representing 1358 different types of policies) different policy components) 1360 Figure 4. Structure of a Policy 1362 Note that aggregation in Figure 4 (named SUPAHasPolicyMetadata) 1363 is realized as an association class, in order to manage which set 1364 of Metadata can be aggregated by which SUPAPolicyObject. The 1365 combination of these three functions enables a PolicyContainer 1366 to define the behavior of how its constituent components will be 1367 accessed, queried, stored, retrieved, and how they operate. 1369 It is often necessary to construct groups of policies. The GPIM 1370 follows [2] and [5], and uses the composite pattern [11] to 1371 implement this functionality, as shown in Figure 5 below. There 1372 are a number of advantages to using the composite pattern over a 1373 simple relationship, as detailed in [11]. 1375 Figure 5 shows that SUPAPolicyStructure has a single subclass, 1376 called SUPAECAPolicyRule. Note, however, that other types of 1377 policies, such as declarative policies, can be defined as 1378 subclasses of SUPAPolicyStructure in the future. 1380 A 1381 +---------------------+ 1382 | SUPAPolicyStructure | 1383 +--------+------------+ 1384 / \ 1385 I 1386 I 1387 +---------------+----------------+ 1388 I I 1389 C I A I 1390 +----------------+---------------+ +-----------+-----------+ 1391 | Future Subclasses to Represent | | SUPAECAPolicyRule | 1392 | Represent Different Policies | +-----------------------+ 1393 +--------------------------------+ 1395 Figure 5. The Composite Pattern Applied to SUPAPolicyStructure 1397 4.4.2. Representing an ECA Policy Rule 1399 An ECA policy rule is a 3-tuple, made up of one or more event 1400 clauses, one or more condition clauses, and one or more action 1401 clauses. Each clause may be viewed as a predicate, as it provides 1402 a TRUE or FALSE output. The canonical form of a clause is a 1403 3-tuple of the form "variable operator value", and can be made 1404 into more complex Boolean expressions. For example, the 1405 SUPAPolicyClause: "((A AND B) OR NOT (C AND D)) consists of two 1406 clauses, "(A AND B)" and "(C OR D)", that are combined together 1407 using the operators OR and NOT. 1409 A SUPAECAPolicyRule is defined (in the EPRIM) as an abstract 1410 subclass of SUPAPolicyStructure. 1412 A A 1413 +---------------------------+ +------------------+ 1414 | SUPAPolicyStructure | | SUPAPolicyClause | 1415 +---------+---------+-------+ +--------+----+----+ 1416 / \ / \ 0..1 1..n / \ / \ 1417 I A | I 1418 I \ / | I 1419 I | | I 1420 I | SUPAHasPolicyClause | I 1421 I +------------------------+ I 1422 A I A I 1423 +------+------------+ +----------+-------+ 1424 | SUPAECAPolicyRule | | SUPAPolicyClause | 1425 +-------------------+ +------------------+ 1427 Figure 6. SUPAECAPolicyRule Aggregating SUPAPolicyClauses 1429 Note that the aggregation SUPAHasPolicyClause in Figure 6 is 1430 realized as an association class, in order to manage which set 1431 of SUPAPolicyClauses can be aggregated by which set of 1432 SUPAECAPolicyRules. This aggregation is defined at the 1433 SUPAPolicyStructure level, and not at the lower level of 1434 SUPAECAPolicyRule, so that non-ECA policies can also use this 1435 aggregation. 1437 Since a SUPAECAPolicyRule consists of three SUPAPolicyClauses, 1438 at least three separate instances of the SUPAHasPolicyClause 1439 aggregation are instantiated in order to make a complete 1440 SUPAECAPolicyRule, as shown in Figure 7. 1442 A A 1443 +-------------------+ +--------------------+ 1444 | SUPAECAPolicyRule | | SUPAPolicyClause | 1445 +--+----+----+------+ +-------+----+----+--+ 1446 / \ / \ / \ 1..n 0..n / \ / \ / \ 1447 A A A | | | 1448 \ / \ / \ / | | | 1449 | | | | | | 1450 | | | SUPAHasPolicyClause #1 | | | 1451 | | +------------------------------+ | | 1452 | | | | 1453 | | SUPAHasPolicyClause #2 | | 1454 | +----------------------------------------+ | 1455 | | 1456 | SUPAHasPolicyClause #3 | 1457 +--------------------------------------------------+ 1459 Figure 7. Instantiating a SUPAECAPolicyRule, part 1 1461 In figure 7, SUPAECAPolicyRule is shown as "owning" these three 1462 aggregations, since it inherits them from its superclass 1463 (SUPAPolicyStructure). The three aggregations represent the 1464 event, condition, and action clauses of a SUPAECAPolicyRule. 1465 Note that each of these clauses MAY consist of one or more 1466 SUPAPolicyClauses. Similarly, each SUPAPolicyClause MAY consist 1467 of one or more predicates. In this way, complex event, condition, 1468 and action clauses, which are combinations of Boolean expressions 1469 that form a logical predicate) are supported, without having to 1470 define additonal objects (as is done in previous work; please 1471 see Appendix A for a comparison to previous work. 1473 The multiplicity of the SUPAHasPolicyClause aggregation is 1474 0..n on the aggregate side and 1..n on the part side. This means 1475 that a particular SUPAECAPolicyRule MUST aggregate at least one 1476 SUPAPolicyClause, and that a given SUPAPolicyClause MAY be 1477 aggregated by zero or more SUPAECAPolicyRule objects. 1479 This cardinality MAY be refined to 3..n for SUPAECAPolicyRules, 1480 since a SUPAECAPolicyRule MUST have at least three separate clauses. 1481 However, since a SUPAPolicyStructure is the owner of this 1482 aggregation (which is inherited by SUPAECAPolicyRule), the 1483 cardinality is defined to be 1..n on the part side because other 1484 types of Policies have different needs. The 0..n cardinality 1485 means that a SUPAPolicyClause may be aggregated by zero or more 1486 SUPAECAPolicyRules. The zero is provided so that SUPAPolicyClauses 1487 can be stored in (for example) a repository before the 1488 SUPAECAPolicyRule is created; the "or more" recognizes the fact 1489 that multiple SUPAECAPolicyRules could aggregate the same 1490 SUPAPolicyClause. 1492 In Figure 7, suppose that SUPAHasPolicyClause#1, #2, and #3 1493 represent the aggregations for the event, condition, and action 1494 clauses, respectively. This means that each of these 1495 SUPAHasPolicyClause aggregations must explicitly identify the 1496 type of clause that it represents. 1498 In looking at Figure 7, there is no difference between any of the 1499 three aggregations, except for the type of clause that the 1500 aggregation represents (i.e., event, condition, or action clause). 1502 Therefore, three different aggregations, each with their own 1503 association class, is not needed. Instead, the GPIM defines a 1504 single aggregation (SUPAHasPolicyClause) that is realized using a 1505 (single) abstract association class (SUPAHasPolicyClauseDetail); 1506 this association class is then subclassed into three concrete 1507 subclasses, one each to represent the semantics for an event, 1508 condition, and action clause. 1510 The policy management system may use any number of different 1511 software mechanisms, such as introspection or reflection, to 1512 determine the nature of the aggregation (i.e., what object types 1513 are being aggregated) in order to select the appropriate subclass 1514 of SUPAHasPolicyClauseDetail. The three subclasses of 1515 SUPAHasPolicyClauseDetail are named SUPAHasPolicyEventDetail, 1516 SUPAHasPolicyConditionDetail, and SUPAHasPolicyActionDetail, 1517 respectively. While Event, Condition, and Action objects are 1518 typically used in ECA policy rules, the design in this document 1519 enables them to be used as policy components of other types of 1520 policies as well. This is shown in Figure 8. 1522 A A 1523 +-------------------+ +------------------+ 1524 | SUPAECAPolicyRule | | SUPAPolicyClause | 1525 +---------+---------+ +----------+-------+ 1526 / \ 1..n 0..n / \ 1527 A | 1528 \ / | 1529 | | 1530 | SUPAHasPolicyClause | 1531 +--------------+-----------------+ 1532 ^ 1533 | 1534 A | 1535 +--------------+------------+ 1536 | SUPAHasPolicyClauseDetail | 1537 +--------------+------------+ 1538 / \ 1539 I 1540 I 1541 +----------------+-----------------------+ 1542 I I I 1543 C I C I C I 1544 +--------+-----+ +-------+----------+ +---------+-----+ 1545 |Event subclass| |Condition subclass| |Action subclass| 1546 +--------------+ +------------------+ +---------------+ 1548 Figure 8. Instantiating a SUPAECAPolicyRule, part 2 1550 4.4.3. Creating SUPA Policy Clauses 1552 There are two different types of Policy Components. They are a 1553 SUPAPolicyClause and a SUPAPolicyComponentDecorator. The former 1554 is used to construct SUPAECAPolicyRules, while the latter is used 1555 to add behavior to a SUPAPolicyClause. This enables the structure 1556 and capabilities of the SUPAPolicyClause to be adjusted 1557 dynamically at runtime. 1559 However, since each SUPAECAPolicyRule can be made up of a variable 1560 number of SUPAPolicyComponents, the decorator pattern is used to 1561 "wrap" any concrete subclass of SUPAPolicyClause with zero or more 1562 concrete subclasses of the PolicyComponentDecorator object. This 1563 avoids problems of earlier models that resulted in a proliferation 1564 of classes and relationships. 1566 Figure 9 shows these two class subclasses. Note that the decorator 1567 pattern [11] is used to enable subclasses of the 1568 SUPAPolicyComponentDecorator class to add their attributes and/or 1569 behavior to a SUPAPolicyClause (as stated in section 4.3) without 1570 affecting the behavior of other objects from the same class. More 1571 specifically, concrete subclasses of the (abstract) 1572 SUPAPolicyComponentDecorator class can be used to decorate, or 1573 "wrap", any of the concrete subclasses of the (abstract) 1574 SUPAPolicyClause class. 1576 A 1577 +------------------------------+ 1..n 1578 | SUPAPolicyComponentStructure +----------------------+ 1579 +----------------+-------------+ | 1580 / \ | 1581 I SUPAHasPolicyComponentDecorators | 1582 I | 1583 +--------------+-----------+ | 1584 I I | 1585 A I A I | 1586 +---------+--------+ +--------------+---------------+ 0..1 | 1587 | | | |/ \ | 1588 | SUPAPolicyClause | | SUPAPolicyComponentDecorator + A -----+ 1589 | | | |\ / 1590 +------------------+ +------------------------------+ 1592 Figure 9. Subclasses of SUPAPolicyComponentStructure 1594 Instead of using inheritance to statically create new classes to 1595 represent new types of objects, the decorator pattern uses 1596 composition to dynamically combine attributes and behavior from 1597 existing objects into new objects. This is done by defining an 1598 interface in SUPAPolicyComponent that all of the subclasses of 1599 SUPAPolicyComponent conform to. Since the subclasses are of the 1600 same type as SUPAPolicyComponent, they all have the same interface. 1601 This allows each concrete SUPAPolicyComponentDecorator subclass to 1602 add its attributes and/or behavior to the concrete subclass of 1603 SUPAPolicyClause that it is decorating (or "wrapping"). 1605 This represents an important design optimization for data models. 1606 Note that a single SUPAECAPolicyRule can consist of any number of 1607 SUPAPolicyClauses, each of very different types. If inheritance 1608 was used, then a subclass AND an aggregation would be required for 1609 each separate clause that makes up the policy rule. 1611 Clearly, continuing to create subclasses is not practical. Worse, 1612 suppose composite objects are desired (e.g., a new object Foo is 1613 made up of existing objects Bar and Baz). If all that was needed 1614 was one attribute of Bar and two of Baz, the developer would still 1615 have to use the entire Bar and Baz classes. This is wasteful and 1616 inefficient. In contrast, the decorator pattern enables all, or 1617 just some, of the attributes and/or behavior of a class to "wrap" 1618 another class. This is used heavily in many production systems 1619 (e.g., the java.io package) because the result is only the 1620 behavior that is required, and no other objects are affected. 1622 The SUPAPolicyComponentDecorator class hierarchy is used to define 1623 objects that may be used to construct a SUPAPolicyClause. The 1624 decorator object can add behavior before, and/or after, it 1625 delegates to the object that it is decorating. The subclasses of 1626 SUPAPolicyComponentDecorator provide a very flexible and completely 1627 dynamic mechanism to: 1629 1) add or remove behavior to/from an object 1630 2) ensure that objects are constructed using the minimum amount 1631 of features and functionality required 1633 SUPAPolicyComponentDecorator defines four subclasses, as shown in 1634 Figure 10. 1636 A 1637 +------------------------------+ 1638 | SUPAPolicyComponentDecorator | 1639 +--------------+---------------+ 1640 / \ 1641 I 1642 I 1643 I 1644 +------------+-------------+----------------+ 1645 I I I I 1646 A I I C I I 1647 +--------+-------+ I +---------+------------+ I 1648 | SUPAPolicyTerm | I | SUPAPolicyCollection | I 1649 +----------------+ I +----------------------+ I 1650 (for defining I (for defining sets and/or I 1651 clauses in I groups of objects) I 1652 canonical form) I I 1653 I I 1654 C I A I 1655 +----------------+--------------+ +---------+--------+ 1656 | SUPAGenericDecoratedComponent | | SUPAECAComponent | 1657 +-------------------------------+ +------------------+ 1658 (for decorating concrete (for defiing reusable 1659 subclasses of SUPAPolicyClause) event, condition, 1660 and action objects) 1662 Figure 10. Subclasses of SUPAPolicyComponentDecorator 1664 If a SUPAEncodedClause is being used, then there is no need to 1665 use any of the SUPAPolicyComponentDecorator subclasses, since 1666 the SUPAEncodedClause already completely defines the content of 1667 the SUPAPolicyClause. 1669 However, if a SUPAEncodedClause is NOT being used, then a 1670 SUPAPolicyClause will be constructed using one or more types of 1671 objects that are each subclasses of SUPAPolicyComponentDecorator. 1673 These four subclasses provide four different ways to construct a 1674 SUPAPolicyClause: 1676 1) SUPAPolicyTerm: as a {variable, operator, value} clause 1677 2) SUPAEncodedClause: as an encoded object (e.g., to pass YANG 1678 or CLI code) 1679 3) SUPAPolicyCollection: as a collection of objects that 1680 requires further processing in order to be made into a 1681 SUPAPolicyClause 1682 4) SUPAECAComponent: subclasses define reusable Event, 1683 Condition, or Action objects 1685 These four different types of objects can be intermixed. For 1686 example, the first and last types can be combined as follows: 1688 Variable == Event.baz (A) 1689 Condition BETWEEN VALUE1 and VALUE2 (B) 1690 (Event.severity == 'Critical' AND 1691 (SLA.violation == TRUE OR User.class == 'Gold')) (C) 1693 In the above rules, (A) uses Event.baz to refer to an attribute 1694 of the Event class; (B) defines two different instances of a Value 1695 class, denoted as Value1 and Value2; (C) uses the nomenclature 1696 foo.bar, where foo is the name of a class, and bar is the name of 1697 an attribute of that class. 1699 4.4.4. Creating SUPAPolicyClauses 1701 The GPIM defines a single subclass of SUPAPolicyClause, called 1702 SUPAEncodedClause. This clause is generic in nature, and MAY be 1703 used with any type of policy (ECA or otherwise). The EPRIM 1704 defines an ECA-specific subclass of the GPIM, called a 1705 SUPABooleanClause, which is intended to be used with just 1706 ECA policy rules; however, other uses are also possible. 1708 Together, the GPIM and EPRIM provide several alternatives to 1709 implement a SUPAPolicyClause, enabling the developer to 1710 optimize the solution for different constraints: 1712 1) The SUPAPolicyClause can be encoded using one or more 1713 SUPAEncodedClauses; a SUPAEncodedClause encodes the 1714 entire content of its respective event, condition, or 1715 action clause. 1716 2) The SUPAPolicyClause can be defined using one or more 1717 SUPABooleanClauses; each of the three clauses can be 1718 defined as either a single SUPABooleanClause, or a 1719 combination of SUPABooleanClauses that are logically 1720 ANDed, ORed, and/or NOTed. 1721 3) The above two mechanisms can be combined (e.g., the first 1722 used to define the event clause, and the second used to 1723 define the condition and action clauses). 1725 Figure 11 shows the subclasses of SUPAPolicyClause. 1727 A 1728 +------------------+ 1729 | SUPAPolicyClause | 1730 +--------+---------+ 1731 / \ 1732 I 1733 I 1734 I 1735 +---------------+-------------+ 1736 I I 1737 A I C I 1738 +--------+----------+ +----------+--------+ 1739 | SUPABooleanClause | | SUPAEncodedClause | 1740 +-------------------+ +-------------------+ 1742 Figure 11. Subclasses of SUPAPolicyClause 1744 SUPABooleanClause is defined in the EPRIM, and is used to 1745 construct Boolean clauses that collectively make up a 1746 SUPAPolicyClause. It is abstract, so that the composite pattern 1747 can be applied to it, which enables hierarchies of Boolean 1748 clauses to be created. SUPAEncodedClause (see section 6.7) is 1749 used to encode the content of a SUPAPolicyClause as an attribute 1750 (instead of reusable objects). 1752 4.4.5. SUPAPolicySources 1754 A SUPAPolicySource is a set of managed entities that authored, 1755 or are otherwise responsible for, this SUPAPolicy. Note that a 1756 SUPAPolicySource does NOT evaluate or execute SUPAPolicies. Its 1757 primary use is for auditability, authorization policies, and 1758 other applications of deontic and/or alethic logic. 1760 SUPAPolicyStructure defines four relationships. Two of these 1761 (SUPAHasPolicySource and SUPAHasPolicyTarget), which are both 1762 aggregations, relate a SUPAPolicyStructure to a SUPAPolicySource 1763 and a SUPAPolicyTarget, respectively. Since SUPAECAPolicyRule is 1764 a subclass of SUPAPolicyStructure, it (and its subclasses) inherit 1765 both of these aggregations. This enables SUPAPolicySources and/or 1766 SUPAPolicyTargets to be attached to SUPAECAPolicyRules (but NOT to 1767 components of a SUPAPolicy). 1769 Figure 12 shows how SUPAPolicySources and SUPAPolicyTargets are 1770 attached to a SUPAPolicy. Note that both of these aggregations 1771 are defined as optional, since their multiplicity is 0..n - 0..n. 1772 In addition, both of these aggregations are realized as 1773 association classes, in order to be able to control which 1774 SUPAPolicySources and SUPAPolicyTargets are attached to a given 1775 SUPAECAPolicyRule. 1777 A 1778 +------------------+ 1779 | SUPAPolicyObject | 1780 +--------+---------+ 1781 / \ 1782 I 1783 I 1784 I 1785 +--------------+-----+---------------------+ 1786 I I I 1787 A I C I C I 1788 +-----------+---------+ +-------+--------+ +--------+-------+ 1789 | SUPAPolicyStructure | |SUPAPolicySource| |SUPAPolicyTarget| 1790 +------+-------+------+ +----------+-----+ +----------+-----+ 1791 0..n / \ / \ 0..n 0..n / \ 0..n / \ 1792 A A | | 1793 \ / \ / | | 1794 | | | | 1795 | | | | 1796 | +--------------------+ | 1797 | SUPAHasPolicySource | 1798 | | 1799 +-------------------------------------------------+ 1800 SUPAHasPolicyTarget 1802 Figure 12. ECAPolicyRules, SUPAPolicySources, and PolicyTargets 1804 A SUPAPolicySource MAY be mapped to a role (e.g., using the 1805 role-object pattern [11]); this indirection makes the system less 1806 fragile, as entities can be transparently added or removed from 1807 the role definition without adversely affecting the definition of 1808 the SUPAPolicy. Note that SUPAPolicyRole is a subclass of 1809 SUPAPolicyMetadata. 1811 4.4.6. SUPAPolicyTargets 1813 A SUPAPolicyTarget defines the set of managed entities that a 1814 SUPAPolicy is applied to. This is useful for debugging, as well as 1815 when the nature of the application requires the set of managed 1816 entities affected by a Policy to be explicitly identified. This is 1817 determined by two conditions: 1819 1) The set of managed entities that are to be affected by the 1820 SUPAPolicy must all agree to play the role of a 1821 SUPAPolicyTarget. For example, a managed entity may not be 1822 in a state that enables SUPAPolicies to be applied to it; 1823 hence, in this case, it MUST NOT assume the role of ability 1824 SUPAPolicyTarget 1825 2) A SUPAPolicyTarget must be able to: 1826 a) process (either directly or with the aid of a proxy) 1827 SUPAPolicies, or 1828 b) receive the results of a processed SUPAPolicy and 1829 apply those results to itself. 1831 Figure 12 showed how SUPAPolicyTargets are attached to 1832 SUPAECAPolicyRules. 1834 A SUPAPolicyTarget MAY be mapped to a role (e.g., using the 1835 role-object pattern [11]); this indirection makes the system less 1836 fragile, as entities can be transparently added or removed from 1837 the role definition without adversely affecting the definition of 1838 the SUPAPolicy. Note that SUPAPolicyRole is a subclass of 1839 SUPAPolicyMetadata. 1841 4.4.7. Policy Metadata 1843 Metadata is, literally, data about data. As such, it can be 1844 descriptive or prescriptive in nature. 1846 4.4.7.1. Motivation 1848 There is a tendency in class design to make certain attributes, 1849 such as description, status, validFor, and so forth, bound to a 1850 specific class (e.g., [6]). This is bad practice in an information 1851 model. For example, different classes in different parts of the 1852 class hierarchy could require the use of any of these attributes; 1853 if one class is not a subclass of the other, then they must each 1854 define the same attribute as part of their class structure. This 1855 makes it difficult to find all instances of the attribute and 1856 ensure that they are synchronized. Furthermore, context can 1857 dynamically change the status of an object, so an easy way to 1858 update the status of one object instance without affecting other 1859 instances of the same object is required. 1861 Many models, such as [4] and [6], take a simplistic approach of 1862 defining a common attribute high in the hierarchy, and making it 1863 optional. This violates classification theory, and defeats the 1864 purpose of an information model, which is to specify the 1865 differences in characteristics and behavior between classes (as 1866 well as define how different classes are related to each other). 1867 Note that this also violates a number of well-known software 1868 architecture principles, including: 1870 o the Liskov Substitution Principle [13] 1871 (if A is a subclass of B, then objects instantiated from 1872 class B may be replaced with objects instantiated from 1873 class A WITHOUT ALTERING ANY OF THE PROGRAM SEMANTICS) 1874 o the Single Responsibility Principle [14] 1875 (every class should have responsibility over one, and only 1876 one, part of the functionality provided by the program) 1878 Most models use inheritance, not composition. The former is 1879 simpler, but has some well-known problems. One is called "weak 1880 encapsulaton", meaning that a subclass can use attributes and 1881 methods of a superclass, but if the superclass changes, the 1882 subclass may break. Another is that each time a new object is 1883 required, a new subclass must be created. These problems are 1884 present in [RFC3460], [4], and [6]. 1886 Composition is an alternative that provides code that is easier to 1887 use. This means that composition can provide data models that are 1888 more resistant to change and easier to use. By using composition, 1889 we can select just the metadata objects that are needed, instead 1890 of having to rely on statically defined objects. We can even 1891 create new objects from a set of existing objects through 1892 composition. Finally, we can use the decorator pattern to select 1893 just the attributes and behaviors that are required for a given 1894 instance. 1896 In [2] and [5], a separate metadata class hierarchy is defined to 1897 address this problem. This document follows this approach. 1899 4.4.7.2. Design Approach 1901 The goal of the GPIM is to enable metadata to be attached to any 1902 subclass of SUPAPolicyObject that requires it. Since this is a 1903 system intended for policy-based management, it therefore makes 1904 sense to be able to control which metadata is attached to which 1905 policies dynamically (i.e., at runtime). 1907 One solution is to use the Policy Pattern [1], [2], [6], [12]. 1908 This pattern was built to work with management systems whose 1909 actions were dependent upon context. The Policy Pattern works as 1910 follows: 1912 o Context is derived from all applicable system inputs (e.g., 1913 OAMP data from network elements, business goals, time of 1914 day, geo-location, etc.). 1915 o Context is then used to select a working set of Policies. 1916 o Policies are then used to define behavior at various 1917 control points in the system. 1918 o One simple type of control point is an association class. 1919 Since the association class represents the semantics of how 1920 two classes are related to each other, then 1921 o ECAPolicyRule actions can be used to change the attribute 1922 values, methods, and relationships of the association 1923 class 1924 o This has the affect of changing how the two classes are 1925 related to each other 1926 o Finally, as context changes, the working set of policies 1927 change, enabling the behavior to be adjusted to follow 1928 changes in context (according to appropriate business goals 1929 and other factors, of course) in a closed loop manner. 1931 Conceptually, this is accomplished as shown in Figure 13 below. 1933 Defines 1934 +----------+ Behavior +------------+ 1935 | Policies +----------------+ | SUPAPolicy | 1936 +----+-----+ 1..n | +------+-----+ 1937 0..n / \ | / \ 0..n 1938 | | A 1939 | | \ / 1940 | 1..n \ / | 1941 | +-----------+--------------+ | 1942 | | SUPAPolicyMetadataDetail | | 1943 | +-----------+--------------+ | 1944 | | | 1945 | Selects | | 1946 | Policies | | 1947 | | | 1948 | +-------------------->+ 1949 | Applies | 1950 / \ Behavior | 1951 A | 1952 0..n \ / \ / 0..n 1953 +----+-----+ +--------+---------+ 1954 | Context | |SUPAPolicyMetadata| 1955 +----------+ +------------------+ 1957 Figure 13. Context-Aware Policy Rules 1959 4.4.7.2.1. Policies and Actors 1961 The Policy Continuum ([1] [5] [10] [12]) was defined to associate 1962 different actors with different policies at different levels of 1963 business and/or technical specificity. Context-aware policy rules, 1964 and the Policy Pattern, were defined to realize this association. 1966 Four important functions related to the lifecycle of policies are 1967 design, implementation, deployment, and execution. There are many 1968 different possible definitions of these functions (even for policy 1969 lifecycle management); however, for the purposes of this document, 1970 they are defined as follows: 1972 o Design: The process of defining a software architecture 1973 to satisfy user requirements. 1974 o Development: the process of documenting, programming, 1975 testing, and maintaining code and applications 1976 as part of a software product 1977 o Deployment: the process that assembles and transfers 1978 completed software artifacts to a state that 1979 enables their execution 1980 o Execution: the process of installing, activating, running, 1981 and subsequently deactivating executable 1982 software products 1984 The design process is responsible for producing a software 1985 architecture. This emphasizes the design, as opposed to the 1986 programming, of software systems. In contrast to design, 1987 development emphasizes constructing software artifacts via coding 1988 and documentation. 1990 Deployment may be described as the process of releasing software. 1991 It includes all of the operations required to assemble a completed 1992 software product. It typically also includes the process of 1993 preparing a software product for execution (e.g., assembling a set 1994 of software products into a larger product, determining if the 1995 consumer site has appropriate resources to install and execute the 1996 software product, and collecting information on the feasbility of 1997 using the software product). This contrasts with the execution 1998 process, which is the set of processes that follow deployment. 2000 In summary, exemplar states in the policy lifecycle process 2001 include: 2003 o Design: determining how the policy-based management 2004 system will operate 2005 o Development: documenting, programming, testing, and 2006 maintaining policies and policy components 2007 o Deployment: assembling the components of a policy-based 2008 management system 2009 o Execution: installing, enabling, running, disabling, 2010 and uninstalling policies and policy components 2012 4.4.7.2.2. Deployment vs. Execution of Policies 2014 One of the primary reasons for separating the deployment and 2015 execution processes is to differentiate between environments that 2016 are not ready to execute policies (i.e., deployment) and 2017 environments that are ready to execute policies (i.e., execution). 2018 This is an important consideration, since policies that are 2019 related to the same set of tasks may be deployed in many different 2020 places (e.g., in a policy system vs. in a network device). In 2021 addition, each managed entity in the set of SUPAPolicyTargets may 2022 or may not be in a state that allows SUPAPolicies to be applied to 2023 it (see section 4.4.6.). 2025 Hence, this design includes dedicated class attributes for 2026 getting and setting the deployment and execution status, as well 2027 as enabling and disabling, SUPAPolicies (see section 5.3.1.). 2029 4.4.7.2.3. Using SUPAMetadata for Policy Deployment and Execution 2031 One way of encoding deployment and execution status for policies 2032 and policy components is to attach Metadata objects to affected 2033 SUPAPolicyStructure and SUPAPolicyComponentStructure objects. 2034 This provides an extensible and efficient means to describe 2035 and/or prescribe deployment and/or execution status of a policy 2036 or a policy component. It is extensible, since classes and 2037 relationships can be used, as opposed to a set of attributes. It 2038 is efficient, because the decorator pattern (see section 5.7) is 2039 used (this enables attributes and/or methods of objects, or the 2040 entire object, to be used to add characteristics and/or behavior 2041 to a given object. 2043 SUPAPolicyMetadata objects (see sections 5.16 - 5.20) may be 2044 attached to the SUPAECAPolicyRule and/or any of its components 2045 to define additional semantics of the SUPAECAPolicyRule. For 2046 example, SUPAAccessMetadataDef (see section 5.19) and/or 2047 SUPAVersionMetadataDef (see section 5.20) may be attached to 2048 define the access privileges and version information, 2049 respectively, of a policy rule and/or its components. 2051 The SUPAPolicyStructure contains two attributes, 2052 supaPolDeployStatus and supaPolExecStatus (see sections 5.3.1.3. 2053 and 5.3.1.4., respectively) that SUPAPolicyMetadata objects can 2054 use to get and set the deployment and execution status of a 2055 SUPAPolicy. This allows metadata to be used to alter the 2056 deployment and/or execution state of a policy (or a set of 2057 policy components) without having to affect other parts of the 2058 policy-based management system. The supaPolDeployStatus attribute 2059 indicates that this SUPAPolicy can or cannot be deployed. If it 2060 cannot be deployed. Similarly, the supaPolExecStatus attribute 2061 is used to indicate if a particular SUPAPolicy has executed, is 2062 currently executing, or is ready to execute, and whether or not 2063 the execution of that SUPAPolicy had any failures. 2065 The reverse is also true (and hence, forms a closed-loop system 2066 controlled by metadata). For example, if the set of deployed 2067 SUPAPolicies are SUPAECAPolicyRules, then when the actions of 2068 these SUPAECAPolicyRules are executed, the overall context has 2069 changed (see section 4.4.7.2). The context manager could then 2070 change attribute values (directly or indirectly) in the 2071 SUPAPolicyMetadataDetail association class. This class represents 2072 the behavior of the SUPAHasPolicyMetadata aggregation, which is 2073 used to define which SUPAPolicyMetadata can be attached to which 2074 SUPAPolicy objet in this particular context. For example, the 2075 access privileges of a policy and/or policy component could be 2076 changed dynamically, according to changes in context. 2078 By using the decorator pattern on SUPAPolicyMetadata, any number 2079 of SUPAPolicyMetadata objects (or their attributes, etc.) can be 2080 wrapped around a concrete subclass of SUPAPolicyMetadata. This is 2081 shown in Figure 14 below. 2083 4.4.7.3. Structure of SUPAPolicyMetadata 2085 SUPAPolicyMetadata also uses the decorator pattern to provide an 2086 extensible framework for defining metadata to attach to SUPAPolicy 2087 subclasses. Its two principal subclasses are 2088 SUPAPolicyConcreteMetadata and SUPAPolicyMetadataDecorator. The 2089 former is used to define concrete subclasses of SUPAPolicyMetadata 2090 that are attached at runtime to SUPAPolicy subclasses, while the 2091 latter is used to define concrete objects that represent reusable 2092 attributes, methods, and relationships that can be added to 2093 subclasses of SUPAPolicyConcreteMetadata. 2095 For example, concepts like identification, access control, and 2096 version information are too complex to represent as a single 2097 attribute, or even a couple of attributes - they require the 2098 generic power of objects to represent their characteristics and 2099 behavior. Furthermore, defining concrete classes to represent 2100 these concepts in the policy hierarchy is fragile, because: 2102 1. not all objects that use these concepts need all of the 2103 information represented by them (e.g., two subclasses of an 2104 Identification Object may be Passport and Certificate, but 2105 these two objects are rarely used together, and even those 2106 contexts that use one of these classes may not need all of 2107 the data in that class) 2108 2. defining a class means defining its attributes, methods, and 2109 relationships at a particular place in the hierarchy; this 2110 means that defining a relationship between a class A and 2111 another class B SHOULD only be done if all of the subclasses 2112 of B can use the attributes, methods, and relationships of A 2113 (e.g., in the above example, defining a relationship between 2114 an Identification Object and a superclass of a router class 2115 is not appropriate, since routers do not use Passports) 2117 A 2118 +------------------+ 2119 | SUPAPolicyObject | 2120 +--------+---------+ 2121 / \ 0..n 2122 A 2123 \ / 2124 | A 2125 | 0..n +--------------------+ 2126 | SUPAHasPolicyMetadata \| | 2127 +-------------+-----------------+ SUPAPolicyMetadata | 2128 ^ /| | 2129 | +------+------+------+ 2130 A | / \ | 1..n 2131 +-------------+---------------+ I | 2132 1..n | | I | 2133 +----------+ SUPAHasPolicyMetadataDetail | I | 2134 | | | I | 2135 | +-----------------------------+ I | 2136 | I | 2137 | (gets/sets values of attributes and/or I | 2138 | methods of the SUPAHasPolicyMetadataDetail I | 2139 | class; this affects which SUPAPolicyMetadata I | 2140 | objects can be attached to which policies I | 2141 | and policy components) I | 2142 | I | 2143 | C I | 2144 | +----------------------------+ I | 2145 | | | I | 2146 +----------+ SUPAPolicyConcreteMetadata +IIIIIIIII+ | 2147 | | I | 2148 +----------------------------+ I | 2149 I | 2150 A I | 2151 +-----------------------------+ I | 2152 | | I | 2153 | SUPAPolicyMetadataDecorator +IIIIIIIII+ | 2154 | | | 2155 +-------+--------------+------+ | 2156 / \ / \ 0..1 | 2157 I A | 2158 I \ / | 2159 I | | 2160 subclasses for adding | | 2161 behavior to policies +-----------------------+ 2162 and policy components PolicyObjectHasMetadata 2164 Figure 14. SUPAPolicyMetadata Subclasses and Relationships 2166 Since a class encapsulates attributes, methods, and behavior, 2167 defining the Identification Object in the above example as a type 2168 of SUPAPolicyMetadata object enables the decorator pattern to be 2169 used to attach all or part of that object to other objects that 2170 need it. 2172 Figure 15 shows a portion of the SUPAPolicyMetadata hierarchy. 2174 A 2175 +--------------------+ 2176 | | HasSUPAMetadataDecorator 2177 | SUPAPolicyMetadata +-------------------+ 2178 | | 1..n | 2179 +---------+----------+ | 2180 I | 2181 I | 2182 I | 2183 +-------------+-----------------+ | 2184 | | | 2185 C | | / \ 2186 +---------+------------------+ | A 2187 | SUPAPolicyConcreteMetadata | A | 0..1 \ / 2188 +----------------------------+ +--------+------------+-------+ 2189 | SUPAPolicyMetadataDecorator | 2190 +------------+----------------+ 2191 I 2192 +------------------------------+--------+ 2193 I I 2194 I I 2195 C I C I 2196 +---------------+-------------+ +---------------------+--------+ 2197 | SUPAPolicyAccessMetadataDef | | SUPAPolicyVersionMetadataDef | 2198 +-----------------------------+ +------------------------------+ 2200 Figure 15. SUPAPolicyMetadata Subclasses and Relationships 2202 Figure 15 shows a relevant portion of the SUPAPolicyMetadata 2203 hierarchy. SUPAPolicyConcreteMetadata is a concrete class that 2204 subclasses of the SUPAPolicyMetadataDecorator class can wrap. 2205 Two such subclasses, SUPAPolicyAccessMetadataDef and 2206 SUPAPolicyVersionMetadataDef, are shown in Figure 15. This 2207 enables access control and version information to be added 2208 statically (at design time) or dynamically (at runtime) to 2209 SUPAPolicyConcreteMetadata; this enables metadata-driven systems 2210 to adjust the behavior of the management system to changes in 2211 context, business rules, services given to end-users, and other 2212 similar factors. This is discussed more in sections 5.18 - 5.20. 2214 4.5. Advanced Features 2216 This section will be completed in the next revision of this 2217 document. 2219 4.5.1. Policy Grouping 2221 This section will be completed in the next revision of this 2222 document. 2224 4.5.2. Policy Rule Nesting 2226 This section will be completed in the next revision of this 2227 document. 2229 5. GPIM Model 2230 This section defines the classes, attributes, and relationships of 2231 the GPIM. 2233 5.1. Overview 2234 The overall class hierarchy is shown in Figure 16; section numbers 2235 are appended after each class. 2237 (Class of another model that SUPA is integrating into) 2238 | 2239 +---SUPAPolicyObject (5.2) 2240 | | 2241 | +---SUPAPolicyStructure (5.3) 2242 | | 2243 | +---SUPAPolicyComponentStructure (5.4) 2244 | | | 2245 | | +---SUPAPolicyClause (5.5) 2246 | | | | 2247 | | | +---SUPAEncodedClause (5.6) 2248 | | | 2249 | | +---SUPAPolicyComponentDecorator (5.7) 2250 | | | 2251 | | +---SUPAPolicyTerm (5.8) 2252 | | | | 2253 | | | +---SUPAPolicyVariable (5.9) 2254 | | | | 2255 | | | +---SUPAPolicyOperator (5.10) 2256 | | | | 2257 | | | +---SUPAPolicyValue (5.11) 2258 | | | 2259 | | +---SUPAGenericDecoratedComponent (5.12) 2260 | | | 2261 | | +---SUPAPolicyCollection (5.13) 2262 | | 2263 | +---SUPAPolicySource (5.14) 2264 | | 2265 | +---SUPAPolicyTarget (5.15) 2266 | 2267 +---SUPAPolicyMetadata (5.16) 2268 | 2269 +---SUPAPolicyConcreteMetadata (5.17) 2270 | 2271 +---SUPAPolicyMetadataDecorator (5.18) 2272 | 2273 +---SUPAPolicyAccessMetadataDef (5.19) 2274 | 2275 +---SUPAPolicyVersionMetadataDef (5.20) 2277 Figure 16: Main Classes of the GPIM 2279 SUPAPolicy is the root of the SUPA class hierarchy. For 2280 implementations, it is assumed that SUPAPolicy is subclassed from 2281 a class from another model. 2283 Classes, attributes, and relationships that are marked as 2284 "mandatory" MUST be part of a conformant implementation (i.e., a 2285 schema MUST contain these entities). This does not mean that these 2286 entities must be instantiated; rather it means that they must be 2287 able to be instantiated. Classes, attributes, and relationships 2288 that are marked as "optional" MAY be part of a conformant 2289 implementation. 2291 Unless otherwise stated, all classes (and attributes) defined in 2292 this section were abstracted from DEN-ng [2], and a version of 2293 them are in the process of being added to [5]. However, the work 2294 in [5] has been put on hold, and the names of many of the classes, 2295 attributes, and relationships are slightly different. 2297 5.2. The Abstract Class "SUPAPolicyObject" 2299 This is a mandatory abstract class. Figure 17 shows the 2300 SUPAPolicyObject class, and its four subclasses. 2302 A 0..n 0..n A 2303 +----------------+/ \ \+------------------+ 2304 |SUPAPolicyObject+ A ------------------------+SUPAPolicyMetadata| 2305 +--------+-------+\ / SUPAHasPolicyMetadata /+------------------+ 2306 / \ 2307 I 2308 I 2309 +-----------------+----------------+-----------+ 2310 I I I I 2311 A I I I I 2312 +--------+------------+ I I I 2313 | SUPAPolicyStructure | I I I 2314 +---------------------+ I I I 2315 A I I I 2316 +-----------------+------------+ I I 2317 | SUPAPolicyComponentStructure | I I 2318 +------------------------------+ I I 2319 C I I 2320 +---------+--------+ I 2321 | SUPAPolicyTarget | I 2322 +------------------+ I 2323 C I 2324 +----------+-------+ 2325 | SUPAPolicySource | 2326 +------------------+ 2328 Figure 17. SUPAPolicyObject and Its Subclasses 2330 This class is the root of the SUPA class hierarchy. It defines the 2331 common attributes and relationships that all SUPA subclasses 2332 inherit. 2334 A SUPAPolicyObject MAY be qualified by a set of zero or more 2335 SUPAPolicyMetadata objects. This is provided by the 2336 SUPAHasPolicyMetadata aggregation (see Section 5.2.2). This 2337 enables the semantics of the SUPAPolicyObject to be more 2338 completely specified. 2340 5.2.1. SUPAPolicyObject Attributes 2342 This section defines the attributes of the SUPAPolicyObject class. 2343 These attributes are inherited by all subclasses of the GPIM 2344 except for the SUPAPolicyMetadata class, which is a sibling class. 2346 5.2.1.1. Object Identifiers 2348 This document defines two class attributes in SUPAPolicyObject, 2349 called supaPolObjIDContent and supaPolObjIDEncoding, that together 2350 define a unique object ID. This enables all class instances to be 2351 uniquely identified. 2353 One of the goals of SUPA is to be able to generate different data 2354 models that support different types of protocols and repositories. 2355 This means that the notion of an object ID must be generic. It is 2356 inappropriate to use data modeling concepts, such as keys, GUIDs, 2357 UUIDs, FQDNs, URIs, and other similar mechanisms, to define the 2358 structure of an information model. Therefore, a synthetic object 2359 ID is defined using these two attributes. This can be used to 2360 facilitate mapping to different data model object schemes, such 2361 as those depending on URIs, FQDNs, UUIDs, primary key-foreign key 2362 relationships, UUIDs, and others can all be accommodated. 2364 The two attributes work together, with the supaPolObjIDContent 2365 attribute defining the content of the object ID and the 2366 supaPolObjIDEncoding attribute defining how to interpret the 2367 content. These two attributes form a tuple, and together enable 2368 a machine to understand the syntax and value of an object 2369 identifier for the object instance of this class. 2371 Similarly, all SUPA classes are attributes are both uniquely 2372 named as well as prepended with the prefixes "SUPA" and "supa", 2373 respectively, to facilitate model integration. 2375 5.2.1.2. The Attribute "supaPolObjIDContent" 2377 This is a mandatory string attribute that represents part of the 2378 object identifier of an instance of this class. It defines the 2379 content of the object identifier. It works with another class 2380 attribute, called supaPolObjIDEncoding, which defines how to 2381 interpret this attribute. These two attributes form a tuple, 2382 and together enable a machine to understand the syntax and value 2383 of an object identifier for the object instance of this class. 2384 This is based on the DEN-ng class design [2]. 2386 5.2.1.3. The Attribute "supaPolObjIDEncoding" 2388 This is a mandatory non-zero enumerated integer attribute that 2389 represents part of the object identifier of an instance of this 2390 class. It defines the format of the object identifier. It works 2391 with another class attribute, called supaPolObjIDContent, which 2392 defines the content of the object ID. These two attributes form 2393 a tuple, and together enable a machine to understand the syntax 2394 and value of an object identifier for the object instance of 2395 this class. The supaPolObjIDEncoding attribute is mapped to the 2396 following values: 2398 0: undefined 2399 1: GUID 2400 2: UUID 2401 3: primary key 2402 4: foreign key 2403 5: URI 2404 6: FQDN 2406 The value 0 may be used to initialize the system, or to signal 2407 that there is a problem with this particular SUPAPolicyObject. 2409 5.2.1.4. The Attribute "supaPolicyDescription" 2411 This is an optional string attribute that defines a free-form 2412 textual description of this object. 2414 5.2.1.5. The Attribute "supaPolicyName" 2416 This is an optional string attribute that defines the name of this 2417 Policy. This enables any existing generic naming attribute to be 2418 used for generic naming, while allowing this attribute to be used 2419 to name Policy entities in a common manner. Note that this is NOT 2420 the same as the commonName attribute of the Policy class defined 2421 in [RFC3060], as that attribute is intended to be used with just 2422 X.500 cn attributes. 2424 5.2.2. SUPAPolicyObject Relationships 2426 The SUPAPolicyObject class currently defines a single relationship, 2427 as defined in the subsections below. 2429 5.2.2.1. The Aggregation "SUPAHasPolicyMetadata" 2431 This is a mandatory aggregation that defines the set of 2432 SUPAPolicyMetadata that are aggregated by this particular 2433 SUPAPolicyObject. This aggregation is defined in section 2434 5.16.2. 2436 5.2.2.2. The Association Class "SUPAHasPolicyMetadataDetail" 2438 This is a mandatory concrete association class that defines the 2439 semantics of the SUPAPolicyMetadata aggregation. This enables the 2440 attributes and relationships of the SUPAPolicyMetadataDetail class 2441 to be used to constrain which SUPAPolicyMetadata objects can be 2442 aggregated by this particular SUPAPolicyObject instance. This 2443 association class is defined in Section 5.16.3. 2445 5.3. The Abstract Class "SUPAPolicyStructure" 2447 This is a mandatory abstract class that is used to represent the 2448 structure of a SUPAPolicy. This class (and all of its subclasses) 2449 is a type of PolicyContainer. SUPAPolicyStructure was abstracted 2450 from DEN-ng [2], and a version of this class is in the process of 2451 being added to [5]. However, the version in [5] differs 2452 significantly. First, the class and relationship definitions ared 2453 different. Second, [5] uses the composite pattern. Neither of 2454 these are implemented in this document because of optimizations 2455 done to the SUPA class hierarchy that are NOT present in [5]. 2457 For this release, the only official type of policy that is 2458 supported is the event-condition-action (ECA) type of policy rule. 2459 However, the structure of the SUPA hierarchy is defined to 2460 facilitate adding new types of rules later. 2462 A SUPAPolicy may take the form of an individual policy or a set 2463 of policies. This requirement is supported by applying the 2464 composite pattern to subclasses of the SUPAPolicyStructure class, 2465 as shown in Figure 5. In this document, this is done for the 2466 SUPAECAPolicyRule subclass, and results in two subclasses: 2467 SUPAECAPolicyRuleAtomic (for defining stand-alone policies) and 2468 SUPAECAPolicyRuleComposite (for defining hierarchies of policies). 2470 Note that there is no need for a "match strategy attribute" that 2471 some models [RFC3460], [4], [6] have; this is because the 2472 SUPAPolicyStructure class is used just for containment. Hence, the 2473 containers themselves serve as the scoping component for nested 2474 policies. 2476 5.3.1. SUPAPolicyStructure Attributes 2478 The following subsections define the attributes of the 2479 SUPAPolicyStructure class. 2481 The SUPAPolicyStructure class has a number of attributes that have 2482 no counterpart in the SUPAPolicyComponentStructure class. This is 2483 because these attributes are only appropriate at the level of a 2484 policy rule, not at the level of a policy component. 2486 Care must be taken in adding attributes to this class, 2487 because the behavior of future subclasses of this class (e.g., 2488 declarative and functional policies) is very different than the 2489 behavior of SUPAECAPolicyRules. 2491 5.3.1.1. The Attribute "supaPolAdminStatus" 2493 This is an optional attribute, which is an enumerated non-negative 2494 integer. It defines the current administrative status of this 2495 SUPAPolicyClause. 2497 This attribute can be used to place this particular 2498 SUPAPolicyStructure object instance into a specific administrative 2499 state, such as enabled, disabled, or in test. Values include: 2501 0: Unknown (an error state) 2502 1: Enabled 2503 2: Disabled 2504 3: In Test (i.e., no operational traffic can be passed) 2506 Value 0 denotes an error that prevents this SUPAPolicyStructure 2507 from being used. Values 1 and 2 mean that this SUPAPolicyStructure 2508 is administratively enabled or disabled, respectively. A value of 2509 3 means that this SUPAPolicyStructure is in a special test mode 2510 and SHOULD NOT be used as part of an OAM&P policy. 2512 5.3.1.2. The Attribute "supaPolContinuumLevel" 2514 This is an optional non-negative integer attribute. It defines 2515 the level of abstraction, or policy continuum level [10], of this 2516 particular SUPAPolicy. The value assignment of this class is 2517 dependent on the application; however, it is recommended that 2518 for consistency with other SUPA attributes, the value of 0 is 2519 reserved for initialization and/or error conditions. 2521 By convention, lower values represent more abstract levels of the 2522 policy continuum. For example, a value of 1 could represent 2523 business policy, a value of 2 could represent application-specific 2524 policies, and a value of 3 could represent low=level policies for 2525 network administrators. 2527 5.3.1.3. The Attribute "supaPolDeployStatus" 2529 This is an optional enumerated, non-negative integer attribute. The 2530 purpose of this attribute is to indicate that this SUPAPolicy can 2531 or cannot be deployed by the policy management system. This 2532 attribute enables the policy manager to know which SUPAPolicies to 2533 retrieve, and may be useful for the policy execution system for 2534 planning the staging of SUPAPolicies. Values include: 2536 0: undefined 2537 1: deployed and enabled 2538 2: deployed and in test 2539 3: deployed but not enabled 2540 4: ready to be deployed 2541 5: cannot be deployed 2543 If the value of this attribute is 0 or 5, then the policy 2544 management system SHOULD ignore this SUPAPolicy. Otherwise, the 2545 policy management MAY use this SUPAPolicy. 2547 5.3.1.4. The Attribute "supaPolExecStatus" 2549 This is an optional attribute, which is an enumerated, 2550 non-negative integer. It defines the current execution status 2551 of this SUPAPolicy. Values include: 2553 0: undefined 2554 1: executed and SUCCEEDED (operational mode) 2555 2: executed and FAILED (operational mode) 2556 3: currently executing (operational mode) 2557 4: ready to execute (operational mode) 2558 5: executed and SUCCEEDED (test mode) 2559 6: executed and FAILED (test mode) 2560 7: currently executing (test mode) 2561 8: ready to execute (test mode) 2563 5.3.1.5. The Attribute "supaPolExecFailStrategy" 2565 This is an optional non-negative, enumerated integer that defines 2566 what actions, if any, should be taken by this 2567 SUPAPolicyStructure object if it fails to execute correctly. 2569 Note that some systems may not be able to support all options 2570 specified in this enumeration. If rollback is supported by the 2571 system, then option 2 may be skipped. Options 3 and 4 can be used 2572 by systems that do and do not support rollback. Values include: 2574 0: undefined 2575 1: attempt rollback of all actions taken and stop execution 2576 2: attempt rollback of only the action that failed and stop 2577 execution 2578 3: stop execution but do not rollback any actions 2579 4: ignore failure and continue execution 2581 A value of 0 can be used as an error condition. A value of 1 means 2582 that ALL execution is stopped, rollback of all actions (whether 2583 successful or not) is attempted, and that SUPAPolicies that 2584 otherwise would have been executed are ignored. A value of 2 means 2585 that execution is stopped, and rollback is attempted for ONLY the 2586 SUPAPolicy that failed to execute correctly. 2588 5.3.2. SUPAPolicyStructure Relationships 2590 The SUPAPolicyStructure class owns four relationships, which are 2591 defined in the following subsections. 2593 5.3.2.1. The Aggregation "SUPAHasPolicySource" 2595 This is an optional aggregation, and defines the set of 2596 SUPAPolicySource objects that are attached to this particular 2597 SUPAPolicyStructure object. The semantics of this aggregation 2598 are defined by the SUPAHasPolicySourceDetail association class. 2599 PolicySource objects are used for authorization policies, as well 2600 as to enforce deontic and alethic logic. 2602 The multiplicity of this aggregation is 0..n - 0..n. This means 2603 that it is an optional aggregation; zero or more SUPAPolicySource 2604 objects may be aggregated by this SUPAPolicyStructure object, 2605 and zero or more SUPAPolicyStructure objects may aggregate this 2606 particular SUPAPolicySource object. 2608 5.3.2.2. The Association Class "SUPAHasPolicySourceDetail" 2610 This is an optional association class, and defines the semantics 2611 of the SUPAHasPolicySource aggregation. The attributes and 2612 relationships of this class can be used to define which 2613 SUPAPolicySource objects can be attached to which particular set 2614 of SUPAPolicyStructure objects. 2616 5.3.2.2.1. The Attribute "supaPolSrcIsAuthenticated" 2618 This is an optional Boolean attribute. If the value of this 2619 attribute is true, then this SUPAPolicySource object has been 2620 authenticated by this particular SUPAPolicyStructure object. 2622 5.3.2.2.2. The Attribute "supaPolSrcIsTrusted" 2624 This is an optional Boolean attribute. If the value of this 2625 attribute is TRUE, then this particular SUPAPolicySource object 2626 has been verified to be trusted by this particular 2627 SUPAPolicyStructure object. 2629 5.3.2.3. The Aggregation "SUPAHasPolicyTarget" 2631 This is an optional aggregation, and defines the set of 2632 SUPAPolicyTargets that are attached to this particular 2633 SUPAPolicyStructure. The semantics of this aggregation is 2634 defined by the SUPAHasPolicyTargetDetail association class. The 2635 purpose of this class is to explicitly identify managed objects 2636 that will be affected by the execution of one or more SUPAPolicies. 2638 The multiplicity of this aggregation is 0..n - 0..n. This means 2639 that it is an optional aggregation; zero or more SUPAPolicyTarget 2640 objects may be aggregated by this SUPAPolicyStructure object, 2641 and zero or more SUPAPolicyStructure objects may aggregate this 2642 particular SUPAPolicyTarget object. 2644 5.3.2.4. The Association Class "SUPAHasPolicyTargetDetail" 2646 This is an optional association class, and defines the semantics 2647 of the SUPAPolicyTargetOf aggregation. The attributes and 2648 relationships of this class can be used to define which 2649 SUPAPolicyTargets can be attached to which particular set of 2650 SUPAPolicyStructure objects. 2652 5.3.2.4.1. The Attribute "supaPolTgtIsAuthenticated" 2654 This is an optional Boolean attribute. If the value of this 2655 attribute is true, then this SUPAPolicyTarget object has been 2656 authenticated by this particular SUPAPolicyStructure object. 2658 5.3.2.4.2. The Attribute "supaPolTgtIsEnabled" 2660 This is an optional Boolean attribute. If its value is TRUE, then 2661 this SUPAPolicyTarget is able to be used as a SUPAPolicyTarget. 2662 This means that it meets two specific criteria: 2664 1. it has agreed to play the role of a SUPAPolicyTarget (i.e., 2665 it is willing to have SUPAPolicies applied to it, and 2666 2. it is able to either process (directly or with the aid of 2667 a proxy) SUPAPolicies or receive the results of a processed 2668 SUPAPolicy and apply those results to itself. 2670 5.3.2.5. The Association "SUPAHasPolExecFailTakeAction" 2672 This is an optional association that defines which, if any, actions 2673 should be taken if this SUPAPolicyStructure object instance fails 2674 to execute correctly. The semantics of this association are defined 2675 in the SUPAHasPolExecFailTakeActionDetail association class. 2677 For a given SUPAPolicyStructure object A, this association defines 2678 a set of policy action objects B to execute if (and only if) the 2679 SUPAPolicyStructure object A failed to execute correctly. The 2680 multiplicity of this association is defined as 0..n on the owner 2681 (A) side and 1..n on the part (B) side. This means that this 2682 association is optional; if it is instantiated, then at least one 2683 SUPAPolicyStructure MUST be instantiated by this 2684 SUPAPolicyStructure object. Similarly, one or more 2685 SUPAPolicyStructure objects may be associated with this given 2686 SUPAPolicyStructure object. 2688 5.3.2.6. The Association Class "SUPAHasPolExecFailTakeActionDetail" 2690 This is an optional concrete class that defines the semantics for 2691 the SUPAHasPolExecFailTakeAction association. The attributes and/or 2692 relationships of this association class can be used to determine 2693 which policy action objects are executed in response to a failure 2694 of the SUPAPolicyStructure object instance that owns this 2695 association. The association relates the policy actions from one 2696 SUPAPolicyStructure B to be executed if a SUPAPolicyStructure A 2697 fails to execute properly. Figure 18 illustrates this approach. 2699 A 2700 +---------------------------+ 0..n 2701 | +---------------------------------+ 2702 | | SUPAHasPolExecFailTakeAction | 2703 | SUPAPolicyStructure |/ | 2704 | + --------------+-----------------+ 2705 | |\ ^ 2706 +---------------------------+ 1..n | 2707 | 2708 C | 2709 +------------------+-----------------+ 2710 | SUPAHasPolExecFailTakeActionDetail | 2711 +------------------------------------+ 2713 Figure 18. SUPAHasPolExecFailTakeAction Association 2715 5.3.2.6.1. The Attribute "supaPolExecFailTakeActionEncoding" 2717 This is an optional enumerated, non-negative integer attribute 2718 that defines how to find the set of SUPAPolicyActions contained 2719 in each element of the supaPolExecFailTakeActionName class 2720 attribute. Values include: 2722 0: undefined 2723 1: String 2724 2: GUID 2725 3: UUID 2726 4: URI 2727 5: FQDN 2729 5.3.2.6.2. The Attribute "supaPolExecFailTakeActionName[1..n]" 2731 This is an optional array of string attributes that identifies the 2732 set of policy actions to take if the SUPAPolicyStructure object 2733 that owns this association failed to execute properly. The 2734 interpretation of this string attribute is defined by the 2735 supaPolExecFailTakeActionEncoding class attribute. The association 2736 defines the SUPAPolicyStructure that contains the set of policy 2737 actions to execute, and this attribute defines which of these 2738 actions are to be executed. Note that there is no need to execute 2739 a SUPAPolicy, since the event and failure have already occurred. 2740 Note: [1..n] means that this is a multi-valued property that has 2741 at least one (and possibly more) attributes. 2743 5.3.2.7. The Aggregation "SUPAHasPolicyClause" 2745 This is an optional aggregation that defines the set of 2746 SUPAPolicyClauses that are aggregated by this particular 2747 SUPAPolicyStructure instance. The semantics of this 2748 aggregation are defined by the SUPAHasPolicyClauseDetail 2749 association class. 2751 Every SUPAPolicyStructure object instance MUST aggregate at 2752 least one SUPAPolicyClause object instance. However, the 2753 converse is NOT true. For example, a SUPAPolicyClause could be 2754 instantiated and then stored for later use in a policy repository. 2755 Furthermore, the same SUPAPolicyClause could be used by zero or 2756 more SUPAPolicyStructure object instances at a given time. Thus, 2757 the multiplicity of this aggregation is defined as 0..1 on the 2758 aggregate (i.e., the SUPAPolicyStructure side) and 1..n on the 2759 part (i.e., the SUPAPolicyClause side). This means that at 2760 least one SUPAPolicyClause MUST be aggregated by this 2761 SUPAPolicyStructure object. Similarly, a SUPAPolicyClause may 2762 be aggregated by this particular SUPAPolicyStructure object. 2764 5.3.2.8. The Association Class "SUPAHasPolicyClauseDetail" 2766 This is an optional association class, and defines the semantics 2767 of the SUPAHasPolicyClause aggregation. The attributes and/or 2768 relationships of this association class can be used to determine 2769 which SUPAPolicyClauses are aggregated by which 2770 SUPAPolicyStructure objects. 2772 Attributes will be added to this class at a later time. 2774 5.4. The Abstract Class "SUPAPolicyComponentStructure" 2776 This is a mandatory abstract class that is the superclass of all 2777 objects that represent different types of components of a 2778 SUPAPolicy. Different types of policies have different types of 2779 structural components. However, all of these are used in at least 2780 one type of policy. This class represents a convenient control 2781 point for defining characteristics and behavior that are common 2782 to objects that serve as components of a policy. 2784 Note that there are significant differences between the definition 2785 of this class, and its attributes, and the definition of the 2786 corresponding class (and its attributes) in [5]. 2788 5.4.1. SUPAPolicyComponentStructure Attributes 2790 No attributes are currently defined for the 2791 SUPAPolicyComponentStructure class. 2793 5.4.2. SUPAPolicyComponentStructure Relationships 2795 SUPAPolicyComponentStructure participates in a single relationship, 2796 SUPAHasDecoratedPolicyComponent, as defined in section 5.7.3. 2798 5.5. The Abstract Class "SUPAPolicyClause" 2800 This is a mandatory abstract class that separates the 2801 representation of a SUPAPolicy from its implementation. 2802 SUPAPolicyClause was abstracted from DEN-ng [2]. This abstraction 2803 is missing in [RFC3060], [RFC3460], [4], and [6]. This class is 2804 called PolicyStatement in [5], but the class and relationship 2805 definitions differ significantly from the corresponding designs 2806 in this document. 2808 A SUPAPolicyClause contains an individual or group of related 2809 functions that are used to define the content of a policy. More 2810 specifically, since the number and type of functions that make up 2811 a SUPAPolicyClause can vary, the decorator pattern is used, so 2812 that the contents of a SUPAPolicyClause can be adjusted 2813 dynamically at runtime without affecting other objects. 2815 This document defines two different types of policy clauses: 2816 SUPAEncodedClause (which is generic, and can be used by any 2817 type of policy), and SUPABooleanClause (which is also generic, 2818 but is typically used by SUPAECAPolicyRule objects). 2820 SUPAPolicyClauses are objects in their own right, which 2821 facilitates their reuse. SUPAPolicyClauses can aggregate a set 2822 of any of the subclasses of SUPAPolicyComponentDecorator, which 2823 was shown in Figure 10. These four subclasses provide four 2824 different ways to construct a SUPAPolicyClause: 2826 1) SUPAPolicyTerm, which enables constructing a {variable, 2827 operator, value} expression for building DUPAPolicyClauses 2828 2) SUPAEncodedClause, which enables policy clauses to be 2829 formed as an encoded object (e.g., to pass YANG or CLI code) 2830 3) SUPAPolicyCollection, which defines a collection of objects 2831 that requires further processing by the policy management 2832 system in order to be made into a SUPAPolicyClause 2833 4) SUPAECAComponent, which enables policy clauses to be formed 2834 using (reusable) Event, Condition, and/or Action objects 2836 SUPAPolicyClauses are aggregated by a SUPAPolicyStructure 2837 object, which enables all types of SUPAPolicies to uniformly be 2838 made up of one or more SUPAPolicyClauses. 2840 5.5.1. SUPAPolicyClause Attributes 2842 This section defines the attributes of the SUPAPolicyClause 2843 class, which are inherited by all SUPAPolicyClause subclasses. 2845 5.5.1.1. The Attribute "supaPolClauseExecStatus" 2847 This is an optional enumerated non-negative integer attribute. It 2848 defines whether this SUPAPolicyClause is currently in use and, if 2849 so, what its execution status is. This attribute can also be used 2850 to place this particular SUPAPolicyClause into a specific execution 2851 state, such as enabled (values 1-4), in test (value 5) or disabled 2852 (value 6). Values include: 2854 0: Unknown (an error state) 2855 1: Completed (i.e., successfully executed, but now idle) 2856 2: Working (i.e., in use and no errors reported) 2857 3: Not Working (i.e., in use, but errors have been reported) 2858 4: Available (i.e., could be used, but currently isn't) 2859 5: In Test (i.e., cannot be used as part of an OAM&P policy) 2860 6: Disabled (i.e., not available for use) 2862 Value 0 denotes an error that prevents this SUPAPolicyClause 2863 from being used. Value 1 means that this SUPAPolicyClause has 2864 successfully finished execution, and is now idle. Value 2 means 2865 that this SUPAPolicyClause is in use; in addition, this 2866 SUPAPolicyClause is working correctly. Value 3 is the same as 2867 value 2, except that this SUPAPolicyClause is not working 2868 correctly. Value 4 means that this SUPAPolicyClause is available, 2869 but not currently in use. Value 5 means that this SUPAPolicyClause 2870 is in a special test state. A test state signifies that it SHOULD 2871 NOT be used to evaluate OAM&P policies. A value of 6 means that 2872 this SUPAPolicyClause is unavailable for use. 2874 5.5.2. SUPAPolicyClause Relationships 2876 SUPAPolicyClause participates in a single relationship, 2877 SUPAHasPolicyClause, as defined in section 5.3.2.7. Note that 2878 SUPAPolicyClause uses the decorator pattern to "wrap" this object 2879 with instances of the (concrete) subclasses of the 2880 SUPAPolicyComponentDecorator object. 2882 5.6. The Concrete Class "SUPAEncodedClause" 2884 This is a mandatory concrete class that refines the behavior of a 2885 SUPAPolicyClause. 2887 This class defines a generalized extension mechanism for 2888 representing SUPAPolicyClauses that have not been modeled 2889 with other SUPAPolicy objects. Rather, the contents of the policy 2890 clause are directly encoded into the attributes of the 2891 SUPAEncodedClause. Hence, SUPAEncodedClause objects are reusable 2892 at the object level, whereas SUPABooleanClause clauses are reusable 2893 at the individual Boolean expression level. 2895 This class uses two of its attributes (supaEncodedClauseContent and 2896 supaEncodedClauseEncoding) for defining the content and type of 2897 encoding used in a given SUPAPolicyClause. The benefit of a 2898 SUPAEncodedClause is that it enables direct encoding of the text of 2899 the SUPAPolicyClause, without having the "overhead" of using other 2900 objects. However, note that while this method is efficient, it 2901 does not reuse other SUPAPolicy objects. 2903 5.6.1. SUPAEncodedClause Attributes 2905 This section defines the attributes of the SUPAEncodedClause class. 2907 5.6.1.1. The Attribute "supaEncodedClauseContent" 2909 This is a mandatory string attribute, and defines the content of 2910 this clause. It works with another class attribute, called 2911 supaEncodedClauseEncoding, which defines how to interpret the 2912 value of this attribute (e.g., as a string or reference). These 2913 two attributes form a tuple, and together enable a machine to 2914 understand the syntax and value of this object instance. 2916 5.6.1.2. The Attribute "supaEncodedClauseEncoding" 2918 This is a mandatory integer attribute, and defines how to 2919 interpret the value of this encoded clause. It works with another 2920 class attribute, called supaEncodedClauseContent, which defines 2921 the content of the encoded clause. These two attributes form a 2922 tuple, and together enable a machine to understand the syntax and 2923 value of the encoded clause for the object instance of this class. 2924 Values include: 2926 0: undefined 2927 1: String 2928 2: GUID 2929 3: UUID 2930 4: URI 2931 5: FQDN 2933 5.6.1.3. The Attribute "supaEncodedClauseResponse" 2935 This is an optional Boolean attribute that emulates a Boolean 2936 response of this clause, so that it may be combined with other 2937 subclasses of the SUPAPolicyClause that provide a status as to 2938 their correctness and/or evaluation state. This enables this 2939 object to be used to construct more complex Boolean clauses. 2941 5.6.2. SUPAEncodedClause Relationships 2943 SUPAPolicyClause participates in a single inherited relationship, 2944 SUPAHasPolicyClause, as defined in section 5.3.2.7. 2946 5.7. The Abstract Class "SUPAPolicyComponentDecorator" 2948 This is a mandatory class, and is used to implement the decorator 2949 pattern. The decorator pattern enables all or part of one or more 2950 objects to "wrap" another concrete object. This means that any 2951 any concrete subclass of SUPAPolicyClause is wrapped by any 2952 concrete subclass of SUPAPolicyComponentDecorator, as shown in 2953 Figure 19 below. 2955 A 2956 +------------------------------+ 2957 | | 1..n 2958 | SUPAPolicyComponentStructure +--------+ 2959 | | | used to wrap 2960 +------------------------------+ | concrete 2961 / \ | subclasses of 2962 I | PolicyClause 2963 I | 2964 +---------------+--------------+ / \ 2965 I I A 2966 A I A I \ / 0..1 2967 +----------+---------+ +--------------+-----+---------+ 2968 | SUPAPolicyClause | | SUPAPolicyComponentDecorator | 2969 +----------+---------+ +--------------+---------------+ 2970 I I 2971 I I 2972 / \ / \ 2973 Concrete Subclasses, Concrete Subclasses 2974 (e.g., SUPAEncodedClause) (e.g., SUPAPolicyCollection) 2975 (object being wrapped) (wrapping object(s)) 2977 Figure 19. The PolicyComponent Decorator Pattern 2979 5.7.1. The Decorator Pattern 2981 Each SUPAPolicyComponentDecorator object HAS_A (i.e., wraps) a 2982 concrete instance of the SUPAPolicyClause object. This means that 2983 the SUPAPolicyComponentDecorator object has an instance variable 2984 that holds a reference to a SUPAPolicyClause object. Since the 2985 SUPAPolicyComponentDecorator object has the same interface as the 2986 SUPAPolicyClause object, the SUPAPolicyComponentDecorator object 2987 (and all of its subclasses) are transparent to clients of the 2988 SUPAPolicyClause object (and its subclasses). This means that 2989 SUPAPolicyComponentDecorator object instances can add attributes 2990 and/or methods to those of the concrete instance of the chosen 2991 subclass of SUPAPolicyClause. 2993 Figure 19 shows how this is done for methods. 19a shows the 2994 initial object to be wrapped; 19b shows SUPAPolicyCollection 2995 wrapping SUPAEncodedClause; 19c shows SUPAGenericDecoratedComponent 2996 wrapping SUPAPolicyCollection. 2998 +-------------------+ 2999 | SUPAEncodedClause | 3000 | eval() | 3001 +-------------------+ 3002 (a) Initial Object 3004 ===> 3005 +------------------------+ 3006 | SUPAPolicyCollection | 3007 | eval() | 3008 | +-------------------+ | 3009 | | SUPAEncodedClause | | 3010 | | eval() | | 3011 | +-------------------+ | 3012 +------------------------+ 3013 (b) SUPAPolicyCollection "wraps" SUPAEncodedClause 3015 ===> 3016 +--------------------------------+ 3017 | SUPAGenericDecoratedComponent | 3018 | eval() | 3019 | +-----------------------+ | 3020 | | SUPAPolicyCollection | | 3021 | | eval() | | 3022 | | +-------------------+ | | 3023 | | | SUPAEncodedClause | | | 3024 | | | eval() | | | 3025 | | +-------------------+ | | 3026 | +-----------------------+ | 3027 +--------------------------------+ 3028 (c) SUPAGenericDecoratedComponent "wraps" SUPAPolicyCollection 3030 Figure 20. Conceptual Depiction of eval() Decorated Method 3032 When eval() is called in the outermost object 3033 (SUPAGenericDecoratedComponent), it delegates to the eval() method 3034 of SUPAPolicyCollection, which in turn delegates to the eval() 3035 method of SUPAEncodedClause. This method executes and returns the 3036 results to SUPAPolicyCollection, which executes and returns the 3037 results to SUPAGenericDecoratedComponent, which executes and returns 3038 the final result. 3040 5.7.2. SUPAPolicyComponentDecorator Attributes 3042 Currently, there are two attributes defined for this class, which 3043 are described in the following subsections. Both attributes are 3044 used by subclasses to constrain the behavior of that subclass; 3045 they do **not** affect the relationship between the concrete 3046 subclass of SUPAPolicyComponentDecorator that is wrapping the 3047 concrete subclass of SUPAPolicyClause. This is different 3048 than the use of similar attributes defined in the 3049 SUPAHasDecoratedPolicyComponentDetail association class (which 3050 are used to constrain the relationship between the concrete 3051 subclass of SUPAPolicyClause and the concrete subclass of the 3052 SUPAHasDecoratedPolicyComponent object that is wrapping it). 3053 Note that [2] does not define any attributes for this class. 3055 5.7.2.1. The Attribute "supaPolCompConstraintEncoding" 3057 This is a mandatory non-negative enumerated integer that defines 3058 how to interpret each string in the supaPolCompConstraint class 3059 attribute. Values include: 3061 0: undefined 3062 1: OCL 2.4 3063 2: OCL 2.x 3064 3: OCL 1.x 3065 4: QVT 1.2 - Relations Language 3066 5: QVT 1.2 - Operational language 3067 6: Alloy 3069 Enumerations 1-3 are dedicated to OCL (with OCL 2.4 being the 3070 latest version as of this writing). QVT defines a set of languages 3071 (the two most powerful and useful are defined by enumerations 4 3072 and 5). Alloy is a language for describing constraints, and uses a 3073 SAT solver to guarantee correctness. 3075 5.7.2.2. The Attribute "supaAPolCompConstraint[0..n]" 3077 This is a mandatory array of string attributes. Each attribute 3078 specifies a constraint to be applied using the encoding defined in 3079 the supaPolCompConstraintEncoding class attribute. This provides 3080 a more rigorous and flexible treatment of constraints than is 3081 possible in [RFC3460]. 3082 Note: [0..n] means that this is a multi-valued property that may 3083 have zero or more attributes. 3085 5.7.3. SUPAPolicyComponentDecorator Relationships 3087 One relationship is currently defined for this class, which is 3088 described in the following subsection. 3090 5.7.3.1. The Aggregation "SUPAHasDecoratedPolicyComponent" 3092 This is a mandatory aggregation, and is part of a decorator 3093 pattern. It is used to enable a concrete instance of a 3094 SUPAPolicyComponentDecorator to dynamically add behavior to a 3095 specific type of SUPAPolicyClause object. The semantics of this 3096 aggregation are defined by the 3097 SUPAHasDecoratedPolicyComponentDetail association class. 3099 5.7.3.2. The Association Class 3100 "SUPAHasDecoratedPolicyComponentDetail" 3102 This is a mandatory concrete association class, and defines the 3103 semantics of the SUPAHasDecoratedPolicyComponent aggregation. The 3104 purpose of this class is to use the Decorator pattern to determine 3105 which SUPAPolicyComponentDecorator object instances, if any, are 3106 required to augment the functionality of the concrete subclass of 3107 SUPAPolicyClause that is being used. 3109 Currently, there are two attributes defined for this class, which 3110 are described in the following subsections. Both attributes are 3111 used in this association class to constrain the **relationship** 3112 between the concrete subclass of SUPAPolicyComponentDecorator that 3113 is wrapping the concrete subclass of SUPAPolicyClause. Note that 3114 class attributes of SUPAPolicyComponentDecorator (see section 3115 5.9.2) only affect that specific subclass. 3117 5.7.3.2.1. The Attribute "supaDecoratedConstraintEncoding" 3119 This is a mandatory non-negative enumerated integer that defines 3120 how to interpret each string in the supaDecoratedConstraint class 3121 attribute. Values include: 3123 0: undefined 3124 1: OCL 2.4 3125 2: OCL 2.x 3126 3: OCL 1.x 3127 4: QVT 1.2 - Relations Language 3128 5: QVT 1.2 - Operational language 3129 6: Alloy 3131 Enumerations 1-3 are dedicated to OCL (with OCL 2.4 being the 3132 latest version as of this writing). QVT defines a set of languages 3133 (the two most powerful and useful are defined by enumerations 4 3134 and 5). Alloy is a language for describing constraints, and uses a 3135 SAT solver to guarantee correctness. 3137 5.7.3.2.2. The Attribute "supaDecoratedConstraint[0..n]" 3139 This is a mandatory array of string attributes. Its purpose is to 3140 collect a set of constraints to be applied to a decorated object. 3141 The interpretation of each constraint in the array is defined in 3142 the supaDecoratedConstraintsEncoding class attribute. 3143 Note: [0..n] means that this is a multi-valued property that may 3144 have zero or more attributes. 3146 5.7.4. Illustration of Constraints in the Decorator Pattern 3148 The following example will illustrate how the different constraints 3149 defined in sections 5.7.2 (class attribute constraints) and section 3150 5.7.3 (relationship constraints) can be used. 3152 Figure 21 builds a simple SUPAPolicyClause that has both types 3153 of relationships. 3155 A A 3156 +------------------+ 0..1 +----------------------------+ 3157 | | 1..n / \| | 3158 | SUPAPolicyClause +------+----- A +SUPAPolicyComponentDecorator| 3159 | | ^ \ /| | 3160 +---------+--------+ | +-----------+----------------+ 3161 I | I 3162 I | I 3163 C I | C I 3164 +--------+--------+ | +---------+----------+ 3165 |SUPAEncodedClause| | |SUPAPolicyCollection| 3166 +-----------------+ | +--------------------+ 3167 | 3168 C | 3169 +-----------------+-------------------+ 3170 |SUPAHasDecoratedPolicyComponentDetail| 3171 +-------------------------------------+ 3173 Figure 21. Constraints in the Decorator Pattern 3175 Figure 21 says that a SUPAPolicyClause, realized as a 3176 SUPAEncodedClause, is wrapped by a SUPAPolicyCollection object. 3177 The attributes in the SUPAPolicyComponentDecorator object are used 3178 to constrain the attributes in the SUPAPolicyCollection object, 3179 while the attributes in the SUPAHasDecoratedPolicyComponentDetail 3180 object are used to contrain the behavior of the aggregation 3181 (SUPAHasDecoratedPolicyComponent). For example, the attributes in 3182 the SUPAPolicyComponentDecorator object could restrict the data 3183 type and range of the components in the SUPAPolicyCollection, while 3184 the attributes in the SUPAHasDecoratedPolicyComponentDetail object 3185 could restrict which SUPAPolicyCollection objects are allowed to be 3186 used with which SUPAEncodedClauses. 3188 5.8. The Abstract Class "SUPAPolicyTerm" 3190 This is a mandatory abstract class that is the parent of 3191 SUPAPolicy objects that can be used to define a standard way to 3192 test or set the value of a variable. It does this by defining a 3193 3-tuple, in the form {variable, operator, value}, where each 3194 element of the 3-tuple is defined by a concrete subclass of the 3195 appropriate type (i.e., SUPAPolicyVariable, SUPAPolicyOperator, 3196 and SUPAPolicyValue classes, respectively). For example, a 3197 generic test or set of the value of a variable is expressed as: 3199 {variable, operator, value}. 3201 For event and condition clauses, this is typically as written above 3202 (e.g., does variable = value); for action clauses, it is typically 3203 written as (e.g., SET var to 1). A 3204 class diagram is shown in Figure 22. 3206 A 3207 +----------------+ 3208 | SUPAPolicyTerm | 3209 +--------+-------+ 3210 / \ 3211 I 3212 I 3213 I 3214 +-----------------+---+--------------------+ 3215 I I I 3216 I I I 3217 C I C I C I 3218 +--------+---------+ +--------+---------+ +-------+-------+ 3219 |SUPAPolicyVariable| |SUPAPolicyOperator| |SUPAPolicyValue| 3220 +------------------+ +------------------+ +---------------+ 3222 Figure 22. SUPAPolicyTerm Class Hierarchy 3224 Note that generic test and set expressions do not have to only use 3225 objects that are subclasses of SUPAPolicyTerm. For example, the 3226 polVendorDecoratedContent attribute of the 3227 SUPAGenericDecoratedComponent could be used as the variable (or the 3228 value) term of a get or set expression. 3230 Hence, the utility of the subclasses of SUPAPolicyTerm is in the 3231 ability of its subclasses to define a generic framework for 3232 implementing get and set expressions. This is in contrast to 3233 previous designs (e.g., [RFC3460] and [6]), which depended on 3234 defining a broad set of subclasses of PolicyVariable and 3235 PolicyValue. (Note that [4] does not have this generic capability). 3237 5.8.1. SUPAPolicyTerm Attributes 3239 Currently, SUPAPolicyTerm defines a single attribute, as described 3240 in the following subsection. Constraints on the subclasses of 3241 SUPAPolicyTerm can be applied in two different ways: 3243 1. use SUPAPolicyComponentDecorator attributes to constrain 3244 just that individual subclass, and/or 3245 2. use SUPAHasDecoratedPolicyComponentDetail association class 3246 attributes to constrain the relationship between the concrete 3247 subclass of SUPAPolicyClause and the concrete subclass of 3248 the SUPAPolicyTerm class 3250 5.8.1.1. The Attribute "supaPolTermIsNegated" 3252 This is a mandatory Boolean attribute. If the value of this 3253 attribute is true, then this particular SUPAPolicyTerm subclass 3254 (which represents a term) is negated; otherwise, it is not. 3256 5.8.2. SUPAPolicyTerm Relationships 3258 Currently, no dedicated relationships are defined for the 3259 SUPAPolicyTerm class (as there are in [RFC3460] and [6]) that 3260 aggregate policy variable and policy value objects into a policy 3261 rule). This is: 3263 1) to enable the subclasses of SUPAPolicyTerm to be used by 3264 other SUPAPolicyComponentDecorator objects, and 3265 2) because the decorator pattern replaces how such relationships 3266 were used in [RFC3460] and [6]. 3268 SUPAPolicyTerm, and its subclasses, inherit the 3269 SUPAHasDecoratedPolicyComponent aggregation, which was defined in 3270 section 5.7.3. 3272 5.9. The Concrete Class "SUPAPolicyVariable" 3274 This is a mandatory concrete class that defines information that 3275 forms a part of a SUPAPolicyClause. It specifies a concept or 3276 attribute that represents a variable, which should be compared to 3277 a value, as specifed in this SUPAPolicyClause. If it is used in 3278 a SUPAECAPolicyRule, then its value MAY be able to be changed at 3279 any time, including run-time, via use of the decorator pattern. 3280 Note that this is not possible in previous designs ([RFC3460, [4], 3281 and [6]). 3283 The value of a SUPAPolicyVariable is typically compared to the 3284 value of a SUPAPolicyValue using the type of operator defined in 3285 a SUPAPolicyOperator. However, other objects may be used instead 3286 of a SUPAPolicyValue object, and other operators may be defined 3287 in addition to those defined in the SUPAPolicyOperator class. 3289 SUPAPolicyVariables are used to abstract the representation of a 3290 SUPAPolicyRule from its implementation. Some SUPAPolicyVariables 3291 are restricted in the values and/or the data type that they may 3292 be assigned. For example, port numbers cannot be negative, and 3293 they cannot be floating-point numbers. These and other constraints 3294 may be defined in two different ways: 3296 1. use SUPAPolicyComponentDecorator attributes to constrain 3297 just that individual subclass, and/or 3298 2. use SUPAHasDecoratedPolicyComponentDetail association class 3299 attributes to constrain the relationship between the concrete 3300 subclass of SUPAPolicyClause and the concrete subclass of 3301 the SUPAPolicyVariable class 3303 Please refer to the examples in section 7, which show how to 3304 restrict the value, data type, range, and other semantics of the 3305 SUPAPolicyVariable when used in a SUPAPolicyClause. 3307 5.9.1. Problems with the RFC3460 Version of PolicyValue 3309 Please see Appendix A for a detailed comparison. 3311 5.9.2. SUPAPolicyVariable Attributes 3313 SUPAPolicyVariable defines one attribute, as described below. 3315 5.9.2.1. The Attribute "supaPolVarName" 3317 This is an optional string attribute that contains the name of 3318 this SUPAPolicyVariable. This variable name forms part of the 3319 {variable, operator, value} canonical form of a SUPAPolicyClause. 3321 5.9.3. SUPAPolicyVariable Relationships 3323 Currently, no relationships are defiend for the SUPAPolicyVariable 3324 class (note that the decorator pattern obviates the need for 3325 relationships such as those in [RFC3460] and [6]). 3326 SUPAPolicyVariable, and its subclasses, inherit the 3327 SUPAHasDecoratedPolicyComponent aggregation, which was defined in 3328 section 5.7.3. 3330 5.10. The Concrete Class "SUPAPolicyOperator" 3332 This is a mandatory concrete class for modeling different types of 3333 operators that are used in a SUPAPolicyClause. 3335 The restriction of the type of operator used in a SUPAPolicyClause 3336 restricts the semantics that can be expressed in that 3337 SUPAPolicyClause. It is typically used with SUPAPolicyVariables 3338 and SUPAPolicyValue to form a SUPAPolicyClause. 3340 5.10.1. Problems with the RFC3460 Version 3342 Please see Appendix A for a detailed comparison. 3344 5.10.2. SUPAPolicyOperator Attributes 3346 Currently, SUPAPolicyOperator defines a single generic attribute, 3347 as described below. 3349 5.10.2.1. The Attribute "supaPolOpType" 3351 This is a mandatory non-negative enumerated integer that specifies 3352 the various types of operators that are allowed to be used in this 3353 particular SUPAPolicyClause. Values include: 3355 0: Unknown 3356 1: Greater than 3357 2: Greater than or equal to 3358 3: Less than 3359 4: Less than or equal to 3360 5: Equal to 3361 6: Not equal to 3362 7: IN 3363 8: NOT IN 3364 9: SET 3365 10: CLEAR 3366 11: BETWEEN 3368 Note that 0 is an unacceptable value. Its purpose is to support 3369 dynamically building a SUPAPolicyClause by enabling the 3370 application to set the value of this attribute to a standard 3371 default value if the real value is not yet known. 3373 Additional operators may be defined in future work. For example, 3374 if SUPAPolicyVariables and SUPAPolicyValues are expanded to/from 3375 include structured objects, then "deep" versions of operators 3376 1-6 could also be defined. In this case, values 1-6 will be 3377 edited to explicitly indicate that they perform "shallow" 3378 comparison operations. 3380 5.10.3. SUPAPolicyOperator Relationships 3382 Currently, no relationships are defiend for the SUPAPolicyOperator 3383 class (note that the decorator pattern obviates the need for 3384 relationships such as those in [6]). SUPAPolicyOperator, and its 3385 subclasses, inherit the SUPAHasDecoratedPolicyComponent 3386 aggregation, which was defined in section 5.7.3. 3388 Please refer to the examples in section 7, which show how to 3389 restrict the value, data type, range, and other semantics of the 3390 SUPAPolicyOperator when used in a SUPAPolicyClause. 3392 5.11. The Concrete Class "SUPAPolicyValue" 3394 The SUPAPolicyValue class is a mandatory concrete class for 3395 modeling different types of values and constants that occur in a 3396 SUPAPolicyClause. 3398 SUPAPolicyValues are used to abstract the representation of a 3399 SUPAPolicyRule from its implementation. Therefore, the design of 3400 SUPAPolicyValues depends on two important factors. First, just as 3401 with SUPAPolicyVariables (see Section 5.11), some types of 3402 SUPAPolicyValues are restricted in the values and/or the data 3403 type that they may be assigned. Second, there is a high likelihood 3404 that specific applications will need to use their own variables 3405 that have specific meaning to a particular application. 3407 In general, there are two ways to apply constraints to an object 3408 instance of a SUPAPolicyValue: 3410 1. use SUPAPolicyComponentDecorator attributes to constrain 3411 just that individual subclass, and/or 3412 2. use SUPAHasDecoratedPolicyComponentDetail association class 3413 attributes to constrain the relationship between the concrete 3414 subclass of SUPAPolicyClause and the concrete subclass of 3415 the SUPAPolicyValue class 3417 The value of a SUPAPolicyValue is typically compared to the value 3418 of a SUPAPolicyVariable using the type of operator defined in 3419 a SUPAPolicyOperator. However, other objects may be used instead 3420 of a SUPAPolicyVariable object, and other operators may be defined 3421 in addition to those defined in the SUPAPolicyOperator class. 3423 5.11.1. Problems with the RFC3460 Version of PolicyValue 3425 Please see Appendix A for a detailed comparison. 3427 5.11.2. SUPAPolicyValue Attributes 3429 Currently, SUPAPolicyValue defines two generic attributes, as 3430 described below. 3432 5.11.2.1. The Attribute "supaPolValContent[0..n]" 3434 This is a mandatory attribute that defines an array of strings. 3435 The array contains the value(s) of this SUPAPolicyValue object 3436 instance. Its data type is defined by the supaPolValEncoding 3437 class attribute. 3438 Note: [0..n] means that this is a multi-valued property that has 3439 zero or more attributes. 3441 5.11.2.2. The Attribute "supaPolValEncoding" 3443 This is a mandatory string attribute that contains the data type 3444 of the SUPAPolicyValue object instance. Its value is defined by 3445 the supaPolValContent class attribute. Values include: 3447 0: Undefined 3448 1: String 3449 2: Integer 3450 3: Boolean 3451 4: Floating Point 3452 5: DateTime 3453 6: GUID 3454 7: UUID 3455 8: URI 3456 9: FQDN 3457 10: NULL 3459 A string is a sequence of zero or more characters. An Integer is 3460 a whole number (e.g., it has no fractional part). A Boolean 3461 represents the values TRUE and FALSE. A floating point number may 3462 contain fractional values, as well as an exponent. A DateTime 3463 represents a value that has a date and/or a time component (as in 3464 the Java or Python libraries). A NULL explicitly models the lack 3465 of a value. 3467 5.11.3. SUPAPolicyValue Relationships 3469 Currently, no relationships are defiend for the SUPAPolicyValue 3470 class (note that the decorator pattern obviates the need for 3471 relationships such as those in [6]). SUPAPolicyValue, and its 3472 subclasses, inherit the SUPAHasDecoratedPolicyComponent 3473 aggregation, which was defined in section 5.7.3. 3475 Please refer to the examples in section 7, which show how to 3476 restrict the value, data type, range, and other semantics of the 3477 SUPAPolicyValue when used in a SUPAPolicyClause. 3479 5.12. The Concrete Class "SUPAGenericDecoratedComponent" 3481 A SUPAGenericDecoratedComponent enables a custom, vendor-specific 3482 object to be defined and used in a SUPAPolicyClause. This class 3483 was derived from [2], but is not present in [RFC3460], [4], [5], 3484 or [6]. 3486 This should not be confused with the SUPAEncodedClause class. The 3487 SUPAGenericDecoratedComponent class represents a single, atomic, 3488 vendor-specific object that defines a **portion** of a 3489 SUPAPolicyClause, whereas a SUPAEncodedClause, which may or 3490 may not be vendor-specific, represents an **entire** 3491 SUPAPolicyClause. 3493 5.12.1. SUPAGenericDecoratedComponent Attributes 3495 Currently, SUPAGenericDecoratedComponent defines two generic 3496 attributes, as described below. 3498 5.12.1.1. The Attribute "supaVendorDecoratedCompContent[0..n]" 3500 This is a mandatory attribute that defines an array of strings. 3501 This array contains the value(s) of the 3502 SUPAGenericDecoratedComponent object instance. Its data type is 3503 defined by the supaVendorDecoratedEncoding class attribute. 3504 Note: [0..n] means that this is a multi-valued property that has 3505 zero or more attributes. 3507 5.12.1.2. The Attribute "supaVendorDecoratedCompEncoding" 3509 This is a mandatory integer attribute that defines the format of 3510 the supaVendorDecoratedContent class attribute. Values include: 3512 0: undefined 3513 1: String 3514 2: Integer 3515 3: Boolean 3516 4: Floating Point 3517 5: DateTime 3518 6: GUID 3519 7: UUID 3520 8: URI 3521 9: FQDN 3522 10: NULL 3524 A string is a sequence of zero or more characters. An Integer is 3525 a whole number (e.g., it has no fractional part). A Boolean 3526 represents the values TRUE and FALSE. A floating point number may 3527 contain fractional values, as well as an exponent. A DateTime 3528 represents a value that has a date and/or a time component (as in 3529 the Java or Python libraries). A NULL explicitly models the lack 3530 of a value. 3532 5.12.2. SUPAGenericDecoratedComponent Relationships 3534 Currently, no relationships are defiend for the 3535 SUPAGenericDecoratedComponent class (note that the decorator 3536 pattern obviates the need for relationships such as those in [6]). 3537 SUPAGenericDecoratedComponent participates in a single relationship, 3538 SUPAHasDecoratedPolicyComponent, as defined in section 5.7.3. 3540 5.13. The Concrete Class "SUPAPolicyCollection" 3542 A SUPAPolicyCollection is an optional concrete class that enables 3543 a collection (e.g., set, bag, or other, more complex, collections 3544 of elements) of **arbitrary objects** to be defined and used as 3545 part of a SUPAPolicyClause. This class was derived from [2], but 3546 is not present in [RFC3460], [4], [5], or [6]. 3548 5.13.1. Motivation 3550 One of the problems with ECA policy rules is when a set of events 3551 or conditions needs to be tested. For example, if a set of events 3552 is received, the policy system may need to wait for patterns of 3553 events to emerge (e.g., any number of Events of type A, followed 3554 by either one event of type B or two events of type Event C). 3556 Similarly, a set of conditions, testing the value of an attribute, 3557 may need to be performed. Both of these represent behavior 3558 similar to a set of if-then-else statements or a switch statement. 3560 It is typically not desirable for the policy system to represent 3561 each choice in such conditions as its own policy clause (i.e., a 3562 3-tuple), as this creates object explosion and poor performance. 3563 Furthermore, in these cases, it is often required to have a set of 3564 complex logic to be executed, where the logic varies according to 3565 the particular event or condition that was selected. It is much 3566 too complex to represent this using separate objects, especially 3567 when the logic is application- and/or vendor-specific. 3569 However, recall that one of the goals of this document was to 3570 facilitate the machine-driven construction of policies. Therefore, 3571 a solution to this problem is needed. 3573 5.13.2. Solution 3575 Therefore, this document defines the concept of a collection of 3576 entities, called a SUPAPolicyCollection. Conceptually, the items 3577 to be collected (e.g., events or conditions) are aggregated in 3578 one or more SUPAPolicyCollection objects of the appropriate type. 3579 Another optional SUPAPolicyCollection object could be used to 3580 aggregate logic blocks (including SUPAPolicies) to execute. 3581 Once finished, all appropriate SUPAPolicyCollection objects are 3582 sent to an external system for evaluation. 3584 The computation(s) represented by the SUPAPolicyCollection may be 3585 part of a larger SUPAPolicyClause, since SUPAPolicyCollection is a 3586 subclass of SUPAPolicyComponentDecorator, and can be used to 3587 decorate a SUPAPolicyClause. Therefore, the external system is 3588 responsible for providing a Boolean TRUE or FALSE return value, so 3589 that the policy system can use that value to represent the 3590 computation of the function(s) performed in the 3591 SUPAPolicyCollection in a Boolean clause. 3593 5.13.3. SUPAPolicyCollection Attributes 3595 Currently, SUPAGenericDecoratedComponent defines five attributes, 3596 as described below. 3598 5.13.3.1. The Attribute "supaPolCollectionContent[0..n]" 3600 This is an optional attribute that defines an array of strings. 3601 Each string in the array identifies a domain-suitable identifier of 3602 an object that is collected by this SUPAPolicyCollection instance. 3603 Note: [0..n] means that this is a multi-valued property that has 3604 zero or more attributes. 3606 5.13.3.2. The Attribute "supaPolCollectionEncoding" 3608 This is an optional non-negative enumerated integer that defines 3609 the data type of the content of this collection instance. Values 3610 include: 3612 0: undefined 3613 1: by regex (regular expression) 3614 2: by URI 3616 For example, if the value of this attribute is 1, then each of 3617 the strings in the supaPolCollectionContent attribute represent 3618 a regex that contains all or part of a string to match the class 3619 name of the object that is to be collected by this instance of 3620 a SUPAPolicyCollection class. 3622 5.13.3.3. The Attribute "supaPolCollectionFunction" 3624 This is an optional non-negative enumerated integer that defines 3625 the function of this collection instance. Values include: 3627 0: undefined 3628 1: event collection 3629 2: condition collection 3630 3: action collection 3631 4: logic collection 3633 Values 1-3 define a collection of objects that are to be used to 3634 populate the event, condition, or action clauses, respectively, of 3635 a SUPAECAPolicyRule. A value of 4 indicates that this collection 3636 contains objects that define logic for processing a SUPAPolicy. 3638 5.13.3.4. The Attribute "supaPolCollectionIsOrdered" 3640 This is an optional Boolean attribute. If the value of this 3641 attribute is TRUE, then all elements in this instance of this 3642 SUPAPolicyCollection are ordered. 3644 5.13.3.5. The Attribute "supaPolCollectionType" 3646 This is an optional non-negative enumerated integer that defines 3647 the type of collection that this instance is. Values include: 3649 0: undefined 3650 1: set 3651 2: bag (e.g., multi-set) 3652 3: dictionary (e.g., associative array) 3654 A set is an unordered collection of elements that MUST NOT have 3655 duplicates. A bag is an unordered collection of elements; it MAY 3656 also have duplicates. A dictonary is a table that associates a 3657 key with a value. 3659 Sets have a number of important functions, including: 3661 o membership: returns TRUE if the element being tested is 3662 in the set, and FALSE otherwise 3663 o subset: returns TRUE if all elements in the first set 3664 are also in the second set 3665 o union: returns all elements from both sets with no 3666 duplicates 3667 o intersection: returns all elements that are in both sets 3668 with no duplicates 3669 o difference: returns all elements in the first set that 3670 are not in the second set 3672 Bags have a number of important functions in addition to the 3673 functions defined for sets (note that while the above set of 3674 functions for a set and a bag are the same, a bag is a different 3675 data type than a set): 3677 o multiplicity: returns the number of occurrences of an 3678 element in the bag 3679 o count: returns the number of all items, including 3680 duplicates 3681 o countDistinct: returns the number of items, where all 3682 duplicates are ignored 3684 A dictionary is an unordered set of key:value pairs, where each 3685 key is unique within a given dictionary. The combination of a 3686 key and a value is called an item. The format of an item is 3687 defined as one element (the key) followed by a colon followed 3688 by a second element (the value). Each item in a set of items is 3689 separated by a comma. Keys MUST NOT be NULL; values MAY be NULL. 3691 An example of a dictionary is {20:"FTP", 21:"FTP", 22: "SSH"}. 3692 An example of a null dictionary is simply {}. 3694 5.13.4. SUPAPolicyCollection Relationships 3696 Currently, no relationships are defiend for the 3697 SUPAGenericDecoratedComponent class (note that the decorator 3698 pattern obviates the need for relationships such as those in [6]). 3699 SUPAPolicyCollection participates in a single relationship, 3700 SUPAHasDecoratedPolicyComponent, as defined in section 5.7.3. 3702 5.14. The Concrete Class "SUPAPolicySource" 3704 This is an optional class that defines a set of managed entities 3705 that authored, or are otherwise responsible for, this 3706 SUPAPolicyRule. Note that a SUPAPolicySource does NOT 3707 evaluate or execute SUPAPolicies. Its primary use is for 3708 auditability and the implementation of deontic and/or alethic logic. 3709 A class diagram is shown in Figure 12. 3711 A SUPAPolicySource SHOULD be mapped to a role or set of roles 3712 (e.g., using the role-object pattern [11]). This enables 3713 role-based access control to be used to restrict which entities 3714 can author a given policy. Note that Role is a type of 3715 SUPAPolicyMetadata. 3717 5.14.1. SUPAPolicySource Attributes 3719 Currently, no attributes are defined for this class. 3721 5.14.2. SUPAPolicySource Relationships 3723 SUPAPolicySource participates in a single relationship, 3724 SUPAHasPolicySource, as defined in section 5.3.2.1. 3725 SUPAPolicySource, and its subclasses, inherit the 3726 SUPAHasDecoratedPolicyComponent aggregation, which was 3727 defined in section 5.7.3. 3729 5.15. The Concrete Class "SUPAPolicyTarget" 3731 This is an optional class that defines a set of managed entities 3732 that a SUPAPolicy is applied to. Figure 12 shows a class diagram 3733 of the SUPAPolicyTarget. 3735 A managed object must satisfy two conditions in order to be defined 3736 as a SUPAPolicyTarget. First, the set of managed entities that are 3737 to be affected by the SUPAPolicy must all agree to play the role of 3738 a SUPAPolicyTarget. In general, a managed entity may or may not be 3739 in a state that enables SUPAPolicies to be applied to it to change 3740 its state; hence, a negotiation process may need to occur to enable 3741 the SUPAPolicyTarget to signal when it is willing to have 3742 SUPAPolicies applied to it. Second, a SUPAPolicyTarget must be able 3743 to process (directly or with the aid of a proxy) SUPAPolicies. 3745 If a proposed SUPAPolicyTarget meets both of these conditions, it 3746 SHOULD set its supaPolicyTargetEnabled Boolean attribute to a 3747 value of TRUE. 3749 A SUPAPolicyTarget SHOULD be mapped to a role (e.g., using the 3750 role-object pattern). This enables role-based access control to 3751 be used to restrict which entities can author a given policy. 3752 Note that Role is a type of SUPAPolicyMetadata. 3754 5.15.1. SUPAPolicyTarget Attributes 3756 Currently, no attributes are defined for the SUPAPolicyTarget 3757 class. 3759 5.15.2. SUPAPolicyTarget Relationships 3761 SUPAPolicyTarget participates in a single relationship, 3762 SUPAHasPolicyTarget, as defined in section 5.3.2.3. 3764 5.16. The Abstract Class "SUPAPolicyMetadata" 3766 Metadata is information that describes and/or prescribes 3767 characteristics and behavior of another object that is **not** 3768 an inherent, distinguishing characteristic or behavior of that 3769 object (otherwise, it would be an integral part of that object). 3771 For example, a socialSecurityNumber attribute should not be part 3772 of a generic Person class. First, most countries in the world do 3773 not know what a social security number is, much less use them. 3774 Second, a person is not created with a social security number; 3775 rather, a social security number is used to track people for 3776 administering social benefits, though it is also used as a form 3777 of identification. 3779 Continuing the example, a better way to add this capability to a 3780 model would be to have a generic Identification class, then 3781 define a SocialSecurityNumber subclass, populate it as necessary, 3782 and then define a composition between a Person and it (this is a 3783 composition because social security numbers are not reused). 3785 Since social security numbers are given to US citizens, permanent 3786 residents, and temporary working residents, and because it is 3787 also used to administer benefits, the composition is realized 3788 as an association class to define how it is being used. 3790 An example of descriptive metadata for network elements would be 3791 documentation about best current usage practices (this could also 3792 be in the form of a reference). An example of prescriptive 3793 metadata for network elements would be the definition of a time 3794 period during which specific types of operations are allowable. 3796 This is an optional class that defines the top of a hierarchy of 3797 model elements that are used to define different types of metadata 3798 that can be applied to policy and policy component objects. This 3799 enables common metadata to be defined as objects and then reused 3800 when the metadata are applicable. One way to control whether 3801 SUPAPolicyMetadata objects are reused is by using the attributes 3802 of the SUPAHasPolicyMetadataDetail association class. 3804 It is recommended that this class, along with its 3805 SUPAPolicyConcreteMetadata and SUPAPolicyMetadataDecorator 3806 subclasses, be used as part of a conformant implementation. It is 3807 defined to be optional, since metadata is not strictly required. 3808 However, metadata can help specify and describe SUPAPolicyObject 3809 entities, and can also be used to drive dynamic behavior. 3811 5.16.1. SUPAPolicyMetadata Attributes 3813 This section defines the attributes of the SUPAPolicyMetadata 3814 class. 3816 5.16.1.1. The Attribute "supaPolMetadataDescription" 3818 This is an optional string attribute that defines a free-form 3819 textual description of this metadata object. 3821 5.16.1.2. The Attribute "supaPolMetadataIDContent" 3823 This is a mandatory string attribute that represents part of the 3824 object identifier of an instance of this class. It defines the 3825 content of the object identifier. It works with another class 3826 attribute, called supaPolMetadataIDEncoding, which defines how to 3827 interpret this attribute. These two attributes form a tuple, 3828 and together enable a machine to understand the syntax and value 3829 of an object identifier for the object instance of this class. 3831 5.16.1.3. The Attribute "supaPolMetadataIDEncoding" 3833 This is an optional non-zero enumerated integer attribute that 3834 represents part of the object identifier of an instance of this 3835 class. It defines the format of the object identifier. It works 3836 with another class attribute, called supaPolMetadataIDContent, 3837 which defines the content of the object ID. 3839 These two attributes form a tuple, and together enable a machine 3840 to understand the syntax and value of an object identifier for 3841 the object instance of this class. The supaPolMetadataIDEncoding 3842 attribute is mapped to the following values: 3844 0: undefined 3845 1: GUID 3846 2: UUID 3847 3: URI 3848 4: FQDN 3850 5.16.1.4. The Attribute "supaPolMetadataName" 3852 This is an optional string attribute that defines the name of this 3853 SUPAPolicyMetadata object. 3855 5.16.2. SUPAPolicyMetadata Relationships 3857 SUPAPolicyMetadata participates in a single aggregation, which is 3858 defined in the following subsections. 3860 5.16.2.1. The Aggregation "SUPAHasPolicyMetadata" 3862 This is an optional aggregation that defines the set of 3863 SUPAPolicyMetadata that are aggregated by this particular 3864 SUPAPolicyObject. It is recommended that this aggregation be used 3865 as part of a conformant implementation. 3867 The multiplicity of this relationship is defined as 0..n on the 3868 aggregate (SUPAPolicyObject) side, and 0..n on the part 3869 (SUPAPolicyMetadata) side. This means that this relationship is 3870 optional. The semantics of this aggregation are implemented using 3871 the SUPAHasPolicyMetadataDetail association class. 3873 5.16.2.2. The Abstract Class "SUPAHasPolicyMetadataDetail" 3875 This is an optional abstract association class, and defines the 3876 semantics of the SUPAHasPolicyMetadata aggregation. Its purpose is 3877 to determine which SUPAPolicyMetadata object instances should be 3878 attached to which particular object instances of the 3879 SUPAPolicyObject class. This is done by using the attributes and 3880 relationships of the SUPAPolicyMetadataDetail class to constrain 3881 which SUPAPolicyMetadata objects can be aggregated by which 3882 particular SUPAPolicyObject instances. It is recommended that this 3883 association class be used as part of a conformant implementation. 3885 5.16.2.2.1. The Attribute "supaPolMetadataIsApplicable" 3887 This is an optional Boolean attribute. If the value of this 3888 attribute is TRUE, then the SUPAPolicyMetadata object(s) of this 3889 particular SUPAHasPolicyMetadata aggregation SHOULD be aggregated 3890 by this particular SUPAPolicyObject. 3892 5.16.2.2.2. The Attribute "supaPolMetadataConstraintEncoding" 3894 This is an optional non-negative enumerated integer that defines 3895 how to interpret each string in the supaPolMetadataConstraint 3896 class attribute. Values include: 3898 0: undefined 3899 1: OCL 2.4 3900 2: OCL 2.x 3901 3: OCL 1.x 3902 4: QVT 1.2 - Relations Language 3903 5: QVT 1.2 - Operational language 3904 6: Alloy 3906 Enumerations 1-3 are dedicated to OCL (with OCL 2.4 being the 3907 latest version as of this writing). QVT defines a set of languages 3908 (the two most powerful and useful are defined by enumerations 4 3909 and 5). Alloy is a language for describing constraints, and uses a 3910 SAT solver to guarantee correctness. 3912 If this class is instantiated, then this attribute SHOULD also be 3913 instantiated, and should be part of a conformant implementation. 3915 5.16.2.2.3. The Attribute "supaPolMetadataConstraint[0..n]" 3917 This is an optional array of string attributes. Each attribute 3918 specifies a constraint to be applied using the format identified 3919 by the value of the supaPolMetadataPolicyConstraintEncoding class 3920 attribute. This provides a more rigorous and flexible treatment of 3921 constraints than is possible in [RFC3460]. 3923 If this class is instantiated, then this attribute SHOULD also be 3924 instantiated, and should be part of a conformant implementation. 3925 Note: [0..n] means that this is a multi-valued property that has 3926 zero or more attributes. 3928 5.17. The Concrete Class "SUPAPolicyConcreteMetadata" 3930 This is an optional concrete class. It defines an object that will 3931 be wrapped by concrete instances of the SUPAPolicyMetadataDecorator 3932 class. It can be viewed as a "carrier" for metadata that will be 3933 attached to a subclass of SUPAPolicyObject. Since the decorator 3934 pattern is used, any number of concrete subclasses of the 3935 SUPAPolicyMetadataDecorator class can wrap an instance of the 3936 SUPAPolicyConcreteMetadata class. 3938 It is recommended that this class be used as part of a conformant 3939 implementation. 3941 5.17.1. SUPAPolicyConcreteMetadata Attributes 3943 Currently, two attributes are defined for the 3944 SUPAPolicyConcreteMetadata class, and are described in the 3945 following subsections. 3947 5.17.1.1. The Attribute "supaPolMDValidPeriodEnd" 3949 This is an optional attribute. Its data type should be able to 3950 express a date and a time. This attribute defines the ending 3951 date and time that this Metadata object is valid for. 3953 5.17.1.2. The Attribute "supaPolMDValidPeriodStart" 3955 This is an optional attribute. Its data type should be able to 3956 express a date and a time. This attribute defines the starting 3957 date and time that this Metadata object is valid for. 3959 5.17.2. SUPAPolicyConcreteMetadata Relationships 3961 This class inherits the relationships of the SUPAPolicyMetadata 3962 class; see section 5.16.2. It can also be used by subclasses of 3963 the SUPAPolicyMetadataDecorator class, and hence, can participate 3964 in the HasSUPAMetadataDecorator aggregation; see section 5.18.2. 3966 5.18. The Abstract Class "SUPAPolicyMetadataDecorator" 3968 This is an optional class, and is used to implement the decorator 3969 pattern (see section 5.7.1.) for metadata objects. This pattern 3970 enables all or part of one or more SUPAPolicyMetadataDecorator 3971 subclasses to "wrap" a SUPAPolicyConcreteMetadata object instance. 3973 It is recommended that this class be used as part of a conformant 3974 implementation. 3976 5.18.1. SUPAPolicyMetadataDecorator Attributes 3978 Currently, no attributes are defined for the 3979 SUPAPolicyMetadataDecorator class. 3981 5.18.2. SUPAPolicyMetadataDecorator Relationships 3983 This class inherits the relationships of the SUPAPolicyMetadata 3984 class; see section 5.16.2. It also defines a single aggregation, 3985 HasSUPAMetadataDecorator, which is used to implement the decorator 3986 pattern, as described in the following subsections. 3988 5.18.2.1. The Aggregation "HasSUPAMetadataDecorator" 3990 This is an optional aggregation, and is part of a decorator 3991 pattern. It is used to enable a concrete instance of a 3992 SUPAPolicyMetadataDecorator to dynamically add behavior to a 3993 SUPAPolicyConcreteMetadata object instance. The semantics of this 3994 aggregation are defined by the HasSUPAMetadataDecoratorDetail 3995 association class. 3997 It is recommended that this aggregation be part of a conformant 3998 implementation. 4000 The multiplicity of this aggregation is 0..1 on the aggregate 4001 (SUPAPolicyMetadataDecorator) side and 1..n on the part 4002 (SUPAPolicyMetadata) side. This means that if this aggregation is 4003 defined, then at least one SUPAPolicyMetadata object (e.g., a 4004 concrete subclass of SUPAPolicyMetadataDecorator) must also be 4005 instantiated and wrapped by this SUPAPolicyConcreteMetadata object 4006 instance. The semantics of this aggregation are defined by the 4007 HasSUPAMetadataDecoratorDetail association class. 4009 5.18.2.2. The Association Class "HasSUPAMetadataDecoratorDetail" 4011 This is an optional concrete association class, and defines the 4012 semantics of the HasSUPAMetadataDecorator aggregation. The purpose 4013 of this class is to use the Decorator pattern to determine 4014 which SUPAPolicyMetadataDecorator object instances, if any, are 4015 required to augment the functionality of the 4016 SUPAPolicyConcreteMetadata object instance that is being used. 4018 It is recommended that this association class be part of a 4019 conformant implementation. 4021 Attributes for this association class will be defined in a future 4022 version of this document. 4024 5.19. The Concrete Class "SUPAPolicyAccessMetadataDef" 4026 This is an optional concrete class that defines access control 4027 information, in the form of metadata, that can be added to a 4028 SUPAPolicyObject. This is done using the SUPAHasPolicyMetadata 4029 aggregation (see section 5.2.2.). This enables all or part of a 4030 standardized description and/or specification of access control 4031 for a given SUPAPolicyObject to be easily changed at runtime by 4032 wrapping an object instance of the SUPAPolicyConcreteMetadata 4033 class (or its subclass) with all or part of this object, and then 4034 adorning the SUPAPolicyObject with the SUPAPolicyConcreteMetadata 4035 object instance. 4037 5.19.1. SUPAPolicyAccessMetadataDef Attributes 4039 Currently, the SUPAPolicyAccessMetadataDef class defines three 4040 attributes; these are described in the following subsections. 4042 5.19.1.1. The Attribute "supaPolAccessPrivilegeDef" 4044 This is an optional non-negative enumerated integer attribute. It 4045 specifies the access privileges that external Applications have 4046 when interacting with a specific SUPAPolicyObject that is adorned 4047 with an instance of this SUPAPolicyAccessMetadataDef object. This 4048 enables the management system to control, in a consistent manner, 4049 the set of operations that external Applications have for 4050 SUPAPolicies and components of SUPAPolicies. Values include: 4052 0: undefined 4053 1: read only (for all policy components) 4054 2: read and write (for all policy components) 4055 3: privileges are specified by an external MAC model 4056 4: privileges are specified by an external DAC model 4057 5: privileges are specified by an external RBAC model 4058 6: privileges are specified by an external ABAC model 4059 7: privileges are specified by an external custom model 4061 Values 1 and 2 apply to ALL SUPAPolicyObject instances that are 4062 adorned with this SUPAPolicyConcreteMetadata object instance; 4063 these two settings are "all-or-nothing" settings, and are included 4064 for ease of use. 4066 Values 3-7 indicate that a formal external access control model is 4067 used. The name of this model, and its location, are specified in 4068 two other class attributes, called supaPolAccessPrivilegeModelName 4069 and supaPolAccessPrivilegeModelRef. MAC, DAC, RBAC, and ABAC 4070 (values 3-6 stand for Mandatory Access Control, Discretionary 4071 Access Control, Role-Based Access Control, and Attribute-Based 4072 Access Control, respectively. A value of 7 indicates that a formal 4073 external model that is not MAC, DAC, RBAC, or ABAC is used. 4075 5.19.1.2. The Attribute "supaPolAccessPrivilegeModelName" 4077 This is an optional string attribute that contains the name of 4078 the access control model being used. If the value of the 4079 supaPolAccessPrivilegeDef is 0-2, then the value of this attribute 4080 is not applicable. Otherwise, the text in this class attribute 4081 should be interpreted according to the value of the 4082 supaPolAccessPrivilegeModelRef class attribute. 4084 5.19.1.3. The Attribute "supaPolAccessPrivilegeModelRef" 4086 This is an optional non-negative enumerated integer attribute 4087 that defines the data type of the supaPolAccessPrivilegeModelName 4088 attribute. If the value of the supaPolAccessPrivilegeDef class 4089 attribute is 0-2, then the value of this attribute is not 4090 applicable. Otherwise, the value of this class attribute defines 4091 how to interpret the text in the supaPolAccessPrivilegeModelRef 4092 class attribute. Values include: 4094 0: Undefined 4095 1: URI 4096 2: GUID 4097 3: UUID 4098 4: FQDN 4100 5.20. The Concrete Class "SUPAPolicyVersionMetadataDef" 4102 This is an optional concrete class that defines versioning 4103 information, in the form of metadata, that can be added to a 4104 SUPAPolicyObject. This enables all or part of a standardized 4105 description and/or specification of version information for a 4106 given SUPAPolicyObject to be easily changed at runtime by 4107 wrapping an object instance of the SUPAPolicyConcreteMetadata 4108 class (or its subclass) with all or part of this object. 4110 5.20.1. SUPAPolicyVersionMetadataDef Attributes 4112 Version information is defined in a generic format as follows: 4114 ... 4116 In this approach: 4118 o supaVersionMajor denotes a major new release 4119 o supaVersionMinor denotes an incremental release, that adds new 4120 features and/or bug fixes to a major release 4121 o supaVersionRelType denotes the type of release (e.g., internal, 4122 alpha, production) 4123 o supaVersionRelTypeNum denotes an incremental release of ability 4124 particular type 4126 Currently, the SUPAPolicyVersionMetadataDef class defines three 4127 attributes; these are described in the following subsections. 4129 5.20.1.1. The Attribute "supaVersionMajor" 4131 This is an optional string attribute, and contains a string 4132 (typically representing an integer) indicating a significant 4133 increase in functionality is present in this version. 4135 5.20.1.2. The Attribute "supaVersionMinor" 4137 This is an optional string attribute, and contains a string 4138 (typically representing an integer) indicating that this release 4139 contains a set of features and/or bug fixes that collectively do 4140 not warrant incrementing the supaVersionMajor attribute. This 4141 attribute should only be used if the supaVersionMajor attribute 4142 is NOT NULL. 4144 5.20.1.3. The Attribute "supaVersionRelType" 4146 This is an optional integer attribute, and contains a string 4147 defining the type of release of this SUPAPolicyObject. Values 4148 include: 4150 0: undefined 4151 1: internal 4152 2: alpha 4153 3: beta 4154 4: release candidate 4155 5: production 4156 6: maintenance 4158 This attribute should only be used if the supaVersionMinor 4159 attribute is NOT NULL. 4161 5.20.1.4. The Attribute "supaVersionRelTypeNum" 4163 This is an optional string attribute, and contains a string 4164 defining the incremental release associated with the 4165 supaVersionRelType class attribute. This attribute should only be 4166 used if the supaVersionRelType attribute is NOT NULL. 4168 6. SUPA ECAPolicyRule Information Model 4170 This section defines the classes, attributes, and relationships 4171 of the SUPA ECAPolicyRule Information Model (EPRIM). Unless 4172 otherwise stated, all classes (and attributes) defined in this 4173 section were abstracted from DEN-ng [2], and a version of them are 4174 in the process of being added to [5]. 4176 6.1. Overview 4178 Conceptually, the EPRIM is a set of subclasses that specialize the 4179 concepts defined in the GPIM for representing the components of a 4180 Policy that uses ECA semantics. This is shown in Figure 23 (only 4181 new EPRIM subclasses and their GPIM superclasses are shown). 4183 (Class of another model that SUPA is integrating into) 4184 | 4185 +---SUPAPolicyObject (5.2) 4186 | 4187 +---SUPAPolicyStructure (5.3) 4188 | | 4189 | +---SUPAECAPolicyRule (6.4) 4190 | | 4191 | +---SUPAECAPolicyRuleAtomic (6.5) 4192 | | 4193 | +---SUPAECAPolicyRuleComposite (6.6) 4194 | 4195 +---SUPAPolicyComponentStructure (5.6) 4196 | 4197 +---SUPAPolicyClause (5.7) 4198 | | 4199 | +---SUPABooleanClause (6.7) 4200 | | 4201 | +---SUPAECAPolicyRuleAtomic (6.8) 4202 | | 4203 | +---SUPAECAPolicyRuleComposite (6.9) 4204 | 4205 +---SUPAPolicyComponentDecorator (5.9) 4206 | 4207 +---SUPAECAComponent(6.10) 4208 | | 4209 | +---SUPAPolicyEvent (6.11) 4210 | | 4211 | +---SUPAPolicyCondition (6.12) 4212 | | 4213 | +---SUPAPolicyAction (6.13) 4215 Figure 23. The EPRIM Class Hierarchy 4217 Specifically, the EPRIM specializes the SUPAPolicyStructure class 4218 class to create a SUPAECAPolicyRule (see sections 6.4 - 6.6); it 4219 also specializes two subclasses of the SUPAPolicyComponentStructure 4220 class to create two new sets of policy components. These two 4221 SUPAPolicyComponentStructure subclasses are: 4223 o a new subclass of SUPAPolicyClause, called SUPABooleanClause 4224 (see sections 6.7 - 6.9), is defined for constructing Boolean 4225 clauses that are specific to the needs of ECA Policy Rules 4226 o a new subclass of SUPAPolicyComponentDecorator, called 4227 SUPAECAComponent (see sections 6.10 - 6.13), is defined for 4228 constructing reusable objects that represent Events, 4229 Conditions, and Actions 4231 The EPRIM provides new functionality, based on the GPIM, by 4232 extending the GPIM to define new classes and relationships. The 4233 EPRIM does NOT define new classes that are not inherited from 4234 existing GPIM classes. This ensures that the semantics of the GPIM 4235 are not changed, even though new functionality (for ECA Policy 4236 Rules and components) are being defined. 4238 The overall strategy for refining the GPIM is as follows: 4240 o SUPAECAPolicyRule is defined as a subclass of the GPIM 4241 SUPAPolicyStructure class 4242 o A SUPAECAPolicyRule has event, condition, and action clauses 4243 o Conceptually, this can be viewed as three aggregations 4244 between the SUPAECAPolicyRule and each clause 4245 o Each aggregation uses an instance of a concrete subclass of 4246 SUPAPolicyClause; this can be a SUPABooleanClause 4247 (making it ECA-specific), a SUPAEncodedClause (making it 4248 generic in nature), or a new subclass of SUPAPolicyClause 4249 o Concrete subclasses of SUPAPolicyClause may be decorated 4250 with zero or more concrete subclasses of the 4251 SUPAPolicyComponentDecorator class 4252 o An optional set of GPIM SUPAPolicySource objects can be 4253 defined to represent the authoring of a SUPAECAPolicyRule 4254 o An optional set of GPIM SUPAPolicyTarget objects can be 4255 defined to represent the set of managed entities that will be 4256 affected by this SUPAECAPolicyRule 4257 o An optional set of SUPAPolicyMetadata can be defined for any 4258 of the objects that make up a SUPAECAPolicyRule, including 4259 any of its components 4261 6.2. Constructing a SUPAECAPolicyRule 4263 There are several different ways to construct a SUPAECAPolicyRule; 4264 they differ in which set of components are used to define the 4265 content of the SUPAECAPolicyRule, and whether each component is 4266 decorated or not. The following are some examples of creating a 4267 SUPAECAPolicyRule: 4269 o Define three types of SUPABooleanClauses, one each for the 4270 event, condition, and action clauses that make up a 4271 SUPAECAPolicyRule 4272 o For one or more of the above clauses, associate an 4273 appropriate set of SUPAPolicyEvent, SUPAPolicyCondition, or 4274 SUPAPolicyAction objects, and complete the clause using an 4275 appropriate SUPAPolicyOperator and a corresponding 4276 SUPAPolicyValue or SUPAPolicyVariable 4277 o Note that compound Boolean clauses may be formed using 4278 one or more SUPABooleanClauseComposite objects with one or 4279 more SUPABooleanClauseAtomic objects 4280 o Define a SUPAPolicyCollection component, which is used to 4281 aggregate a set of objects appropriate for a clause, and 4282 complete the clause using an appropriate SUPAPolicyOperator 4283 and a corresponding SUPAPolicyValue or SUPAPolicyVariable 4284 o Create a new concrete subclass of SUPAPolicyComponentStructure 4285 (i.e., a sibling class of SUPAPolicyComponentDecorator and 4286 SUPAPolicyClause), and use this new subclass in a concrete 4287 subclass of SUPABooleanClause; note that this approach enables 4288 the new concrete subclass of SUPAPolicyComponentStructure to 4289 optionally be decorated as well 4290 o Create a new subclass of SUPAPolicyComponentDecorator (e.g., 4291 a sibling of SUPAECAComponent) that provides ECA-specific 4292 functionality, and use that to decorate a SUPAPolicyClause 4293 o Create a new concrete subclass of SUPAPolicyStructure that 4294 provides ECA-specific functionality, and define all or part 4295 of its content by aggregating a set of SUPAPolicyClauses 4297 6.3. Working With SUPAECAPolicyRules 4299 A SUPAECAPolicyRule is a type of SUPAPolicy. It is a tuple that 4300 MUST have three clauses, defined as follows: 4302 o The event clause defines a Boolean expression that, if TRUE, 4303 triggers the evaluation of its condition clause (if the 4304 event clause is not TRUE, then no further action for this 4305 policy rule takes place). 4306 o The condition clause defines a Boolean expression that, if 4307 TRUE, enables the actions in the action clause to be executed 4308 (if the condition clause is not TRUE, then no further action 4309 for this policy rule takes place). 4310 o The action clause contains a set of actions (note that an 4311 action MAY invoke another SUPAECAPolicyRule; see section 4312 6.13). 4314 Each of the above clauses can be a simple Boolean expression (of 4315 the form {variable operator value}, or a compound Boolean 4316 expression consisting of Boolean combinations of clauses. 4317 Compound Boolean expressions SHOULD be in CNF or DNF. 4319 Note that each of the above three clauses MAY have a set of 4320 SUPAPolicyMetadata objects that can constrain, or otherwise 4321 affect, how that clause is treated. For example, a set of 4322 SUPAPolicyMetadata MAY affect whether none, some, or all actions 4323 are executed, and what happens if an action fails. 4325 Each of the three clauses can be constructed from either a 4326 SUPAEncodedClause or a SUPABooleanClause. The advantage of using 4327 SUPAEncodedClauses is simplicity, as the content of the clause is 4328 encoded directly into the attributes of the SUPAEncodedClause. The 4329 advantage of using SUPABooleanClauses is reusability, since each 4330 term in each clause is potentially a reusable object. 4332 Since a SUPABooleanClause is a subclass of a SUPAPolicyClause 4333 (see Section 6.7), it can be decorated by one or more concrete 4334 subclasses of SUPAPolicyComponentDecorator. Therefore, a 4335 SUPAECAPolicyRule can be built entirely from objects defined in 4336 the GPIM and EPRIM, which facilitates the construction of 4337 SUPAPolicies by a machine. 4339 The relation between a SUPAECAPolicyRule and a SUPAPolicyClause 4340 is shown in Figure 24, and is explained in further detail in 4341 Section 6.4. 4343 SUPAHasPolicyClause 4344 +----------------+------------------------+ 4345 | ^ | 4346 | | | 4347 / \ | | 4348 A | | 4349 A \ / 0..1 | A 1..n \ / 4350 +----------+-----------+ | +-----------+------+ 4351 | SUPAPolicyStructure | | | SUPAPolicyClause | 4352 +----------+-----------+ | +-----------+------+ 4353 / \ | / \ 4354 I A | | 4355 I +----------+----------------+ | 4356 I | SUPAHasPolicyClauseDetail | | 4357 I +---------------------------+ | 4358 I | 4359 C I A | 4360 +----------+----------+ +--------+----------+ 4361 | SUPAECAPolicyRule | | SUPABooleanClause | 4362 +---------------------+ +-------------------+ 4364 Figure 24. SUPAECAPolicyRule Clauses 4366 The SUPAHasPolicyClause aggregation is implemented using the 4367 SUPAHasPolicyClauseDetail association class. These were 4368 described in sections 5.4.2.1 and 5.4.2.2, respectively. 4370 6.4. The Abstract Class "SUPAECAPolicyRule" 4372 This is a mandatory abstract class, which is a PolicyContainer 4373 that aggregates PolicyEvents, PolicyConditions, PolicyActions into 4374 a type of policy rule known as an Event-Condition-Action (ECA) 4375 policy rule. As previously explained, this has the following 4376 semantics: 4378 IF the event clause evaluates to TRUE 4379 IF the condition clause evaluates to TRUE 4380 THEN execute actions in the action clause 4381 ENDIF 4382 ENDIF 4384 The event clause, condition clause, and action clause collectively 4385 form a three-tuple. Each clause MUST be defined by at least one 4386 SUPAPolicyClause (which MAY be decorated with other elements, 4387 as described in section 5.7). 4389 Each of the three types of clauses is a 3-tuple of the form: 4391 {variable operator value} 4393 Each of the three clauses MAY be combined with additional clauses 4394 using any combination of logical AND, OR, and NOT operators; this 4395 forms a "compound" Boolean clause. For example, if A, B, and C are 4396 three attributes in an event, then a valid event clause could be: 4398 (A AND B) OR C 4400 Note that the above expression is in DNF; the equivalent CNF form 4401 is ((A OR C) AND (B OR C)). In either case, the output of all 4402 three clauses is either TRUE or FALSE; this facilitates combining 4403 and chaining SUPAECAPolicyRules. 4405 An action clause MAY invoke a new SUPAECAPolicyRule; see section 4406 6.13 for more details. 4408 An ECAPolicyRule MAY be optionally augmented with PolicySources 4409 and/or PolicyTargets (see sections 5.16 and 5.17, respectively). 4410 In addition, all objects that make up a SUPAECAPolicyRule MAY 4411 have SUPAPolicyMetadata (see section 5.16) attached to them to 4412 further describe and/or specify behavior. 4414 When defined in an information model, each of the event, condition, 4415 and action clauses MUST be represented as an aggregation between a 4416 SUPAECAPolicyRule (the aggregate) and a set of event, condition, 4417 or action objects (the components). However, a data model MAY map 4418 these definitions to a more efficient form (e.g., by flattening 4419 these three types of object instances, along with their respective 4420 aggregations, into a single object instance). 4422 The composite pattern [3] is applied to the SUPAECAPolicyRule 4423 class, enabling its (concrete) subclasses to be used as either a 4424 stand-alone policy rule or as a hierarchy of policy rules. This is 4425 shown in Figure 25. 4427 A 4428 1..n +-------------------+ 4429 \| | 4430 +--------------- + SUPAECAPolicyRule | 4431 | /| | 4432 | +--------+----------+ 4433 | / \ 4434 | SUPAHasECAPolicyRule I 4435 | I 4436 | I 4437 | I 4438 | +---------------+-------------+ 4439 | I I 4440 / \ I I 4441 A I I 4442 C \ / 0..1 I C I 4443 +-----+---------+----------+ +-----------+-----------+ 4444 |SUPAECAPolicyRuleComposite| |SUPAECAPolicyRuleAtomic| 4445 +--------------------------+ +-----------------------+ 4447 Figure 25. The Composite Pattern Applied to a SUPAECAPolicyRule 4449 SUPAECAPolicyRuleComposite and SUPAECAPolicyRuleAtomic both 4450 inherit from SUPAECAPolicyRule. This means that they are both 4451 a type of SUPAECAPolicyRule. Hence, the HasSUPAECAPolicyRule 4452 aggregation enables a particular SUPAECAPolicyRuleComposite 4453 object to aggregate both SUPAECAPolicyRuleComposite as well as 4454 SUPAECAPolicyRuleAtomic objects. In contrast, a 4455 SUPAECAPolicyRuleAtomic can NOT aggregate either a 4456 SUPAECAPolicyRuleComposite or a SUPAECAPolicyRuleAtomic. 4457 SUPAECAPolicyRuleAtomic and SUPAECAPolicyRuleComposite are 4458 defined in sections 6.5 and 6.6, respectively. 4460 Note that the HasSUPAECAPolicyRule aggregation is defined by the 4461 HasSUPAECAPolicyRuleDetail association class; both are defined 4462 in sections 6.6.2 and 6.6.3, respectively. 4464 6.4.1. SUPAECAPolicyRule Attributes 4466 Currently, the SUPAECAPolicyRule defines two attributes, as 4467 described in the following subsections. 4469 6.4.1.1. The Attribute "supaECAPolicyRulePriority" 4471 This is a mandatory non-negative integer attribute that defines 4472 the priority of this particular SUPAECAPolicyRule. A larger value 4473 indicates a higher priority. A default value of 0 MAY be assigned. 4475 Priority is used primarily for 2 reasons: (1) to resolve conflicts 4476 among policy actions (e.g., given a set of conflicting actions, 4477 which one will execute) and (2) to define the execution order of 4478 policy actions (e.g., when one action may depend on the output of 4479 one or more previous actions). 4481 6.4.1.2. The Attribute "supaECAPolicyRuleStatus" 4483 This is an optional non-negative enumerated integer whose value 4484 defines the current status of this policy rule. Values include: 4486 0: In development, not ready to be deployed 4487 1: Ready to be deployed 4488 2: Deployed but not enabled 4489 3: Deployed and enabled, but not executed 4490 4: Executed without errors 4491 5: Executed with errors 4492 6: Aborted during execution 4494 6.4.2. SUPAECAPolicyRule Relationships 4496 Currently, the SUPAECAPolicyRule does not define any 4497 relationships. It inherits all four relationships defined by 4498 the SUPAPolicyStructure class (see section 5.3.2.). 4500 6.5. The Concrete Class "SUPAECAPolicyRuleAtomic" 4502 This is a mandatory concrete class. This class is a type of 4503 PolicyContainer, and represents a SUPAECAPolicyRule that can 4504 operate as a single, stand-alone, manageable object. Put another 4505 way, a SUPAECAPolicyRuleAtomic object can NOT be modeled as a set 4506 of hierarchical SUPAECAPolicyRule objects; if this is required, 4507 then a SUPAECAPolicyRuleComposite object should be used instead. 4509 6.5.1. SUPAECAPolicyRuleAtomic Attributes 4511 Currently, the SUPAECAPolicyRuleAtomic class does not define any 4512 attributes. 4514 6.5.2. SUPAECAPolicyRuleAtomic Relationships 4516 Currently, the SUPAECAPolicyRuleAtomic class does not define any 4517 relationships. It inherits all four relationships defined by the 4518 SUPAPolicyStructure class (see section 5.3.2.). 4520 6.6. The Concrete Class "SUPAECAPolicyRuleComposite" 4522 This is a mandatory concrete class. This class is a type of 4523 PolicyContainer, and represents a SUPAECAPolicyRule as a hierarchy 4524 of SUPAPolicy objects, where the hierarchy contains instances of a 4525 SUPAECAPolicyRuleAtomic and/or SUPAECAPolicyRuleComposite objects. 4526 Each of the SUPAPolicy objects, including the outermost 4527 SUPAECAPolicyRuleComposite object, are separately manageable. More 4528 importantly, each SUPAECAPolicyRuleComposite object represents an 4529 aggregated object that is itself manageable. 4531 6.6.1. SUPAECAPolicyRuleComposite Attributes 4533 Currently, the SUPAECAPolicyRuleComposite defines one attribute, 4534 as described in the following subsection. 4536 6.6.1.1. The Attribute "supaECAEvalStrategy" 4538 This is a mandatory, non-zero, integer attribute that enumerates 4539 a set of allowable alternatives that define how the set of 4540 SUPAECAPolicyRule object instances in a SUPAECAPolicyRuleComposite 4541 object are evaluated. It is assumed that the event and condition 4542 clauses of the SUPAECAPolicyRules have evaluated to TRUE (e.g., the 4543 event has occurred and the conditions were met). Values include: 4545 0: undefined 4546 1: execute the first SUPAECAPolicyRule in the 4547 SUPAECAPolicyRuleComposite and then terminate 4548 2: execute only the highest priority SUPAECAPolicyRule(s) in 4549 the SUPAECAPolicyRuleComposite and then terminate 4550 3: execute all SUPAECAPolicyRules in prioritized order (if 4551 any) regardless of whether their SUPAPolicyActions 4552 succeed or fail 4553 4: execute all SUPAECAPolicyRules in prioritized order (if 4554 any) until at least one SUPAPolicyAction in a 4555 SUPAECAPolicyRule fails, and then terminate 4557 If the value of supaECAEvalStrategy is 3 or 4, then all 4558 SUPAECAPolicyRules that have a priority will be executed first 4559 (starting with the SUPAECAPolicyRule(s) that have the highest 4560 priority, and descending); all SUPAECAPolicyRule(s) that do not 4561 have a priority are then executed (in any order). 4563 Assume that the actions in a given SUPAECAPolicyRuleComposite 4564 are defined as follows 4566 SUPAECAPolicyRule A, priority 0 4567 SUPAECAPolicyRule B, priority 10 4568 SUPAECAPolicyRule C, priority 5 4569 SUPAECAPolicyRule D, priority 10 4570 SUPAECAPolicyRule E, priority 2 4572 Then, if the supaECAEvalStrategy attribute value equals: 4574 0: an error is issued 4575 1: only SUPAECAPolicyRule A is executed 4576 2: only SUPAECAPolicyRules B and D are executed 4577 3: all SUPAECAPolicyRules are executed, regardless of any 4578 failures in their SUPAPolicyActions 4579 4: all SUPAECAPolicyRules are executed until a failure is 4580 detected, and then execution for all SUPAECAPolicyRules 4581 terminate 4583 6.6.2. SUPAECAPolicyRuleComposite Relationships 4585 Currently, the SUPAECAPolicyRuleComposite defines a single 4586 aggregation between it and SUPAECAPolicyRule, as described below. 4588 6.6.2.1. The Aggregation "SUPAHasECAPolicyRule" 4590 This is an optional aggregation that implements the composite 4591 pattern. The multiplicity of this aggregation is 0..1 on the 4592 aggregate (SUPAECAPolicyRuleComposite) side and 1..n on the part 4593 (SUPAECAPolicyRule) side. This means that if this aggregation 4594 is defined, then at least one SUPAECAPolicyRule object (which may 4595 be either an instance of a SUPAECAPolicyRuleAtomic or a 4596 SUPAECAPolicyRuleComposite class) must also be instantiated and 4597 aggregated by this particular SUPAECAPolicyRuleComposite object. 4598 The semantics of this aggregation are defined by the 4599 SUPAHasECAPolicyRuleDetail association class. 4601 6.6.3. The Association Class "SUPAHasECAPolicyRuleDetail" 4603 This is an optional association class, and defines the semantics 4604 of the SUPHasECAPolicyRule aggregation. This enables the 4605 attributes and relationships of the SUPAHasECAPolicyRuleDetail 4606 class to be used to constrain which SUPHasECAPolicyRule objects 4607 can be aggregated by this particular SUPAECAPolicyRuleComposite 4608 object instance. 4610 6.6.3.1. The Attribute "supaECAPolicyIsDefault" 4612 This is an optional Boolean attribute. If the value of this 4613 attribute is true, then this SUPAECAPolicyRule is a default 4614 policy, and will be executed if no other SUPAECAPolicyRule 4615 in the SUPAECAPolicyRuleComposite container has been executed. 4616 This is a convenient way for error handling, though care should 4617 be taken to ensure that only one default policy rule is defined 4618 per SUPAECAPolicyRuleComposite container. 4620 6.7. The Abstract Class "SUPABooleanClause" 4622 A SUPABooleanClause specializes a SUPAPolicyClause, and defines 4623 a Boolean expression consisting of a standard structure in the 4624 form of a SUPAPolicyVariable, a SUPAPolicyOperator, and a 4625 SUPAPolicyValue. For example, this enables the following Boolean 4626 clause to be defined: 4628 Foo >= Baz 4630 where 'Foo' is a PolicyVariable, '>=' is a PolicyOperator, and 4631 'Baz' is a PolicyValue. 4633 Note that in this approach, the SUPAPolicyVariable and 4634 SUPAPolicyValue terms are defined as an appropriate subclass of 4635 the SUPAPolicyComponentDecorator class; it is assumed that the 4636 SUPAPolicyOperator is an instance of the SUPAPolicyOperator class. 4637 This enables the EPRIM, in conjunction with the GPIM, to be used 4638 as a reusable class library. This encourages interoperability, 4639 since each element of the clause is itself an object defined by 4640 the SUPA object hierarchy. 4642 An entire SUPABooleanClause may be negated by setting the 4643 supaBoolClauseIsNegated class attribute of the SUPABooleanClause 4644 class to TRUE. Individual terms of a Boolean clause can be negated 4645 by using the supaTermIsNegated Boolean attribute in the 4646 SUPAPolicyTerm class (see section 5.10). 4648 A PolicyClause is in Conjunctive Normal Form (CNF) if it is a 4649 sequence of logically ANDed terms, where each term is a sequence 4650 of logically ORed terms. 4652 A PolicyClause is in Disjunctive Normal Form (DNF) if it is a 4653 sequence of logically ORed terms, where each term is a sequence 4654 of logically ANDed terms. 4656 The construction of more complex clauses, which consist of a set 4657 of simple clauses in CNF or DNF (as shown in the above example), 4658 is provided by using the composite pattern [3] to construct two 4659 concrete subclasses of the abstract SUPABooleanClause class. These 4660 are called SUPABooleanClauseAtomic and SUPABooleanClauseComposite, 4661 and are defined in sections 6.8 and 6.9, respectively. This 4662 enables instances of either a SUPABooleanClauseAtomic and/or a 4663 SUPABooleanClauseComposite to be aggregated into a 4664 SUPABooleanClauseComposite object. 4666 6.7.1. SUPABooleanClause Attributes 4668 The SUPABooleanClause class currently defines one attribute, 4669 which are defined in the following subsections. 4671 6.7.1.1. The Attribute "supaBoolClauseIsNegated" 4673 This is a mandatory Boolean attribute. If the value of this 4674 attribute is TRUE, then this (entire) SUPABooleanClause is 4675 negated. Note that the supaPolTermIsNegated class attribute of 4676 the SUPAPolicyTerm class is used to negate a single term. 4678 6.7.2. SUPABooleanClause Relationships 4680 Currently, no relationships are defined for the SUPABooleanClause 4681 class. It inherits the relationships of SUPAPolicyClause (see 4682 section 5.5.). 4684 6.8. The Concrete Class "SUPABooleanClauseAtomic" 4686 This is a mandatory concrete class that represents a 4687 SUPABooleanClause that can operate as a single, stand-alone, 4688 manageable object. A SUPABooleanClauseAtomic object can NOT be 4689 modeled as a set of hierarchical clauses; if this functionality is 4690 required, then a SUPABooleanClauseComposite object must be used. 4691 Examples of Boolean clauses that could be contained in a 4692 SUPABooleanClauseAtomic include P, NOT P, and (P OR Q), where P 4693 and Q are literals (e.g., a variable name that can be either true 4694 or false, or a formula that evaluates to a literal). Examples of 4695 Boolean clauses that are NOT in CNF are NOT(P AND Q), 4696 (P AND Q) OR R, and P AND (Q OR (R AND S)); their CNF equivalent 4697 forms are NOT P AND NOT Q, (P AND R) OR (Q AND R), and 4698 P AND (Q OR S) AND (Q OR S), respectively. 4700 6.8.1. SUPABooleanClauseAtomic Attributes 4702 No attributes are currently defined for the 4703 SUPABooleanClauseAtomic class. 4705 6.8.2. SUPABooleanClauseAtomic Relationships 4707 Currently, no relationships are defined for the 4708 SUPABooleanClauseAtomic class. It inherits the relationships of 4709 SUPAPolicyClause (see section 5.5.). 4711 6.9. The Concrete Class "SUPABooleanClauseComposite" 4713 This is a mandatory concrete class that represents a 4714 SUPABooleanClause that can operate as a hierarchy of PolicyClause 4715 objects, where the hierarchy contains instances of 4716 SUPABooleanClauseAtomic and/or SUPABooleanClauseComposite 4717 objects. Each of the SUPABooleanClauseAtomic and 4718 SUPABooleanClauseComposite objects, including the outermost 4719 SUPABooleanClauseComposite object, are separately manageable. 4721 More importantly, each SUPAECAPolicyRuleComposite object 4722 represents an aggregated object that is itself manageable. 4723 Examples of Boolean clauses that could be contained in a 4724 SUPABooleanClauseAtomic include ((P OR Q) AND R), and 4725 ((NOT P OR Q) AND (R OR NOT S) AND T), where P, Q, R, S, and 4726 T are literals. 4728 6.9.1. SUPABooleanClauseComposite Attributes 4730 Two attributes are currently defined for the 4731 SUPABooleanClauseComposite class, and are described in the 4732 following subsections. 4734 6.9.1.1. The Attribute "supaBoolClauseBindValue" 4736 This is a mandatory non-zero integer attribute, and defines the 4737 order in which terms bind to a clause. For example, the Boolean 4738 expression "((A AND B) OR (C AND NOT (D OR E)))" has the following 4739 binding order: terms A and B have a bind value of 1; term C has a 4740 binding value of 2, and terms D and E have a binding value of 3. 4742 6.9.1.2. The Attribute "supaBoolClauseIsCNF" 4744 This is an optional Boolean attribute. If the value of this 4745 attribute is TRUE, then this SUPABooleanClauseComposite is in CNF 4746 form. Otherwise, it is in DNF form. 4748 6.9.2. SUPABooleanClauseComposite Relationships 4750 Currently, the SUPABooleanClauseComposite class defined a single 4751 aggregation, which is described in the subsections below. 4753 6.9.2.1. The Aggregation "SUPAHasBooleanClause" 4755 This is a mandatory aggregation that defines the set of 4756 SUPABooleanClause objects that are aggregated by this 4757 SUPABooleanClauseComposite object. 4759 The multiplicity of this relationship is 0..1 on the aggregate 4760 (SUPABooleanClauseComposite) side, and 1..n on the part 4761 (SUPABooleanClause) side. This means that one or more 4762 SUPABooleanClauses are aggregated and used to define this 4763 SUPABooleanClauseComposite object. The 0..1 cardinality on the 4764 SUPABooleanClauseComposite side is necessary to enable 4765 SUPABooleanClauses to exist (e.g., in a PolicyRepository) before 4766 they are used by a SUPABooleanClauseComposite. The semantics of 4767 this aggregation is defined by the SUPAHasBooleanClauseDetail 4768 association class. 4770 6.9.3. The Concrete Class "SUPAHasBooleanClauseDetail" 4772 This is a mandatory association class that defines the semantics 4773 of the SUPAHasBooleanClause aggregation. This enables the 4774 attributes and relationships of the SUPAHasBooleanClauseDetail 4775 class to be used to constrain which SUPABooleanClause objects 4776 can be aggregated by this particular SUPABooleanClauseComposite 4777 object instance. 4779 6.9.3.1. SUPAHasBooleanClauseDetail Attributes 4781 The SUPAHasBooleanClauseDetail class currently does not define 4782 any attributes at this time. 4784 6.10. The Abstract Class "SUPAECAComponent" 4786 This is a mandatory abstract class that defines three concrete 4787 subclasses, one each to represent the concepts of reusable events, 4788 conditions, and actions. They are called SUPAPolicyEvent, 4789 SUPAPolicyCondition, and SUPAPolicyAction, respectively. 4791 SUPAECAComponents provide two different ways to construct 4792 SUPAPolicyClauses. The first is for the SUPAECAComponent to be 4793 used as either a SUPAPolicyVariable or a SUPAPolicyValue, and the 4794 second is for the SUPAECAComponent to contain the entire clause 4795 text. 4797 For example, suppose it is desired to define a policy condition 4798 clause with the text 'queueDepth > 10'. The two approaches could 4799 satisfy this as follows: 4801 Approach #1 (canonical form): 4802 SUPAPolicyCondition.supaPolicyConditionData contains the text 4803 'queueDepth' 4804 SUPAPolicyOperator.supaPolOpType is set to '1' (greater than) 4805 SUPAPolicyValue.supaPolValContent is set to '10' 4807 Approach #2 (SUPAECAComponent represents the entire clause): 4808 SUPAPolicyCondition.supaPolicyConditionData contains the text 4809 'queueDepth > 10' 4811 The class attribute supaECACompIsTerm, defined in subsection 4812 6.10.1.1, is used to identify which of these two approaches is 4813 used by an object instance of this class. 4815 6.10.1. SUPAECAComponent Attributes 4817 A single attribute is currently defined for this class, and is 4818 described in the following subsection. 4820 6.10.1.1. The Attribute supaECACompIsTerm 4822 This is an optional Boolean attribute. If the value of this 4823 attribute is TRUE, then this SUPAECAComponent is used as the value 4824 of a SUPAPolicyTerm to construct a SUPAPolicyClause (this is 4825 approach #1 in section 6.10 above). If the value of this attribute 4826 is FALSE, then this SUPAECAComponent contains the text of the 4827 entire corresponding SUPAPolicyClause (this is approach #2 in 4828 section 6.10 above). 4830 6.10.2. SUPAECAComponent Relationships 4832 No relationships are currently defined for this class. 4834 6.11. The Concrete Class "SUPAPolicyEvent" 4836 This is a mandatory concrete class that represents the concept of 4837 an Event that is applicable to a policy management system. Such 4838 an Event is defined as any important occurrence in time of a 4839 change in the system being managed, and/or in the environment of 4840 the system being managed. SUPAPolicyEvents can be used as part of 4841 a SUPAPolicyClause; this is done by specifying the attribute name 4842 and value of an Event in the supaPolicyEventData attribute of the 4843 SUPAPolicyEvent. This enables event attributes to be used as part 4844 of a SUPAPolicyClause. 4846 Note: this class does NOT model the "raw" occurrences of Events. 4847 Rather, it represents the concept of an Event object whose class 4848 attributes describe pertinent attributes that can trigger the 4849 evaluation of a SUPAECAPolicyRule. 4851 6.11.1. SUPAPolicyEvent Attributes 4853 Currently, five attributes are defined for the SUPAPolicyEvent 4854 class, which are described in the following subsections. 4856 6.11.1.1. The Attribute "supaPolicyEventIsPreProcessed" 4858 This is an optional Boolean attribute. If the value of this 4859 attribute is TRUE, then this SUPAPolicyEvent has been pre- 4860 processed by an external entity, such as an Event Service Bus, 4861 before it was received by the Policy Management System. 4863 6.11.1.2. The Attribute "supaPolicyEventIsSynthetic" 4865 This is an optional Boolean attribute. If the value of this 4866 attribute is TRUE, then this SUPAPolicyEvent has been produced by 4867 the Policy Management System. If the value of this attribute is 4868 FALSE, then this SUPAPolicyEvent has been produced by an entity 4869 in the system being managed. 4871 6.11.1.3. The Attribute "supaPolicyEventTopic[0..n]" 4873 This is a mandatory array of string attributes, and contains the 4874 subject that this PolicyEvent describes. 4875 Note: [0..n] means that this is a multi-valued property that has 4876 zero or more attributes. 4878 6.11.1.4. The Attribute "supaPolicyEventEncoding" 4880 This is a mandatory non-zero enumerated integer attribute, and 4881 defines how to interpret the supaPolicyEventData class attribute. 4882 These two attributes form a tuple, and together enable a machine 4883 to understand the syntax and value of the data carried by the 4884 object instance of this class. Values include: 4886 0: Undefined 4887 1: String 4888 2: Integer 4889 3: Boolean 4890 4: Floating Point 4891 5: DateTime 4893 6.11.1.5. The Attribute "supaPolicyEventData[1..n]" 4895 This is a mandatory attribute that defines an array of strings. 4896 Each string in the array represents an attribute name and value 4897 of an Event object. The format of each string is defined as 4898 name:value. The 'name' part is the name of the SUPAPolicyEvent 4899 attribute, and the 'value' part is the value of that attribute. 4900 Note: [1..n] means that this is a multi-valued property that has 4901 at least one (and possibly more) attributes. For example, if 4902 this value of this attribute is: 4904 {(startTime:0800), (endTime:1700)} 4906 then this attribute contains two properties, called startTime and 4907 endTime, whose values are 0800 and 1700, respectively. 4909 Note that the supaPolicyEventEncoding class attribute defines how 4910 to interpret the value portion of this attribute. 4912 This attribute works with another class attribute, called 4913 supaPolicyEventEncoding, which defines how to interpret this 4914 attribute. These two attributes form a tuple, and together enable 4915 a machine to understand the syntax and value of the data carried 4916 by the object instance of this class. 4918 6.11.2. SUPAPolicyEvent Relationships 4920 No relationships are currently defined for this class. It inherits 4921 the relationships defined by the SUPAPolicyComponentDecorator (see 4922 section 5.7.3.). 4924 6.12. The Concrete Class "SUPAPolicyCondition" 4926 This is a mandatory concrete class that represents the concept of 4927 an Condition that will determine whether or not the set of Actions 4928 in the SUPAECAPolicyRule to which it belongs are executed or not. 4929 SUPAPolicyConditions can be used as part of a SUPAPolicyClause 4930 (e.g., var = SUPAPolicyCondition.supaPolicyConditionData) or as a 4931 stand-alone SUPAPolicyClause (e.g., the supaPolicyConditionData 4932 attribute contains text that defines the entire condition clause). 4934 6.12.1. SUPAPolicyCondition Attributes 4936 Currently, two attributes are defined for the SUPAPolicyCondition 4937 class, which are described in the following subsections. 4939 6.12.1.1. The Attribute "supaPolicyConditionData[1..n]" 4941 This is a mandatory array of string attributes that contains the 4942 content of this SUPAPolicyCondition object. 4943 Note: [1..n] means that this is a multi-valued property that has 4944 at least one (and possibly more) attributes. 4946 This attribute works with another class attribute, called 4947 supaPolicyConditionEncoding, which defines how to interpret this 4948 attribute. These two attributes form a tuple, and together enable 4949 a machine to understand the syntax and value of the data carried 4950 by the object instance of this class. 4952 6.12.1.2. The Attribute "supaPolicyConditionEncoding" 4954 This is a mandatory non-zero enumerated integer attribute, and 4955 defines the data type of the supaPolicyConditionData attribute. 4956 These two attributes form a tuple, and together enable a machine 4957 to understand the syntax and value of the content of this 4958 SUPAPolicyCondition object. Values include: 4960 0: undefined 4961 1: String 4962 2: OCL 2.x 4963 3: OCL 1.x 4964 4: QVT 1.2 - Relations Language 4965 5: QVT 1.2 - Operational language 4966 6: Alloy 4968 6.12.2. SUPAPolicyEvent Relationships 4970 No relationships are currently defined for this class. It inherits 4971 the relationships defined by the SUPAPolicyComponentDecorator (see 4972 section 5.7.3.). 4974 6.13. The Concrete Class "SUPAPolicyAction" 4976 This is a mandatory concrete class that represents the concept of 4977 an Action, which is a part of a SUPAECAPolicyRule, which may be 4978 executed when both the event and the condition clauses of its 4979 owning SUPAECAPolicyRule evaluate to true. The execution of this 4980 action is determined by its SUPAECAPolicyRule container, and any 4981 applicable SUPAPolicyMetadata objects. SUPAPolicyActions can be 4982 used in three different ways: 4984 o as part of a SUPAPolicyClause (e.g., var = 4985 SUPAPolicyAction.supaPolicyActionData) 4986 o as a stand-alone SUPAPolicyClause (e.g., the 4987 supaPolicyActionData attribute contains text that defines 4988 the entire action clause) 4989 o to invoke a SUPAECAPolicyRule 4991 In the third case, the execution semantics SHOULD be to suspend 4992 the current execution of the set of SUPAPolicyActions that are 4993 executing, transfer execution control to the invoked 4994 SUPAECAPolicyRule, and resume the execution of the original set 4995 of SUPAPolicyActions when the invoked SUPAECAPolicyRule has 4996 finished execution. 4998 6.13.1. SUPAPolicyAction Attributes 5000 Currently, two attributes are defined for the SUPAPolicyCondition 5001 class, which are described in the following subsections. 5003 6.13.1.1. The Attribute "supaPolicyActionData[1..n]" 5005 This is a mandatory array of string attributes that contains the 5006 content of this SUPAPolicyAction object. This attribute works with 5007 another class attribute, called supaPolicyActionEncoding, which 5008 defines how to interpret this attribute. These two attributes form 5009 a tuple, and together enable a machine to understand the syntax 5010 and value of the data carried by the object instance of this class. 5011 Note: [1..n] means that this is a multi-valued property that has 5012 at least one (and possibly more) attributes. 5014 Since this attribute could represent a term in a SUPAPolicyClause 5015 (e.g., var = SUPAPolicyAction.supaPolicyActionData), a complete 5016 SUPAPolicyClause (e.g., the supaPolicyActionData attribute 5017 contains text that defines the entire action clause), or the 5018 name of a SUPAECAPolicyRule to invoke, each element in the string 5019 array is prepended with one of the following strings: 5021 o 't:' (or 'term:'), to denote a term in a SUPAPolicyClause 5022 o 'c:' (or 'clause:'), to denote an entire SUPAPolicyClause 5023 o 'r:' (or 'rule:'), to invoke a SUPAECAPolicyRule 5025 6.13.1.2. The Attribute "supaPolicyActionEncoding" 5027 This is a mandatory non-zero enumerated integer attribute, and 5028 defines the data type of the supaPolicyActionData attribute. This 5029 attribute works with another class attribute, called 5030 supaPolicyActionData, which contains the content of the action. 5031 These two attributes form a tuple, and together enable a machine 5032 to understand the syntax and value of the content of this 5033 SUPAPolicyAction object. Values include: 5035 0: undefined 5036 1: GUID 5037 2: UUID 5038 3: URI 5039 4: FQDN 5040 5: String 5041 6: OCL 2.x 5042 7: OCL 1.x 5043 8: QVT 1.2 - Relations Language 5044 9: QVT 1.2 - Operational language 5045 10: Alloy 5047 6.13.2. SUPAPolicyAction Relationships 5049 No relationships are currently defined for this class. It inherits 5050 the relationships defined by the SUPAPolicyComponentDecorator (see 5051 section 5.7.3.). 5053 Enumerations 1-4 are used to provide a reference to an action 5054 object. Enumerations 5-10 are used to express the action to 5055 perform as a string. 5057 7. Examples 5059 This will be defined in the next version of this document. 5061 8. Security Considerations 5063 This will be defined in the next version of this document. 5065 9. IANA Considerations 5067 This document has no actions for IANA. 5069 10. Contributors 5071 The following people contributed significantly to the previous 5072 versions of this document: 5074 - Jason Coleman (Cisco) 5076 11. Acknowledgments 5078 This document has benefited from reviews, suggestions, comments 5079 and proposed text provided by the following members, listed in 5080 alphabetical order: Andy Bierman, Bob Natale, Fred Feisullin, 5081 Georgios Karagiannis, Liu (Will) Shucheng, Marie-Jose Montpetit. 5083 12. References 5085 This section defines normative and informative references for this 5086 document. 5088 12.1. Normative References 5090 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5091 Requirement Levels", BCP 14, RFC 2119, March 1997. 5093 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for 5094 the Network Configuration Protocol (NETCONF)", 5095 RFC 6020, October 2010. 5097 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 5098 July 2013. 5100 12.2. Informative References 5102 [RFC3060] Moore, B., Ellesson, E., Strassner, J., Westerinen, 5103 A., "Policy Core Information Model -- Version 1 5104 Specification", RFC 3060, February 2001 5106 [RFC3198] Westerinen, A., Schnizlein, J., Strassner, J., 5107 Scherling, M., Quinn, B., Herzog, S., Huynh, A., 5108 Carlson, M., Perry, J., Waldbusser, S., "Terminology 5109 for Policy-Based Management", RFC 3198, November, 2001 5111 [RFC3460] Moore, B., ed., "Policy Core Information Model (PCIM) 5112 Extensions, RFC 3460, January 2003 5114 [1] Strassner, J., "Policy-Based Network Management", 5115 Morgan Kaufman, ISBN 978-1558608597, Sep 2003 5117 [2] Strassner, J., ed., "The DEN-ng Information Model", 5118 add stable URI 5120 [3] Riehle, D., "Composite Design Patterns", Proceedings 5121 of the 1997 Conference on Object-Oriented Programming 5122 Systems, Languages and Applications (OOPSLA '97). 5123 ACM Press, 1997, Page 218-228 5125 [4] DMTF, CIM Schema, v2.44, 5126 http://dmtf.org/standards/cim/cim_schema_v2440 5128 [5] Strassner, J., ed., "ZOOM Policy Architecture and 5129 Information Model Snapshot", TR235, part of the 5130 TM Forum ZOOM project, October 26, 2014 5132 [6] TM Forum, "Information Framework (SID), GB922 and 5133 associated Addenda, v14.5, 5134 https://www.tmforum.org/information-framework-sid/ 5136 [7] Liskov, B.H., Wing, J.M., "A Behavioral Notion of 5137 subtyping", ACM Transactions on Programming languages 5138 and Systems 16 (6): 1811 - 1841, 1994 5140 [8] Klyus, M., Strassner, J., Liu, W., Karagiannis, G., 5141 Bi, J., "SUPA Value Proposition", 5142 draft-klyus-supa-value-proposition-00, March 21, 2016 5144 [9] ISO/IEC 10746-3 (also ITU-T Rec X.903), "Reference 5145 Model Open Distributed Processing Architecture", 5146 April 20, 2010 5148 [10] Davy, S., Jennings, B., Strassner, J., "The Policy 5149 Continuum - A Formal Model", Proc. of the 2nd Intl. 5150 IEEE Workshop on Modeling Autonomic Communication 5151 Environments (MACE), Multicon Lecture Notes, No. 6, 5152 Multicon, Berlin, 2007, pages 65-78 5154 [11] Gamma, E., Helm, R., Johnson, R., Vlissides, J., 5155 "Design Patterns - Elements of Reusable Object-Oriented 5156 Software", Addison-Wesley, 1994, ISBN 0-201-63361-2 5158 [12] Strassner, J., de Souza, J.N., Raymer, D., Samudrala, 5159 S., Davy, S., Barrett, K., "The Design of a Novel 5160 Context-Aware Policy Model to Support Machine-Based 5161 Learning and Reasoning", Journal of Cluster Computing, 5162 Vol 12, Issue 1, pages 17-43, March, 2009 5164 [13] Liskov, B.H., Wing, J.M., "A Behavioral Notion of 5165 subtyping", ACM Transactions on Programming languages 5166 and Systems, 16 (6): 1811 - 1841, 1994 5168 [14] Martin, R.C., "Agile Software Development, Principles, 5169 Patterns, and Practices", Prentice-Hall, 2002, 5170 ISBN: 0-13-597444-5 5172 [15] Halpern, J., Strassner, J., "Generic Policy Data Model 5173 for Simplified Use of Policy Abstractions (SUPA)" 5174 draft-halpern-supa-generic-policy-data-model-01, 5175 April 15, 2016 5177 Authors' Addresses 5179 John Strassner 5180 Huawei Technologies 5181 2330 Central Expressway 5182 Santa Clara, CA 95138 USA 5183 Email: john.sc.strassner@huawei.com 5185 Joel Halpern 5186 Ericsson 5187 P. O. Box 6049 5188 Leesburg, VA 20178 5189 Email: joel.halpern@ericsson.com 5191 Appendix A. Brief Analyses of Previous Policy Work 5193 This appendix describes of some of the important problems with 5194 previous IETF policy work., and describes the rationale for 5195 taking different design decisions in this document. 5197 A.1. PolicySetComponent vs. SUPAPolicyStructure 5199 The ability to define different types of policy rules is not 5200 present in [RFC3060] and [RFC3460], because both are based on [4], 5201 and this ability is not present in [4]. [RFC3060], [RFC3460], and 5202 [4] are all limited to CA (condition-action) policy rules. In 5203 addition, events are NOT defined. These limitations mean that 5204 RFC3060], [RFC3460], and [4] can only represent CA Policy Rules. 5206 In contrast, the original design goal of SUPA was to define a 5207 single class hierarchy that could represent different types of 5208 policies (e.g., imperative and declarative). Hence, it was 5209 decided to make SUPAPolicyStructure generic in nature, so that 5210 different types of policies could be defined as subclasses. This 5211 enables a single Policy Framework to support multiple types of 5212 policies. 5214 A.2. Flat Hierarchy vs. SUPAPolicyComponentStructure 5216 Figure 26 shows a portion of the class hierarchy of [RFC3460]. 5218 A 5219 +--------+ 5220 | Policy | 5221 +----+---+ 5222 / \ 5223 | 5224 | 5225 +---------+------+------+------------+-----------+ 5226 | | | | | 5227 A | | A | | A | 5228 +-----+-----+ | +--------+--------+ | +------+-------+ 5229 | PolicySet | | | PolicyCondition | | | PolicyAction | 5230 +-----+-----| | +--------+--------+ | +------+-------+ 5231 / \ | / \ | / \ 5232 | | | | | 5233 ... | ... | ... 5234 A | A | 5235 +-------+--------+ +-------+-----+ 5236 | PolicyVariable | | PolicyValue | 5237 +-------+--------+ +-------+-----+ 5238 / \ / \ 5239 | | 5240 ... ... 5242 Figure 26. Simplified Class Hierarcy of [RFC3460] 5244 RFC3060], [RFC3460], and [4] defined PolicyConditions and 5245 PolicyActions as subclasses of Policy (along with PolicySet, 5246 which is the superclass of PolicyRules and PolicyGroups). This 5247 means that there is no commonality between PolicyConditions and 5248 PolicyActions, even though they are both PolicyRule components. 5249 From an object-oriented point-of-view, this is incorrect, since a 5250 PolicyRule aggregates both PolicyConditions and PolicyActions. 5252 In addition, note that both PolicyVariables and PolicyValues are 5253 siblings of PolicyRules, PolicyConditions, and PolicyActions. This 5254 is incorrect for several reasons: 5256 o a PolicyRule cannot rectly contain PolicyVariables or 5257 PolicyValues, so they shouldn't be at the same level of the 5258 class hierarchy 5259 o both PolicyConditions and PolicyActions can contain 5260 PolicyVariables and PolicyValues, which implies that both 5261 PolicyVariables and PolicyValues should be lower in the 5262 class hierarchy 5264 Note that in the current version of [4], PolicyVariable and 5265 PolicyValue are both deleted. There are other changes as well, 5266 but they are beyond the scope of this Appendix. 5268 The original design goal of SUPA was to define a single class 5269 hierarchy that could represent different types of policies and 5270 policy components. This cannot be accomplished in [RFC3460], since 5271 there is no notion of a policy component (or alternatively, 5272 PolicyCondition, PolicyAction, PolicyVariable, and PolicyValue are 5273 all components at the same abstraction level, which is clearly not 5274 correct). Hence, SUPA defined the SUPAPolicyComponentStructure 5275 class to capture the concept of a reusable policy component. 5277 In summary, SUPAPolicyStructure subclasses define the structure of 5278 a policy in a common way, while SUPAPolicyComponentStructure 5279 subclasses define the content that is contained in the structure 5280 of a policy, also in a common way. 5282 A.3. PolicyRules and PolicyGroups vs. SUPAPolicyRules 5284 A PolicySetComponent is an aggregation, implemented as an 5285 association class, that "collects instances of PolicySet 5286 subclasses into coherent sets of Policies". This is a recursive 5287 aggregation, with multiplicity 0..n - 0..n, on the PolicySet 5288 class. 5290 Since this is a recursive aggregation, it means that a PolicySet 5291 can aggregate zero or more PolicySets. This is under-specified, 5292 and can be interpreted in one of two ways: 5294 1. A PolicySet subclass can aggregate any PolicySet subclass 5295 (PolicyRules can aggregate PolicyRules and PolicyGroups, and 5296 vice-versa) 5297 2. PolicyRules can aggregate PolicyRules, and PolicyGroups can 5298 aggregate PolicyGroups, but neither class can aggregate the 5299 other type of class 5301 Both interpretations are ill-suited for policy-based management. 5302 The problem with the first is that if PolicyGroup is the mechanism 5303 for grouping, why can a PolicyRule aggregate a PolicyGroup? This 5304 implies that PolicyGroups are not needed. The problem with the 5305 second is that PolicyGroups cannot aggregate PolicyRules (which 5306 again implies that PolicyGroups are not needed). 5308 Furthermore, there are no mechanisms defined in the [RFC3460] 5309 model to prevent loops of PolicyRules. This is a problem, because 5310 EVERY PolicyRule and PolicyGroup inherits this recursive 5311 aggregation. 5313 This is why this document uses the composite pattern. First, this 5314 pattern clearly shows what object is aggregating what other 5315 object (i.e., a SUPAECAPolicyRuleAtomic cannot aggregate ability 5316 SUPAECAPolicyRuleComposite). Second, it does not allow ability 5317 SUPAECAPolicyRule to be aggregated by another SUPAECAPolicyRule 5318 (this is discussed more in the following subsection). 5320 A.3.1. Sub-rules 5322 Sub-rules (also called nested policy rules) enable a policy rule to 5323 be contained within another policy rule. These have very complex 5324 semantics, are very hard to debug, and provide limited value. They 5325 also require a complex set of aggregations (see section A.4.). 5327 The main reason for defining sub-rules in [RFC3460] is to enable 5328 "complex policy rules to be constructed from multiple simpler 5329 policy rules". However, the composite pattern does this much more 5330 efficiently than a simple recursive aggregation, and avoids the 5331 ambiguous semantics of a recursive aggregation. This latter point 5332 is important, because if PolicyRule and/or PolicyGroup is 5333 subclassed, then all subclasses still inherit this recursive 5334 aggregation, along with its ambiguous semantics. 5336 A.4. PolicyConditions and PolicyActions vs. SUPAECAComponent 5338 There is no need to use the SimplePolicyCondition and 5339 ComplexPolicyCondition objects defined in [RFC3460], since the 5340 SUPAPolicyComponentStructure uses the decorator pattern (see 5341 section 5.7) to provide more extensible types of conditions than is 5342 possible with those classes. This also applies for the 5343 SimplePolicyAction and the ComplexPolicyAction classes defined in 5344 [RFC3460]. 5346 More importantly, this removes the need for a complex set of 5347 aggregations (i.e., PolicyComponent, PolicySetComponent, 5348 PolicyConditionStructure, PolicyConditionInPolicyRule, 5349 PolicyConditionInPolicyCondition, PolicyActionStructure, 5350 PolicyActionInPolicyRule, and PolicyActionInPolicyAction). 5351 Instead, ANY SUPAECAComponent is defined as a decorator (i.e., a 5352 subclass of SUPAPolicyComponentDecorator), and hence, Any 5353 SUPAECAComponent is wrapped onto a concrete subclass of 5354 SUPAPolicyClause using the SAME aggregation 5355 (SUPAHasDecoratedPolicyComponent). This is a significantly simpler 5356 design that is also more powerful. 5358 A.5. The SUPAPolicyComponentDecorator Abstraction 5360 One of the problems in building a policy model is the tendency to 5361 have a multitude of classes, and hence object instances, to 5362 represent different combinations of policy events, conditions, and 5363 actions. This can lead to class and/or relationship explosion, as 5364 is the case in [RFC3460], [4], and [6]. 5366 For example, [RFC3460] defines five subclasses of PolicyCondition: 5367 PolicyTimePeriodCondition, VendorPolicyCondition, 5368 SimplePolicyCondition, CompoundPolicyCondition, and 5369 CompoundFilterCondition. Of these: 5371 o PolicyTimePeriodCondition is a data structure, not a class 5372 o VendorPolicyCondition represents a condition using two 5373 attributes that represent a multi-valued octet string 5374 o SimplePolicyCondition, CompoundPolicyCondition, and 5375 CompoundFilterCondition all have ambiguous semantics 5377 SimplePolicyCondition represents an ordered 3-tuple, in the form 5378 {variable, match, value}. However, the match operator is not 5379 formally modeled. Specifically, "the 'match' relationship is to 5380 be interpreted by analyzing the variable and value instances 5381 associated with the simple condition". This becomes problematic 5382 for several cases, such as shallow vs. deep object comparisons. 5383 More importantly, this requires two separate aggregations 5384 (PolicyVariableInSimplePolicyCondition and 5385 PolicyValueInSimplePolicyCondition) to associate variables and 5386 values to the SimplePolicyCondition, respectively. Since [RFC3460] 5387 defines all relationships as classes, this means that the 5388 expression "Foo > Bar" requires a total of FIVE objects (one each 5389 for the variable and value, one for the SimplePolicyCondition, and 5390 one each to associate the variable and value with the 5391 SimplePolicyCondition). 5393 This is exacerbated when SimplePolicyConditions are used to build 5394 CompoundPolicyConditions. In addition to the above complexity 5395 (which is required for each SimplePolicyCondition), a new 5396 aggregation (PolicyConditionInPolicyCondition) is required to 5397 aggregation PolicyConditions. Thus, the compound expression: 5398 "((Foo > Bar) AND (Foo < Baz))" requires a total of THIRTEEN 5399 objects (five for each of the terms being ANDed, plus one for the 5400 CompoundPolicyCondition, and two to aggregate each term to the 5401 CompoundPolicyCondition). 5403 Note that in the above examples, the superclasses of each of the 5404 relationships are omitted for clarity. In addition, [RFC3460] is 5405 built using inheritance; this means that if a new function is 5406 required, a new class must be built (e.g., CompoundFilterCondition 5407 is a subclass, but all it adds is one attribute). 5409 In constrast, the Decorator Pattern enables behavior to be 5410 selectively added to an individual object, either statically or 5411 dynamically, without having to build association classes. In 5412 addition, the decorator pattern uses composition, instead of 5413 inheritance, to avoid class explosion. This means that a new 5414 variable, value, or even condition class can be defined at 5415 runtime, and then all or part of that class can dynamically wrap 5416 an existing object without need for recompilation and 5417 redeployment. 5419 A.6. The Abstract Class "SUPAPolicyClause" 5421 This abstraction is missing in [RFC3060], [RFC3460], [4], and [6]. 5422 SUPAPolicyClause was abstracted from DEN-ng [2], and a version of 5423 this class is in the process of being added to [5]. However, the 5424 class and relationship design in [5] differs significantly from 5425 the corresponding designs in this document. 5427 SUPAPolicyClause further reinforces the different between a policy 5428 rule and a component of a policy rule by abstracting the content 5429 of a policy rule as a reusable object. This is fundamental for 5430 enabling different types of policy rules (e.g., imperative and 5431 declarative) to to be represented using the same constructs. 5433 A.7. Problems with the RFC3460 Version of PolicyVariable 5435 The following subsections define a brief, and incomplete, set of 5436 problems with the implementation of [RFC3460] (note that [RFC3060 5437 did not define variables, operators, and/or values). 5439 A.7.1. Object Bloat 5441 [RFC3460] used two different and complex mechanisms for providing 5442 generic get and set expressions. PolicyVariables were subclassed 5443 into two subclasses, even though they performed the same semantic 5444 function. This causes additional problems: 5446 o PolicyExplicitVariables are for CIM compatibility; note that 5447 the CIM does not contain either PolicyVariables or 5448 PolicyValues ([4]) 5449 o PolicyImplicitVariable subclasses do not define attributes; 5450 rather, they are bound to an appropriate subclass of 5451 PolicyValue using an association 5453 Hence, defining a variable is relatively expensive in [RFC3460], 5454 as in general, two objects and an association must be used. The 5455 objects themselves do not define content; rather, their names are 5456 used as a mechanism to identify an object to match. This means 5457 that an entire object must be used (instead of, for example, an 5458 attribute), which is wasteful. It also make it difficult to 5459 adjust constraints at runtime, since the constraint is defined in 5460 a class that is statically defined (and hence, requires 5461 recompilation and possibly redeployment if it is changed). 5463 A.7.2. Object Explosion 5465 The above three problems lead to class explosion (recall that in 5466 [RFC3060], [RFC3460], and [4], associations are implemented as 5467 classes). 5469 In contrast to this approach, the approach in this document keeps 5470 the idea of the class hierarchy for backwards compatibility, but 5471 streamlines the implementation. Specifically: 5473 1. The decorator pattern is an established and very used 5474 software pattern (it dates back to at least 1994 [11]). 5475 2. The use of a single association class 5476 (i.e., SUPAHasDecoratedPolicyComponentDetail) can represent 5477 more constraints than is possible in the approaches of 5478 [RFC3460] and [4] in a much more flexible manner, due to its 5479 function as a decorator of other objects. 5480 3. Note that there is no way to enforce the constraint matching 5481 in [RFC3460] and [6]; the burden is on the developer to 5482 check and see if the constraints specified in one class are 5483 honored in the other class. 5484 4. If these constraints are not honored, there is no mechanism 5485 specified to define the clause as incorrectly formed. 5487 A.7.3. Specification Ambiguities 5489 There are a number of ambiguities in [RFC3460]. 5491 First, [RFC3460] says: "Variables are used for building individual 5492 conditions". While this is true, variables can also be used for 5493 building individual actions. This is reflected in the definition 5494 for SUPAPolicyVariable. 5496 Second, [RFC3460] says: "The variable specifies the property of a 5497 flow or an event that should be matched when evaluating the 5498 condition." While this is true, variables can be used to test many 5499 other things than "just" a flow or an event. This is reflected in 5500 the SUPAPolicyVariable definition. 5502 Third, the [RFC3460] definition requires the use of associations 5503 in order to properly constrain the variable (e.g., define its 5504 data type, the range of its allowed values, etc.). This is both 5505 costly and inefficient. 5507 Fourth, [RFC3460] is tightly bound to the DMTF CIM schema [4]. 5508 The CIM is a data model (despite its name), because: 5510 o It uses keys and weak relationships, which are both concepts 5511 from relational algebra and thus, not technology-independent 5512 o It has its own proprietary modeling language 5513 o It contains a number of concepts that are not defined in UML 5514 (including overriding keys for subclasses) 5516 Fifth, the class hierarchy has two needless classes, called 5517 SUPAImplicitVariable and SUPAExplicitVariable. These classes do 5518 not define any attributes or relationships, and hence, do not 5519 add any semantics to the model. 5521 Finally, in [RFC3460], defining constraints for a variable is 5522 limited to associating the variable with a PolicyValue. This is 5523 both cumbersome (because associations are costly; for example, 5524 they equate to a join in a relational database management system), 5525 and not scalable, because it is prone to proliferating PolicyValue 5526 classes for every constraint (or range of constraints) that is 5527 possible. Therefore, in SUPA, this mechanism is replaced with 5528 using an association to an association class that defines 5529 constraints in a much more general and powerful manner (i.e., 5530 the SUPAHasDecoratedPolicyComponentDetail class). 5532 A.8. Problems with the RFC3460 Version of PolicyValue 5534 The following subsections define a brief, and incomplete, set of 5535 problems with the implementation of [RFC3460] (note that [RFC3060 5536 did not define variables, operators, and/or values). 5538 A.8.1. Object Bloat 5540 [RFC3460] defined a set of 7 subclasses; three were specific to 5541 networking (i.e., IPv4 Address, IPv6 Address, MAC Address) and 4 5542 (PolicyStringValue, PolicyBitStringValue, PolicyIntegerValue, and 5543 PolicyBooleanValue) were generic in nature. However, each of these 5544 objects defined a single class attribute. This has the same two 5545 problems as with PolicyVariables (see section 5.9.1.1): 5547 1. Using an entire object to define a single attribute is very 5548 wasteful and expensive 5549 2. It also make it difficult to adjust constraints at runtime, 5550 since the constraint is defined in a class that is statically 5551 defined (and hence, requires recompilation and possibly 5552 redeployment if it is changed). 5554 A.8.2. Object Explosion 5556 [RFC3460] definition requires the use of associations 5557 in order to properly constrain the variable (e.g., define its 5558 data type, the range of its allowed values, etc.). This is both 5559 costly and inefficient (recall that in [RFC3060], [RFC3460], and 5560 [4], associations are implemented as classes). 5562 A.8.3. Lack of Constraints 5564 There is no generic facility for defining constraints for a 5565 PolicyValue. Therefore, there is no facility for being able to 5566 change such constraints dynamically at runtime. 5568 A.8.4. Tightly Bound to the CIM Schema 5570 [RFC3460] is tightly bound to the DMTF CIM schema [4]. The CIM is 5571 a data model (despite its name), because: 5573 o It uses keys and weak relationships, which are both concepts 5574 from relational algebra and thus, not technology-independent 5575 o It has its own proprietary modeling language 5576 o It contains a number of concepts that are not defined in UML 5577 (including overriding keys for subclasses) 5579 A.8.5. Specification Ambiguity 5581 [RFC3460] says: It is used for defining values and constants used 5582 in policy conditions". While this is true, variables can also be 5583 used for building individual actions. This is reflected in the 5584 SUPAPolicyVariable definition. 5586 A.8.6. Lack of Symmetry 5588 Most good information models show symmetry between like components. 5589 [RFC3460] has no symmetry in how it defines variables and values. 5590 In contrast, this document recognizes that variables and values 5591 are just terms in a clause; hence, the only difference in the 5592 definition of the SUPAPolicyVariable and SUPAPolicyValue classes 5593 is that the content attribute in the former is a single string, 5594 whereas the content attribute in the latter is a string array. 5595 In particular, the semantics of both variables and values are 5596 defined using the decorator pattern, along with the attributes of 5597 the SUPAPolicyComponentDecorator and the 5598 SUPAHasDecoratedPolicyComponentDetail classes. 5600 Appendix B. Mathematical Logic Terminology and Symbology 5602 Appendix C. SUPA Logic Statement Information Model