Note: The SMP Agent for ULM 8.x uses Communication Profiles to distribute certificates; this is an alternate method
The SMP Agent for Unix, Linux, and Mac (ULM) uses its certificate store.
By default, the SMP Agent for ULM will download the certificate bound to port 443 of the NS it is assigned to. This happens automatically when the agent is installed. This is the only certificate that the SMP Agent for ULM will download by itself.
It is possible and sometimes required, for the ULM agent to store multiple certificates. Such instances include when the Notification Server (NS) and Site Server (SS) or Package Server (PS) use different certificates or when switching certificates on an NS or SS. In these situations, the certificates must be manually exported from each server, combined into a single file, copied to a file on each client, and the agent must be configured, via an NS console setting, to find and load those certificates into the NS agent's certificate store. (The SMP Agent for ULM has its certificate store apart from anything the OS does.)
Following is a high-level description of the process to load multiple certificates to a ULM client, followed by additional notes and information.
Recommended steps to add multiple certificates to a ULM client:
- Export the certificate from the NS or site server. (See more detailed instructions, below.)
- Repeat this for all required certificates from all required servers.
- If multiple certificates were exported, combine them into a single file. (See example below.)
- Copy the new certificate file to the ULM client computer. It can be copied anywhere on the client computer. The file name and location of the client do not matter.
- In the NS console, browse to 'Targeted Agent Settings', select an appropriate policy or create a new one and assign appropriate targets/computers.
- In the Targeted Agent Settings policy, click the Unix/Linux/Mac tab and check "Use system CA store for certificate checks" and specify the full, absolute path and name of the new cert file from step #4, above.
- Allow the client to refresh policies. A new version of the agent's certificate store will be created and used by the agent for subsequent communication to the NS and any site or package servers.
- By default, the agent will automatically store the certificate bound to port 443 on the NS/SMP server upon initial installation or after an interactive reconfiguration of the agent (aex-configure -iconfigure).
- The default certificate is stored on the client in the /opt/altiris/notification/nsagent/etc//cainfo.pem. Please avoid adding any certificates to “info.pem” (except for testing purposes) as these will be lost during an agent upgrade. The "aex-configure -iconfigure" utility has a prompt to re-download the certificate with a given fingerprint. Agent version 7.5 and 7.5 SP1 will overwrite cainfo.pem! 7.6+ will add/append the certificate to cainfo.pem if required.
- The SMP Agent for ULM uses its certificate store. The location of this store is the /opt/altiris/notification/nsagent/etc/cainfo-merged.pem file. No certificates should be added to the file manually (except for testing purposes), as this file can be overwritten by an agent-initiated regeneration of the contents of this file.
- The ‘cainfo-merged.pem’ file is regenerated during several agent communication processes, such as sending basic inventory, refreshing policies, etc. The agent compares the contents of the following files and if any have changed since their last known state, the agent regenerates the cainfo-merged.pem file: 1) cainfo.pem, 2) cainfo-ss.pem and 3) the file specified in Targeted Agent Settings CA file setting. It is possible to manually run these processes to trigger the regeneration the cainfo-merged.pem file. (Note that a refresh policies may have to occur twice - once to get the new or updated targeted settings policy and once to regenerate the cainfo-merged.pem file.)
- When establishing communications with an NS or SS, the agent will attempt to do so with each certificate in the cainfo-merged.pem file, in order, until a connection is established. It is recommended that the certificates most likely to be used are placed at the beginning or top of the targeted agent settings CA file.
- For initial testing purposes, it is recommended that a new targeted agent settings policy be created and that a single computer be assigned to this new policy. This avoids needlessly locking out client computers in case of issues with the certificate or policy. Additional computers can be assigned after testing has been completed and this method has been validated.
- Only PEM formatted certificates are supported. When using MMC to export the client certificate from a Notification Server or Site Server, the proper format is: “Base-64 encoded X.509 (CER)”.
- When using a chain of certificates on the NS, it is typically sufficient to download only the cert that the agent will use - not every certificate in the chain. This lower-level cert usually has permission from the root certificate. So, the root certificate and any in-between certificates do not need to be in the ULM agent's certificate store.
- The file specified in the Targeted Agent Settings CA file can have multiple base64 certs. These will all be added to the cainfo-merged.pem file, which can also store multiple certificates. The agent will try each one until a connection is established.
BASE64DATA for certificate 1
BASE64DATA for certificate 2
Important notes regarding the Targeted Agent Settings for specifying an additional certificate file
- The file specified in the Targeted Agent Settings must include the full, absolute path (beginning from root (/) of the file containing the additional certificate(s). The file can be located anywhere on the client system. The file name does not matter as long as it is correctly named in the Targeted Agent Settings policy.
- Once the Targeted Agent Settings policy has been properly created and the targeted clients have refreshed policies, the corresponding client-side policy file will contain the following line indicating the name of the new certificate file. By default, the policy is found at: "/opt/altiris/notification/nsagent/var/policies/<targeted agent settings policy guid>.xml". (Hint: In the …/nsagent/var/policies directory, run “grep name *” to find the correct policy and policy guid.)
<CurlSSL SSLNSPublicHttpsCertFingerprint="" SSLVerifyPeer="yes" SSLVerifyHost="yes" CAInfo="/mycert.pem" CAPath=""/>
Important note regarding switching certificates on a Notification Server, Site Server, etc.:
- Please keep in mind that directing client computers to a different NS and/or adding Site servers, etc., certificates may need to be added to the clients prior to making the change. This is to ensure agent connectivity after these changes have been implemented.
The aex-getsscert utility
The new utility aex-getsscert can also be used to get a self-signed certificate from a specified Notification, Site or Package server. It can be interactive or non-interactive depending on the use command-line parameters. A soft link for this utility is created by default in the /usr/bin directory. It can easily be scripted. See 'aex-getsscert -h' for additional details. This only works for self-signed certificates, apparently.
Validating that a certificate is bound to port 443 on the SMP server
A certificate must be bound to port 443 on the NS/SMP server. See KB: TECH230421. Following is a screen shot that shows where this can be validated in IIS.
How to export a certificate
- On the Windows system that has the desired certificate, click ‘Start’.
- In the ‘search’ field, enter ‘certmgr.msc’.
- Right-click on the entry under ‘Programs’ and select ‘Run as administrator’.
- In the Cert Manager window, expand the left-pane tree and browse to the location of the desired certificate.
- Right-click on the desired certificate in the right-hand pane, select ‘All Tasks’, then ‘Export’. A new window will appear.
- Click 'Next' on the first dialog screen.
- Select 'No, do not export the private key', then click ‘Next’.
- Select 'Base-64-encoded X.509 (CER), then click 'Next'.
- Click ‘Browse’ to select an appropriate location to save the file.
- Give it a file name and click 'Save'.
- Click 'Next'.
- Click 'Finish'.