developer_guide Quick Start Std

This section contains a Quick Start developer_guide for the Secure PVAccess Standard Authenticator.

Standard Authenticator is the default form of authentication supported by Secure PVAccess. It takes the username, organization, organizational unit, and country and uses them, without verification, to create X.509 certificates. These certificates are generated in the PENDING_APPROVAL state, so an SPVA network Administrator needs to APPROVE them before they will work.

Our starting point for this Quick Start Guide is the end of the Quick Start PVXS so if you haven’t gone through it yet do that now then come back here. The main difference here is that we’ll create users for the different roles we’ll be testing.

Other Quick Start Guides:

local_library You will learn

deployed_codePrepackaged

If you want a prepackaged environment, try the following. You will need four terminal sessions.

counter_1 Load image

  • computer¹

  • start new container with Prepackaged Secure PVAccess and 4 Users

docker run -it --name spva_std georgeleveln/spva_std:latest
2025-03-04 20:41:23,799 INFO Included extra file "/etc/supervisor/conf.d/pvacms.conf" during parsing
2025-03-04 20:41:23,802 INFO supervisord started with pid 1
2025-03-04 20:41:24,820 INFO spawned: 'pvacms' with pid 7
2025-03-04 20:41:25,957 INFO success: pvacms entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

counter_2 Administrator

  • computer²

  • log in as pre-configured Admin User, certificate is already configured

docker exec -it --user admin spva_std /bin/bash
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

counter_3 Service

  • computer³

  • log in as softioc service account

docker exec -it --user softioc spva_std /bin/bash
  • create a server certificate using the Standard Authenticator

authnstd -u server
Keychain file created   : /home/softioc/.config/pva/1.3/server.p12
Certificate identifier  : 47530d89:15756710596521133410

counter_4 Client

  • computer

  • log in as a Secure PVAccess client

docker exec -it --user client spva_std /bin/bash
  • create a client certificate using the Standard Authenticator

authnstd
Keychain file created   : /home/client/.config/pva/1.3/client.p12
Certificate identifier  : 47530d89:7450074183745406049

counter_5 Approve Certs

  • computer²

  • approve the server certificate

pvxcert --approve 47530d89:15756710596521133410
Approve ==> CERT:STATUS:47530d89:15756710596521133410 ==> Completed Successfully
  • approve the client certificate

pvxcert --approve 47530d89:7450074183745406049
Approve ==> CERT:STATUS:47530d89:7450074183745406049 ==> Completed Successfully

counter_6 Start SoftIOC

  • computer³

  • start SoftIOC

softIocPVX \
    -m user=test,N=tst,P=tst \
    -d ${PROJECT_HOME}/pvxs/test/testioc.db \
    -d ${PROJECT_HOME}/pvxs/test/testiocg.db \
    -d ${PROJECT_HOME}/pvxs/test/image.db \
    -G ${PROJECT_HOME}/pvxs/test/image.json \
    -a ${PROJECT_HOME}/pvxs/test/testioc.acf
INFO: PVXS QSRV2 is loaded, permitted, and ENABLED.
2025-03-04T20:51:56.413890180 WARN pvxs.tcp.init Server unable to bind TCP port 5075, falling back to [::]:41807
2025-03-04T20:51:56.413970847 WARN pvxs.tcp.init Server unable to bind TLS port 5076, falling back to [::]:33809
Starting iocInit
############################################################################
## EPICS R7.0.8.2-DEV
## Rev. R7.0.8.1-123-g48607a42586b1a316cd6
## Rev. Date Git: 2024-11-29 17:08:28 +0000
############################################################################
iocRun: All initialization complete
epics>

counter_7 Get PV value

  • computer

  • get a PV test:enumExample value from the SoftIOC

