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.

(cherry picked from commit c747b17d)

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` and/or `metadata/shib13-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>',
     );