User Authorization

Note
In this section, we use the term "object" or "crypto-object" to indicate a key, secret, or certificate.

To execute a specific operation in the CORE system, the following preconditions must be met:

  1. The object permits the required operation.
  2. The user is authorized to execute the operation using the specified object.
  3. The partition's policy permits using the specified object type, the required operation, and the parameters the specified parameters of the operation.

This section focuses on #2.

Note
The CORE User Authorization applies to operations performed within the CORE servers. In particular, it doesn't apply to operations performed by CORE clients that perform data encryption or signature verification using public keys.

The objective of user authorization is to define the minimum set of permissions required by a user to carry out its function. In CORE, the set of permissions assigned to a user is defined by its membership in User Group(s) or, for backward compatibility, by the assigned Role.

At the highest level, the CORE authorization model looks as follows: a user may be a member of many User Groups. Each User Group ties up its members with a set of permissions granted to the group's members.

Authorization Model - High Level

Similar to the user group, permission ties up a group of objects and a set of operations that may be performed using or managing the objects in this group.

Authorization Model - Permission

For backward compatibility and more coarse management, we bundle a set of permissions into a Role. In particular, users generated in earlier releases remain associated with their roles. This requirement modifies the top-level model as follows: 

Authorization Model - Permissions bundled into Roles

We apply this user authorization model to the following:

The detailed model below combines all these elements. It also shows the categories of the objects and operations that are addressed by user authorization. The following sections address each block in the model.

User Group

A CORE partition user group ties up its members with a role or a set of roles granted to the group's members. A user group specifies:

Users
The list of internal CORE users that are members of this group.
Note: the default "user" may be assigned any role but it can't be a member of a user group.
Expression
A regular expression that identifies the SSOClosedSingle Sign-On members of the group using personal information provided by the OIDCClosedOpenID Connect is identity layer on top of the OAuth 2.0 protocol Provider.
Roles
The list of roles granted to the group members.

Permissions from all roles specified in a user group are granted to a member of a user group.

Note
To modify permissions in a role, you'll have to manage the role itself.

User groups are managed by the partition SOs using UI commands. See User Groups Tab.

Roles

CORE user role is a bundle of permissions. Roles are static and custom.

  • Static roles are created during the partition creation. They serve two groups of users: partition managers and crypto users by granting them unrestricted permissions in the relevant categories (see below).
  • A custom role allows granting a user the least privilege required to fulfill the required function.

Static Roles

The static roles are persistent - permissions specified in these roles can not be modified. By default, a partition is created with two static roles:

  • A static SOClosedSecurity officer - UKC partition administrator role. role with single permission that grants:
    • Management of all non-crypto elements in the partition.
    • Management of all crypto objects in the partition.
  • A static USER role with single permission that grants:
    • Management of crypto objects in the partition.
    • Unrestricted use of all applicable crypto operations using any crypto object.

The above points are summarized in the following table:

Static Role Use of Crypto Objects Management of Crypto Objects Management of Non-Crypto Elements

 

SOClosedSecurity officer - UKC partition administrator role.

 

NO permissions

 

 

Complete set of permissions to manage keys, certificates, and secrets.

Permissions to Manage Crypto Objects

Complete set of permissions to manage all non-crypto elements.

Permissions to Manage Non-Crypto Objects

 

USER

Complete set of permission to perform crypto operations with all keys, certificates, and secrets.

Permissions to Use Crypto Objects

 