pvxinfo -v test:enumExample
Effective config
EPICS_PVA_AUTO_ADDR_LIST=YES
EPICS_PVA_BROADCAST_PORT=5076
EPICS_PVA_CONN_TMO=30
EPICS_PVA_SERVER_PORT=5075
EPICS_PVA_TLS_KEYCHAIN=/home/client/.config/pva/1.3/client.p12
EPICS_PVA_TLS_OPTIONS=on_expiration=fallback-to-tcp on_no_cms=fallback-to-tcp
EPICS_PVA_TLS_PORT=5076
XDG_CONFIG_HOME=/home/client/.config/pva/1.3
XDG_DATA_HOME=/home/client/.local/share/pva/1.3
# TLS x509:47530d89:7450074183745406049:EPICS Root Certificate Authority/softioc@172.17.0.2:33809
test:enumExample from 172.17.0.2:33809
struct "epics:nt/NTEnum:1.0" {
   struct "enum_t" {
       int32_t index
       string[] choices
   } value
   struct "alarm_t" {
       int32_t severity
       int32_t status
       string message
   } alarm
   struct "time_t" {
       int64_t secondsPastEpoch
       int32_t nanoseconds
       int32_t userTag
   } timeStamp
   struct {
       string description
   } display
}
  • verify that connection is TLS

    • TLS x509:47530d89:7450074183745406049:EPICS Root Certificate Authority/softioc @ 172.17.0.2 indicates that:

      • The connection is TLS,

      • The Server end of the channel has been authenticated by the Root Certificate Authority EPICS Root Certificate Authority

      • The Server end of the channel’s name has been authenticated as softioc and is connecting from host 172.17.0.2

checklist Step-By-Step

done_all Docker Image

counter_1 Use a Prepackaged pvxs image compiled with TLS enabled

  • computer¹

  • open a terminal and load pre-built image

docker run -it --name spva_std georgeleveln/pvxs:latest

done_all EPICS Agents

This section shows you what basic configuration you’ll need for each type of EPICS agent. Look at the environment variable settings and the file locations referenced by this configuration to understand how to configure EPICS agents in your environment.

counter_1 Set up environment

export XDG_DATA_HOME=${XDG_DATA_HOME-~/.local/share}
export XDG_CONFIG_HOME=${XDG_CONFIG_HOME-~/.config}
export PVXS_HOST_ARCH=$(${PROJECT_HOME}/epics-base/startup/EpicsHostArch)
export PATH="${PROJECT_HOME}/pvxs/bin/${PVXS_HOST_ARCH}:$PATH"

counter_2 Add PVACMS

  • add user and when prompted use “PVACMS” as Full Name

adduser pvacms
info: Adding user `pvacms' ...
info: Selecting UID/GID from range 1000 to 59999 ...
info: Adding new group `pvacms' (1001) ...
info: Adding new user `pvacms' (1001) with group `pvacms (1001)' ...
info: Creating home directory `/home/pvacms' ...
info: Copying files from `/etc/skel' ...
New password:
Retype new password:
passwd: password updated successfully
Changing the user information for pvacms
Enter the new value, or press ENTER for the default
    Full Name []: PVACMS
    Room Number []:
    Work Phone []:
    Home Phone []:
    Other []:
Is the information correct? [Y/n]
info: Adding new user `pvacms' to supplemental / extra groups `users' ...
info: Adding user `pvacms' to group `users' ...
  • set up environment for pvacms

su - pvacms
cat >> ~/.bashrc <<EOF
export XDG_DATA_HOME=\${XDG_DATA_HOME-~/.local/share}
export XDG_CONFIG_HOME=\${XDG_CONFIG_HOME-~/.config}
export PROJECT_HOME=/opt/epics
export PATH="\$(echo \${PROJECT_HOME}/pvxs/bin/*):$PATH"
cd ~
EOF

exit
logout

log back in as pvacms with environment set by .bashrc

