User roles

Edit online

IBM Digital Asset Offline Signing Orchestrator distinguishes between different types of user roles to complete their tasks. Roles that can operate against a component of the IBM Digital Asset Offline Signing Orchestrator need to authenticate through client certificates before they initiate the commands.

System Administrator

Edit online

The System Administrator (SYSADM1 and SYSADM2) sets up the LPAR partitions and create various components on those LPARS by using the bootstrap process.

A System Administrator SYSADM1 is responsible to:

Make sure that the prerequisites are met as per the OSO Appliance Installation procedure
Manage OSO Appliance infrastructure:
- Create LPAR1, LPAR2, LPAR3 Service Secure Containers.
- Configure hardware resources for LPARs.

A System Administrator SYSADM2 is responsible to:

Install OSO Appliance on all 3 lpars.
Set up the Linux Workstation.
Set up each HiperSocket.
Set up the initial VLAN configurations of the HiperSockets.
Configure Infrastructure details about LPAR1, LPAR2, and LPAR3 in bootstrap configuration file.
Trigger bootstrap command that will bring up various components like network, storage, logging, internal registry, and load container images to internal registry as needed on all lpars.
Share the necessary infrastructure information with OSO Admin.
Upgrade the oso image on our LPARS.
Deploy the conductor and notifies OSO Admin.
Undeploy the conductor whenever needed.
Upload SWID tags.
List/delete the sync servers present on the lpars.
Verify the recourse details like crypto, logging, network, registry, storage, VSI and appliance info by using Troubleshooting and Monitoring Commands.
Retrieve Offline Signing Orchestrator HPCR cert, oso-cli.tar file from the bundle, and to distribute to the auditor and operator.

SYSADM2 have access to the following commands:

Bootstrap commands:

# Standard bootstrap
1. oso-cli [-v] sa bootstrap <config_file> [--output <path>] [--env_file_path <path>]

Note:

Default output: conductor_config.yaml Default env_file_path: encrypted_env.yaml

# Image-only upgrade bootstrap
2. oso-cli [-v] sa bootstrap <config_file> [--output <path>] [--env_file_path <path>] --image-only --conductor-config <path>

# Upgrade bootstrap
3. oso-cli [-v] sa bootstrap <config_file> [--output <path>] [--env_file_path <path>] --upgrade --conductor-config <path> --import-config <path> [--image-upgrade]

# Bond-only configuration bootstrap
4. oso-cli [-v] sa bootstrap <config_file> [--output <path>] [--env_file_path <path>] --bond-only

# Encrypted environment only
5. oso-cli [-v] sa bootstrap <config_file> [--output <path>] [--env_file_path <path>] --enc-env

# Export LPAR configuration
6. oso-cli [-v] sa export <bootstrap_config>

Deploying and undeploying conductor:

oso-cli [-v] sa deploy-conductor —bootstrap-config <path> —shared-config <path> —encrypted-workload <path> [—encrypted-env <path>]
oso-cli [-v] sa undeploy-conductor —bootstrap-config <path> —shared-config <path>

Sync server commands:

oso-cli [-v] sa sync-server —bootstrap-config <path> —client-ca-cert <path> [—output <path>]

Note: Default output: sync_server_ca.txt

oso-cli [-v] sa delete-sync-server —bootstrap-config <path>

Troubleshooting & Monitoring Commands:

# Network Commands:
1. oso-cli [-v] sa network --bootstrap-config <path> devices [--lpar (lpar1|lpar2|lpar3)] [--type (hipersocket|other)]
2. oso-cli [-v] sa network --bootstrap-config <path> connections [--lpar (lpar1|lpar2|lpar3)] [--verbose]

# Storage Commands
1. oso-cli [-v] sa storage --bootstrap-config <path> list disk [--lpar (lpar1|lpar2|lpar3)] [--type (fcp|dasd)]
2. oso-cli [-v] sa storage --bootstrap-config <path> list pool [--lpar (lpar1|lpar2|lpar3)]
3. oso-cli [-v] sa storage --bootstrap-config <path> list pool disk [--lpar (lpar1|lpar2|lpar3)] --pool-id <pool_id>
4. oso-cli [-v] sa storage --bootstrap-config <path> add disk --lpar (lpar1|lpar2|lpar3) --disk-ids <disk_id1,disk_id2,...>

