Operation

Setting Up the oxi CLI

Many administrative commands require authentication via an EC key pair. This step is required once per user.

Create a Key Pair

oxi cli create

# Output:
#     Please enter password to encrypt the key (empty to skip):
#     Please retype password:
#     ---
#     id: YIDR0GocM-e78JPI9dXoaDBYJxKiV2bE7Cy72ErFjg4
#     private: |
#         -----BEGIN EC PRIVATE KEY-----
#         ....
#         -----END EC PRIVATE KEY-----
#     public: |
#         -----BEGIN PUBLIC KEY-----
#         .....
#         -----END PUBLIC KEY-----

Register the Public Key

Add the public key to config.d/system/cli.yaml:

auth:
    admin:
        key: |
            -----BEGIN PUBLIC KEY-----
            MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
            -----END PUBLIC KEY-----
        role: RA Operator

The name (admin) is used for logging purposes only. The role determines which API commands may be executed.

Deploy the Private Key

Place the private key at ~/.oxi/client.key:

mkdir -p ~/.oxi && chmod 700 ~/.oxi
# Paste the private key from the oxi cli create output:
cat > ~/.oxi/client.key << 'EOF'
-----BEGIN EC PRIVATE KEY-----
...
-----END EC PRIVATE KEY-----
EOF
chmod 600 ~/.oxi/client.key

Alternatively: oxi --auth-key /path/to/key.key <command>

Connection Test

oxi cli ping
# Expected output:
# ---
# result: ok

Note: The OS user must be a member of the openxpkiclient group to access the backend socket.

Setting Up the Datavault Token

The datavault token encrypts sensitive data in the datapool (e.g. private keys). It must be set up before all other tokens.

Option 1: Symmetric Vault (recommended from v3.32)

Generate a 64-character hex key and enter it in config.d/system/crypto.yaml:

openssl rand -hex 32
# Output: a3f7c2...  (64 hex characters)

Enter the key in config.d/system/crypto.yaml under secret.svault.value:

secret:
    svault:
        label: Secret group for datavault encryption
        method: literal
        value: <enter 64-character hex key here>

Important: Keep this key in a safe place — it cannot be recovered. If lost, all encrypted data becomes permanently inaccessible.

Option 2: Asymmetric Vault (key on filesystem)

Create the key and certificate:

mkdir -p -m755 /etc/openxpki/local/keys
cd /etc/openxpki/local/keys

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -aes-256-cbc \
    -out vault-1.pem

openssl req -config /etc/openxpki/contrib/vault.openssl.cnf -x509 -days 365 \
    -key vault-1.pem -out vault-1.crt

chmod 400 vault-1.pem
chown openxpki:openxpki vault-1.pem

Import the certificate and register it as a token:

oxi certificate add --cert vault-1.crt
oxi token add --realm democa --type datasafe --cert vault-1.crt

Token functional test:

oxi api get_token_info --realm democa -- alias=datasafe-1
# key_usable: 1 must appear in the output

Setting Up CA Tokens

Import the Root CA

In a two-tier hierarchy, import the root CA certificate first:

oxi token add --realm rootca --type certsign --cert rootca.crt

If you have multiple root CAs, import all of them. Intermediate certificates without their own token are imported with oxi certificate add. Always start with the self-signed root.

Set Up the Issuing CA

Issuing CA keys and certificates must be created externally. Recommended tool: clca

Keys stored in the database (default):

oxi token add --realm democa --type certsign \
    --cert issuingca.crt --key issuingca.key

The command imports the certificate, encrypts the private key, and stores it in the datapool. The output shows the generated alias (on initial setup: ca-signer-1).

Keys stored on the filesystem:

Place the key in /etc/openxpki/local/keys/<realm>/ (permissions: 0400, owner: openxpki), then:

oxi token add --realm democa --type certsign --cert issuingca.crt
# without --key, since the key is on the filesystem

Verify the Token List

oxi token list --realm democa
# Output:
# ---
# token_groups:
#   ca-signer:
#     active: ca-signer-1
#     count: 1
#     token:
#     - key_usable: 1
#       key_store: DATAPOOL

Functional Test: Create a CRL

oxi workflow create --realm democa --type crl_issuance
# state: SUCCESS confirms the signing token is working

Setting Up the SCEP/RA Token

The SCEP token is a TLS server certificate that serves as the SCEP RA signing token:

oxi token add --realm democa --type scep \
    --cert ratoken.crt --key ratoken.key

Note: Each realm needs its own SCEP token. The same certificate can be used in multiple realms.

Token Rollover

When a token expires or is compromised, add a new one. OpenXPKI manages tokens via generation numbers:

# Add a new issuing CA token (automatically receives the next generation number)
oxi token add --realm democa --type certsign \
    --cert newissuingca.crt --key newissuingca.key

# Verify the token list after import
oxi token list --realm democa

The new token is automatically set as the active token. Certificates issued under the old token remain associated with it (important for CRL issuance).

Status and Diagnostics

Check Token Status

# List all tokens in a realm
oxi token list --realm democa

# Detailed info for a specific token
oxi api get_token_info --realm democa -- alias=ca-signer-1

System Status

# Test backend connectivity
oxi cli ping

# Run the system status workflow
oxi workflow create --realm democa --type status_system