== [[/|Shibboleth]] / IdP Key Roll Over ==

This page documents the process of rolling over the IdP's keys. This includes the process of generating a new certificate for the IdP. The certificate and key are only used for signing the assertions and securing the attribute query back channel that is not user facing.

The process from the 10k foot level is to add a second key and cert to the IdP and its metadata for distribution ahead of the actual roll over. Once all of the SPs have the new metadata then the IdP can be rolled over to using the new key and cert and the SPs will transparently follow since they have both the new cert and old cert in metadata.

**Note**: All operations in this procedure occur under the tomcat user.

1. Generate a new key/certificate:
{{{
-bash-3.2$ openssl req -x509 -newkey rsa:2048 -nodes -days 1095 -keyout idp.new.key -out idp.new.crt
Generating a 2048 bit RSA private key
...........................................+++
............................................................+++
writing new private key to 'idp.new.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:US
State or Province Name (full name) [Berkshire]:Alaska
Locality Name (eg, city) [Newbury]:Fairbanks
Organization Name (eg, company) [My Company Ltd]:University of Alaska
Organizational Unit Name (eg, section) []:Office of Information Technology
Common Name (eg, your name or your server's hostname) []:idp.alaska.edu
Email Address []:iam@alaska.edu
}}}

2. Copy the key/certificate into the credentials directory of the IdP installation. You will need to do this on all Shibboleth servers as the credential directory is not managed in subversion. See [ [#IamProjectHosts IAM Project Hosts] ].
{{{
-bash-3.2$ cp idp.new.crt /opt/shibboleth-idp/credentials/
-bash-3.2$ cp idp.new.key /opt/shibboleth-idp/credentials/
}}}

3. Add the new key/certificate to the relying party configuration. After this step there should be two "security:Credential" stanzas. One with the "IdPCredential" id and one with the "IdPCredentialNew" id.
{{{
-bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/conf
-bash-3.2$ vi conf/relying-party.xml
...
    <security:Credential id="IdPCredentialNew" xsi:type="security:X509Filesystem">
        <security:PrivateKey>/opt/shibboleth-idp/credentials/idp.new.key</security:PrivateKey>
        <security:Certificate>/opt/shibboleth-idp/credentials/idp.new.crt</security:Certificate>
    </security:Credential>
...
:wq!
-bash-3.2$ svn ci conf/relying-party.xml -m "Added new IdP key/cert."
}}}

4. Add the new certificate to the IdP metadata. There should be two "<!KeyDescriptor>" stanzas after this step in the metadata for the "<IDPSSODescriptor>" stanza and the "<!AttributeAuthorityDescriptor>" stanza.
{{{
-bash-3.2$ cat idp.new.crt 
-----BEGIN CERTIFICATE-----
MIIFDDCCA/SgAwIBAgIJAN58IPd0DVLpMA0GCSqGSIb3DQEBBQUAMIG0MQswCQYD
VQQGEwJVUzEPMA0GA1UECBMGQWxhc2thMRIwEAYDVQQHEwlGYWlyYmFua3MxHTAb
BgNVBAoTFFVuaXZlcnNpdHkgb2YgQWxhc2thMSkwJwYDVQQLEyBPZmZpY2Ugb2Yg
SW5mb3JtYXRpb24gVGVjaG5vbG9neTEXMBUGA1UEAxMOaWRwLmFsYXNrYS5lZHUx
HTAbBgkqhkiG9w0BCQEWDmlhbUBhbGFza2EuZWR1MB4XDTExMDcwNzIzMDc1NFoX
DTE0MDcwNjIzMDc1NFowgbQxCzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2Ex
EjAQBgNVBAcTCUZhaXJiYW5rczEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFz
a2ExKTAnBgNVBAsTIE9mZmljZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcw
FQYDVQQDEw5pZHAuYWxhc2thLmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNr
YS5lZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqzXokjJWPQdz8
cHsoSiNADLwYX89wxjTe5Xp47iqSWlx3eaxQlOOSY9OJ59dE4+tN8ACqiWJp0iga
/GpyEH93jLoZBToTGMImto0SgC1I2eTk+htpJ6wn7Mu8fKpBhZ74OYiXf6NHoMCJ
w4exXAv+inZcbcIrLnfUKPQxbRhoKvJO/DQHvMl7KNtN+H0rjFNu0ASTdQ96hffi
SQpolP9kb1cnGH1xGmAcm+4O3LG+3//qNk22R0JpP+UAu3ZVITMXzbhOzyZ26RQK
DA16v2kDzJEONJJM9/rk/YlG35cLea72NjTs4IPoyJLSk6ZaFZV4z4wsC5ChGoKB
4r3hCOqRAgMBAAGjggEdMIIBGTAdBgNVHQ4EFgQU2V5wFIfP1b31LPo89aUrJX2i
MZkwgekGA1UdIwSB4TCB3oAU2V5wFIfP1b31LPo89aUrJX2iMZmhgbqkgbcwgbQx
CzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2ExEjAQBgNVBAcTCUZhaXJiYW5r
czEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFza2ExKTAnBgNVBAsTIE9mZmlj
ZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcwFQYDVQQDEw5pZHAuYWxhc2th
LmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNrYS5lZHWCCQDefCD3dA1S6TAM
BgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBiXjlb84MPNRuPISvPa/hG
qbZWDAYRvH3b+/3JxGeDtkcBYkmk8/HZZKRxxbdm9OBSYmkdhY/NqA+LVd08nP6T
rpWM1sYIGfXo3OoyQOgDiwB1RnJwTRsHX+qUkKZWeUF5TzW7dhNtW5Efv7kMMU+X
dBy3y0HhLJKUnUEgRD6c21bAaRow1uowhNZMZ9Pl+TbJyiOZdWPPUFSXDk/VarwI
DOq2Qf8ih5EnbMLVtIDRlAUkfoskx69nWiwt4pmw5BjwnthYdNCfmZLoEJbpWCh8
8QBWVqNSK1+XRDa6lm1v3UkNMBR3+TZG3MAVcYrwHDnUTayxGZ6psy2yY+ET0mwH
-----END CERTIFICATE-----
-bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/metadata
-bash-3.2$ vi metadata/idp-metadata.xml
...
    <IDPSSODescriptor protocolSupportEnumeration="urn:mace:shibboleth:1.0 urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol">
...
        <KeyDescriptor use="signing">
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
MIIFDDCCA/SgAwIBAgIJAN58IPd0DVLpMA0GCSqGSIb3DQEBBQUAMIG0MQswCQYD
VQQGEwJVUzEPMA0GA1UECBMGQWxhc2thMRIwEAYDVQQHEwlGYWlyYmFua3MxHTAb
BgNVBAoTFFVuaXZlcnNpdHkgb2YgQWxhc2thMSkwJwYDVQQLEyBPZmZpY2Ugb2Yg
SW5mb3JtYXRpb24gVGVjaG5vbG9neTEXMBUGA1UEAxMOaWRwLmFsYXNrYS5lZHUx
HTAbBgkqhkiG9w0BCQEWDmlhbUBhbGFza2EuZWR1MB4XDTExMDcwNzIzMDc1NFoX
DTE0MDcwNjIzMDc1NFowgbQxCzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2Ex
EjAQBgNVBAcTCUZhaXJiYW5rczEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFz
a2ExKTAnBgNVBAsTIE9mZmljZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcw
FQYDVQQDEw5pZHAuYWxhc2thLmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNr
YS5lZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqzXokjJWPQdz8
cHsoSiNADLwYX89wxjTe5Xp47iqSWlx3eaxQlOOSY9OJ59dE4+tN8ACqiWJp0iga
/GpyEH93jLoZBToTGMImto0SgC1I2eTk+htpJ6wn7Mu8fKpBhZ74OYiXf6NHoMCJ
w4exXAv+inZcbcIrLnfUKPQxbRhoKvJO/DQHvMl7KNtN+H0rjFNu0ASTdQ96hffi
SQpolP9kb1cnGH1xGmAcm+4O3LG+3//qNk22R0JpP+UAu3ZVITMXzbhOzyZ26RQK
DA16v2kDzJEONJJM9/rk/YlG35cLea72NjTs4IPoyJLSk6ZaFZV4z4wsC5ChGoKB
4r3hCOqRAgMBAAGjggEdMIIBGTAdBgNVHQ4EFgQU2V5wFIfP1b31LPo89aUrJX2i
MZkwgekGA1UdIwSB4TCB3oAU2V5wFIfP1b31LPo89aUrJX2iMZmhgbqkgbcwgbQx
CzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2ExEjAQBgNVBAcTCUZhaXJiYW5r
czEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFza2ExKTAnBgNVBAsTIE9mZmlj
ZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcwFQYDVQQDEw5pZHAuYWxhc2th
LmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNrYS5lZHWCCQDefCD3dA1S6TAM
BgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBiXjlb84MPNRuPISvPa/hG
qbZWDAYRvH3b+/3JxGeDtkcBYkmk8/HZZKRxxbdm9OBSYmkdhY/NqA+LVd08nP6T
rpWM1sYIGfXo3OoyQOgDiwB1RnJwTRsHX+qUkKZWeUF5TzW7dhNtW5Efv7kMMU+X
dBy3y0HhLJKUnUEgRD6c21bAaRow1uowhNZMZ9Pl+TbJyiOZdWPPUFSXDk/VarwI
DOq2Qf8ih5EnbMLVtIDRlAUkfoskx69nWiwt4pmw5BjwnthYdNCfmZLoEJbpWCh8
8QBWVqNSK1+XRDa6lm1v3UkNMBR3+TZG3MAVcYrwHDnUTayxGZ6psy2yY+ET0mwH
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
...
    </IDPSSODescriptor>

    <AttributeAuthorityDescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol">
...
        <KeyDescriptor use="signing">
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
MIIFDDCCA/SgAwIBAgIJAN58IPd0DVLpMA0GCSqGSIb3DQEBBQUAMIG0MQswCQYD
VQQGEwJVUzEPMA0GA1UECBMGQWxhc2thMRIwEAYDVQQHEwlGYWlyYmFua3MxHTAb
BgNVBAoTFFVuaXZlcnNpdHkgb2YgQWxhc2thMSkwJwYDVQQLEyBPZmZpY2Ugb2Yg
SW5mb3JtYXRpb24gVGVjaG5vbG9neTEXMBUGA1UEAxMOaWRwLmFsYXNrYS5lZHUx
HTAbBgkqhkiG9w0BCQEWDmlhbUBhbGFza2EuZWR1MB4XDTExMDcwNzIzMDc1NFoX
DTE0MDcwNjIzMDc1NFowgbQxCzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2Ex
EjAQBgNVBAcTCUZhaXJiYW5rczEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFz
a2ExKTAnBgNVBAsTIE9mZmljZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcw
FQYDVQQDEw5pZHAuYWxhc2thLmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNr
YS5lZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqzXokjJWPQdz8
cHsoSiNADLwYX89wxjTe5Xp47iqSWlx3eaxQlOOSY9OJ59dE4+tN8ACqiWJp0iga
/GpyEH93jLoZBToTGMImto0SgC1I2eTk+htpJ6wn7Mu8fKpBhZ74OYiXf6NHoMCJ
w4exXAv+inZcbcIrLnfUKPQxbRhoKvJO/DQHvMl7KNtN+H0rjFNu0ASTdQ96hffi
SQpolP9kb1cnGH1xGmAcm+4O3LG+3//qNk22R0JpP+UAu3ZVITMXzbhOzyZ26RQK
DA16v2kDzJEONJJM9/rk/YlG35cLea72NjTs4IPoyJLSk6ZaFZV4z4wsC5ChGoKB
4r3hCOqRAgMBAAGjggEdMIIBGTAdBgNVHQ4EFgQU2V5wFIfP1b31LPo89aUrJX2i
MZkwgekGA1UdIwSB4TCB3oAU2V5wFIfP1b31LPo89aUrJX2iMZmhgbqkgbcwgbQx
CzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2ExEjAQBgNVBAcTCUZhaXJiYW5r
czEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFza2ExKTAnBgNVBAsTIE9mZmlj
ZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcwFQYDVQQDEw5pZHAuYWxhc2th
LmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNrYS5lZHWCCQDefCD3dA1S6TAM
BgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBiXjlb84MPNRuPISvPa/hG
qbZWDAYRvH3b+/3JxGeDtkcBYkmk8/HZZKRxxbdm9OBSYmkdhY/NqA+LVd08nP6T
rpWM1sYIGfXo3OoyQOgDiwB1RnJwTRsHX+qUkKZWeUF5TzW7dhNtW5Efv7kMMU+X
dBy3y0HhLJKUnUEgRD6c21bAaRow1uowhNZMZ9Pl+TbJyiOZdWPPUFSXDk/VarwI
DOq2Qf8ih5EnbMLVtIDRlAUkfoskx69nWiwt4pmw5BjwnthYdNCfmZLoEJbpWCh8
8QBWVqNSK1+XRDa6lm1v3UkNMBR3+TZG3MAVcYrwHDnUTayxGZ6psy2yY+ET0mwH
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
...
:wq!
-bash-3.2$ svn ci metadata/idp-metadata.xml -m "Added new IdP cert."
}}}

5. Submit the new certificate to !InCommon for inclusion in the next federation metadata publication. This occurs daily and is done from an administrative web interface. See David Bantz for more details as he currently is the only individual with access to this.

6. Test config changes according to procedure. See [ [#TestIdPConfig Test IdP Config Change] ].

7. Notify non-federation SPs of metadata change and instruct them to update. SPs in the !InCommon federation should be polling the !InCommon metadata distribution point daily. Wait for SPs to get metadata. See [ [#InCommonMetadata InCommon Metadata] ].

8. Move to the new key/certificate and delete the old key/certificate "security:Credential" stanza in the relying party configuration. After this step there should be //only// one "security:Credential" stanza that points to the key/cert. **Note**: The id //must// be "IdPCredential". 
{{{
-bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/conf
-bash-3.2$ vi conf/relying-party.xml
...
    <security:Credential id="IdPCredential" xsi:type="security:X509Filesystem">
        <security:PrivateKey>/opt/shibboleth-idp/credentials/idp.new.key</security:PrivateKey>
        <security:Certificate>/opt/shibboleth-idp/credentials/idp.new.crt</security:Certificate>
    </security:Credential>
...
:wq!
-bash-3.2$ svn ci conf/relying-party.xml -m "Moved to new IdP key/cert and deleted old IdP key/cert."
}}}

9. Move to the new key/certificate in the IdP metadata. There should be one "<!KeyDescriptor>" stanza after this step in the metadata for the new cert in the "<IDPSSODescriptor>" stanza and the "<!AttributeAuthorityDescriptor>" stanza.
{{{
-bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/metadata
-bash-3.2$ vi metadata/idp-metadata.xml
...
:wq!
-bash-3.2$ svn ci metadata/idp-metadata.xml -m "Moved to new IdP cert and deleted old cert."
}}}

10. Create a new Java Key Store for Tomcat containing the new key/cert for securing the back channel. You will need the !ImportKey Java utility for importing a pre-existing cert/key into a Java Key Store. You will also need the !InCommon intermediary cert, and the !AddTrust Root CA cert for this process. See [ [#ImportKeyUtil Import Key Util] ], [ [#InCommonCert InCommon Cert] ], and [ [#AddTrustCert AddTrust Cert] ].
{{{
-bash-3.2$ openssl pkcs8 -topk8 -nocrypt -in idp.new.key -out idp.new.key.der -outform der
-bash-3.2$ openssl x509 -in idp.new.crt -out idp.new.crt.der -outform der
-bash-3.2$ openssl x509 -in incommon.crt -out incommon.crt.der -outform der
-bash-3.2$ openssl x509 -in addtrust.crt -out addtrust.crt.der -outform der
-bash-3.2$ cat incommon.crt.der addtrust.crt.der >> idp.new.crt.der
-bash-3.2$ java ImportKey idp.new.key.der idp.new.crt.der 
Using keystore-file : /opt/tomcat/temp/keystore.ImportKey
One certificate, no chain.
Key and certificate stored.
Alias:importkey  Password:importkey
-bash-3.2$ keytool -storepasswd -new changeit -keystore keystore.ImportKey -storepass importkey
-bash-3.2$ keytool -keypasswd -alias importkey -new changeit -keystore keystore.ImportKey -keypass importkey -storepass changeit
-bash-3.2$ keytool -changealias -alias importkey -destalias tomcat -storepass changeit -keystore keystore.ImportKey
-bash-3.2$ mv keystore.ImportKey idp.new.jks
-bash-3.2$ cp idp.new.jks /opt/shibboleth-idp/credentials/
}}}

11. Edit the tomcat server.xml config file to change to the new Java Key Store for the back channel query.
{{{
-bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/tomcat/trunk/conf
-bash-3.2$ vi conf/server.xml
...
	    <!-- added per shibb installation -->
	    <Connector port="8443"
	           protocol="org.apache.coyote.http11.Http11Protocol"
	           SSLImplementation="edu.internet2.middleware.security.tomcat6.DelegateToApplicationJSSEImplementation"
	           scheme="https"
	           SSLEnabled="true"
	           clientAuth="true"
	           keystoreFile="/opt/shibboleth-idp/credentials/idp.new.jks"
	           keystorePass="changeit" />
...
:wq!
-bash-3.2$ svn ci conf/server.xml -m "Changed back channel query to use new key/cert."
}}}

12. Test config changes according to procedure. See [ [#TestIdPConfig Test IdP Config Change] ]

References:[[br]]
[=#ImportKeyUtil][ [[ImportKeyUtil|Import Key Utility]] ][[br]]
[=#InCommonCert][ [[https://www.incommon.org/cert/repository/AddTrustExternalCARoot.txt|AddTrust External CA Root]] ][[br]]
[=#AddTrustCert][ [[https://www.incommon.org/cert/repository/InCommonServerCA.txt|InCommon Server CA]] ][[br]]
[=#IamProjectHosts][ [[https://iam.alaska.edu/projects/wiki/IamProjectHosts|IAM Project Hosts]] ][[br]]
[=#TestIdPConfig][ [[https://iam.alaska.edu/shib/wiki/TestIdPConfig|Test IdP Config Change]] ][[br]]
[=#InCommonMetadata][ [[http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml|InCommon Metadata Distribution Point]] ][[br]]