Finnish Trust Network

Full Message-Level Encryption for FTN

5447 views May 9, 2019 November 7, 2019 7

The Finnish Trust Network (FTN) requires Full Message-Level Encryption (MLE) as well as Transport-Level Encryption (TLS). The two main sections of this document detail the steps required to set up MLE for OpenID Connect (OIDC) and SAML2 respectively.

OIDC

Prerequisites

We need you to provide an encryption key, so that we can encrypt our responses with this key. This key needs to be in a specific format:

  1. Generate a JWK RSA pair (2048 or 4096-bit). It is important that you create a JWK and not a PEM, CER, CRT, etc.
  2. Send the public part to Signicat. The public part can be sent through email as it does not contain sensitive information.

Please note, when we store your key in our system a new Key ID (“kid”) will be generated. We will provide you with this new Key ID. You have to use this Key ID, as we do not have the ability to change the Key ID in our keystore.

Implementation

You should send your requests as a normal OIDC request (see exception below). The difference between a normal OIDC flow and MLE flow are:

  1. The ID token and the response from user info is a nested JWT which is encrypted and signed.
    1. Decrypt it with your private key from the RSA pair given to Signicat.
    2. Deserialize the resulting signed JWT and verify the signature.
  2. The ID token must, as always, be verified according OIDC specifications.

Note that <ENV> equals preprod.signicat.com for pre-production and your Signicat subdomain for production.

A functional example implementation of full message-level encryption for FTN can be found at https://github.com/signicat/OIDC-MLE/tree/master/py-ftn-example.

Encrypting Authorization Requests

The instructions from Traficom specify “all personal data shall be encrypted and signed at the message level”. Normally the authorization request itself contains no personal data, and as such it does not need to be encrypted. However there does exist certain unlikely edge-case scenarios where you might include personal data in the authorization request.

PS: FTN does not support “prefilling” of national identity numbers, so this should not be a valid use-case. 

If your implementation requires it, here is our guide to implementing encrypted authorization requests:

Begin crafting the OIDC Authorization Request. The parameters are standard OIDC parameters. Examples of Authorization Request encryption in a number of common languages can be found at https://github.com/signicat/OIDC-MLE/tree/master/authorize-encrypt-examples. The requirements are as follows:

  • The HTTP request can be made using either GET or POST.
  • The payload must be a Request Object (per OIDC Core specifications, section 6.1). An example for a typical payload Request Object looks as follows:
    {
        "login_hint": ["subject-210281-9988"],
        "ui_locales": "en",
        "scope": "openid profile signicat.national_id",
        "acr_values": "urn:signicat:oidc:method:ftn-nordea-auth",
        "response_type": "code",
        "redirect_uri": "https://labs.signicat.com/redirect",
        "state": "state123",
        "client_id": "CLIENTID",
    }
    Value Type Required
    login_hint List of Strings No
    ui_locales String No
    scope String Yes
    acr_values String Yes
    response_type String Yes
    redirect_uri String Yes
    state String Yes
    client_id String Yes
  • The request must be an encrypted JWT, which contains the aforementioned Request Object (as specified at https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests).
  • The JWE token must be encrypted with the public key ("use":"enc") available at https://<ENV>.signicat.com/oidc/jwks.json.
  • The protected header for the JWE token must contain the following claims:
    • "enc"="A256CBC-HS512"
    • "typ"="JWE"
    • "kid" and "alg" (the values for “kid” and “alg” are specified at https://<ENV>.signicat.com/oidc/jwks.json).

SAML2

If you are using SAML2 for your integration, follow the instructions in the sections below.

Prerequisites

  • Your SAML 2.0 Service Provider (SP) software must support encrypted assertions (see supported algorithms below). Support for encrypted assertions in SP software is normally enabled by configuring an encryption key and a certificate, but the process can vary depending on the software you are using.
  • You must have an encryption certificate. It must be an X.509 certificate with a key length of at least 2048 bits (RSA). Note that the encryption certificate is just a means of transporting a public key, it does not need to be issued by a publicly trusted CA and can even be self-signed. It is your responsibility as a service provider to handle the private key of your certificate in a secure, compliant manner.
  • Your metadata must contain your encryption certificate (see metadata section below).

Encryption algorithms

By default, Signicat supports the following algorithms related to SAML2 assertion encryption in FTN.

Encrypted data algorithms:

  • http://www.w3.org/2009/xmlenc11#aes128-gcm
  • http://www.w3.org/2009/xmlenc11#aes192-gcm
  • http://www.w3.org/2009/xmlenc11#aes256-gcm

EncryptedKey algorithms:

  • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

If you can’t use any of these algorithms, contact us and we will help you find an alternative.

Metadata

As stated in the prerequisites, the SP metadata must contain an encryption certificate.

The encryption certificate must either be in a KeyDescriptor element without a “use” attribute,

<KeyDescriptor>
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
            <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
    </ds:KeyInfo>
</KeyDescriptor>

or in a KeyDescriptor element with a “use” attribute specifying that it is for encryption.

<KeyDescriptor use="encryption">
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
            <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
    </ds:KeyInfo>
</KeyDescriptor>

Implementation

1. Test encryption in preproduction

  1. Send the following information to Signicat:
    • Updated SP metadata (in XML format) for preproduction. The metadata can be linked to one of your existing EntityIDs or a new one.
    • The desired encryption algorithms.
  2. Signicat will enable assertion encryption for your entity.
  3. Test encrypted assertions in your preproduction environment.

2. Roll out to production

  1. Once you have tested encrypted assertions in preproduction, notify Signicat that you are ready to roll out to production. When you send this notification, include the updated SP metadata (in XML format) for production. The metadata can be linked to one of your existing EntityIDs or a new one.
  2. Signicat will enable assertion encryption in production.

Was this helpful?