org.apache.geode.security.generator

## Class AuthzCredentialGenerator

- java.lang.Object
- - org.apache.geode.security.generator.AuthzCredentialGenerator

- Direct Known Subclasses:
    DummyAuthzCredentialGenerator, XmlAuthzCredentialGenerator

      public abstract class AuthzCredentialGenerator
      extends java.lang.Object

  Encapsulates obtaining authorized and unauthorized credentials for a given operation in a region. Implementations will be for different kinds of authorization scheme and authentication scheme combos.
  Since:
    GemFire 5.5

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `AuthzCredentialGenerator.ClassCode` Enumeration for various `AuthzCredentialGenerator` implementations.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected CredentialGenerator` | `generator` The `CredentialGenerator` being used.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AuthzCredentialGenerator()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract AuthzCredentialGenerator.ClassCode` | `classCode()` The `AuthzCredentialGenerator.ClassCode` of the particular implementation.
    `static AuthzCredentialGenerator` | `create(AuthzCredentialGenerator.ClassCode classCode)` A factory method to create a new instance of an `AuthzCredentialGenerator` for the given `AuthzCredentialGenerator.ClassCode`.
    `java.util.Properties` | `getAllowedCredentials(OperationContext.OperationCode[] opCodes, java.lang.String[] regionNames, int index)` Get a set of credentials generated using the given index allowed to perform the given `OperationContext.OperationCode`s for the given regions.
    `protected abstract java.security.Principal` | `getAllowedPrincipal(OperationContext.OperationCode[] opCodes, java.lang.String[] regionNames, int index)` Get a `Principal` generated using the given index allowed to perform the given `OperationContext.OperationCode`s for the given region.
    `abstract java.lang.String` | `getAuthorizationCallback()` The name of the `AccessControl` factory function that should be used as the authorization module on the server side.
    `CredentialGenerator` | `getCredentialGenerator()` Get the `CredentialGenerator` being used by this instance.
    `java.util.Properties` | `getDisallowedCredentials(OperationContext.OperationCode[] opCodes, java.lang.String[] regionNames, int index)` Get a set of credentials generated using the given index not allowed to perform the given `OperationContext.OperationCode`s for the given regions.
    `protected abstract java.security.Principal` | `getDisallowedPrincipal(OperationContext.OperationCode[] opCodes, java.lang.String[] regionNames, int index)` Get a `Principal` generated using the given index not allowed to perform the given `OperationContext.OperationCode`s for the given region.
    `protected abstract int` | `getNumPrincipalTries(OperationContext.OperationCode[] opCodes, java.lang.String[] regionNames)` Get the number of tries to be done for obtaining valid credentials for the given operations in the given region.
    `java.util.Properties` | `getSystemProperties()`
    `protected abstract java.util.Properties` | `init()` Initialize the authorized credential generator.
    `boolean` | `init(CredentialGenerator generator)` Initialize the authorized credential generator.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### generator

          protected CredentialGenerator generator

      The `CredentialGenerator` being used.

  - ### Constructor Detail

    - #### AuthzCredentialGenerator

          public AuthzCredentialGenerator()

  - ### Method Detail

    - #### create

          public static AuthzCredentialGenerator create(AuthzCredentialGenerator.ClassCode classCode)

      A factory method to create a new instance of an `AuthzCredentialGenerator` for the given `AuthzCredentialGenerator.ClassCode`. Caller is supposed to invoke `init(org.apache.geode.security.generator.CredentialGenerator)` immediately after obtaining the instance.
      Parameters:
        `classCode` - the `ClassCode` of the `AuthzCredentialGenerator` implementation
      Returns:
        an instance of `AuthzCredentialGenerator` for the given class code

    - #### init

          public boolean init(CredentialGenerator generator)

      Initialize the authorized credential generator.
      Parameters:
        `generator` - an instance of `CredentialGenerator` of the credential implementation for which to obtain authorized/unauthorized credentials.
      Returns:
        false when the given `CredentialGenerator` is incompatible with this authorization module.

    - #### getSystemProperties

          public java.util.Properties getSystemProperties()

      Returns:
        A set of extra properties that should be added to Gemfire system properties when not null.

    - #### getCredentialGenerator

          public CredentialGenerator getCredentialGenerator()

      Get the `CredentialGenerator` being used by this instance.

    - #### init

          protected abstract java.util.Properties init()
                                                throws java.lang.IllegalArgumentException

      Initialize the authorized credential generator. Required to be implemented by concrete classes that implement this abstract class.
      Returns:
        A set of extra properties that should be added to Gemfire system properties when not null.
      Throws:
        `java.lang.IllegalArgumentException` - when the `CredentialGenerator` is incompatible with this authorization module.

    - #### classCode

          public abstract AuthzCredentialGenerator.ClassCode classCode()

      The `AuthzCredentialGenerator.ClassCode` of the particular implementation.
      Returns:
        the `ClassCode`

    - #### getAuthorizationCallback

          public abstract java.lang.String getAuthorizationCallback()

      The name of the `AccessControl` factory function that should be used as the authorization module on the server side.
      Returns:
        name of the `AccessControl` factory function

    - #### getAllowedCredentials

          public java.util.Properties getAllowedCredentials(OperationContext.OperationCode[] opCodes,
                                                            java.lang.String[] regionNames,
                                                            int index)

      Get a set of credentials generated using the given index allowed to perform the given `OperationContext.OperationCode`s for the given regions.
      Parameters:
        `opCodes` - the list of `OperationContext.OperationCode`s of the operations requiring authorization; should not be null
        `regionNames` - list of the region names requiring authorization; a value of null indicates all regions
        `index` - used to generate multiple such credentials by passing different values for this
      Returns:
        the set of credentials authorized to perform the given operation in the given regions

    - #### getDisallowedCredentials

          public java.util.Properties getDisallowedCredentials(OperationContext.OperationCode[] opCodes,
                                                               java.lang.String[] regionNames,
                                                               int index)

      Get a set of credentials generated using the given index not allowed to perform the given `OperationContext.OperationCode`s for the given regions. The credentials are required to be valid for authentication.
      Parameters:
        `opCodes` - the `OperationContext.OperationCode`s of the operations requiring authorization failure; should not be null
        `regionNames` - list of the region names requiring authorization failure; a value of null indicates all regions
        `index` - used to generate multiple such credentials by passing different values for this
      Returns:
        the set of credentials that are not authorized to perform the given operation in the given region

    - #### getNumPrincipalTries

          protected abstract int getNumPrincipalTries(OperationContext.OperationCode[] opCodes,
                                                      java.lang.String[] regionNames)

      Get the number of tries to be done for obtaining valid credentials for the given operations in the given region. It is required that `getAllowedPrincipal(org.apache.geode.cache.operations.OperationContext.OperationCode[], java.lang.String[], int)` method returns valid principals for values of `index` from 0 through (n-1) where `n` is the value returned by this method. It is recommended that the principals so returned be unique for efficiency. This will be used by `getAllowedCredentials(org.apache.geode.cache.operations.OperationContext.OperationCode[], java.lang.String[], int)` to step through different principals and obtain a set of valid credentials. Required to be implemented by concrete classes that implement this abstract class.
      Parameters:
        `opCodes` - the `OperationContext.OperationCode`s of the operations requiring authorization
        `regionNames` - list of the region names requiring authorization; a value of null indicates all regions
      Returns:
        the number of principals allowed to perform the given operation in the given region

    - #### getAllowedPrincipal

          protected abstract java.security.Principal getAllowedPrincipal(OperationContext.OperationCode[] opCodes,
                                                                         java.lang.String[] regionNames,
                                                                         int index)

      Get a `Principal` generated using the given index allowed to perform the given `OperationContext.OperationCode`s for the given region. Required to be implemented by concrete classes that implement this abstract class.
      Parameters:
        `opCodes` - the `OperationContext.OperationCode`s of the operations requiring authorization
        `regionNames` - list of the region names requiring authorization; a value of null indicates all regions
        `index` - used to generate multiple such principals by passing different values for this
      Returns:
        the `Principal` authorized to perform the given operation in the given region

    - #### getDisallowedPrincipal

          protected abstract java.security.Principal getDisallowedPrincipal(OperationContext.OperationCode[] opCodes,
                                                                            java.lang.String[] regionNames,
                                                                            int index)

      Get a `Principal` generated using the given index not allowed to perform the given `OperationContext.OperationCode`s for the given region. Required to be implemented by concrete classes that implement this abstract class.
      Parameters:
        `opCodes` - the `OperationContext.OperationCode`s of the operations requiring authorization failure
        `regionNames` - list of the region names requiring authorization failure; a value of null indicates all regions
        `index` - used to generate multiple such principals by passing different values for this
      Returns:
        a `Principal` not authorized to perform the given operation in the given region