# VSI Commands
1. oso-cli [-v] sa vsi clean --bootstrap-config <path>
2. oso-cli [-v] sa vsi list --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)] [--vsi-name <name>] [--console]
3. oso-cli [-v] sa vsi vsi-networks --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)]

# Monitoring
1. oso-cli [-v] sa monitor —bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)] [--type (storage|cpu|memory)]

# Certificates
1. oso-cli [-v] sa certificate --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)] [—service (registry|logging|stunnel|hpcr|vendor)]

 # Crypto cards
1. oso-cli [-v] sa crypto --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)]

# Logging Configuration
1. oso-cli [-v] sa logging --bootstrap-config <path>

# Network Commands
1. oso-cli [-v] sa network devices --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)] [--type (hipersocket|other)]
2. oso-cli [-v] sa network connections --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)] [--verbose]

# Registry Images
1. oso-cli [-v] sa registry --bootstrap-config <path> [--image <image_name>]

# Appliance Information
1. oso-cli [-v] sa appliance --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)]

# Data Volumes
1. oso-cli [-v] sa datavolume --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)]

# Port Mappings
1. oso-cli [-v] sa portmap --bootstrap-config <path> [--lpar (lpar1|lpar2|lpar3)]

OSO Administrator

Edit online

OSO Administrator is responsible for creating a conductor workload and this will be used to bring up our conductor.

Configures conductor workload by getting all the necessary information from various users such as OSO Operator, OSO Auditor, and Plugin Owners.
Triggers conductor workload command to generate encrypted workload contract and shares to sscadm2.
Shares information like certificate to other users, enabling them to perform their operations.
```
oso-cli [-v] sa conductor-workload [config] --hpcr-cert [path] --oso-config [path]
```
Note: Default output: encrypted_workload.txt

OSO Operator

Edit online

The Operator has access to view the Digital Assert Offline Signing Orchestrator information and manage signing iterations. An Operator is responsible for:

Secure communication between the API’s Operator needs to create a cacert and needs to share with auditor for their use.
Starting a signing iteration.
Flushing all existing data to reset the state of the components back to the post-init state.
Verifying the status of Conductor.
Getting the ILMTs reports.
Executing all kind of change request commands.

The Operator can access the following commands:

oso-cli operator —cert CERT —key KEY (-i | —cacert CACERT) [-v] cacert -f <file>
oso-cli operator -v —cert CERT —key KEY (-i | —cacert CACERT) run [—allow_empty]
oso-cli operator —cert CERT —key KEY (-i | —cacert CACERT) [-v] flush
oso-cli operator —cert CERT —key KEY (-i | —cacert CACERT) [-v] status
oso-cli operator —cert CERT —key KEY (-i | —cacert CACERT) [-v] ilmts
      
 Change Request:

  oso-cli operator --cert CERT --key KEY (-i | --cacert CACERT) [-v] cr create dr backup --datavolumes <vol1> [vol2...] —client-ca-cert <path>

 oso-cli operator --cert CERT --key KEY (-i | --cacert CACERT) [-v] cr create dr restore --datavolumes <vol1> [vol2...] --source <ip> --server-ca-cert <path>

 oso-cli operator --cert CERT --key KEY (-i | --cacert CACERT) [-v] cr create dump --reason <reason> [--lpar (lpar1|lpar2|lpar3)]

Note: < Default: lpar3>

oso-cli operator --cert CERT —key KEY (-i | --cacert CACERT) [-v] cr get
oso-cli operator --cert CERT —key KEY (-i | --cacert CACERT) [-v] cr dr-info
oso-cli operator --cert CERT —key KEY (-i | --cacert CACERT) [-v] cr approve [--comment <comment>]
oso-cli operator --cert CERT —key KEY (-i | --cacert CACERT) [-v] cr deny <reason>
oso-cli operator --cert CERT —key KEY (-i | --cacert CACERT) [-v] cr complete
oso-cli operator --cert CERT --key KEY (-i | --cacert CACERT) [-v] cr run
oso-cli operator --cert CERT --key KEY (-i | --cacert CACERT) [-v] cr download-dump [--lpar (lpar1|lpar2|lpar3)] [--output <path>]

