OpenFL Public Key Infrastructure (PKI) Solutions

Overview

Transport Layer Security (TLS) encryption is used for network connections in federated learning. Therefore, security keys and certificates will need to be created for the aggregator and collaborators to negotiate the connection securely.

If you have trusted workspaces and connections, you can start your experiment with the disable_tls option.

Otherwise, you can certify nodes with your own PKI solution or use the PKI solution workflows provided by OpenFL.

Note

The OpenFL PKI solution is based on step-ca as a server and step as a client utilities. They are downloaded during the workspace setup.

Note

Different certificates can be created for each project workspace.

sequenceDiagram Title: Collaborator Certificate Signing Flow participant A as Alice participant AC as Alice's Collaborator Node participant B as Bob participant BG as Bob's Certificate Signing System A->>AC: Alice runs<br>`fx collaborator generate-cert-request`<br>to create .key and .csr file AC->>A: PKI script outputs a hash to the screen A->>B: Alice sends the .csr to Bob B->>BG: Bob moves the .csr<br/> to the signing system with<br>`fx collaborator certify --request-pkg` B-->>A: Bob Calls Alice to confirm PKI Note over A,B: This is the **root of trust** : Bob called Alice to verify the hash A-->>B: Alice reads the hash to Bob Note over A,B: This ensures Bob is signing the same .csr Alice generated B->>BG: Bob runs script to sign .csr,<br/> confirming the hash as input,<br/> creating the .crt file B->>A: Bob sends the .crt file back to Alice A->>AC: Alice copies the signed certificate (.crt)<br/>to her collaborator node.<br/>She now has a signed certificate.

Manual certificate generation and signing

sequenceDiagram Title: Collaborator Certificate Signing Flow participant A as Aggregator participant CA as CA participant C as Collaborator CA->>CA: 1. Create CA:<br>`step ca init --password-file pass_file` CA->>CA: 2. Up HTTPS CA server:<br>`step_ca ca_config.json` CA->>CA: 3. Generate JWK pair:<br>`step crypto jwk create pub.json priv.json --password-file pass_file` CA->>CA: 4. Get JWT for aggregator:<br>`step ca token localhost --key priv.json --password-file pass_file --ca-url ca_url` CA->>A: 5. Copy JWT to aggregator. A->>CA: 6. Certify node:<br>`step ca certificate localhost agg.crt agg.key --token AbC1d2E..` Note over A,CA: Get agg.crt CA->>CA: 7. Get JWT for collaborator:<br>`step ca token col_name --key priv.json --password-file pass_file --ca-url ca_url` CA->>C: 8. Copy JWT to collaborator. C->>CA: 9. Certify node:<br>`step ca certificate col_name col_name.crt col_name.key --token AbC1d2E..` Note over C,CA: Get col_name.crt CA->>A: 10. Copy root_ca.crt to aggregator Note over A,CA: This could be done at step 5 with token CA->>C: 11. Copy root_ca.crt to collaborator Note over C,CA: This could be done at step 8 with token

Step-ca certificate generation and signing

Semi-Automatic PKI Workflow

The OpenFL PKI pipeline involves creating a local certificate authority (CA) on a HTTPS server that listens for signing requests. Certificates from each client are signed by the CA via a token. The token must be copied to clients in a secure manner.

  1. Create the CA.

    $ fx pki install -p </path/to/ca/dir> --ca-url <host:port>
    where
    -p defines the path to the directory that contains CA files, and
    --ca-url defines the host and port that the CA server will listen, if not specified, --ca-url will be “localhost:9123”

    When executing this command, you will be prompted for a password and password confirmation. The password will encrypt some CA files. This command will also download step-ca and step binaries.

  2. Run the CA server.

    $ fx pki run -p </path/to/ca/dir>
    where
    -p defines the path to the directory that contains CA files.

  3. Create a token for client.

    $ fx pki get-token -n <subject> --ca-path </path/to/ca/dir> --ca-url <host:port>
    where
    -n defines the subject name, FQDN for director, collaborator name for envoy, or API name for the API-layer node.
    --ca-path defines the path to the directory that contains CA files.
    --ca-url defines the host and port that the CA server will listen, if not specified, --ca-url will be “localhost:9123”

    Run this command from the CA directory on the CA server. The output is a token which contains a JWT (JSON web token) from the CA server and the CA root certificate concatenated together. This JWT is valid for 24 hours.

  4. Copy the token to the clients (director or envoy) via a secure channel, and certify the token.

    $ cd <path/to/subject/folder>
$ fx pki certify -n <subject> -t <generated token for subject>
    where
    -n defines the subject name, FQDN for director, collaborator name for envoy, or API name for the API-layer node.
    -t defines the output token from the previous command.

    With this command, the client connects to the CA server over HTTPS, which is provided by the root certificate which was copied together with the JWT. The CA server authenticates the client via the JWT, and the client authenticates the server via the root certificate.

The signed certificate and private key are stored on each node in the federation. The signed certificate is valid for one year. You should certify all nodes that will participate in the federation director, which includes all envoys and API-layer nodes.

Manual PKI Workflow

This solution is embedded into the aggregator-based workflow. See Configure the Federation for details.