New-NCacheTlsCertificate

The New-NCacheTlsCertificate PowerShell cmdlet generates the client certificate required when NCache clients connect to servers configured with mutual TLS. The cmdlet generates the private key locally on the machine where it is run, creates a Certificate Signing Request (CSR), and sends only the CSR for signing. The resulting client certificate is written as a PEM file containing the private key, leaf certificate, and any Intermediate certificates in that order.

The -Server parameter is required, regardless of whether you run the cmdlet on an NCache server, an NCache client, or a machine without an NCache installation. Use -Server to specify the registered NCache server from which the cmdlet reads the account email associated with the NCache license. If node security is enabled on that server, provide -Credentials. After generating the client certificate, configure tlsCertPath in the client application's ncache section to use the generated PEM file and then enable mutual TLS on the target servers with Enable-NCacheTLS -UseMutualTls.

Important

The generated PEM file contains an unencrypted private key. Keep the file permissions restricted to the account that runs the client application and do not copy the file to systems that do not require it. On Linux, the cmdlet restricts the file to its owner (chmod 600); on Windows, follow the icacls command suggested by the cmdlet output.

New-NCacheTlsCertificate [-Path] <string> -Server <string> [-Force] `
                         [-TlsCertPath <string>] [-TlsCertPassword <string>] `
                         [-Credentials <pscredential>] [-NoLogo]

Examples

  • This command requests a signed client certificate using the account registered on server 20.200.20.11 and writes the resulting PEM file to C:\ncache-certs\client.pem.
New-NCacheTlsCertificate -Server "20.200.20.11" -Path "C:\ncache-certs\client.pem"
  • This command writes the client certificate to /etc/ncache/client-certs/client.pem. Because a directory path is provided, the cmdlet appends client.pem. The -Force switch allows an existing file at that location to be replaced.
New-NCacheTlsCertificate -Server "20.200.20.11" -Path "/etc/ncache/client-certs/" -Force
  • This command requests a client certificate from a server where NCache node security is enabled. Get-Credential prompts for the credentials required to read the server's license and account information.
New-NCacheTlsCertificate -Server "20.200.20.11" -Path "client.pem" -Credentials (Get-Credential)
  • This command issues a client PEM from a machine without an NCache server installation when the target server already requires mTLS. The -TlsCertPath PEM is used to authenticate the cmdlet; it is not the new certificate written to -Path.
New-NCacheTlsCertificate -Server "20.200.20.11" -Path "C:\ncache-certs\client.pem" `
                         -TlsCertPath "C:\certs\existing-client.pem" `
                         -TlsCertPassword "clientKeyPassword"

Properties

Note

The parameters with an asterisk (*) are required, while the remaining parameters are optional.

Parameters Data Types Description Default Value
-Path* <String> Specifies where to write the generated client certificate as a PEM file. The file contains the private key, leaf certificate, and any Intermediate certificates in that order. If a directory or a path without a file extension is specified, the cmdlet appends client.pem. The cmdlet does not overwrite an existing file unless -Force is also specified. -
-Server* <String> Specifies the IP address or hostname of the registered NCache server from which the cmdlet reads the account email associated with the NCache license. The server does not need to have TLS enabled before this cmdlet is run. -
-Force <SwitchParameter> Overwrites an existing file at the resolved -Path. Without this switch, the cmdlet does not replace an existing client certificate file. False
-TlsCertPath <String> Existing client PEM certificate used to authenticate this PowerShell command to a server requiring mTLS when running from a machine without an NCache server installation. -
-TlsCertPassword <String> Password to decrypt the private key in -TlsCertPath, if encrypted. It is used only for the current command and is not stored on the NCache server. -
-Credentials <pscredential> Specifies the credentials required to read the license and account information from -Server when NCache node security is enabled on that server. -
-NoLogo <SwitchParameter> Suppresses display of the NCache logo banner. False