With the new Keystore Monitor available with 24-June-2017 release (2.29*), you can maintain your keys and certificates yourself. This blog describes how to use this monitor to import certificates of systems you want to connect, how to add keys and how to download certificates from your cloud integration tenant for importing into backends to connect.
For connecting sender or receiver systems the tenant administrator needs to maintain keys and certificates in different systems, sender, receiver and the Cloud Integration tenant. The new keystore monitor available in cluster 2.x in the cloud integration tenant can now be used to execute the certificate management by yourself, without the need to create service requests to the cloud operations team.
The new Keystore Monitor separates the keys and certificates into SAP owned entries and entries owned by the tenant administrator. There is a clear separation based on user roles, SAP is not allowed to change the content of the tenant administrator and the tenant administrator is not allowed to change or delete SAP owned entries.
The monitor is available in Operations View in Web. In section Manage Security, you find the Keystore tile, which directly informs you about the number of keys and certificates available in the tenant keystore.
In the first version of the monitor you are able to see all entries contained in the tenant keystore, also the SAP owned keys and certificates are visible and the public part of them can be downloaded. Furthermore, you can upload externally created keystores with key pairs and certificates and download public content of the keystore. Expired keys and certificates are highlighted showing the expiration date.
With 12-November-2017 release, you can navigate to the details of a certificate or key pair by clicking the alias. This will open the details view. For certificates you see the details of the selected certificate, the fingerprints and who created and changed the certificate. For key pairs, in addition, you see the certificate chain on the navigation pane on the left. At the top of the chain normally the root CA can be found, followed by one or more intermediate certificates and the key pair:
A sample setup of an outbound communication using client certificates using the new monitor is described in the blog ‘How to Setup Secure Outbound HTTP Connection using Keystore Monitor’.
To separate the entries in the keystore specific naming conventions were introduced. Tenant Administrators are therefore not allowed to create aliases with prefix sap_, this prefix and the aliases hcicertificate, hcicertificate1 and hcimsgcertificate are reserved for SAP owned artifacts.
In the past (prior to release 2.29*) there was no separation between entries owned by the tenant administrator and owned by SAP. Then the keystore was typically maintained by SAP, via service requests customers could get their own certificates and keys added to the tenant keystore. In case there already is such a keystore with certificates and/or key pairs deployed in the cloud integration tenant these entries will automatically be migrated to the new keystore monitor as soon as there is a change done to the keystore entries.
The migration is done according to the naming conventions mentioned above, meaning all keys and certificates in SAP namespace will be converted into SAP owned entries, which cannot be changed by customers. Keys and certificates not matching the SAP naming conventions will be converted into customer owned artifacts and will be from now on managed by the customer tenant administrator.
Furthermore, during the migration three SAP owned CA root certificates, which enable the communication to SAP cloud systems, like Ariba and CRM, are added to the tenant keystore. If the Tenant Administrator detects that one of the three SAP CA root certificates is also available as customer owned certificate, the Tenant Administrator can delete this duplicate entry.
Note: Before the migration the number of available entries in the keystore is not known and so the keystore tile on the overview screen does not show the number of entries. After the first change in the new Keystore Monitor the number of entries in the keystore tile will show the correct number of entries.
In the first version of the Keystore Monitor only externally created keystores could be merged into the tenant keystore. For maintaining external keystores you can, for example, use the keystore explorer described in the cloud integration documentation chapter ‘Creating X.509 Keys’.
To add root certificates from backends or additional private keys you needed to first import them into a keystore via external tool and upload this keystore afterwards in Keystore Monitor via Add -> Key Store action at the top of the monitor. An upload dialog will appear asking for the keystore to upload and the password of the keystore.
Furthermore, you select if the entries shall be added or the whole keystore is to be replaced. When selecting Add it is also possible to choose Overwrite to overwrite entries with the same alias.
Note: With the Replace and Overwrite option existing entries will be overwritten, so be careful using these options. Overwrite will also overwrite private key pairs with public certificate in case the alias is the same.
After the import a confirmation screen will be shown summarizing which entries were added or overwritten and which entries could not be imported, for example because they are using the SAP prefix or because an alias with the same name already exists.
With the 15-April-2018 update the option to import single certificates is added. In Keystore Monitor select Add -> Certificate action at the top of the monitor. An upload dialog appears asking for the certificate to upload and the alias to be used for the certificate.
With the 15-April-2018 update the option to import single key pairs is added. In Keystore Monitor select Add -> Key Pair action at the top of the monitor. An upload dialog appears asking for the alias for the key pair and the key pair file to upload. In addition you need to enter the password of the key pair.
With the 12-May-2019 update you can also upload SSH keys to the keystore monitor. It is possible to upload SSH or putty keys. In Keystore Monitor choose Add -> SSH Key to upload a putty or SSH key for the sftp connectivity.
In the upload dialog select the putty or SSH key and specify the password for the key and define the key specific values and a validity period. The alias is generated automatically based on the key type of the putty or SSH key:
Select Add to create the key. If a key with the respective alias already exists, an error message is given. In this case you may use the existing one for your scenario or use a different Key Type or rename the existing alias.
With the 02-September-2018 release you will have the option to create private keys directly in the Keystore monitor. You can create SSH Keys to be used for secure connection to sftp servers and Key Pairs for secure SSL connections and encryption and signature.
Creating private key pairs is available via Create action at the top of the monitor. Select Key Pair to create a private key in the keystore:
In the creation dialog enter the Alias you want to use, select and define the key specific values and define a validity period. Select Deploy to create the key. If a key with the defined alias already exists, an error message is given. In this case you have to use a different Alias.
Note that creating signing requests for this key is available only with the 30-Setember-2018 release, then this key can be signed and used for setting up SSL connections. How to create signing requests and import the response is described below.
Creating SSH keys is available via Create action at the top of the monitor.
In the creation dialog select and define the key specific values and define a validity period. The alias is generated automatically based on the selected Key Type:
Select Deploy to create the key. If a key with the respektive alias already exists, an error message is given. In this case you have to either use a different Key Type or rename the existing alias.
The SSH key can be used as is for setting up secure connection to sftp servers.
To get root certificates to be imported into backend keystores the download option form Keystore monitor can be used. Either download the whole keystore or download single certificates or the certificate chain for a key pair.
Downloading the whole keystore is available via Download action at the top of the monitor. The public part of the keystore will be downloaded into a file with the name system.jks. The file is saved without password and can be opened and changed with any external keystore editor. It can also be used for importing into the keystore of another tenant.
Note: The download only downloads the public content of the keystore, private keys are not downloaded for security reason. This means if you download the keystore and import it again with the overwrite option, this overwrite the private keys! Do not use the download as backup option, for this use the backup functionality available in the keystore monitor.
Downloading single certificates or keys, or the certificate chain of the private key pairs can be done using the single line actions. Download is available for SAP owned artifacts as well to enable customers to use the provisioned private key pair to setup connections to external systems.
Selecting Download for a certificate will create a certificate file with the name <alias>.cer in the download directory. This certificate file can be imported into other keystores or backend systems, if required.
Download Certificate Chain for a Key Pair will create a file with the name <alias>.p7b in the download directory. The file contains the whole certificate chain assigned to the private key, which can be used for client certificate authentication.
Via external tools, for example the Certificates Snap-in of Microsoft Management Console (Certmgr.msc), which is usually available on Windows systems, you can open the certificate chain. The entry on the top is the root certificate. Opening it in the Details tab there is the option Copy to File, which will start the export of the certificate into a *.cer file, which can be imported into receiver backend systems.
Furthermore, Download Certificate option is available, which will download the public certificate of the key pair file with the name <alias>.cer. This file can be imported into backends during connection setup.
The option Download Root Certificate is available with 28-October-2018 release, which will download the root certificate of the certificate chain with the name <alias>_rootCA.cer. This file can be imported into backends during connection setup.
In addition to the already described option Download Certificate for an id_rsa, id_dsa and id_ecdsa key pair the option Download Public OpenSSH Key is available. This option will create an id_rsa.pub, id_dsa.pub or id_ecdsa.pub file in the download directory. The file contains the certificate in openSSH format, which can be used to to setup the connection to the sftp server.
Detailed setup of sftp connection using the keystore is described in Blog 'How to setup secure sftp communication'.
With the 28-October-2018 release you will have the option to sign your created key pair. You can create a Signing Request in the Keystore Monitor, send it to a Certificate Signing Authority (CA) and import the Signing Response in the Keystore Monitor. Afterwards this Key Pair can be used for secure SSL connections and encryption and signature.
To create a signing request for a Key Pair you can use the option Download -> Download Signing Request in the details screen for the key pair. The download creates a file with the name <alias>.csr. This file can be send to a CA for signing the key.
Once you received the signing response from the CA you can upload this usíng the option Update -> Signing Response in the details screen for the key pair. Select the file containing the signing response and select Update. The signature details are shown in the details of the key pair when you navigate through the certificate chain.
With the 18th-Feb-2018 update the option to rename the Alias is available. This option is available as Rename in the single line actions for keys and certificates owned by the tenant administrator.
The details screen for this certificate/key is opened in edit mode. Change and afterwards Save the alias. The option is also available in the details screen directly, switch to Rename, change and Save the alias.
Note, that changing the alias name may lead to issues in running scenarios, so keep in mind to change the alias in the integrations flows using the alias as well.
With the 5th-August-2018 update the option to update the Certificate or Key Pair for an existing Alias is available. This option is available as Update in the single line actions for keys and certificates owned by the tenant administrator.
An upload dialog opens requesting to upload the new certificate or key pair file:
When uploading an updated Key Pair the password of the private key file needs to be entered as well:
After the upload the details screen for this certificate/key is opened with the updated certificate or key pair.
Note, that changing an existing certificate or key pair may lead to issues in running scenarios. You may have to adjust pubic certificates in the connected backends. Because of this risk, it is recommended to backup the keystore before this change. Then you have a chance to restore the old keystore with it's certificates and key pairs.
The backup and restore feature is described in detail in Blog Configure Backup and Restore using Keystore Monitor.
Delete single entries is available as action on the single line items. SAP owned certificates and key pairs cannot be deleted, hence there is no option to delete them.
The Renewal feature for SAP owned keys is described in the Blog 'Activate Keys in Keystore Monitor'.
To secure the use of Keystore Monitor in Web, two roles are available.
With the role NodeManager.read the user is able to see the entries in keystore and to download public content, but creation of entries and changes are not possible. For changing role NodeManager.deploysecuritycontent is required.
Role NodeManager.read is available in the group roles AuthGroup.IntegrationDeveloper and AuthGroup.ReadOnly, and role NodeManager.deploysecuritycontent is contained in group role AuthGroup.Administrator.
The following size restrictions exist for the keystore:
For all the actions in the tenant keystore OData APIs are available. The APIs are described in more detail in the SAP Cloud Integration documentation chapter ‘API documentation – OData API’.
An option how to get notified about keys and certificates, which will soon expire, is described in the Blog 'Automated Notification of Keystore Entries Reaching Expiry'.
The keystore deployment that was available in eclipse for managing certificates is not available anymore. Also downloading keystores was disabled with the introduction of the Keystore Monitor in Web.
Maintain Keys and Certificates in Keystore Monitor
For connecting sender or receiver systems the tenant administrator needs to maintain keys and certificates in different systems, sender, receiver and the Cloud Integration tenant. The new keystore monitor available in cluster 2.x in the cloud integration tenant can now be used to execute the certificate management by yourself, without the need to create service requests to the cloud operations team.
The new Keystore Monitor separates the keys and certificates into SAP owned entries and entries owned by the tenant administrator. There is a clear separation based on user roles, SAP is not allowed to change the content of the tenant administrator and the tenant administrator is not allowed to change or delete SAP owned entries.
Keystore Monitor in Web
The monitor is available in Operations View in Web. In section Manage Security, you find the Keystore tile, which directly informs you about the number of keys and certificates available in the tenant keystore.
In the first version of the monitor you are able to see all entries contained in the tenant keystore, also the SAP owned keys and certificates are visible and the public part of them can be downloaded. Furthermore, you can upload externally created keystores with key pairs and certificates and download public content of the keystore. Expired keys and certificates are highlighted showing the expiration date.
Details of Certificates and Key Pairs
With 12-November-2017 release, you can navigate to the details of a certificate or key pair by clicking the alias. This will open the details view. For certificates you see the details of the selected certificate, the fingerprints and who created and changed the certificate. For key pairs, in addition, you see the certificate chain on the navigation pane on the left. At the top of the chain normally the root CA can be found, followed by one or more intermediate certificates and the key pair:
A sample setup of an outbound communication using client certificates using the new monitor is described in the blog ‘How to Setup Secure Outbound HTTP Connection using Keystore Monitor’.
Naming Conventions
To separate the entries in the keystore specific naming conventions were introduced. Tenant Administrators are therefore not allowed to create aliases with prefix sap_, this prefix and the aliases hcicertificate, hcicertificate1 and hcimsgcertificate are reserved for SAP owned artifacts.
Migration of existing Keystores
In the past (prior to release 2.29*) there was no separation between entries owned by the tenant administrator and owned by SAP. Then the keystore was typically maintained by SAP, via service requests customers could get their own certificates and keys added to the tenant keystore. In case there already is such a keystore with certificates and/or key pairs deployed in the cloud integration tenant these entries will automatically be migrated to the new keystore monitor as soon as there is a change done to the keystore entries.
The migration is done according to the naming conventions mentioned above, meaning all keys and certificates in SAP namespace will be converted into SAP owned entries, which cannot be changed by customers. Keys and certificates not matching the SAP naming conventions will be converted into customer owned artifacts and will be from now on managed by the customer tenant administrator.
Furthermore, during the migration three SAP owned CA root certificates, which enable the communication to SAP cloud systems, like Ariba and CRM, are added to the tenant keystore. If the Tenant Administrator detects that one of the three SAP CA root certificates is also available as customer owned certificate, the Tenant Administrator can delete this duplicate entry.
Note: Before the migration the number of available entries in the keystore is not known and so the keystore tile on the overview screen does not show the number of entries. After the first change in the new Keystore Monitor the number of entries in the keystore tile will show the correct number of entries.
Adding Entries to the Keystore
Add Key Store
In the first version of the Keystore Monitor only externally created keystores could be merged into the tenant keystore. For maintaining external keystores you can, for example, use the keystore explorer described in the cloud integration documentation chapter ‘Creating X.509 Keys’.
To add root certificates from backends or additional private keys you needed to first import them into a keystore via external tool and upload this keystore afterwards in Keystore Monitor via Add -> Key Store action at the top of the monitor. An upload dialog will appear asking for the keystore to upload and the password of the keystore.
Furthermore, you select if the entries shall be added or the whole keystore is to be replaced. When selecting Add it is also possible to choose Overwrite to overwrite entries with the same alias.
Note: With the Replace and Overwrite option existing entries will be overwritten, so be careful using these options. Overwrite will also overwrite private key pairs with public certificate in case the alias is the same.
After the import a confirmation screen will be shown summarizing which entries were added or overwritten and which entries could not be imported, for example because they are using the SAP prefix or because an alias with the same name already exists.
Add Certificate
With the 15-April-2018 update the option to import single certificates is added. In Keystore Monitor select Add -> Certificate action at the top of the monitor. An upload dialog appears asking for the certificate to upload and the alias to be used for the certificate.
Add Key Pair
With the 15-April-2018 update the option to import single key pairs is added. In Keystore Monitor select Add -> Key Pair action at the top of the monitor. An upload dialog appears asking for the alias for the key pair and the key pair file to upload. In addition you need to enter the password of the key pair.
Add SSH key
With the 12-May-2019 update you can also upload SSH keys to the keystore monitor. It is possible to upload SSH or putty keys. In Keystore Monitor choose Add -> SSH Key to upload a putty or SSH key for the sftp connectivity.
In the upload dialog select the putty or SSH key and specify the password for the key and define the key specific values and a validity period. The alias is generated automatically based on the key type of the putty or SSH key:
- Key Type RSA -> generated alias: id_rsa
- Key Type DSA -> generated alias: id_dsa
- Key Type EC -> generated alias: id_ecdsa
Select Add to create the key. If a key with the respective alias already exists, an error message is given. In this case you may use the existing one for your scenario or use a different Key Type or rename the existing alias.
Creating Private Keys in the Keystore (option available with 02-September-2018 release)
With the 02-September-2018 release you will have the option to create private keys directly in the Keystore monitor. You can create SSH Keys to be used for secure connection to sftp servers and Key Pairs for secure SSL connections and encryption and signature.
Create Key
Creating private key pairs is available via Create action at the top of the monitor. Select Key Pair to create a private key in the keystore:
In the creation dialog enter the Alias you want to use, select and define the key specific values and define a validity period. Select Deploy to create the key. If a key with the defined alias already exists, an error message is given. In this case you have to use a different Alias.
Note that creating signing requests for this key is available only with the 30-Setember-2018 release, then this key can be signed and used for setting up SSL connections. How to create signing requests and import the response is described below.
Create SSH Key
Creating SSH keys is available via Create action at the top of the monitor.
In the creation dialog select and define the key specific values and define a validity period. The alias is generated automatically based on the selected Key Type:
- Key Type RSA -> generated alias: id_rsa
- Key Type DSA -> generated alias: id_dsa (because of security reasons not available anymore after the 14-04-2019 update)
- Key Type EC -> generated alias: id_ecdsa (new with the 14-04-2019 update)
Select Deploy to create the key. If a key with the respektive alias already exists, an error message is given. In this case you have to either use a different Key Type or rename the existing alias.
The SSH key can be used as is for setting up secure connection to sftp servers.
Downloading Keystore or Keystore entries
To get root certificates to be imported into backend keystores the download option form Keystore monitor can be used. Either download the whole keystore or download single certificates or the certificate chain for a key pair.
Download of Keystore
Downloading the whole keystore is available via Download action at the top of the monitor. The public part of the keystore will be downloaded into a file with the name system.jks. The file is saved without password and can be opened and changed with any external keystore editor. It can also be used for importing into the keystore of another tenant.
Note: The download only downloads the public content of the keystore, private keys are not downloaded for security reason. This means if you download the keystore and import it again with the overwrite option, this overwrite the private keys! Do not use the download as backup option, for this use the backup functionality available in the keystore monitor.
Download of Single Entries
Downloading single certificates or keys, or the certificate chain of the private key pairs can be done using the single line actions. Download is available for SAP owned artifacts as well to enable customers to use the provisioned private key pair to setup connections to external systems.
Download Options for Certificate
Selecting Download for a certificate will create a certificate file with the name <alias>.cer in the download directory. This certificate file can be imported into other keystores or backend systems, if required.
Download Options for Key Pair
Download Certificate Chain for a Key Pair will create a file with the name <alias>.p7b in the download directory. The file contains the whole certificate chain assigned to the private key, which can be used for client certificate authentication.
Via external tools, for example the Certificates Snap-in of Microsoft Management Console (Certmgr.msc), which is usually available on Windows systems, you can open the certificate chain. The entry on the top is the root certificate. Opening it in the Details tab there is the option Copy to File, which will start the export of the certificate into a *.cer file, which can be imported into receiver backend systems.
Furthermore, Download Certificate option is available, which will download the public certificate of the key pair file with the name <alias>.cer. This file can be imported into backends during connection setup.
The option Download Root Certificate is available with 28-October-2018 release, which will download the root certificate of the certificate chain with the name <alias>_rootCA.cer. This file can be imported into backends during connection setup.
Download Options for id_rsa, id_dsa and id_ecdsa Key Pair
In addition to the already described option Download Certificate for an id_rsa, id_dsa and id_ecdsa key pair the option Download Public OpenSSH Key is available. This option will create an id_rsa.pub, id_dsa.pub or id_ecdsa.pub file in the download directory. The file contains the certificate in openSSH format, which can be used to to setup the connection to the sftp server.
Detailed setup of sftp connection using the keystore is described in Blog 'How to setup secure sftp communication'.
Handle Signing Request for Key Pairs (option available with 28-October-2018 release)
With the 28-October-2018 release you will have the option to sign your created key pair. You can create a Signing Request in the Keystore Monitor, send it to a Certificate Signing Authority (CA) and import the Signing Response in the Keystore Monitor. Afterwards this Key Pair can be used for secure SSL connections and encryption and signature.
Download Signing Request
To create a signing request for a Key Pair you can use the option Download -> Download Signing Request in the details screen for the key pair. The download creates a file with the name <alias>.csr. This file can be send to a CA for signing the key.
Upload Signing Response
Once you received the signing response from the CA you can upload this usíng the option Update -> Signing Response in the details screen for the key pair. Select the file containing the signing response and select Update. The signature details are shown in the details of the key pair when you navigate through the certificate chain.
Rename Alias
With the 18th-Feb-2018 update the option to rename the Alias is available. This option is available as Rename in the single line actions for keys and certificates owned by the tenant administrator.
The details screen for this certificate/key is opened in edit mode. Change and afterwards Save the alias. The option is also available in the details screen directly, switch to Rename, change and Save the alias.
Note, that changing the alias name may lead to issues in running scenarios, so keep in mind to change the alias in the integrations flows using the alias as well.
Update Certificate or Key Pair for Existing Alias
With the 5th-August-2018 update the option to update the Certificate or Key Pair for an existing Alias is available. This option is available as Update in the single line actions for keys and certificates owned by the tenant administrator.
An upload dialog opens requesting to upload the new certificate or key pair file:
When uploading an updated Key Pair the password of the private key file needs to be entered as well:
After the upload the details screen for this certificate/key is opened with the updated certificate or key pair.
Note, that changing an existing certificate or key pair may lead to issues in running scenarios. You may have to adjust pubic certificates in the connected backends. Because of this risk, it is recommended to backup the keystore before this change. Then you have a chance to restore the old keystore with it's certificates and key pairs.
Backup/Restore of Keystore
The backup and restore feature is described in detail in Blog Configure Backup and Restore using Keystore Monitor.
Deleting entries from Keystore
Delete single entries is available as action on the single line items. SAP owned certificates and key pairs cannot be deleted, hence there is no option to delete them.
SAP Key Renewal
The Renewal feature for SAP owned keys is described in the Blog 'Activate Keys in Keystore Monitor'.
Authorizations
To secure the use of Keystore Monitor in Web, two roles are available.
With the role NodeManager.read the user is able to see the entries in keystore and to download public content, but creation of entries and changes are not possible. For changing role NodeManager.deploysecuritycontent is required.
Role NodeManager.read is available in the group roles AuthGroup.IntegrationDeveloper and AuthGroup.ReadOnly, and role NodeManager.deploysecuritycontent is contained in group role AuthGroup.Administrator.
Size Restrictions
The following size restrictions exist for the keystore:
- The maximum size of the whole keystore is currently 1MB.
- The maximum size allowed for a certificate is 3KB.
- The maximum size allowed for a key pair is 24KB.
APIs
For all the actions in the tenant keystore OData APIs are available. The APIs are described in more detail in the SAP Cloud Integration documentation chapter ‘API documentation – OData API’.
Configure Notification for Keystore Entry Expiry
An option how to get notified about keys and certificates, which will soon expire, is described in the Blog 'Automated Notification of Keystore Entries Reaching Expiry'.
Keystore Deployment in Eclipse
The keystore deployment that was available in eclipse for managing certificates is not available anymore. Also downloading keystores was disabled with the introduction of the Keystore Monitor in Web.
- SAP Managed Tags:
21 Comments