NO permissions

  • Crypto Management Exceptions:
    • Management of the trusted key material is permitted to SOs only.
    • Key Management by the USER-role users may be blocked by the partition policy setting only-crypto.

    Custom Roles

    The CORE custom role enables implementing the principle of least privilege (PoLP) at the granularity of one key and one operation. As needed, you may specify a role that permits a single specific operation with a specific key.

    The custom roles are managed by the partition SOs using UI commands:

    • Create.
    • Modify - allows adding modifying or deleting permissions.
    • Delete a role once it is not referred to by users and not included in CORE user groups.

    See Roles Tab.

    User Permissions

    Internal User

    The complete list of permissions of Internal user (user authenticated by CORE) is assembled from the permissions granted by:

    • Its role.
    • Its membership in the partition's user group(s).

    SSO User

    The assembly of permissions granted to an SSOClosedSingle Sign-On user follows the same path but requires more planning because an SSOClosedSingle Sign-On user may be specified using a combination of pattern-matching expressions that utilize the predetermined OIDCClosedOpenID Connect is identity layer on top of the OAuth 2.0 protocol claims provided to CORE by the OIDCClosedOpenID Connect is identity layer on top of the OAuth 2.0 protocol provider. For example, it may deliver the email address of the authenticated user

    The received personal information (PI) claims are matched with the different users and groups in the different partitions and a list of authorized partitions with authorized permissions is created.

    A pattern-matching expression is defined using the following:

    1. The relevant PI claims
    2. For example, the email address, the given name, and similar PI data.

      Note
      For additional info regarding PI claims, see Claims and Scopes in a Nutshell.

    3. The mandatory and optional character strings in the specified type of claim.
    4. For example:

      ClaimClosedPiece of information asserted about an Entity.: email address

      Matching criteria: must include character string 112358.

    5. The logic that combines all matches and produces the found / not found decision.
    6. For example, email address A or email address B or any email address that contains character string 112358. The logic here is defined using the OR construct.

    SSO Expressions

    SSOClosedSingle Sign-On expressions are the standard Regular Expressions that use the following elements:

    <OIDCClosedOpenID Connect is identity layer on top of the OAuth 2.0 protocol claim name>: <regular expression regarding the expected data in the claim>

    Warning
    It is important to check that your regular expressions are securely written. Care should be taken to ensure that a malicious attacker cannot exploit them.

    For example:

    • Terminate the expression with a "$" so that extraneous characters cannot be added.
    • Ensure proper use of special characters, such as using "\." instead of just a "." to denote a period in an expression.

    Warning
    See here for more information about issues with regular expressions, and specifically the section on Potential Mitigations.

    To specify the matching criteria, use the standard Regular Expression syntax:

    • In its simplest form, the regular expression is the exact email address or a list of exact addresses. For example, an OR-list of two emails:
    • (email: foo@dep\.company\.com)|(email: bar@dep\.company\.com)

    • To specify any person whose email claims to belong to the above department, we could use regex on any string notation:
    • email:.*@dep\.company\.com$.

    • In the most general case, a regular expression applies certain AND / OR logic to the matched patterns.
    • Note
      To specify and test a regular expression, use online tools such as open-source Rustexp or similar online tools.

    Examples:

    1. A single expression
    2. Any person with the @group.division.company.com email address:

      email: .*@group\.division\.company\.com$

      Notes:

      1. email: - specifies the type of PI claim that must be used to evaluate the expression.
      2. . - (dot) means ANY SINGLE character.
      3. .* - (dot followed by an asterisk) means any characters.
      4. \. - (escaped dot) means the dot character itself.

      Warning
      It is important to check that the regular expression is secure. For example, if this regex did not have the trailing "$", an attacker could use an address such as foo@group.division.company.com.attacker.com for malicious purposes.

    3. A or B expression
    4. Any person from one of the following groups and divisions:

      (email: .*@groupA\.divisionA\.company\.com)|(email: .*@groupB\.divisionB\.company\.com)

      Notes:

      1. Use the parenthesis ( ) to separate each clause of compound expression.
      2. The "|" symbol indicates logical OR.
      3. To specify A or B or C, use (A)|(B)|(C).
    5. A and B expression
    6. Any person from the group "A" that also has string 25519 in the subject (sub:) claim returned by the OIDCClosedOpenID Connect is identity layer on top of the OAuth 2.0 protocol provider:

      (?=.*(email: .*@groupA\.divisionA\.company\.com))
      (?=.*(sub:[0-9]*25519[0-9]*))

      Notes:

      1. (?=A)(?=B) checks that both A and B conditions are met.
      2. [0-9]* indicates any sequence of digits
    7. Disable Character Case Sensitivity
    8. To disable sensitivity to character case (lowercase vs. uppercase), use the (?i) directive. For example, the following expression matches all <name.lastname>@company.com users from the Company regardless of the character cases in the provided subject.

      (?i)(sub:\w*\.\w*@COMPANY\.com)$

      Note
      By default, information received in the email: claim is case insensitive.

    Defining a Permission

    A CORE permission ties up a group of objects and a set of permitted operations.

    For example, create a SIGNER role with one permission that allows using a particular group of keys for signing and signature verification. You may define a different role (SIGKEY-MAKER) with one permission that allows managing keys used for signing.

    Role: SIGNER
    Permission:
    key group: <name of a signing keys group>
    operations: Sign, Verify
     
    Role: SIGNKEY-MAKER
    Permission:
    key group: <name a signing keys group>
    operations: Generate-KeyPair, Activate, Revoke, Delete

    You can assign users to these roles, and you may create a user group that combines both roles and allows its members to manage and use signing keys:

    User Group: SuSigners
    Role: SIGNER
    Role: SIGNKEY-MAKER

    Permission is not a managed element - each permission must be explicitly specified in a role by listing the permitted operations and a name (tag) that identifies CORE objects applicable to these operations. The CORE objects are divided into two types:

    For example, if the permissions of user "sign-maker" indicate that it is authorized to generate keys in group "sign-keys" only, then the user's attempt to generate a key in group "enc-keys" will be declined:

    ucl generate -t rsa --groups enc-keys -p test --user signer-maker -w Password1!

    Error (pkcs#11) 0x000000a0: Key generation failed
    Additional error information: User has no permissions to perform CreateKeyPair in groups [enc-keys], code=3, partition=test

    Similarly, if a user is attempting to carry not permitted operation in a group where it is permitted to operate (e.g. "sign-keys"), the attempt will be declined as well, now indicating the invalid operation instead of an invalid key group:

    ucl generate -t rsa --groups sign-keys -p test --user signer -w Password1!

    Error (pkcs#11) 0x000000a0: Key generation failed.
    Additional error information: User does not have permissions for operation CreateKeyPair, code=3, partition=test

    As noted in Static Roles, we classify all permissions into the following categories:

    • Permissions to manage crypto objects (keys, certificates, secrets).
    • Permissions to use crypto objects.
    • Permissions to manage partition's non-crypto objects (clients, users, groups, roles, and similar).

    Permissions to Manage Crypto Objects

    To manage a crypto-object using one of the following methods, the operation must be listed in a user's permission that applies to the object's group.

    Create Operations:

      Generate-Key
      Generate-KeyPair
      Generate a symmetric key or an asymmetric key pair.

      Note
      To start using a created key you will need to Activate it. Usually, this operation is listed in the same permission that grants Generate (Key or KeyPair) privilege.

      Import
      Import key material, certificate, or secret.
      Derive
      Generate and store in CORE a new key by deriving it from the existing key material.
      Re-key
      Re-keyPair
      Generate replacement (rotate) for a symmetric or asymmetric key. Keep the predecessor.
      Link
      Create a representation of a key in an External Keystore and obtain its metadata.

    Export Operations:

      Export-key
      Export key material or certificate.
      Export-secret
      Export secret material.

    Update Operations:

      Activate
      Activate a created key or secret.
      Attr-Add
      Add a metadata attribute to a key.
      Attr-Change
      Modify the specific metadata attribute of a key. See Note.
      Attr-List-Change
      Modify a group of metadata attributes of a key. See Note.
      Attr-Delete
      Delete the metadata attribute of a key.
      Change-secret
      Change the content of secret data.

    Note
    The Attr-List-Change permission has been introduced in the CORE version 2.0.2112. It will eventuality eliminate the need for a separate Attr-Change permission. In the meantime, both should be either allowed or forbidden.

    State Change Operations:

      Disable
      Enable
      Suspend and resume the use.
      Revoke
      Revoke key or secret use.
      Destroy
      Destroy the key or secret material. Keep its metadata.
      Delete
      Completely erase the object from the CORE database.

    Permissions to Use Crypto Objects

    To use a crypto-object in one of the following operations, the operation must be listed in a user's permission that applies to the object's group.

    Encrypt
    Encrypt data.
    Decrypt
    Decrypt encrypted data.
    Tokenize
    Tokenize data.
    Detokenize
    Detokenize tokenized data.
    Sign
    Generate signature.
    Verify
    Verify the signature.
    MACClosedMessage Authentication Code - for example, CMAC, GMAC, HMAC.-Create
    Create Message AuthenticationClosedProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity. Code (MACClosedMessage Authentication Code - for example, CMAC, GMAC, HMAC.).
    MACClosedMessage Authentication Code - for example, CMAC, GMAC, HMAC.-Verify
    Verify Message AuthenticationClosedProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity. Code (MACClosedMessage Authentication Code - for example, CMAC, GMAC, HMAC.).
    Derive-Ext
    Derive an ephemeral key. The derived key is not stored in the CORE.

    Permissions to Manage Non-Crypto Objects

    All non-crypto objects in a partition are currently managed as one group of objects using one set of permissions defined in the static SOClosedSecurity officer - UKC partition administrator role. role. To manage non-crypto objects, a user must have the SOClosedSecurity officer - UKC partition administrator role. role or be a member of a user group that has the SOClosedSecurity officer - UKC partition administrator role. role among its roles.

    Crypto Object Groups

    In CORE, the grouping of objects is implemented by assigning a group membership tag to an object.

    An object may be a member of multiple groups by possessing multiple group-name tags.

    Note
    An Objects Group is not a managed element in CORE. CORE doesn't create or manage object groups. Instead, the group membership is specified in the object's settings and in the permission that specifies operations permitted to this group.

    The order of referencing to a user group is not important - you may create permissions that see a name of a non-existing object group and then tag the required objects with the selected name. Or, you may tag objects with a group name that doesn't appear in any permission and then create permission that refers to this name.

    The name of an object group is a string of characters without spaces. See Key-group Name Characters.

    All objects are members of at least one group - the default group. It has the following properties:

    • The membership in the default group cannot be revoked.
    • When an object is created and tagged with a "<group-name>", it is also added to the "default" group.

    Crypto Group CRUD

    When a crypto object is created, it is automatically assigned to the "default" object group. You may also instantly assign it to the required groups or modify this list later.

    Create
    The following create operations allow specifying membership in crypto groups (in addition to the mandatory membership in the default key group).
    Generate-Key
    Generate-KeyPair
    Import
    Link
    The following creation methods preserve group membership of their origins:
    Derive
    Re-key
    Re-keyPair
    Read
    Object membership in crypto groups is listed when the object is shown.
    Update
    To update object membership, replace the current membership list with the updated one. Membership in the "default" group is permanent.
    Delete
    To delete a membership in particular groups, use the Update method.