-
Notifications
You must be signed in to change notification settings - Fork 6
Home
Power Code Signing Process
Version 9.0
Author: Chris Engel
- Chris Engel
- Subramanian Swaminathan
- Tim Block
- Dave Heller
- Matt Vaught
- Ken Goldman
- Support remote code signing and project audit capability
- Provide a simple and secure process that can be used by op-build, FSP build and OEMs to sign code.
- As much as possible use existing Linux tools
- Support for x86_64 as well as ppc64el Linux
- Validate authentication of person requesting the code signing
- Accomplished with two step operation of ssh keys and ssh key passphrase used to access signing server. The ssh key passphrase MUST be entered in by the signer for each request and not stored in a file.
- Validate authority of person requesting the code signing to the project keys requested
- Accomplished with ssh keys used to access signing server which is correlated to a specific signer. Then the signer access rights are verified against the project configuration
- Encrypted password for HSM card also used to validate authority
- Log all signing requests for later auditing. Project auditors can retrieve the logs or can be setup to receive them periodically
- Notification sent to project auditors for all signing requests
- Automated access removal through LDAP lookup of signer by signing framework for each request.
The signing framework design uses SFTP and chroot jails to limit access to the signing server by the signers. The SFTP protocol is then used to upload a request to the signing server dropbox which is being monitored by the signing server framework. When the framework sees a new request it will perform all required validations and authorizations and then proceed to perform the signing request. When the framework completes the request it stores the result back in the dropbox for the signer to download via SFTP.
Illustration 1: Signing Process Flow
- Target platform is Linux
- The framework is single threaded and processes requests serially
- Each signer has their own unique dropbox
- There is currently no requirement to encrypt the request and response JSON on the build server
- The signing program uses an IBM 4767 coprocessor to perform the signature operation
- The IBM 4767 is a tamper responding secure crypto coprocessor. Signing keys are generated on the card and never leave the card in plaintext.
The following roles have been defined such that access to the signing server(s) is limited as follows:
- Signing server system administrator: server root access and CCA GUI access
- CCA administrators: temporary root access & CCA GUI access, removed after Master Key generation, before signing key generation
- Signing framework developer/project administrator: signframework source and configuration file change access
- Signing project auditor: audit project read access
- CCA signers: signing project signature permissions
- Signing server system administrator
- Provides support of signing server system and OS updates/patches
- Has local console root login access to signing server framework
- System/framework backup and recovery procedures
- Control signing requestor access to signing server (See section Signing server administrator steps)
- Create/revoke platform linux user accounts
- Generate CCA signer role and profiles
- Manage review/revocation of CCA signers
- Setup SSH keys for signer dropbox support
- Create new project keys using framework tools (See section Create New Project)
- Has CCA administrator access
- Must NOT have access to the HSM master keys
- With root authority to the signing server this person could modify the framework to sign whatever they want. Because of this they must be trusted
- Master key holders
- CCA administrator access during master key setup phase
- Hold copies of the master keys for the HSM
- USB stick and hard copy with 1st line management awareness/access
- The master key holders must NOT have access to signing keys
- Signing framework developer/project administrator
- Maintains framework and signing programs
- Maintains project configurations
- Grants signers access to project keys (as requested by signing project auditor)
- Has framework dropbox access through SFTP
- Must use a unique passphrase protected SSH keypair. Private key passphrase MUST NOT be stored in a filesystem and must be manually entered for each request
- With control of the signing framework code and project configurations this person could modify the framework to sign whatever they want. Because of this they must be trusted
- Signing project auditor
- Monitors project audit logs and configuration
- Archive of project logs on 90 day rotation
- Request add/remove of projects and signers
- Communicate project info to project administrator
- Backup plaintext public and master key encrypted private portions of the signing key
- Could be stored with framework configuration source code repository (as long as master key holders don't have access)
- Monitor changes to signing framework and configuration files done by the framework developer
- Has framework dropbox access through SFTP
- Must use a unique passphrase protected SSH keypair. Private key passphrase MUST NOT be stored in a filesystem and must be manually entered for each request
- CCA signers
- Small controlled list of users with authority to request production code signing
- Common build ids are not allowed to be used for signing. Must be able to correlate sign requestor id to individual who requested it
- Has framework dropbox access through SFTP
- Must use a unique passphrase protected SSH keypair. Private key passphrase MUST NOT be stored in a filesystem and must be manually entered for each request
- Has encrypted CCA password which can be placed in the filesystem with authority such that only the signer has read authority
- The signing server system administrator is a system trust anchor. A compromised administrator can, for example, rewrite and install programs that remove authentication and authorization checks, or tamper with audit logs. The administrator could grant additional signers and has access to encrypted passwords in the dropbox and project files so could impersonate any signer.
- The signing framework developer is a system trust anchor. A compromised developer can, for example, rewrite and install programs that remove authentication and authorization checks, or tamper with audit logs. The administrator could grant additional signers and has access to encrypted passwords in the dropbox and project files so could impersonate any signer.
- The signers SSH private key, key passphrase and encrypted password are project trust anchors. An attacker could brute force a signer's password and key passphrase on a build machine to obtain these and assume the identity of the signer.
- The builder is a trusted entity. The builder has the authority to sign any image without the need for any approvals and as such must be trusted. Project auditors will receive notification and can audit the signing logs after the request has been completed.
The design includes several features to support remote administration. The overall philosophy is “extensive remote read, zero remote write.”
- Authorized users are automatically removed when they leave IBM.
- Project managers are automatically polled periodically to confirm authorized users for each project. The list can be viewed at any time.
- Audit logs are pushed to project managers periodically and automatically. They can be viewed by anyone at any time.
- Server administrators can view each request and response at any time.
- A list of people can receive an alert each time a signing event occurs.
- Configuration files can be read to aid in debug.
- Each project has a remotely enabled verbose mode, where extensive tracing is returned to aid in debug.
- The overall signer framework has a manually enabled verbose mode to aid in framework debug.
- The signer framework does extensive validation of configuration at startup, so that errors can be detected while the administrator is local.
Illustration 2: Signing Dropbox Flow
- On the build server the signer generates a unique identifier for this signing transaction (ex: <hostname>_<timestamp>)
- Signer generates a JSON request structure containing required fields. Details of the request structure are defined in JSON Format
- The request JSON is stored in a file on the build machine. The name of the file is <IDENTIFIER>.request.
- Signer uploads the JSON file to the signing server using SFTP (ex: echo “put asdf_12345.request” | sftp argus1.rch.stglabs.ibm.com:dropbox/)
- Signer uploads an empty file to notify the signing server to execute the request. The use of the .go file is to ensure the entire request (or response later) has been written before the server or client access the request file (ex: echo “put asdf_12345.request.go” | sftp argus1.rch.stglabs.ibm.com:dropbox/)
- Because of the signing server setup these files will be uploaded to the chroot jail associated with the id of the signer
- The signer may now repeat steps 2-7 for additional signing requests or continue on to wait for the result
- The signing framework will monitor all the known dropboxes on the system looking for unprocessed requests
- When a new request is detected the framework maps the specific dropbox to the signers userid and proceeds to validate the users authorization to the project
- Optionally: The framework may do an LDAP lookup to validate the signing user
- The framework parses the request JSON and makes a call into the code-signing program
- The code-signing program signs the code with the project specific signing key
- The framework packages the result into a JSON response and stores in the signers dropbox with the filename <IDENTIFIER>.response and then creates the empty go file <IDENTIFIER>.response.go. Details of the response structure are define in JSON Format
- The signer on the build server is polling waiting for the signing response (ex: echo “get asdf_12345.response.go” | sftp argus1.rch.stglabs.ibm.com:dropbox/)
- When the go is available the signer downloads the response (ex: echo “get asdf_12345.response “ | sftp argus1.rch.stglabs.ibm.com:dropbox/)
- The signer parses the JSON response to retrieve the return status and results
Request:
“project”: string, # Project to use
“parameters”: string, # Project control parameters
“user”: string, # Userid requesting signing
“epwd”: hexascii string, # Encrypted password for CCA account
“payload”: hexascii string, # Optional: Incoming payload
“comment”: string, # Comment to include in audit log
Response:
“retval”: int # Return code, non-zero on failure
“result”: hexascii string, # Optional: Resultant payload
“stdout”: string, # Output from project program
The following installation instructions are based on RHEL 7.3.
# rhn-channel --add --channel=rhel-x86_64-workstation-optional-7
# yum install gcc json-c json-c-devel libcurl libcurl-devel make openssl-devel kernel-devel redhat-rpm-config git openldap-devel
Setup authorized_keys
# mkdir /etc/ssh/authorized_keys
Edit /etc/ssh/sshd_config
AuthorizedKeysFile /etc/ssh/authorized_keys/%u
PasswordAuthentication no
Configure the firewall as follows:
- Pass port 53 (DNS) from the signing server to the Intranet
- Allow port 22 (SSH) from the intranet to the signing server
- Allow UDP port 123 (NTP)
Run the installation tool and use the default settings when prompted.
# ./setup4767_5.3.12.bin
Logout and log back in for changes to be applied.
Do these steps only once. Definitely do not initialize the coprocessor once it is in production.
- Need admin with root authority
- /opt/ibm/4767/clu/csulclu -c ST
Coprocessor Load Utility (CLU) version 5.3.12 ---------------------------------------------------------------------- Invocation : /opt/ibm/4767/clu/csulclu -c ST Log File : DV685353.log Started : Tue Oct 11 14:14:27 2016 ---------------------------------------------------------------------- Vital Product Data Part Number : 00LV498 Secure Part Number : 00LV498 EC Number : 0N37015 Serial Number : DV685353 Description : IBM 4767-002 PCI-e Cryptographic Coprocessor Manufacturing Site : 91 POST-0 Version : 1 POST-0 Release : 35 MiniBoot-0 Version : 1 MiniBoot-0 Release : 33 ROM Status Page 1 Certified : YES Segment-1 State : INITIALIZED Segment-2 State : RUNNABLE Segment-2 Owner ID : 2 Segment-3 State : RUNNABLE Segment-3 Owner ID : 2 Segment-1 Information Segment-1 Image : 5.3.12 P0123 M0121 P0123 F0D01 201608111501503A000022000000000000 Segment-1 Revision : 50312 Segment-1 Hash : 47DE D8EE BB79 CF98 2250 DDBB 1CE9 45C4 6CAB 4243 BD11 E4B0 D742 664C 978C 1702 C201 EF4E 4C97 21A 73D1 F227 BAFD B5FE 5125 421C EEBC A9C3 4A12 7E32 645F 1588 Segment-2 Information Segment-2 Image : 5.3.12 1.0-lnx-2015-06-16-20 201608180952503A000000000312031200 Segment-2 Revision : 50312 Segment-2 Hash : 90E2 97C1 6A4B EAC5 39BB 1E3B 9C88 0975 D478 1EF1 EDE1 73C2 CCBC 628B F877 7AA9 9399 528F FCB6 B14 1E11 362C EBAB 52E9 A060 C67C 44ED C2F7 1620 CD58 44F1 B79A Segment-3 Information Segment-3 Image : 5.3.12 CCA 201608180952503A000000000000000000 Segment-3 Revision : 50312 Segment-3 Hash : 8E21 5A7F FA7A DDD0 4B3F BEF5 7A11 E3A7 AA34 1942 F24F 9589 1055 86BD 4F1A A354 0FBE CA90 1747 EFF3 75D1 B0BC 62F1 48E8 3E49 333A 7AAD FFB2 29AA C6F0 27B9 1685 ---------------------------------------------------------------------- Obtain Status ended successfully at Tue Oct 11 14:14:59 2016 ---------------------------------------------------------------------- Finished : Tue Oct 11 14:15:07 2016 ----------------------------------------------------------------------
-
Load Segment One (If factory fresh card)
If ‘Segment-1 Information’ from above output contains the following execute this step, otherwise skip to next :
Segment-1 Information Segment-1 Image : 5.2.19 P0123 M0121 P0123 F0D01 201601041015502A000011000000000000 --INFO-- This appears to be a factory fresh card. --INFO-- The segment-1 key swap CLU file (reload_seg1_xipz_factory_to_prod_keyswap_<version>.clu). --INFO-- must be loaded before loading segments 2 & 3.
- cd /opt/ibm/4767/clu && ./csulclu -c PL -d reload_seg1_xipz_factory_to_prod_keyswap_5.3.12.clu
----------------------------------------------------------------------
Coprocessor Load Utility (CLU) version 5.3.12
----------------------------------------------------------------------
Invocation : ./csulclu -c PL -d reload_seg1_xipz_factory_to_prod_keyswap_5.3.12.clu
Log File : DV67Z302.log
Started : Wed Aug 30 16:42:18 2017
----------------------------------------------------------------------
Vital Product Data
Part Number : 00LV498
Secure Part Number : 00LV498
EC Number : 0N37015
Serial Number : DV67Z302
Description : IBM 4767-002 PCI-e Cryptographic Coprocessor
Manufacturing Site : 91
POST-0 Version : 1
POST-0 Release : 35
MiniBoot-0 Version : 1
MiniBoot-0 Release : 33
ROM Status
Page 1 Certified : YES
Segment-1 State : INITIALIZED
Segment-2 State : UNOWNED
Segment-2 Owner ID : 0
Segment-3 State : UNOWNED
Segment-3 Owner ID : 0
----------------------------------------------------------------------
Starting load...
Reload Segment-1 command successful (177.470 seconds).
Microcode download ended successfully!
----------------------------------------------------------------------
Finished : Wed Aug 30 16:45:30 2017
----------------------------------------------------------------------
-
Establish ownership (If UNOWNED)
If Segment 2 and 3 state in the output above list ‘UNOWNED’ instead of ‘RUNNABLE’ then follow this step, otherwise skip to next step.
Segment-1 State : INITIALIZED Segment-2 State : '''UNOWNED''' Segment-2 Owner ID : 0 Segment-3 State : '''UNOWNED''' Segment-3 Owner ID : 0
- cd /opt/ibm/4767/clu && ./csulclu -c PL -d establish_ownership_then_emergency_reload_seg2_seg3_xip_5.3.12.clu
----------------------------------------------------------------------
Coprocessor Load Utility (CLU) version 5.3.12
----------------------------------------------------------------------
Invocation : ./csulclu -c PL -d establish_ownership_then_emergency_reload_seg2_seg3_xip_5.3.12.clu
Log File : DV67Z302.log
Started : Wed Aug 30 16:47:06 2017
----------------------------------------------------------------------
Vital Product Data
Part Number : 00LV498
Secure Part Number : 00LV498
EC Number : 0N37015
Serial Number : DV67Z302
Description : IBM 4767-002 PCI-e Cryptographic Coprocessor
Manufacturing Site : 91
POST-0 Version : 1
POST-0 Release : 35
MiniBoot-0 Version : 1
MiniBoot-0 Release : 33
ROM Status
Page 1 Certified : YES
Segment-1 State : INITIALIZED
Segment-2 State : UNOWNED
Segment-2 Owner ID : 0
Segment-3 State : UNOWNED
Segment-3 Owner ID : 0
----------------------------------------------------------------------
Starting load...
Establish Segment 2 Owner command successful (25.339 seconds).
Trying to open coprocessor (max 90-second delay)...
----------------------------------------------------------------------
Starting load...
Load Segment-2 command successful (98.583 seconds).
Trying to open coprocessor (max 90-second delay)...
----------------------------------------------------------------------
Starting load...
Establish Segment-3 Owner command successful (31.689 seconds).
Trying to open coprocessor (max 90-second delay)...
----------------------------------------------------------------------
Starting load...
Load Segment-3 command successful (92.808 seconds).
Microcode download ended successfully!
----------------------------------------------------------------------
Finished : Wed Aug 30 16:53:06 2017
----------------------------------------------------------------------
- Start the CCA Node Management Utility
- cd /opt/ibm/4767/cnm && ./csulcnm
- Reset the coprocessor.
- Crypto Node - Initialize, Yes, OK
- Synchronize the clock time.
- Crypto Node – Time, Set
- Set up the Administrator access role
- Access Control - Roles
- New
- Role ID: admin
- Comment: administrator
- Strength: 50
- Check all valid days
- Enable All
- Load - OK - Cancel
- Set up two or more administrator profiles. Each administrator should log on and change the password.
- Two or more administrator profiles MUST be created for the system administrators.
- An administrator profile must be created for each master key holder. The master key holders will change their password later in the process.
- It is very important that more than one person have an administrator profile. If all lose their password, the coprocessor can no longer be administered.
- Access Control - Profiles
- New
- User ID: subras
- Comment: Sub Swaminathan
- set a long expiration date and passphrase expiration date
- Role: admin
- Load - OK – Cancel
- Log on with an administrator profile
- File - Passphrase logon
- Limit the DEFAULT access role. This is the role in effect when there is no profile login.
- Access Control - Roles
- DEFAULT - Edit
- Disable All
- Select
- 008E Generate Key - Permit
- 0103 PKA96 Key Generate - Permit
- 0110 Set Clock - Permit
- 011B Force User Logoff – Permit
- 012A Encipher - Permit
- Load, OK, Cancel
- This step MUST be performed by the master key holder and not the system admin.
- The master key holder must first change their CCA profile password from the default generated by the system admin
-
Generate a master key and save the parts. Save to removable media like a USB stick, CDROM, etc. Do not save it on the hard drive. Write down the values and save multiple copies. Keep copies on and off site.
- You must back up and secure the master key. If it is lost, the ability to recover signing keys is lost. If the 4767 coprocessor fails, all signing keys will be lost.
- The verification pattern is not secret. However, for logistical reasons, it makes sense to save it with the three key parts.
- The master key is created in three parts. Ideally, different people should hold the parts so that no one person can compromise the security.
-
Repeat these steps for the DES/PKA master key and the AES master key.
MK is a menu selection variable in the below pseudocode loop. Do this step 2 or 3 three times.
for MK =
Master Key – DES/PKA Master Keys
Master Key – AES Master Key
Master Key - APKA Master Key (4765 only)
{
MK – Clear New – Yes - OK
This may return a session HMAC error the first time through. Try exiting and restarting csulclu.
MK - Parts
First Part - Generate
Load - OK
Save…
Enter path or folder name:
Enter file name: (e.g. pkapart1.bin, aespart2.bin)
Save - OK
Middle Part and Last Part - repeat generate, load, save
Cancel
MK - Set - Yes - OK
MK - Verify - Current
Save …
Enter path or folder name:
Enter file name: (e.g. pkaverify.bin)
Save - OK
Cancel
} end for MK loop
- Remaining CCA steps are run by the system administrator
- Set up a Signer Role
- Access Control - Roles
- New
- Role ID: signer
- Comment: signer
- Strength: 50
- Check all valid days
- Select
- 0100 PKA96 Digital Signature Generate - Permit
- 0101 PKA96 Digital Signature Verify - Permit
- 0103 PKA96 Key Generate - Permit
- 0114 Change User Profile Authentication Data
- 011E PKA Encipher Clear Key***
- 011F PKA Decipher Key Data***
- 012A Encipher Data Using AES
- Load - OK - Cancel
- These are only required for the encrypt/decrypt application, not for code signing.
- Load the function control vector
- Crypto Node - Authorization - Load
- Enter path or folder name: /opt/ibm/4767/cnm/
- Files:
- fcv_td4kECC521_ECDSA.crt(4767)
- OPEN - Yes - OK
- Log out
- File - Logoff - Yes – OK
A 4767 coprocessor can be cloned, either as a hot backup, as a second signing server, or after the primary coprocessor has failed.
Master keys are wrapping keys or key encrypting keys. The ECC signing keys are encrypted with the DES/PKA master key. The AES key used for password encryption is encrypted with the AES master key. Clone a card by installing the master keys. Simply copy the other encrypted keys (e.g. ecc_opbuild_keya.tok) from disk to disk. There will be one set of keys for each project defined (3 sets of HW signing keys and at least 2 sets of FW signing keys).
- Log on from CNM GUI with an administrator profile
- File - Passphrase logon
Master Key – DES/PKA Master Keys
Master Key – AES Master Key
Master Key - APKA Master Key
MK - (Master Key) Parts
for First Part, Middle Part, Last Part
Open
Select the file, e.g. aes-mk.part1
Open - Load - OK
Cancel
MK - Set - Yes - OK
MK - Verify - Current - Compare
Select the file, e.g. aes-verify.bin
Open - OK – Cancel
Before entering production, it is very important to test that the install is correct. In particular, test that the master key is backed up correctly. If the master key is lost and the 4764 fails, all keys for all projects are lost!
To test the recovery mechanism and create a backup 4764 at the same time, insert the new card and redo the initialization procedure. When it comes time for master key generation, use the master key recovery procedure of this section rather than generating a new key. Then sign a code blob and verify success.
A less useful method is to test recovery on the same 4764.
- Install the framework. See section Signing framework installation
- Create a signer profile. See section New Signer Setup
- Create a signing key. See section Create New Project
- Use the framework test program locally to sign a code blob.
# framework_test -obody obody.txt -sender sender -di masterkey.bin -do sig.bin -log athena.log -key athenakey.tok -usr backups -pwd aaaaaa
- Erase the master key. The below steps are intentionally duplicated since the 4764 keeps an old master key.
Master Key - DES/PKA Master Key - Create Random Master Key - Yes
Master Key - AES Master Key - Auto Set - Yes
Master Key - AES Master Key - Auto Set - Yes
- Sign again and verify that an error is returned. The message should say that the master key verification pattern is not valid.
- Restore the PKA and AES master keys. See section Master Key Restore.
- Sign a code blob and verify success. See this section step.
Create an id to run the framework (as root)
# groupadd signers # useradd -G signers framework # passwd framework
Dropbox setup
The following design was adapted from : https://wiki.archlinux.org/index.php/SFTP_chroot
# mkdir /home/dropbox # chmod 770 /home/dropbox # chgrp signers /home/dropbox
The following steps are run as the 'framework' user that will be running the signing framework.
Install the signing framework:
# cd $HOME # git clone https://github.com/open-power/sb-signing-framework.git # chmod 700 $HOME/sb-signing-framework # cd $HOME/sb-signing-framework/src/signframework # make # (cd signecc && make) # export FRAMEWORK_CONFIG_FILE=$HOME/sb-signing-framework/src/signframework/framework.cfg
IBM INTERNAL: Clone the framework configuration respository and apply configuration:
# cd $HOME # git clone https://github.ibm.com/cjengel/signframework-cfg.git # chmod 700 $HOME/signframework-cfg # cd $HOME/sb-signing-framework/src/signframework # ./pullconfig $HOME/signframework-cfg
EXTERNAL: Follow the instructions in section Basic Framework Configuration to complete the configuration of the framework
Generate a master AES key
This is a one-time operation.
Generate this key using the ‘frameworkkey_generate’ program. There are no required arguments.
# frameworkkey_generate # chmod 440 masterkey.bin
The program generates the master AES key used for CCA password security. It stores it in the file specified by the framework configuration.
Setup systemd files to auto-start the harness and start the framework (as root)
# cp /home/framework/sb-signing-framework/src/signframework/systemd/signframework.service /etc/systemd/system/ # systemctl daemon-reload # systemctl enable signframework # systemctl start signframework
Setup Other Utilities
There are other utilities that can be setup to help administer the framework. See Signer Validation, Coprocessor Clock, Dropbox File Cleanup and Archiving Audit Logs.
The signing client setup must be done on any machine that will be used to access the signing server.
The signing and administration client is in the same source repository as the signing framework.
Client Dependencies
# yum install gcc json-c json-c-devel libcurl make
Build Client
# cd $HOME # git clone https://github.com/open-power/sb-signing-framework.git # cd $HOME/sb-signing-framework/src/client # make
For the latest documentation run './sf_client -h.
# ./sf_client -h sf_client: -h print usage help Required: -project '' - Name of the project -comments '' - Identifier/Message for audit log -epwd 'path' - File path to the hsm encrypted password -url '' - sftp url. Example: sftp://user@address -pkey 'path' - File path to the *encrypted* private key file Optional: -payload <path> - File path to the binary to be signed -param '' - Parameters to be passed to the signing framework. Ex '-v' or '-h' -o <file> - output file to save the return payload -stdout - Displays the stdout from the server Debugging: -v - verbose tracing -d - debug mode - files will not be deleted
The following instructions are used to grant new signers access to the signing server dropbox.
- Generate ssh key. The signer MUST use a passphrase to encrypt the SSH key and MUST create a unique keypair for the signing process. To create a unique keypair enter in a unique file name when asked where to save the key.
# ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/home/cengel/.ssh/id_rsa): /home/cengel/.ssh/id_rsa.sign Enter passphrase (empty for no passphrase): xxxxxxxxxxxxxxxx Enter same passphrase again: xxxxxxxxxxxxxxxx Your identification has been saved in /home/cengel/.ssh/id_rsa.sign. Your public key has been saved in /home/cengel/.ssh/id_rsa.sign.pub.
- Send the public key file as an email attachment to the signing server administrator and include :
- The name of the project you are requesting access to
- The userid on the system to create
- IBM INTERNAL:When writing the email, under 'Delivery Options' – 'Security Options', check 'Sign'.
These steps use the example username 'ccasign1', the username in the examples must be replaced with the id requested. The userid has a limit of 8 characters.
Validate sign requestor
- IBM Internal: Validate the email is signed by the requestor. This is done by looking for the following text in the Lotus Notes email client:
- Verify from a project auditor of the requested project that the signer should be allowed access the signing server.
- Verify the requested userid is not already in use and is 8 characters or less in length
Place the signers SSH public key in a temporary file (ex ~/ccasign1.pub)
Run the following as root:
# cd /home/framework/sb-signing-framework/src/signframework/ # ./adddropbox ccasign1 ~/ccasign1.pub
Create signer profile on CCA
Start cnm and log in as a CCA administrator
- /opt/ibm/4767/cnm/csulcnm
- File – Passphrase Logon
- Access Control – Profiles – New
- Fill in the following:
- User ID (ccasign1) ← Set to requested userid
- Comment
- Expiration Date
- Role (signer)
- Passphrase (aaaaaa) ←-- Enter password as shown
- Load – OK – Cancel
Generate a strong signer passhrase
Run the following as the signing framework id (framework) to generate the strong passphrase and email to the sign requestor
# cd ~/sb-signing-framework/src/signframework # export FRAMEWORK_CONFIG_FILE=$PWD/framework.cfg # ./password_generate -profile ccasign1 -sender ccasign1[mailto:[email protected] @email.com]
- Delete the CCA profile
- Delete the SSH public key (/etc/ssh/authorized_keys/<userid>)
- Restart SSH
- Remove user from project configuration files
- Restart the framework (See Stopping and Restarting the Framework)
Do NOT test on the production server. The production server should only sign GA code! A new signing program should be thoroughly tested by both the framework developer and at least one signer. Projects can share a program if applicable. Each project has a "project administrator". This person is responsible for:
- Backing up the signing key.
- Authorizing signers. The project administrator may or may not be authorized to sign.
- Authorizing people to receive notification of a signing event.
- The project administrator should supply the following to the signer framework developer:
- A short descriptive name for the project. The users will specify this name in a signing request email.
- The name of an existing signing program, or the source for a new program.
- The email address of the project administrator.
- The CCA profile ids of authorized signers
- The email addresses of additional people who should receive notification of each signing event.
- The signing framework developer sends a request to the signing server admin to generate new project signing keys. The developer must provide the following:
- .tok and .bin filenames to use
- Directory in framework to store them, currently signecc
- Key type to generate RSA vs ECC
- Email address of project administrator
- The signing server admin will generate the requested project keys and send them to the project administrator
# cd $HOME/sb-signing-framework/src/signframework
- To Generate ECC p521 keys
# cd <signtool subdir> # ../keygeneccp521 -k <tokfile> -p <binfile>
- To Generate RSA keys
# cd <signtool subdir> # ../keygen [-sz bitsize] -k <tokfile> -p <binfile>
- To Generate RSA keys to be used with RSAPSS signature scheme
- Note this is only supported with the sign_sha512 sign tool and the '-rsassa-pss' option must be provided to the sign tool in the project configuration
# cd <signtool subdir> # ../keygen [-sz bitsize] -k <tokfile> -p <binfile> -aesc
- Send the public and encrypted private keys to the project admin
- Run once per admin email address
# ./sendkeys "<ProjectName>" <binfile> <tokfile> <email addr>
- IBM INTERNAL: Archive the project keys
# cp <binfile> <tokfile> $HOME/signframework-cfgs/keys # cd $HOME/signframework-cfgs # git commit -m “Project Keys” -a && git push
-
EXTERNAL: Archive the project keys
- The public and encrypted private key must be archived somewhere off the signing server to allow recovery in the case where the signing server fails.
The framework stops or restarts in under 1 second if it is idle, but can take longer if it is processing requests.
Stop the framework by creating the file specified by stop_file, typically using the Unix command ‘touch’ command.
Restart the framework by creating the file specified by ‘restart_file’, typically using the Unix command ‘touch’ command.
Use the sender_validate program to periodically validate that the senders for each project still require authorization. This program scans each project configuration file. It sends an email to the project administrator with a list of the currently authorized senders.
The program runs outside the signer framework to keep the framework small and thus more secure.
- Run the program manually from the command line at any time.
- Run the program automatically using a cron job. A sample cron file might look like this:
[email protected] FRAMEWORK_CONFIG_FILE=/home/framework/sb-signing-framework/src/signframework/framework.cfg @weekly cd /home/framework/sb-signing-framework/src/signframework && (./sender_validate -cfg sender_validate.cfg > logs/sv.log) 2> logs/sv.err
To install this cron file (named sender_validate.cron) as the framework id:
# crontab -r ; crontab sender_validate.cron ; crontab -l
Root privilege is not required. See the cron man pages for more options besides @weekly.
At login, the coprocessor compares the login time from the host to its internal clock. If the clocks differ by more than 5 minutes, the log in is rejected to protect against replays. Thus, the coprocessor clock must be periodically to compensate for drift.
If the login fails, the administrator must:
- Use cnm to read the coprocessor time.
- Adjust the server clock to agree with the coprocessor clock
- Log in to the card.
- Adjust the server clock back to the correct time.
- Set the coprocessor clock.
@monthly cd /home/framework/sb-signing-framework/src/signframework && (./setclock > logs/sc.log) 2> logs/sc.err
If you are not familiar with Unix cron jobs, see Signer Validation for details.
The framework doesn't remove files from the dropbox after the completion of a request. A utility has been provided to automatically clean old files after 90 days.
Add this line to the cron file:
@weekly cd /home/framework/sb-signing-framework/src/signframework && (./cleandropbox /home/dropbox > logs/clean.log) 2> logs/clean.err
Reading audit logs and configuration files uses the existing framework. An authorized administrator can call an audit program, which is just another signer program to the framework. This audit program supports these options:
- -fc Return the framework configuration file
- -fl Return the framework audit log
- -pc projectReturn any project configuration file
- -pl projectReturn any project audit log file
- -pauxReturn any project auxiliary configuration file
The options to return audit logs permit remote access to these logs by framework or project administrator.
A ‘verbose’ option permits remote debugging of the programs themselves.
Problems cannot be fixed remotely. Because of the security threat, there is no provision for remote writing of configuration files. Only a local framework or project administrator can fix problems.
Example of pulling the framework configuration (See Signing Client to build and run the client):
# ./sf_client -project audit -param "-fc" -epwd ~/private/epwd.txt -comments "Pulling framework config" -url sftp://argus4 -pkey $HOME/.ssh/id_rsa_signing -o framework.cfg
Since the signing server cannot connect to a backup facility, the audit_archive program can periodically email the framework audit log to the framework administrators and all project audit logs to the project administrator.
Recommended is to add a cron job to archive the audit logs, perhaps monthly. E.g., add this line to the cron file:
@monthly cd /home/framework/sb-signing-framework/src/signframework && (./audit_archive -cfg audit_archive.cfg > logs/aa.log) 2> logs/aa.err
If you are not familiar with Unix cron jobs, see Signer Validation for details.
The administrator can recover a lost user password, as the framework logs it in the framework log file.
It might be easier to simply generate a new one, as if it expired. See section CCA Password Expiration.
The CCA user profile password expires based on the value in the framework configuration file. The administrator can view the expiration date using cnm:
- File - Passphrase Logon
- Access Control - Profiles - (select a profile) - Edit
The administrator does not know the plaintext passphrase, and so cannot change the Passphrase Expiration Date. Thus, the current procedure is to change the password back to ‘aaaaaa’ and then run the procedure to generate the password in section Signing server administrator steps.
User:
The user can change their password using a framework project plug-in. Authorize all senders to call the ‘password_change’ project. Run the request (See Signing Client to build and run the client):
# ./sf_client -project password_change -epwd ~/private/epwd.txt -comments "Changing Password" -url sftp://argus4 -pkey $HOME/.ssh/id_rsa_signing
It is unlikely that the user, or an attacker using the user’s profile, can exceed the CCA login failure maximum, which is currently hard coded to 3 - in CCA, not in the framework. The reason is that the encrypted password is digitally signed (HMAC’ed). An incorrect encrypted password will surely fail the signature check and not be applied to the card.
The procedure to reset the failure count is:
- File - Passphrase Logon
- Access Control - Profiles - (select a profile) - Reset FC
A user sends a query to the server for the signing public key.
The options are:
- project : getpubkey or getpubkeyecc
- signproject [name]
# ./sf_client -project getpubkey -param “-signproject athena” -epwd ~/private/epwd.txt -comments "Retrieving athena pubkey" -url sftp://argus4 -pkey $HOME/.ssh/id_rsa_signing -o athenakey.pub
For getpubkey, an optional -format argument determines the format of the returned payload. The default is binary, and returns the public key as a big endian binary array. The value le32 returns the public key as a compilable little endian array of 32-bit integers as required by the UEFI verifier.
The value pem returns the public key in pem format. This code has not been deployed on the production server yet.
Other formats can be added as required.
Currently, a user is authorized to get a public key only if they are authorized to run the project that uses the key. There is no particular security reason for this. It was done more as sample code for how a program can check sender authorization. The check may be removed.
If the user has local access to the CCA key token, that can also run the getpubkey or getpubkeyecc program from their Linux command line.
Note:
It is incrementally better for the user to ask for the public key (as above) rather than receiving it in an unsolicited email.
- The server administrator has to be trusted to form the email correctly and not substitute a bogus public key.
The user sends a query to the signing server to generate a signature over the provided hash.
The parameters are:
- -project : Project keys to use
- -comments : Identifier used for auditing to indicate what is being signed
- -payload : Input hash in a binary file for signing
- -o : Output file to place signature
# ./sf_client -project athena -epwd ~/private/epwd.txt -comments "Signing FW with athena key" -url sftp://argus4 -pkey $HOME/.ssh/id_rsa_signing -payload fwhash -o athenakey.pub
There are several layers or backups, in order of decreasing down time in case of failure.
These MUST be backed up. If either is lost, the administrator cannot recover from a server or coprocessor card failure. That is, the down time is forever.
- Master Keys - See section Master Key Generation
- Signing Keys - See section Create New Project
There SHOULD be a backup coprocessor card. Otherwise, a card failure causes down time until a new card is purchased, which might entail the IBM capital approval process.
The current plan is to use the existing, off-network coprocessor card as a backup.
The master keys should be preinstalled in the backup coprocessor. This both saves down time and validates that the saved master keys are correct. See section Master Key Restore.
New CCA accounts and passwords must be created.
There SHOULD be a backup signing server. Otherwise, a failure causes days of down time until a new server is found, software is installed, and accounts are created.
The existing coprocessor card is moved to the backup server.
My opinion is that servers are really cheap, perhaps free. Maintaining a backup server powered on permits the administrator to simultaneously create Linux and CCA accounts on both machines and move signing keys as they are created.
While migrating the master key permits simple migration of the signing keys, there is no current procedure to migrate user CCA accounts or passwords.
Here are two alternatives:
- Generate a second password. This can be done in advance for section New Signer Setup. For the others, it must be done after the server is brought on line. It can be automated if a program is written to parse and sort the project configuration file authorized signers.
- Write a program to migrate the existing passwords. The end user can do this. The administrator can do it assuming that the framework log file is available.
- Comments beginning with # and blank lines are permitted
- The order of entries CANNOT change
- Key value pairs are defined as :
- <key></key>=<value></value>
- Arrays are defined with the first line specifying the number of entries followed by separate lines for each entry
- <key></key>=<numrows></numrows>
- <row></row>
- <row></row>
There is only one of these framework configuration file. It contains mostly static data. The last entry, the project map, changes each time the administrator adds or deletes a project.
Copy the sample framework.cfg file:
# cp framework.cfg.sample framework.cfg
Edit the framework.cfg file and update the admins field. The defaults for the other fields may be sufficient.
This file contains:
- Maximum limits for various input parameters. These are used as sanity checks against attacks using large data blocks.
- Lines, including the in the request comments and configuration files
- Request JSON total size
- Password expiration period in months
- Hard coded file names for use by the framework. The files must be read/write.
- Framework audit log
- The stop file causes the framework to gracefully exit without losing work in progress.
- The restart file causes the framework to reread all configuration files.
- Output body is a temporary file to construct the response.
- Notification log is a temporary file used to construct the response to notification receivers.
- Input attachment is a temporary file to store the input payload. It must be rooted.
- Output attachment is a temporary file to store the output payload. It must be rooted.
- Password encryption key token file name. This file must be read/write when generating the key. It can be read-only during use.
- Number of server administrators and their email addresses.
- Mapping of project name to project configuration file name. There must be at least one entry.
- In general, each project has a unique configuration file. There is no point in projects sharing a configuration file.
There is one project configuration file per project. It contains mostly static data. The last entries, the project administrator, authorized senders and notification receivers, change each time the administrator adds or deletes an entry.
This file contains:
- Project program file name (typically the signer program).
- Each project may have a unique signer program. It is legal (and a long-term goal) for projects to share a program.
- Project audit log file name
- Signing key file name, preceded by a flag indicating whether the project requires a signing key.
- The name of an auxiliary project configuration file, preceded by a flag indicating whether the project requires it. The name is passed to the project program.
- Flags for whether input and output attachments, and a CCA password. are required by the project program
- Project administrator’s email address. The entry is used for:
- The target email address for periodic audit log archiving
- The target email address for periodic sender validation
- An informative in the email body to notification receivers
- CCA profile ids of authorized users of the project. The list is preceded by:
- A flag indicating that a sender list is required.
- A sender count, the number of authorized users
- If the flag is false, any user may call the project. There is no authorization. The sender count must be zero.
- If the flag is true, only authorized users may call the project. The sender count must be non-zero.
- Generally, signing programs require authorization. Administrative programs may not.
- The signing server software imposes no limit on the number of authorized signers. Management procedures may impose limits. Authorized users must be trusted to sign only final, GA builds that will be shipped, not test code.
- Notification receiver count and email addresses to receive notification. There may be zero or more entries.
A project configuration file may reference an optional auxiliary configuration file. The framework does not open this file. It simply passes the file name on to the project program.
The intent, however, is to specify additional input parameters. The framework cannot pass in these parameters because it only understands certain standard parameters, and it would be unwise to modify the framework program each time new project requirement arises. While the user could supply these parameters in an email, this is also unwise. First, it burdens the user with a task, when these parameters are in fact fixed for the project. Second, it opens an attack surface, where the user might intentionally supply incorrect parameters.
The project program is encouraged, but not required, to use the configuration file parsing routines already part of the framework. Beyond the advantage of code reuse, the configuration file format will also be familiar to the signer framework administrator.
Example use cases are:
- The project program handles multiple digest algorithms (SHA-1, SHA-256). However, the selection is determined by the project, not by the user.
- The project program requires multiple keys, while the framework only permits specification of one key.
- The project program can output its response in several formats, depending on project requirements.
- The project program sends email beyond the standard framework reply and notification. The file can specify the additional email addresses.
The following steps can be used to setup the signing server to the requirements used by IBM. For each file listed below rename the sample version and make the required changes:
framework.cfg
# cd /home/framework/sb-signing-framework/src/signframework # cp framework.cfg.sample framework.cfg
Update the following fields in framework.cfg:
- Set admins property to appropriate email addresses
- Change list of projects to following:
- audit=audit.cfg
- password_change=password_change.cfg
- getpubkeyecc=getpubkeyecc.cfg
- sign_ecc_pwr_hw_key_a=signecc/signecc-hwa.cfg
- sign_ecc_pwr_hw_key_b=signecc/signecc-hwb.cfg
- sign_ecc_pwr_hw_key_c=signecc/signecc-hwc.cfg
- sign_ecc_pwr_fw_key_p=signecc/signecc-swp.cfg
- Set the project administrator appropriately
- Set the authorized senders appropriately
- Set the project administrator appropriately
- Set the notification receivers appropriately
- Set the project administrator appropriately
signecc/signecc-hwaux.cfg
- No changes
- Set the project administrator appropriately
- Set the notification receivers appropriately
- Set the authorized senders appropriately
signecc/signecc-swaux.cfg
- Change cfg_files to 1
- Comment out swq/swr configuration files
- Set the project administrator appropriately
- Set the notification receivers appropriately
- Set the authorized senders appropriately
audit_archive.cfg / sender_validate.cfg
- No changes