Certificate Usage
Last updated on August 30, 2021.
Document Status: Document Developer Quality Complete.
Introduction
The future security needs of the RPS security infrastructure are currently planned to depend on a Public Key Infrastructure (PKI). However, the current landscape of development for the project does not allow for the full implementation of PKI. In its absence, a Self-Signed Certificate strategy has been developed as a temporary measure to provide improved security over plain text secrets and ease the future adoption of full PKI.
By default, RPS includes a variety of certificates (even self-signed/RPS-signed) to showcase functionality, and it is expected that these development or test certificates will be replaced with appropriate secure and trusted certificates to perform the various functions using the roles indicated.
Important
Each certificate must have a certificate root that is trusted by the local host (i.e., Trusted Root Certification Authorities).
Warning
Use of self-signed or untrustworthy certificates presents a security risk for all assets and functions "secured" by said certificates.
Note
The .pfx file is capable of storing both public and private keys whereas the .cer file is generated from the .pfx and contains only the public key.
Certificate Roles and Functions
The tables below map certificates in the ContentStore, as well as certificates generated by the deployment, to their role and corresponding function.
RPS Specific Roles
The following table describes all the RPS Certificate Roles. For details on how each certificate's requirements, see corresponding Generic Role row in the Generic Role Templates table below.
| RPS Role Name | Generic Role Name | Scope | Other Notes |
|---|---|---|---|
| CertManager | ClientAuthentication | Hosts that will access the Certificate Manager plugin | Used for certificate authentication with Certificate Manager Plugin |
| DscEncryption | DscEncryption | All computers | Credential encryption in DSC .mof files |
| DscPullServer | DscPullServer | All computers configured for DSC Pull mode | Used for certificate authentication with DSC Pull Server |
| MasterKeyEncryption | MasterKeyEncryption | Computers where RPS protected properties will need to be accessed | Used for decryption of RPS Master Key |
| NodeEncryption | DscEncryption | Provisioning hosts | Used for encryption of exported RPS Node data |
| ProvisioningSSL | ProvisioningSSL | Provisioning hosts | RPS Provisioning endpoint |
| RdtSsl | SSL | Computers where RDT is installed | RDT UI HTTPS binding |
| RpsApi | ClientAuthentication | Hosts that will access the RpsApi plugin | Used for certificate authentication with RPS Api Plugin |
| RpsGuiSSL | SSL | RpsGui hosts | RPS Gui HTTPS binding |
| RpsPackage | ClientAuthentication | All Computers | Used for certificate authentication with RPS Package Manager Plugin |
| RpsRoot | Root | All Computers | Used to sign initial RPS Certificates |
| RpsSync | ClientAuthentication | RpsSync hosts | Cert:\CurrentUser\My for Sync account |
| RpsSyncSSL | SSL | RpsSync hosts | RpsSync HTTPS endpoint |
| RpsWebApiSsl | SSL | RPS Web API hosts | RPS Web API HTTPS endpoint |
| WinRm | ServerAuthentication | All computers | PowerShell HTTPS endpoint |
Generic Role Templates
The following table describes the specific certificate attributes required by each generic role. The Key Usages and Enhanced Key Usages should be used for referenced when creating certificate templates. The signature algorithm and key length columns indicate the default values for certificates signed by RPS root certificate. All RPS certificate roles support Elliptical Curve Cryptography based algorithms and larger key lengths, with the exception of DscEncryption. The certificate used for DscEncryption only support RSA algorithm.
| Generic Role Name | Key Usages | Enhanced Key Usages | Signature Algorithm |
Key Length |
|---|---|---|---|---|
| ClientAuthentication | Client Authentication (1.3.6.1.5.5.7.3.2) | SHA256 | 2048 | |
| DscEncryption | Key Encipherment, Data Encipherment (30) |
Document Encryption (1.3.6.1.4.1.311.80.1) | SHA256 | 2048 |
| DscPullServer | Digital Signature (80) | Client Authentication (1.3.6.1.5.5.7.3.2) | SHA256 | 2048 |
| ProvisioningSSL | Data Encipherment, Key Encipherment (e0) |
Server Authentication (1.3.6.1.5.5.7.3.1) | SHA256 | 2048 |
| Root | Certificate Signing, Off-line CRL Signing, CRL Signing (06) |
SHA256 | 4096 | |
| ServerAuthentication | Digital Signature, Non-Repudiation, Key Encipherment (e0) |
Server Authentication (1.3.6.1.5.5.7.3.1) | SHA256 | 2048 |
| SSL | Digital Signature, Non-Repudiation, Key Encipherment (e0) |
SHA256 | 2048 |
Generating Certificates
Certificates can be generated as part of the installer process or supplied from an external PKI. By default,
the New-RpsNodeConfiguration.ps1 script will generate self-signed certificates for each role and server using the existing configuration data.
If external certificates will be used,the certificate data file located at {ContentRoot}\Setup\Configuration\MNCertificateData.psd1 will need
to be updated to store the certificate role and password information.
The certificates themselves must also be stored in the following path: {ContentRoot}\Certificates.
The naming convention required for each certificate file should be as follows: {TargetItemName}_{CertificateRole}.pfx/cer.
Set-RpsCertificate
As part of the Rps-Encryption PowerShell module,
the Set-RpsCertificate function generates a certificate based on Rps template and imports it into the CMDB.
If the certificate already exists at the path specified,
it will only import the certificate into the CMDB.
For detailed documentation on this function from PowerShell, run Get-Help Set-RpsCertificate.
Example:
$properties = @{
SigningCertificate = @{
Name = 'RpsRoot.pfx'
Password = 'ExamplePasswordHere'
}
CertificateFolderPath = 'C:\ContentStore\Certificates'
'Member.Unit.Domain' = @{
RpsSync = 'ExamplePasswordHere'
}
}
$targetItem = Get-RpsTargetItem -Name 'Member.Unit.Domain' -Type 'VirtualMachine'
Set-RpsCertificate -Role RpsSync -Target $targetItem -Properties $properties
New-RpsCertificate
Also part of the Rps-Encryption module, the New-RpsCertificate function allows you to create template driven certificates.
The function will generate certificates but do not import the certificate into an existing Rps session.
For detailed documentation on this function from PowerShell, run Get-Help Set-RpsCertificate.
Example:
$parameters = @{
Type = 'SSL'
SubjectName = 'Member'
SubjectAlternativeName = 'member.unit.domain'
FriendlyName = 'Member.unit.domain RpsWebApiSSL'
OutputPath = 'C:\ContentStore\Certificates\Member.unit.domain_RpsWebApiSSL.pfx'
Password = ConvertTo-SecureString 'ExamplePassword' -AsPlainText -Force
NotBefore = Get-Date
NotAfter = (Get-Date).AddYears(2)
SigningCertificatePath = 'C:\ContentStore\Certificates\RpsRoot.pfx'
SigningCertificatePassword = ConvertTo-SecureString 'ExamplePasswordHere' -AsPlainText -Force
}
New-RpsCertificate @parameters
Import-RpsCertificate
As part of the Rps-Installer module, the Import-RpsCertificate function allows you to import an existing certificate into the Rps CMDB.
For detailed documentation on this function from PowerShell, run Get-Help Set-RpsCertificate.
Example:
# Get the target item to assign the certificate to.
$targetItem = Get-RpsTargetItem -Name 'Member.Unit.Domain' -Type 'VirtualMachine'
$password = ConvertTo-SecureString 'ExamplePasswordHere' -AsPlainText -Force
Import-RpsCertificate -Name 'Member.unit.domain_RpsWebApiSSL' -Path 'C:\ContentStore\Certificates\Member.unit.domain_RpsWebApiSSL.pfx' -Password $password -AssignTo $targetItem -Role RpsWebApiSsl
The New-RpsCertificate function implements the New-RpsSelfSignedCertificate function in the Rps-Encryption Module.
The New-RpsSelfSignedCertificate function is generic and allows the configuration of many different certificate settings.
PostgreSQL Encryption
SSL connections encrypt all data sent across the network: the password, the queries, and the data returned. The pg_hba.conf file allows administrators to specify which hosts can use non-encrypted connections (host) and which require SSL-encrypted connections (hostssl). Also, clients can specify that they connect to servers only via SSL. Stunnel or SSH can also be used to encrypt transmissions.
RPS Database Encryption
RPS is configured to use SSL connections for the RPS CMDB using DSC. The certificate used to secure the DEK is generated automatically with DSC,
is called RpsDatabaseCertificate.crt, and is backed up to disk (by default in C:\Backups\Certificates).
The server’s master key is backed up to RpsDatabaseMasterKey.crt using the password supplied for the RPS Configuration.
Warning
The compromise of the certificates could allow malicious users to retrieve unencrypted data. Follow proven certificate management and backup practices to mitigate security vulnerabilities while preserving the ability for a legitimate administrator to restore the RPS CMDB or TMS databases if needed.