From c747b17d10ff75e0a3691b0c44e116668a7e076a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Freitag?= <mail@franek.fr>
Date: Wed, 31 Mar 2021 09:38:51 +0200
Subject: [PATCH] Key rollover: Doc new_privatekey_pass option
The old privatekey_pass was (wrongly) expected to be reused for the new
privatekey_pass. That prevented my SP from loading the new_privatekey.
Users could not log in from entities using the new key.
Clarify that the new key needs a new_privatekey_pass entry.
---
modules/saml/docs/keyrollover.md | 22 ++++++++++++++++++----
1 file changed, 18 insertions(+), 4 deletions(-)
diff --git a/modules/saml/docs/keyrollover.md b/modules/saml/docs/keyrollover.md
index 7a23448be..1053ccec4 100644
--- a/modules/saml/docs/keyrollover.md
+++ b/modules/saml/docs/keyrollover.md
@@ -22,7 +22,7 @@ If you are doing key rollover for a service provider, the new key must be added
To do key rollover for an identity provider, you must add the new key to `metadata/saml20-idp-hosted.php`.
If you are changing the keys for both an service provider and identity provider at the same time, you must update both locations.
-The new certificate and key is added to the configuration with the prefix `new_`:
+The new certificate, private key and private key passphrase are added to the configuration with the prefix `new_`:
When the new key is added, SimpleSAMLphp will attempt to use both the new key and the old key for decryption of messages, but only the old key will be used for signing messages.
The metadata will be updated to list the new key for signing and encryption, and the old key will no longer listed as available for encryption.
@@ -37,8 +37,13 @@ In `config/authsources.php`:
'saml:SP',
'privatekey' => 'old.pem',
'certificate' => 'old.crt',
+ // When private key is passphrase protected.
+ 'privatekey_pass' => '<old-secret>',
+
'new_privatekey' => 'new.pem',
'new_certificate' => 'new.crt',
+ // When new private key is passphrase protected.
+ 'new_privatekey_pass' => '<new-secret>',
),
In `metadata/saml20-idp-hosted.php`:
@@ -48,8 +53,13 @@ In `metadata/saml20-idp-hosted.php`:
'auth' => 'example-userpass',
'privatekey' => 'old.pem',
'certificate' => 'old.crt',
+ // When private key is passphrase protected.
+ 'privatekey_pass' => '<old-secret>',
+
'new_privatekey' => 'new.pem',
'new_certificate' => 'new.crt',
+ // When new private key is passphrase protected.
+ 'new_privatekey_pass' => '<new-secret>',
);
@@ -69,7 +79,7 @@ Remove the old key
------------------
Once you are certain that all your peers are using the new metadata, you must remove the old key.
-Replace the existing `privatekey` and `certificate` options in your configuration with the `new_privatekey` and `new_certificate` options.
+Replace the existing `privatekey`, `privatekey_pass` and `certificate` options in your configuration with the `new_privatekey`, `new_privatekey_pass` and `new_certificate` options.
This will cause your old key to be removed from your metadata.
### Examples
@@ -78,8 +88,10 @@ In `config/authsources.php`:
'default-sp' => array(
'saml:SP',
- 'privatekey' => 'new.pem',
'certificate' => 'new.crt',
+ 'privatekey' => 'new.pem',
+ // When private key is passphrase protected.
+ 'privatekey_pass' => '<new-secret>',
),
In `metadata/saml20-idp-hosted.php`:
@@ -87,8 +99,10 @@ In `metadata/saml20-idp-hosted.php`:
$metadata['__DYNAMIC:1__'] = array(
'host' => '__DEFAULT__',
'auth' => 'example-userpass',
- 'privatekey' => 'new.pem',
'certificate' => 'new.crt',
+ 'privatekey' => 'new.pem',
+ // When private key is passphrase protected.
+ 'privatekey_pass' => '<new-secret>',
);
--
GitLab