su - pvacms
  • create admin certificate:

    • create PVACMS certificate database

      • creates database if does not exist

      • at location pointed to by EPICS_PVACMS_DB or ${XDG_DATA_HOME}/pva/1.3/certs.db by default

    • creates root Certificate Authority certificate if does not exist

      • creates root Certificate Authority certificate if does not exist,

      • at location specified by EPICS_CERT_AUTH_TLS_KEYCHAIN or ${XDG_CONFIG_HOME}/pva/1.3/cert_auth.p12 by default

      • with CN specified by EPICS_CERT_AUTH_NAME

      • with O specified by EPICS_CERT_AUTH_ORGANIZATION

      • with OU specified by EPICS_CERT_AUTH_ORGANIZATIONAL_UNIT

      • with C specified by EPICS_CERT_AUTH_COUNTRY

    • create the default ACF file that controls permissions for the PVACMS service

      • creates default ACF (or yaml) file

      • at location pointed to by EPICS_PVACMS_ACF or ${XDG_CONFIG_HOME}/pva/1.3/pvacms.acf by default

    • create the default admin client certificate that can be used to access PVACMS admin functions like REVOKE and APPROVE

      • creates default admin client certificate

      • at location specified by EPICS_ADMIN_TLS_KEYCHAIN or ${XDG_CONFIG_HOME}/pva/1.3/admin.p12 by default

pvacms --admin-keychain-new admin
Certificate DB created  : /home/pvacms/.local/share/pva/1.3/certs.db
Keychain file created   : /home/pvacms/.config/pva/1.3/cert_auth.p12
Created Default ACF file: /home/pvacms/.config/pva/1.3/pvacms.acf
Keychain file created   : /home/pvacms/.config/pva/1.3/admin.p12
exit
logout

counter_3 Add an Administrator

  • add user and when prompted use “ADMIN User” as Full Name

adduser admin
info: Adding user `admin' ...
info: Selecting UID/GID from range 1000 to 59999 ...
info: Adding new group `admin' (1002) ...
info: Adding new user `admin' (1002) with group `admin (1002)' ...
info: Creating home directory `/home/admin' ...
info: Copying files from `/etc/skel' ...
New password:
Retype new password:
passwd: password updated successfully
Changing the user information for admin
Enter the new value, or press ENTER for the default
    Full Name []: ADMIN User
    Room Number []:
    Work Phone []:
    Home Phone []:
    Other []:
Is the information correct? [Y/n]
info: Adding new user `admin' to supplemental / extra groups `users' ...
info: Adding user `admin' to group `users' ...
  • set up environment for administrator

su - admin
cat >> ~/.bashrc <<EOF
export XDG_DATA_HOME=\${XDG_DATA_HOME-~/.local/share}
export XDG_CONFIG_HOME=\${XDG_CONFIG_HOME-~/.config}
export PROJECT_HOME=/opt/epics
export PATH="\$(echo \${PROJECT_HOME}/pvxs/bin/*):$PATH"
cd ~
EOF

exit
logout
  • copy admin certificate from pvacms

mkdir -p ~admin/.config/pva/1.3
cp -pr ~pvacms/.config/pva/1.3/admin.p12 ~admin/.config/pva/1.3/client.p12
chown admin ~admin/.config/pva/1.3/client.p12
chmod 400 ~admin/.config/pva/1.3/client.p12

counter_4 Add a Secure PVAccess Server - SoftIOC

  • add user and when prompted use “SOFTIOC Server” as Full Name

adduser softioc
info: Adding user `softioc' ...
info: Selecting UID/GID from range 1000 to 59999 ...
info: Adding new group `softioc' (1003) ...
info: Adding new user `softioc' (1003) with group `softioc (1003)' ...
info: Creating home directory `/home/softioc' ...
info: Copying files from `/etc/skel' ...
New password:
Retype new password:
passwd: password updated successfully
Changing the user information for softioc
Enter the new value, or press ENTER for the default
    Full Name []: SOFTIOC Server
    Room Number []:
    Work Phone []:
    Home Phone []:
    Other []:
Is the information correct? [Y/n]
info: Adding new user `softioc' to supplemental / extra groups `users' ...
info: Adding user `softioc' to group `users' ...
  • set up environment for softioc server

