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:
- The object permits the required operation.
- The user is authorized to execute the operation using the specified object.
- 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.
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.
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.
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:
We apply this user authorization model to the following:
- Three categories of users: Internal, LDAPLightweight Directory Access Protocol, and SSOSingle Sign-On users. SSOSingle Sign-On users are represented by expressions or by internal CORE users that represent them.
- Two categories of permissions: permissions to handle crypto objects and the partition housekeeping permissions.
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.
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:
- 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.
- A regular expression that identifies the SSOSingle Sign-On members of the group using personal information provided by the OIDCOpenID Connect is identity layer on top of the OAuth 2.0 protocol Provider.
- 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.
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.
A 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.
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 SOSecurity 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|
Complete set of permissions to manage keys, certificates, and secrets.
Complete set of permissions to manage all non-crypto elements.
Complete set of permission to perform crypto operations with all keys, certificates, and secrets.
- 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
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:
- 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.
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).
The assembly of permissions granted to an SSOSingle Sign-On user follows the same path but requires more planning because an SSOSingle Sign-On user may be specified using a combination of pattern-matching expressions that utilize the predetermined OIDCOpenID Connect is identity layer on top of the OAuth 2.0 protocol claims provided to CORE by the OIDCOpenID 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:
- The relevant PI claims
- The mandatory and optional character strings in the specified type of claim.
- The logic that combines all matches and produces the found / not found decision.
For example, the email address, the given name, and similar PI data.
For additional info regarding PI claims, see Claims and Scopes in a Nutshell.
ClaimPiece of information asserted about an Entity.: email address
Matching criteria: must include character string 112358.
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.
SSOSingle Sign-On expressions are the standard Regular Expressions that use the following elements:
<OIDCOpenID Connect is identity layer on top of the OAuth 2.0 protocol claim name>: <regular expression regarding the expected data in the claim>
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.
- 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.
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:
- To specify any person whose email claims to belong to the above department, we could use regex on any string notation:
- In the most general case, a regular expression applies certain AND / OR logic to the matched patterns.
(email: foo@dep\.company\.com)|(email: bar@dep\.company\.com)
To specify and test a regular expression, use online tools such as open-source Rustexp or similar online tools.
- A single expression
email:- specifies the type of PI claim that must be used to evaluate the expression.
.- (dot) means ANY SINGLE character.
.*- (dot followed by an asterisk) means any characters.
\.- (escaped dot) means the dot character itself.
- A or B expression
- Use the parenthesis
( )to separate each clause of compound expression.
- The "
|" symbol indicates logical OR.
- To specify A or B or C, use
- A and B expression
(?=A)(?=B)checks that both A and B conditions are met.
[0-9]*indicates any sequence of digits
- Disable Character Case Sensitivity
Any person with the @group.division.company.com email address:
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 email@example.com for malicious purposes.
Any person from one of the following groups and divisions:
email: .*@groupA\.divisionA\.company\.com)|(email: .*@groupB\.divisionB\.company\.com)
Any person from the group "A" that also has string 25519 in the subject (sub:) claim returned by the OIDCOpenID Connect is identity layer on top of the OAuth 2.0 protocol provider:
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.
By default, information received in the
email: claim is case insensitive.
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
- key group: <name of a signing keys group>
- operations: Sign, Verify
- Role: SIGNKEY-MAKER
- 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:
- Crypto objects. Groups of these objects are identified by crypto-group tags (see Crypto Object Groups),
- Non-crypto objects. Currently bundled into one all-inclusive group. To manage any non-crypto object in a partition, all you need is the SOSecurity officer - UKC partition administrator role. role among your roles.
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).
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.
- Generate a symmetric key or an asymmetric key pair.
- Import key material, certificate, or secret.
- Generate and store in CORE a new key by deriving it from the existing key material.
- Generate replacement (rotate) for a symmetric or asymmetric key. Keep the predecessor.
- Create a representation of a key in an External Keystore and obtain its metadata.
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.
- Export key material or certificate.
- Export secret material.
- Activate a created key or secret.
- Add a metadata attribute to a key.
- Modify the metadata attribute of a key.
- Delete the metadata attribute of a key.
- Change the content of secret data.
State Change Operations:
- Suspend and resume the use.
- Revoke key or secret use.
- Destroy the key or secret material. Keep its metadata.
- Completely erase the object from the CORE database.
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 data.
- Decrypt encrypted data.
- Tokenize data.
- Detokenize tokenized data.
- Generate signature.
- Verify the signature.
- MACMessage Authentication Code - for example, CMAC, GMAC, HMAC.-Create
- Create Message AuthenticationProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity. Code (MACMessage Authentication Code - for example, CMAC, GMAC, HMAC.).
- MACMessage Authentication Code - for example, CMAC, GMAC, HMAC.-Verify
- Verify Message AuthenticationProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity. Code (MACMessage Authentication Code - for example, CMAC, GMAC, HMAC.).
- Derive an ephemeral key. The derived key is not stored in the CORE.
All non-crypto objects in a partition are currently managed as one group of objects using one set of permissions defined in the static SOSecurity officer - UKC partition administrator role. role. To manage non-crypto objects, a user must have the SOSecurity officer - UKC partition administrator role. role or be a member of a user group that has the SOSecurity officer - UKC partition administrator role. role among its roles.
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.
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
defaultgroup cannot be revoked.
- When an object is created and tagged with a "<group-name>", it is also added to the "default" group.
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.
- The following create operations allow specifying membership in crypto groups (in addition to the mandatory membership in the default key group).
- The following creation methods preserve group membership of their origins:
- Object membership in crypto groups is listed when the object is shown.
- To update object membership, replace the current membership list with the updated one. Membership in the "default" group is permanent.
- To delete a membership in particular groups, use the Update method.