You can run all example applications with security configuration.
Specify the security supported configuration file in the development environment.
OSPL_URI=file://${OSPL_HOME}/examples/dcps/Security/ospl_sp_ddsi_secure.xml
You can run the example application according to its running instructions.
To enable DDS Security with OpenSplice, DDS Security has to be enabled in the DDSI service configuration.
To do this, the DDSSecurity element has to be included in the DDSI configuration section of the OpenSplice configuration file.
The DDS Security implementation consists of three plugins which are:
See Security section of Deployment Guide for explanations about PKI and configuration items.
For each DDS Security plugin a corresponding mandatory element should be present in the DDSSecurity element within the configuration file (see DeploymentGuide for more information).
For each plugin this includes the path to the plugin library and the names of the initialization and finalize functions. The Authentication and Access Control plugins need some additional configuration.
The authentication plugin requires the specification of the identity certificate, identity certificate authority and the private key. All should be in PEM format either specified directly in the configuration file (with 'data:,' prefix) or by referencing a file that contains the information (with 'file:' prefix). See deployment guide for detailed information.
(DDSSecurity/Authentication/IdentityCertificate)
The identity certificate binds the Public Key of the OpenSplice instance to the Distinguished Name (subject name) of this OpenSplice instance.
All DomainParticipants created within this OpenSplice instance will use the same identity certificate. Also the private key associated with the identity certificate has to be configured.
(DDSSecurity/Authentication/PrivateKey).
The private key is either a 2048-bit RSA key or else a 256-bit Elliptic Curve Key for the prime256v1 curve.
Note that the private key maybe protected by a password. When that is the case also the password must be included in the configuration (DDSSecurity/Authentication/Password).
(DDSSecurity/Authentication/IdentityCA)
The indentity CA is a X509 certificate of the issuer of the identity certificates. The identity CA should be a self-signed certificate that is used to sign the identity certificate.
The access control plugin requires governance document, permissions document and permissions CA. Governance and permissions documents should be in SMIME format and permissions CA should be in PEM format. All can be either specified directly in the configuration file (with 'data:,' prefix) or by referencing a file that contains the information (with 'file:' prefix). See deployment guide for detailed information.
(DDSSecurity/AccessControl/Governance)
Governance document defines the security behavior of domains and topics.
(DDSSecurity/AccessControl/Permissions)
The permissions document is an XML document containing the permissions of the domain participant and binding them to the subject name of the DomainParticipant as defined in the identity certificate
(DDSSecurity/AccessControl/PermissionsCA)
The permissions CA is a X509 certificate of the issuer of the permissions and governance documents.
The certificates that have to be generated are::
- Identity CA
- Identity Certificate signed by the Identity CA
- Permissions CA
The certificates are already generated and placed under examples/dcps/Security/Certificates directory. However, you can generate them yourself with the instructions in this section.
Commands are supposed to be run under examples/dcps/Security/Certificates directory.
Generation of Authentication/Identity CA private key:
openssl genrsa -out Identity_CA_Private_Key.pem 2048
Generation of Certificate for the Identity/Authentication CA (self-signed certificate)
openssl req -x509 -key Identity_CA_Private_Key.pem -out Identity_CA_Cert.pem -days 3650 -subj "/C=NL/ST=OV/L=Locality Name/OU=Organizational Unit Name/O=Example Signer CA/CN=Example CA/emailAddress=authority@identitycaltd.org"
Now the full path of Identity_CA_Cert.pem can be used as IdentityCA in the DDS Security authorization configuration. You can change the subject name according to your needs.
Here we are creating private key and certificate for identity named Alice. We should repeat the procedures for each identity in the system.
Generation of Identity private key:
openssl genrsa -out Example_Alice_Private_Key.pem 2048
Generation of certificate request to be signed by the Identity CA:
openssl req -new -key Example_Alice_Private_Key.pem -out Example_Alice.csr -subj "/C=NL/ST=OV/L=Locality Name/OU=Organizational Unit Name/O=Example Organization/CN=Alice Example/emailAddress=alice@exampleltd.com"
Generation of the Identity certificate signed by the Identity CA
openssl x509 -req -CA Identity_CA_Cert.pem -CAkey Identity_CA_Private_Key.pem -CAcreateserial -days 3650 -in Example_Alice.csr -out Example_Alice_Cert.pem
Now the full path of Example_Alice_Cert.pem can be used as IdentityCertificate in the DDS Security authorization configuration.
If you want to generate x509 v3 certificates, you should create an extenstion (i.e. v3.ext) file with content like the following:
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
and then run the certificate generation command with -extfile option:
openssl x509 -req -CA Identity_CA_Cert.pem -CAkey Identity_CA_Private_Key.pem -CAcreateserial -extfile v3.ext -days 3650 -in Example_Alice.csr -out Example_Alice_Cert.pem
Generation of Permissions CA private key:
openssl genrsa -out Permissions_CA_Private_Key.pem 2048
Generation of Certificate for the Permissions CA (self-signed certificate)
openssl req -x509 -key Permissions_CA_Private_Key.pem -out Permissions_CA_Cert.pem -days 3650 -subj "/C=NL/ST=OV/L=Locality Name/OU=Organizational Unit Name/O=Example CA Organization/CN=Example Permissions CA/emailAddress=authority@permissionscaltd.org"
Now the full path of permissions_ca_cert.pem can be used as PermissionsCA in the DDS Security access control configuration.
We need a governance document and permissions documents for each identity. The example documents are placed under examples/dcps/Security. However you can follow the instructions below to recreate them.
Commands are supposed to be run under examples/dcps/Security directory.
Default OpenSplice_Governance_template.xml template is provided as a starting point.
To generate the governance document,
1. make a copy of the OpenSplice_Governance_template.xml template
cp $OSPL_HOME/etc/OpenSplice_Governance_template.xml Example_Governance.xml
2. sign this governance document with the permissions_ca.
openssl smime -sign -in Example_Governance.xml -text -out Example_Governance.p7s -signer Certificates/Permissions_CA_Cert.pem -inkey Certificates/Permissions_CA_Private_Key.pem
The permissions document is an XML document containing the permissions of the domain participant and binding them to the subject name (distinguished name) of the DomainParticipant as defined in the DDS:Auth:PKI-DH authentication plugin. For this purpose a default OpenSplice_Permissions_template.xml template is provided.
To generate the permissions document for Alice,
1. make a copy of the OpenSplice_Permissions_template.xml template
cp $OSPL_HOME/etc/OpenSplice_Permissions_template.xml Example_Permissions_Alice.xml
2. update the subject name with the certificate information as specified in the identity certificate. A sample subject name may be:
/C=NL/ST=OV/L=Locality Name/OU=Organizational Unit Name/O=Example Organization/CN=Alice Example/emailAddress=alice@exampleltd.com
you can get the subject name of an identity certificate by
openssl x509 -noout -subject -in Certificates/Example_Alice_Cert.pem
3. sign this permissions document with the permissions_ca.
openssl smime -sign -in Example_Permissions_Alice.xml -text -out Example_Permissions_Alice.p7s -signer Certificates/Permissions_CA_Cert.pem -inkey Certificates/Permissions_CA_Private_Key.pem
You can either put all permissions of all identities in a single permissions document (each in separate grant element) or create separate permissions document for each identity.