Note:

< Default lpar: lpar3 Default output: <lpar>dump<timestamp>.tar.gz>

OSO Auditor

Edit online

OSO Auditor can access the documents on the pre confirmation queues:

OSO Auditor can approves / denies the documents in the pre/post confirmation queue
Listing the documents present in the pre/post confirmation queue
Get the details about the particular document in the pre/post confirmation queue

OSO Auditor has access to the following commands:

oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] pre list
oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] pre get <document_id>
oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] pre approve <document_id> [document_id...] [—comment <comment>]
oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] pre deny <document_id> [document_id...] [—comment <comment>]
oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] post list
oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] post get <document_id>
oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] post approve <document_id> [document_id...] [—comment <comment>]
oso-cli audit —cert CERT —key KEY (-i | —cacert CACERT) [-v] post deny <document_id> [document_id...] [—comment <comment>]

System Custodian

Edit online

System Custodian is responsible for creating the certificates and distributing across the Operator, Auditor, and system admin.

A System Custodian can:

Create certificates on their own way or system custodian can use script file on the bundle to create.
```
contracts/certificates/create-user-certs.sh
 
```

Plugin Custodian

Edit online

A Plugin Custodian is responsible for creating the frontend and backend workloads by using their own plugins or by using our testend.

Note:

Where:

[] → optional parameter

<> → replace with actual value

() → choose either one from the group

| → OR (alternative options)

Notes → has defaults

Note:

[-v] flag enables verbose output for debugging
(-i | --cacert) allows auto-fetch (-i) or manual CA cert path (—cacert)
All SA commands require --bootstrap-config parameter
LPAR choices are always: lpar1, lpar2, or lpar3
Frontend and IPTables commands are for local/development use only
CR (Change Request) operations require approval workflow
Storage pool operations use comma-separated disk IDs
Network type choices: hipersocket or other
Storage type choices: fcp or dasd
Monitor type choices: storage, cpu, or memory
Certificate service choices: registry, logging, stunnel, hpcr, or vendor

Users and roles for OSO appliance deployment

Edit online

The following roles are involved in the OSO appliance deployment:

Table 1. Users and roles
Users	Roles
acsadmin	Defines HMC users and manages resources and tasks allowed for sscadm1, sscadm2.
sscadm1	Makes sure that the prerequisites are met as per the OSO Appliance Installation procedure. Manages OSO Appliance infrastructure: Creates LPAR1, LPAR2, LPAR3 Service Secure Containers. Configures hardware resources for LPARs.
sscadm2	As an OSO Appliance administrator, sscadm2: Sets its credentials for all 3 lpars. Installs OSO Appliance on all 3 lpars. Sets up the Linux Workstation. Configures Infrastructure details about LPAR1, LPAR2, and LPAR3 in bootstrap configuration file. Triggers bootstrap command that will bring up various components like network, storage, logging, internal registry, and load container images to internal registry as needed on all lpars. Shares the necessary infrastructure information with OSO Admin. Deploys the conductor and notifies OSO Admin. Uploads SWID tags.
OSO Admin	Sets up the Linux Workstation. Configures conductor workload by getting all the necessary information from various users such as OSO Operator, OSO Auditor, and Plugin Owners. Triggers conductor workload command to generate encrypted workload contract and shares to sscadm2. Shares information like certificate to other users, enabling them to perform their operations.
OSO Operator	Performs the flush operation. Triggers the signing iteration. Performs backup and restore operations. Collects diagnostic dumps from LPAR1 and LPAR2 using the `oso-cli sa dump` command. Fetches the ILMT scan report.
OSO Auditor	Approves or denies the documents.
System Custodian	Creates certificates or uses own certificates.
Plugin Custodian	Plugin custodian must have the testend/ folder to generate the contracts to get access to the code, image, ccrv, image sha, and certs. sscadm2 must grant access to the testend folder and provide sha and certs.