su - softioc
cat >> ~/.bashrc <<EOF
export XDG_DATA_HOME=\${XDG_DATA_HOME-~/.local/share}
export XDG_CONFIG_HOME=\${XDG_CONFIG_HOME-~/.config}
export PROJECT_HOME=/opt/epics
export PATH="\$(echo \${PROJECT_HOME}/pvxs/bin/*):$PATH"
cd ~
EOF

exit
logout

counter_5 Add a Secure PVAccess Client

  • add user and when prompted use “SPVA client” as Full Name

adduser client
info: Adding user `client' ...
info: Selecting UID/GID from range 1000 to 59999 ...
info: Adding new group `client' (1004) ...
info: Adding new user `client' (1004) with group `client (1004)' ...
info: Creating home directory `/home/client' ...
info: Copying files from `/etc/skel' ...
New password:
Retype new password:
passwd: password updated successfully
Changing the user information for client
Enter the new value, or press ENTER for the default
    Full Name []: SPVA client
    Room Number []:
    Work Phone []:
    Home Phone []:
    Other []:
Is the information correct? [Y/n]
info: Adding new user `client' to supplemental / extra groups `users' ...
info: Adding user `client' to group `users' ...
  • set up environment for client

su - client
cat >> ~/.bashrc <<EOF
export XDG_DATA_HOME=\${XDG_DATA_HOME-~/.local/share}
export XDG_CONFIG_HOME=\${XDG_CONFIG_HOME-~/.config}
export PROJECT_HOME=/opt/epics
export PATH="\$(echo \${PROJECT_HOME}/pvxs/bin/*):$PATH"
cd ~
EOF

exit
logout

done_all Run PVACMS

counter_1 Login as pvacms in a new shell

  • computer²

  • in a different terminal log in as the pvacms user in the same container:

docker exec -it --user pvacms spva_std /bin/bash

counter_2 Run PVACMS

  • run pvacms:

    • create the pvacms server certificate

      • creates pvacms server certificate

      • at location specified by EPICS_PVACMS_TLS_KEYCHAIN or ${XDG_CONFIG_HOME}/pva/1.3/pvacms.p12 by default

    • start pvacms with verbose logging off

pvacms
Keychain file created   : /home/pvacms/.config/pva/1.3/pvacms.p12
PVACMS [46093d7c] Service Running

Note

46093d7c is the issuer ID which is comprised of the first 8 characters of the hex Subject Key Identifier of the certificate authority certificate. You will see this preceding all certificate identifiers from this PVACMS

Leave this PVACMS service running while running SoftIOC and SPVA client below.

done_all Run SoftIOC

counter_1 Login as softioc in a new shell

  • computer³

docker exec -it --user softioc spva_std /bin/bash

counter_2 Create Server Certificate

  • create a softioc server certificate

    • creates softioc server certificate

    • at location specified by EPICS_PVAS_TLS_KEYCHAIN or ${XDG_CONFIG_HOME}/pva/1.3/server.p12 by default

authnstd -u server \
  -n "IOC1" \
  -o "KLI:LI01:10" \
  --ou "FACET"
Keychain file created   : /home/softioc/.config/pva/1.3/server.p12
Certificate identifier  : 46093d7c:13415272142438558829

Note

Write down the certificate ID 46093d7c:13415272142438558829 (<issuer_id>:<serial_number>). You will need this ID to carry out operations on this certificate including APPROVING it.

counter_3 Verify that certificate is created pending approval

  • get the current status of a certificate

pvxcert 46093d7c:13415272142438558829
Certificate Status:
============================================
Certificate ID: 46093d7c:13415272142438558829
Status        : PENDING_APPROVAL
Status Issued : Sat Mar 08 12:31:11 2025 UTC
Status Expires: Sat Mar 08 13:01:11 2025 UTC
--------------------------------------------

counter_4 Login as admin in a new shell

  • computer

docker exec -it --user admin spva_std /bin/bash

counter_5 Approve certificate

pvxcert --approve 46093d7c:13415272142438558829
Approve ==> CERT:STATUS:46093d7c:13415272142438558829 ==> Completed Successfully

