From c9f93caca1b24b4b637c2d8caa65e71061893eee Mon Sep 17 00:00:00 2001 From: Mikk Bachmann Date: Tue, 17 Dec 2024 13:03:44 +0200 Subject: [PATCH 1/2] feat: RHEL and Dockerized versions of the Security Server do not support migrating contacts from acme.yml to mail.yml refs: XRDDEV-2783 --- ...-ss_x-road_6_security_server_user_guide.md | 28 +++++++-------- .../ug-syspar_x-road_v6_system_parameters.md | 8 +++-- sidecar/files/_entrypoint_common.sh | 4 +++ .../niis/xroad/common/acme/AcmeService.java | 28 +++++++++------ .../ee/ria/xroad/common/SystemProperties.java | 2 +- .../acme_contacts_and_keystore_pw_migra.sh | 35 ++++++++++++++++++ .../redhat/SPECS/xroad-proxy-ui-api.spec | 5 +++ .../generic/xroad-proxy-ui-api.postinst | 36 ++----------------- 8 files changed, 81 insertions(+), 65 deletions(-) create mode 100755 src/packages/src/xroad/common/proxy-ui-api/usr/share/xroad/scripts/acme_contacts_and_keystore_pw_migra.sh diff --git a/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md b/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md index cbb1899922..6e078a562d 100644 --- a/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md +++ b/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md @@ -2,7 +2,7 @@ **X-ROAD 7** -Version: 2.88 +Version: 2.89 Doc. ID: UG-SS --- @@ -117,6 +117,7 @@ Doc. ID: UG-SS | 16.09.2024 | 2.86 | Acme automatic renewal related updates | Mikk-Erik Bachmann | | 28.10.2024 | 2.87 | Minor updates to remote database migration | Eneli Reimets | | 08.11.2024 | 2.88 | Add EC key support for authentication and signing certificates | Ovidijus Narkevicius | +| 17.12.2024 | 2.89 | Acme related updates | Mikk-Erik Bachmann | ## Table of Contents @@ -3250,17 +3251,17 @@ The ACME protocol can be used only if the Certificate Authority (CA) issuing the **Automatic certificate renewal** -Besides requesting new certificates from the ACME server, Security Server also runs automatic job periodically, that checks whether any of the existing certificates should be renewed and if so, new certificate is ordered and the old certificate removed. In case of authentication certificates, the old one is not removed until the new ordered certificate is manually registered on the Central Server. Whether the job runs and how often it runs is controlled by corresponding `[proxy-ui-api]` system parameters starting with [acme-renewal-*](ug-syspar_x-road_v6_system_parameters.md#39-management-rest-api-parameters-proxy-ui-api). The time when a certificate is ready for renewal is determined by the ACME server, if it supports it (ACME ARI extension \[[ACME-ARI](#Ref_ACME-ARI)\]). Otherwise, by a `acme-renewal-time-before-expiration-date` system parameter. +Besides requesting new certificates from the ACME server, Security Server also runs automatic job periodically, that checks whether any of the existing certificates should be renewed and if so, new certificate is ordered. Authentication certificate is sent for registration to the Central Server automatically, but enabling of the new ordered signing and authentication certificates needs to be done manually and once their enabled, the old certificates can be removed. Whether the job runs and how often it runs is controlled by corresponding `[proxy-ui-api]` system parameters starting with [acme-renewal-*](ug-syspar_x-road_v6_system_parameters.md#39-management-rest-api-parameters-proxy-ui-api). The time when a certificate is ready for renewal is determined by the ACME server, if it supports it (ACME ARI extension \[[ACME-ARI](#Ref_ACME-ARI)\]). Otherwise, by a `acme-renewal-time-before-expiration-date` system parameter. The renewal status of ACME supported certificates can be seen on the Keys and certificates page: -* **"N/A"** - certificate is not `REGISTERED` or not issued by ACME supported CA. -* **"Renewal in progress"** - Renewal has started, but is not yet finished. This can be shown on Authentication certificates that have new certificate ordered, but not yet manually registered on the Central Server. +* **"N/A"** - certificate is not `REGISTERED` or not issued by ACME supported CA and is ignored by the automatic certificate renewal job. +* **"Renewal in progress"** - Renewal has started, but is not yet finished. Once the new certificate is registered and enabled, this certificate can be removed. * **"Renewal error:"** followed by an error message - indicates that the last renewal attempt has failed, also showing the reason for the failure. * **"Next planned renewal on"** followed by a date - indicates when the next renewal should happen. Note that this date might change in the future when the information is received from the ACME Server. **E-mail notifications** -Automatic certificate renewal process also has the option to notify members with an e-mail in case of a successful renewal as well as of failure. Successful and failure notifications can be turned on and off separately with a [system paramater](ug-syspar_x-road_v6_system_parameters.md#39-management-rest-api-parameters-proxy-ui-api). The member's e-mail defined in the contact information in the `mail.yml` file is used as the recipient. +Automatic certificate renewal process also has the option to notify members with an e-mail in case of a successful renewal as well as of failure. Successful and failure notifications can be turned on and off separately with a [system paramater](ug-syspar_x-road_v6_system_parameters.md#39-management-rest-api-parameters-proxy-ui-api). The member's e-mail defined in the contact information in the `mail.yml` file is used as the recipient. These are also used as contact information of the member for whom the certificate is ordered from ACME Server. It is passed along to the Certificate Authority at the beginning of the communication between Security Server and the CA's ACME server. For the e-mail notifications to work a mail server needs to be configured beforehand in the `/etc/xroad/conf.d/mail.yml` file. These include: @@ -3280,9 +3281,8 @@ The Security Server has a `[proxy-ui-api]` parameter [acme-challenge-port-enable Although the main ACME-related configuration is managed on the Central Server and distributed to the Security Servers over the Global Configuration, in order to use the ACME standard, some of the member-specific configurations have to be set on the Security Server side as well. These configurations go in the file `acme.yml`, that is in the configurations folder on the file system (default `/etc/xroad/conf.d`). An example file is added by the installer when installing or upgrading X-Road to version 7.5. The configurations to be added are: -1. Contact information, usually an email address, of the member for whom the certificate is ordered. It is passed along to the Certificate Authority at the beginning of the communication between Security Server and the CA's ACME server. - -2. Credentials (kid and hmac secret) for external account binding. Some CAs require these for added security. They tie the X-Road member to an external account on the Certificate Authority's side and so need to be acquired externally from the CA. +1. Credentials (kid and hmac secret) for external account binding. Some CAs require these for added security. They tie the X-Road member to an external account on the Certificate Authority's side and so need to be acquired externally from the CA. +2. `account-keystore-password` - a password of the ACME Server account PKCS #12 keystore that is populated automatically by the Security Server, when communicating with the ACME Server. There are currently two ways to let the ACME server know which type of certificate to return (the chosen CA also needs to support them). The first one, which sends profile ids for authentication and signing certificates in http header, does not require any further configuration on the Security Server side. The second one uses certificate type specific external account credentials. For the authentication certificate add "**auth-**" prefix to the external account binding credentials property names in the `/etc/xroad/conf.d/acme.yml` file. For the signing certificate add the prefix "**sign-**". @@ -3293,14 +3293,6 @@ Example of the `/etc/xroad/conf.d/acme.yml` file contents (can be found from `/e # that is used to automate acquiring certificates from Certificate Authorities. To use this file # remove '.example' form the file name and replace with correct values as needed or create a new file named 'acme.yml'. -# Contact emails for each Member used when ordering certificates from the ACME Servers, -# where the key is the Member ID in the form :: and -# should also be surrounded by quotation marks to allow for ':' (both single and double work). -# When ordering Authentication Certificates, Security Server owner's Member ID is used. -contacts: - 'EU:COM:1234567-8': member1@example.org - 'EU:GOV:9090909-1': member2@example.org - # ACME external account binding credentials grouped by Certification Authorities(CA-s) and Members, # where CAs have their name as key and should be surrounded by quotation marks to allow spaces. # For Members the key is the Member ID in the form :: and @@ -3326,6 +3318,10 @@ eab-credentials: kid: kid123 mac-key: goodlongsecretwordthatisnotshort +# This is a password of the ACME Server account PKCS #12 keystore that is populated automatically by the Security Server. +# Keystore is at /etc/xroad/ssl/acme.p12 +account-keystore-password: acmep12Password1234 + ``` ## 25 Migrating to EC Based Authentication and Signing Certificates diff --git a/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md b/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md index b74b88278d..6dd8c785b5 100644 --- a/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md +++ b/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md @@ -1,6 +1,6 @@ # X-Road: System Parameters User Guide -Version: 2.92 +Version: 2.93 Doc. ID: UG-SYSPAR @@ -103,6 +103,7 @@ Doc. ID: UG-SYSPAR | 08.11.2024 | 2.90 | Added new parameters *key-named-curve*, *soft-token-pin-keystore-algorithm*, *authentication-key-algorithm* and *signing-key-algorithm* to add ECDSA support for Authentication/Signing certificates | Ovidijus Narkevicius | | 09.12.2024 | 2.91 | Rename parameters *global_conf_tls_cert_verification* -> *global-conf-tls-cert-verification*, *global_conf_hostname_verification* -> *global-conf-hostname-verification* | Eneli Reimets | | 12.12.2024 | 2.92 | Added new parameter *server-conf-service-endpoints-cache-size* | Eneli Reimets | +| 17.12.2024 | 2.93 | Added *acme-keypair-renewal-time-before-expiration-date*, changed the default for *acme-renewal-interval* | Mikk-Erik Bachmann | ## Table of Contents @@ -454,9 +455,10 @@ the message log. | acme-certificate-wait-attempts | 5 | Number of attempts to check whether the ACME certificate is ready before giving up | | acme-certificate-wait-interval | 5000 | Amount of time in milliseconds to wait between ACME certificate completion check attempts | | acme-certificate-account-key-pair-expiration | 365 | Amount of days the ACME server account's self-signed certificate is valid | -| acme-challenge-port-enabled | false | If enabled, the API will listen on port 80 for incoming acme challenge requests | +| acme-keypair-renewal-time-before-expiration-date | 14 | When to trigger automatic ACME account keypair renewal subtracted as days from the expiration date of the certificate | +| acme-challenge-port-enabled | false | If enabled, the API will listen on port 80 for incoming ACME challenge requests | | acme-renewal-active | true | If enabled, the ACME automatic certificate renewal job will run periodically | -| acme-renewal-interval | 1200 | Amount of seconds between automatic ACME certificate renewal job runs | +| acme-renewal-interval | 3600 | Amount of seconds between automatic ACME certificate renewal job runs | | acme-renewal-retry-delay | 60 | Amount of seconds between automatic ACME certificate renewal runs, if the last run was a failure | | acme-renewal-time-before-expiration-date | 14 | When to trigger next automatic renewal. Subtracted as days from the expiration date of the certificate. Used when it's not possible to receive the ACME renewal information from the ACME server. | | acme-renewal-success-notification-enabled | true | If enabled, notification e-mail is sent to the member when automatic certificate renewal has successfully renewed a certificate | diff --git a/sidecar/files/_entrypoint_common.sh b/sidecar/files/_entrypoint_common.sh index 644c84689e..51f7d402c8 100755 --- a/sidecar/files/_entrypoint_common.sh +++ b/sidecar/files/_entrypoint_common.sh @@ -116,6 +116,10 @@ else warn "Installed version ($INSTALLED_VERSION) does not match packaged version ($PACKAGED_VERSION)" fi +if dpkg --compare-versions "$CONFIG_VERSION" lt-nl "7.6.0" && test -f /etc/xroad/conf.d/acme.yml; then + /usr/share/xroad/scripts/acme_contacts_and_keystore_pw_migra.sh +fi + # Generate internal and admin UI TLS keys and certificates if necessary if [ ! -f /etc/xroad/ssl/internal.crt ]; then log "Generating new internal TLS key and certificate" diff --git a/src/common/common-acme/src/main/java/org/niis/xroad/common/acme/AcmeService.java b/src/common/common-acme/src/main/java/org/niis/xroad/common/acme/AcmeService.java index 51406fc8e3..9ee86528e6 100644 --- a/src/common/common-acme/src/main/java/org/niis/xroad/common/acme/AcmeService.java +++ b/src/common/common-acme/src/main/java/org/niis/xroad/common/acme/AcmeService.java @@ -163,7 +163,8 @@ public void checkAccountKeyPairAndRenewIfNecessary(String memberId, ApprovedCAIn File acmeKeystoreFile = new File(acmeAccountKeystorePath); char[] storePassword = acmeProperties.getAccountKeystorePassword(); KeyStore keyStore = CryptoUtils.loadPkcs12KeyStore(acmeKeystoreFile, storePassword); - X509Certificate certificate = (X509Certificate) keyStore.getCertificate(memberId); + String alias = getAlias(memberId, keyUsage, caInfo); + X509Certificate certificate = (X509Certificate) keyStore.getCertificate(alias); int renewalTimeBeforeExpirationDate = SystemProperties.getAcmeKeypairRenewalTimeBeforeExpirationDate(); if (certificate != null && Instant.now() .isAfter(certificate.getNotAfter().toInstant().minus(renewalTimeBeforeExpirationDate, ChronoUnit.DAYS))) { @@ -173,11 +174,11 @@ public void checkAccountKeyPairAndRenewIfNecessary(String memberId, ApprovedCAIn login.getAccount().changeKey(keyPair); long expirationInDays = SystemProperties.getAcmeAccountKeyPairExpirationInDays(); - X509Certificate[] certificateChain = createSelfSignedCertificate(memberId, keyPair, expirationInDays); + X509Certificate[] certificateChain = createSelfSignedCertificate(alias, keyPair, expirationInDays); keyStore.setKeyEntry( - memberId, + alias, keyPair.getPrivate(), - memberId.toCharArray(), + alias.toCharArray(), certificateChain); log.info("Renewed acme account keypair for {}", memberId); } @@ -188,13 +189,7 @@ public void checkAccountKeyPairAndRenewIfNecessary(String memberId, ApprovedCAIn private KeyPair getAccountKeyPair(String memberId, KeyUsageInfo keyUsage, ApprovedCAInfo caInfo) throws GeneralSecurityException, IOException, OperatorCreationException { - AcmeProperties.Credentials credential = acmeProperties.getEabCredentials(caInfo.getName(), memberId); - String alias = memberId; - if (credential.getAuthKid() != null && keyUsage == KeyUsageInfo.AUTHENTICATION) { - alias = "auth_" + alias; - } else if (credential.getSignKid() != null && keyUsage == KeyUsageInfo.SIGNING) { - alias = "sign_" + alias; - } + String alias = getAlias(memberId, keyUsage, caInfo); File acmeKeystoreFile = new File(acmeAccountKeystorePath); KeyStore keyStore; char[] storePassword = acmeProperties.getAccountKeystorePassword(); @@ -236,6 +231,17 @@ private KeyPair getAccountKeyPair(String memberId, KeyUsageInfo keyUsage, Approv return keyPair; } + private String getAlias(String memberId, KeyUsageInfo keyUsage, ApprovedCAInfo caInfo) { + AcmeProperties.Credentials credential = acmeProperties.getEabCredentials(caInfo.getName(), memberId); + String alias = memberId; + if (credential.getAuthKid() != null && keyUsage == KeyUsageInfo.AUTHENTICATION) { + alias = "auth_" + alias; + } else if (credential.getSignKid() != null && keyUsage == KeyUsageInfo.SIGNING) { + alias = "sign_" + alias; + } + return alias; + } + private Account startSession(KeyUsageInfo keyUsage, ApprovedCAInfo caInfo, KeyPair keyPair, String memberId) throws AcmeException { log.info("Creating session with directory url: {}", caInfo.getAcmeServerDirectoryUrl()); String acmeUri; diff --git a/src/common/common-core/src/main/java/ee/ria/xroad/common/SystemProperties.java b/src/common/common-core/src/main/java/ee/ria/xroad/common/SystemProperties.java index 68da70026b..97900e8bad 100644 --- a/src/common/common-core/src/main/java/ee/ria/xroad/common/SystemProperties.java +++ b/src/common/common-core/src/main/java/ee/ria/xroad/common/SystemProperties.java @@ -1216,7 +1216,7 @@ public static int getAcmeCertificateRenewalRetryDelay() { * @return the ACME certificate renewal job interval in seconds */ public static int getAcmeCertificateRenewalInterval() { - return Integer.parseInt(System.getProperty(PROXY_UI_API_ACME_RENEWAL_INTERVAL, "1200")); + return Integer.parseInt(System.getProperty(PROXY_UI_API_ACME_RENEWAL_INTERVAL, "3600")); } /** diff --git a/src/packages/src/xroad/common/proxy-ui-api/usr/share/xroad/scripts/acme_contacts_and_keystore_pw_migra.sh b/src/packages/src/xroad/common/proxy-ui-api/usr/share/xroad/scripts/acme_contacts_and_keystore_pw_migra.sh new file mode 100755 index 0000000000..1fe779e59d --- /dev/null +++ b/src/packages/src/xroad/common/proxy-ui-api/usr/share/xroad/scripts/acme_contacts_and_keystore_pw_migra.sh @@ -0,0 +1,35 @@ +#!/bin/bash + +echo "Migrating contact information from acme.yml to mail.yml" + +awk '/^contacts:/ {contacts=1} { + if (/^ *#/) { + commentbuf = commentbuf $0 ORS; + } else if (/^eab-credentials:/ || !contacts) { + contacts=0; + commentbuf=""; + } else if (!/^ *#/) { + printf "%s", commentbuf; + commentbuf=""; + } + } !/^ *#/ && contacts' /etc/xroad/conf.d/acme.yml >> /etc/xroad/conf.d/mail.yml + +if test -f /etc/xroad/ssl/acme.p12; then + echo "Generating new stronger password for ACME account keystore" + + deststorepass=$(head -c 24 /dev/urandom | base64 | tr "/+" "_-") + echo "account-keystore-password: $deststorepass" >>/etc/xroad/conf.d/acme.yml + + awk '/^contacts:/{contacts=1;next} /^eab-credentials:/{contacts=0} + /'\'':/ && contacts {print substr($0, index($0, "'\''")+1, index($0, "'\'':")-4)} + /\":/ && contacts {print substr($0, index($0, "\"")+1, index($0, "\":")-4)}' /etc/xroad/conf.d/acme.yml > /etc/xroad/conf.d/temp_member_codes.txt + + while read membercode; do + if keytool -list -keystore /etc/xroad/ssl/acme.p12 -alias "$membercode" | grep -q "PrivateKeyEntry"; then + echo | keytool -importkeystore -srckeystore /etc/xroad/ssl/acme.p12 -srcstoretype PKCS12 -destkeystore /etc/xroad/ssl/acme_tmp.p12 -deststoretype PKCS12 -deststorepass "$deststorepass" -srcalias "$membercode" -srckeypass "$membercode" + fi + done /dev/null 2>&1 || : fi diff --git a/src/packages/src/xroad/ubuntu/generic/xroad-proxy-ui-api.postinst b/src/packages/src/xroad/ubuntu/generic/xroad-proxy-ui-api.postinst index 10175b94a5..fd1f1c9006 100644 --- a/src/packages/src/xroad/ubuntu/generic/xroad-proxy-ui-api.postinst +++ b/src/packages/src/xroad/ubuntu/generic/xroad-proxy-ui-api.postinst @@ -31,40 +31,8 @@ case "$1" in crudini --set /etc/xroad/conf.d/local.ini proxy-ui-api strict-identifier-checks false fi - if dpkg --compare-versions "$2" lt-nl "7.5.0" && test -f /etc/xroad/conf.d/acme.yml; then - log "Migrating contact information from acme.yml to mail.yml" - - awk '/^contacts:/ {contacts=1} { - if (/^ *#/) { - commentbuf = commentbuf $0 ORS; - } else if (/^eab-credentials:/) { - contacts=0; - commentbuf=""; - } else if (!/^ *#/) { - printf "%s", commentbuf; - commentbuf=""; - } - } !/^ *#/ && contacts' /etc/xroad/conf.d/acme.yml >> /etc/xroad/conf.d/mail.yml - - if test -f /etc/xroad/ssl/acme.p12; then - log "Generating new stronger password for ACME account keystore" - - deststorepass=$(head -c 24 /dev/urandom | base64 | tr "/+" "_-") - echo "account-keystore-password: $deststorepass" >>/etc/xroad/conf.d/acme.yml - - awk '/^contacts:/{contacts=1;next} /^eab-credentials:/{contacts=0} - /'\'':/ && contacts {print substr($0, index($0, "'\''")+1, index($0, "'\'':")-4)} - /\":/ && contacts {print substr($0, index($0, "\"")+1, index($0, "\":")-4)}' /etc/xroad/conf.d/acme.yml > /etc/xroad/conf.d/temp_member_codes.txt - - while read membercode; do - if keytool -list -keystore /etc/xroad/ssl/acme.p12 -alias "$membercode" | grep -q "PrivateKeyEntry"; then - echo | keytool -importkeystore -srckeystore /etc/xroad/ssl/acme.p12 -srcstoretype PKCS12 -destkeystore /etc/xroad/ssl/acme_tmp.p12 -deststoretype PKCS12 -deststorepass "$deststorepass" -srcalias "$membercode" -srckeypass "$membercode" - fi - done Date: Wed, 18 Dec 2024 13:16:13 +0200 Subject: [PATCH 2/2] docs: Editorial update to the Security Server User Guide refs: XRDDEV-2783 --- .../ug-ss_x-road_6_security_server_user_guide.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md b/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md index 6e078a562d..5a10b05aab 100644 --- a/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md +++ b/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md @@ -3245,25 +3245,29 @@ In case it is needed to pass additional flags to internally initialized `PGOPTIO ## 24 Configuring ACME -Automated Certificate Management Environment \[[ACME](#Ref_ACME)\] protocol enables automated certificate management of the authentication and sign certificates on the Security Server. The Security Server supports automating most of the certificate request process, but the process has to be initiated manually. Also, activating and/or registering the received certificates is a manual task. +Automated Certificate Management Environment \[[ACME](#Ref_ACME)\] protocol enables automated certificate management of the authentication and sign certificates on the Security Server. The Security Server supports automating the certificate request process, but the process has to be initiated manually when applying for a certificate for the first time. Also, activating the received certificates is a manual task. The ACME protocol can be used only if the Certificate Authority (CA) issuing the certificates supports it and the X-Road operator has enabled the use of the protocol on the Central Server. Therefore, also the communication between the CA's ACME server and the Security Server is disabled by default. In addition, some member-specific configuration is required on the Security Server. **Automatic certificate renewal** -Besides requesting new certificates from the ACME server, Security Server also runs automatic job periodically, that checks whether any of the existing certificates should be renewed and if so, new certificate is ordered. Authentication certificate is sent for registration to the Central Server automatically, but enabling of the new ordered signing and authentication certificates needs to be done manually and once their enabled, the old certificates can be removed. Whether the job runs and how often it runs is controlled by corresponding `[proxy-ui-api]` system parameters starting with [acme-renewal-*](ug-syspar_x-road_v6_system_parameters.md#39-management-rest-api-parameters-proxy-ui-api). The time when a certificate is ready for renewal is determined by the ACME server, if it supports it (ACME ARI extension \[[ACME-ARI](#Ref_ACME-ARI)\]). Otherwise, by a `acme-renewal-time-before-expiration-date` system parameter. +Authentication and sign certificates issued by a CA that supports ACME can be automatically renewed. Automatic renewal is enabled by default, but the Security Server administrator can turn it off. + +The Security Server runs an automatic renewal job periodically and tries to renew certificates ready for renewal. If the server supports the ACME ARI extension (\[[ACME-ARI](#Ref_ACME-ARI)\]), the time when a certificate is ready for renewal is determined by the ACME server. Otherwise, the time is defined by the `proxy-ui-api.acme-renewal-time-before-expiration-date` system property. The default value of the property is 14 days, which means that the Security Server starts trying to renew a certificate 14 days before it expires. The renewal job configuration can be managed by the `proxy-ui-api.acme-renewal-*` configuration properties. The renewal status of ACME supported certificates can be seen on the Keys and certificates page: -* **"N/A"** - certificate is not `REGISTERED` or not issued by ACME supported CA and is ignored by the automatic certificate renewal job. +* **"N/A"** - certificate is not `REGISTERED` or not issued by ACME supported CA and therefore, it is ignored by the automatic certificate renewal job. * **"Renewal in progress"** - Renewal has started, but is not yet finished. Once the new certificate is registered and enabled, this certificate can be removed. * **"Renewal error:"** followed by an error message - indicates that the last renewal attempt has failed, also showing the reason for the failure. * **"Next planned renewal on"** followed by a date - indicates when the next renewal should happen. Note that this date might change in the future when the information is received from the ACME Server. **E-mail notifications** -Automatic certificate renewal process also has the option to notify members with an e-mail in case of a successful renewal as well as of failure. Successful and failure notifications can be turned on and off separately with a [system paramater](ug-syspar_x-road_v6_system_parameters.md#39-management-rest-api-parameters-proxy-ui-api). The member's e-mail defined in the contact information in the `mail.yml` file is used as the recipient. These are also used as contact information of the member for whom the certificate is ordered from ACME Server. It is passed along to the Certificate Authority at the beginning of the communication between Security Server and the CA's ACME server. +The Security Server supports sending email notifications on ACME-related events. Notifications are sent in case of authentication and sign certificate renewal success and failure and authentication certificate registration success. The notifications can be turned on and off separately with [system paramaters](ug-syspar_x-road_v6_system_parameters.md#39-management-rest-api-parameters-proxy-ui-api). + +The member's e-mail address defined in the `mail.yml` configuration file is used as the recipient. The same email address is also used as a member-specific contact information when a certificate is ordered from the ACME Server. -For the e-mail notifications to work a mail server needs to be configured beforehand in the `/etc/xroad/conf.d/mail.yml` file. These include: +For the e-mail notifications to work, an external mail server needs to be configured beforehand in the `/etc/xroad/conf.d/mail.yml` configuration file. The configuration include: * **host** - host name used to connect to the mail server. * **port** - port number used to connect to the mail server. @@ -3271,7 +3275,7 @@ For the e-mail notifications to work a mail server needs to be configured before * **password** - used for authentication to the mail server. * **use-ssl-tls** - if "true", then full `ssl/tls` protocol is used for connection. If "false" or missing, then `starttls` protocol is used instead. -**host**, **port**, **username** and **password** are mandatory. If Diagnostics page shows that the configuration is incomplete, it means that at least one of them is missing. +The **host**, **port**, **username** and **password** properties are mandatory. The mail server configuration status can be viewed in the Diagnostics page. If the Diagnostics page shows that the configuration is incomplete, it means that at least one of required configuration properties is missing. Instead, if all the required configuration are in-place, a test email can be sent from the Diagnostics page. **Enable connections from the ACME server**