counter_6 Check the certificate status has changed

pvxcert 46093d7c:13415272142438558829
Certificate Status:
============================================
Certificate ID: 46093d7c:13415272142438558829
Status        : VALID
Status Issued : Sat Mar 08 12:31:50 2025 UTC
Status Expires: Sat Mar 08 13:01:50 2025 UTC
--------------------------------------------

counter_7 Run Secure PVAccess Service

  • computer³

  • back in the server shell start the service

softIocPVX \
    -m user=test,N=tst,P=tst \
    -d ${PROJECT_HOME}/pvxs/test/testioc.db \
    -d ${PROJECT_HOME}/pvxs/test/testiocg.db \
    -d ${PROJECT_HOME}/pvxs/test/image.db \
    -G ${PROJECT_HOME}/pvxs/test/image.json \
    -a ${PROJECT_HOME}/pvxs/test/testioc.acf
INFO: PVXS QSRV2 is loaded, permitted, and ENABLED.
2025-03-08T12:32:06.263544555 WARN pvxs.tcp.init Server unable to bind TCP port 5075, falling back to [::]:37961
2025-03-08T12:32:06.263601805 WARN pvxs.tcp.init Server unable to bind TLS port 5076, falling back to [::]:35093
Starting iocInit
############################################################################
## EPICS R7.0.8.2-DEV
## Rev. R7.0.8.1-123-g48607a42586b1a316cd6
## Rev. Date Git: 2024-11-29 17:08:28 +0000
############################################################################
iocRun: All initialization complete
epics>

done_all SPVA Client

counter_1 Login as client in a new shell

  • computer

docker exec -it --user client spva_std /bin/bash

counter_2 Create Certificate

  • create a client certificate

    • creates a client certificate

    • at location specified by EPICS_PVA_TLS_KEYCHAIN or ${XDG_CONFIG_HOME}/pva/1.3/client.p12 by default

authnstd -u client \
  -n "greg" \
  -o "SLAC.STANFORD.EDU" \
  --ou "Controls"
Keychain file created   : /home/client/.config/pva/1.3/client.p12
Certificate identifier  : 46093d7c:5283204721404445451

Note

Write down the certificate ID 46093d7c:5283204721404445451 (<issuer_id>:<serial_number>). You will need this ID to carry out operations on this certificate including APPROVING it.

counter_3 Approve certificate

  • computer

  • in the admin shell again, approve the certificate

pvxcert --approve 46093d7c:5283204721404445451
Approve ==> CERT:STATUS:46093d7c:5283204721404445451 ==> Completed Successfully

counter_4 Run an SPVA client

  • computer

  • back to the client shell again to get a value

pvxget -F tree test:structExample
test:structExample
    struct {
        struct {
            struct {
                int32_t queueSize = 0
                bool atomic = true
            } _options
        } record
        ...
        struct "epics:nt/NTScalar:1.0" {
            double value = 0
            struct "alarm_t" {
                int32_t severity = 2
                int32_t status = 1
                string message = "LOLO"
            } alarm
            struct "time_t" {
                int64_t secondsPastEpoch = 1741433438
                int32_t nanoseconds = 665740043
                int32_t userTag = 0
            } timeStamp
            struct {
                double limitLow = 0
                double limitHigh = 10
                string description = "Counter"
                string units = "Counts"
                int32_t precision = 0
                struct "enum_t" {
                    int32_t index = 0
                    string[] choices = {7}["Default", "String", "Binary", "Decimal", "Hex", "Exponential", "Engineering"]
                } form
            } display
            struct {
                double limitLow = 0
                double limitHigh = 10
                double minStep = 0
            } control
            struct {
                bool active = false
                double lowAlarmLimit = 2
                double lowWarningLimit = 4
                double highWarningLimit = 6
                double highAlarmLimit = 8
                int32_t lowAlarmSeverity = 0
                int32_t lowWarningSeverity = 0
                int32_t highWarningSeverity = 0
                int32_t highAlarmSeverity = 0
                double hysteresis = 0
            } valueAlarm
        } calc
    }
  • show that TLS is being used

pvxinfo -v test:enumExample
Effective config
EPICS_PVA_AUTO_ADDR_LIST=YES
EPICS_PVA_BROADCAST_PORT=5076
EPICS_PVA_CONN_TMO=30
EPICS_PVA_SERVER_PORT=5075
EPICS_PVA_TLS_KEYCHAIN=/home/client/.config/pva/1.3/client.p12
EPICS_PVA_TLS_OPTIONS=on_expiration=fallback-to-tcp on_no_cms=fallback-to-tcp
EPICS_PVA_TLS_PORT=5076
XDG_CONFIG_HOME=/home/client/.config/pva/1.3
XDG_DATA_HOME=/home/client/.local/share/pva/1.3
# TLS x509:46093d7c:13415272142438558829:EPICS Root Certificate Authority/softioc@172.17.0.2:35093
test:enumExample from 172.17.0.2:35093
struct "epics:nt/NTEnum:1.0" {
    struct "enum_t" {
        int32_t index
        string[] choices
    } value
    struct "alarm_t" {
        int32_t severity
        int32_t status
        string message
    } alarm
    struct "time_t" {
        int64_t secondsPastEpoch
        int32_t nanoseconds
        int32_t userTag
    } timeStamp
    struct {
        string description
    } display
}

Note

  • TLS x509:46093d7c:13415272142438558829:EPICS Root Certificate Authority/softioc @ 172.17.0.2 indicates that:

    • The connection is TLS,

    • The Server end of the channel has been authenticated by the Root Certificate Authority EPICS Root Certificate Authority

    • The Server end of the channel’s name has been authenticated as softioc and is connecting from host 172.17.0.2

done_all Permissions

counter_1 Security Configuration

  • field test:spec is defined in testioc.db and protected by the SPECIAL security group

...

record(ao, "$(user):spec") {
   field(ASG, "SPECIAL")
}
  • the SPECIAL security group protects test:spec in testioc.acf

    • it makes it writeable if, and only if

      • user is “michael” and

      • method is x509 - client has been authenticated using an X.509 certificate and

      • the certificate authority that signed the certificate was EPICS Root Certificate Authority

AUTHORITY(AUTH_EPICS_ROOT, "EPICS Root Certificate Authority")

UAG(OPERATORS) {
    "michael"
}

ASG(SPECIAL) {
    RULE(1,WRITE,TRAPWRITE) {
        UAG(OPERATORS)
            AUTHORITY(AUTH_EPICS_ROOT)
            METHOD("x509")
    }
}

counter_2 Security Enforcement

  • show that we can GET the value with or without TLS

pvxget test:spec -r value
test:spec
    value double = 0
env EPICS_PVA_TLS_KEYCHAIN= pvxget test:spec -r value
test:spec
    value double = 0
  • show that we cannot set (PUT) the value with, or without TLS if we are not identified as “michael”

pvxput test:spec 10
Error N4pvxs6client11RemoteErrorE : Put not permitted
env EPICS_PVA_TLS_KEYCHAIN= pvxput test:spec 10
Error N4pvxs6client11RemoteErrorE : Put not permitted

counter_3 Client Authorization

  • So we need to create a new certificate that will identify us as “michael”

export EPICS_PVA_TLS_KEYCHAIN=~/.config/pva/1.3/michael.p12
authnstd -n michael
Keychain file created   : /home/client/.config/pva/1.3/michael.p12
Certificate identifier  : b271f07a:4803259031245539247
  • computer

  • and ask our administrator to approve it

pvxcert --approve b271f07a:4803259031245539247
Approve ==> CERT:STATUS:b271f07a:4803259031245539247 ==> Completed Successfully
  • computer

  • show that we can set the value if

    • we are identified as “michael”

    • using an X.509 certificate

    • created by the EPICS Root Certificate Authority

   pvxput test:spec 10
   pvxget test:spec -r value

.. code-block:: console

    test:spec
        value double = 10