Confusing documentation with regards to encryption/signing certificates.

[dino8890]

The documentation states that there are 2 ways to specify certificate and key for encryption and signing, however it is not clear what are the differences between them and which setting is preferred.

To quote the latest docs:

key_file
key_file is the name of a PEM formatted file that contains the private key of the service. This is currently used both to encrypt/sign assertions and as the client key in an HTTPS session.
cert_file
This is the public part of the service private/public key pair. cert_file must be a PEM formatted file with a single certificate.

    'sp': {
          'key_file': BASE_DIR + '/certificates/private.key',
          'cert_file': BASE_DIR + '/certificates/public.cert',
    }

However, there is also encryption_keypairs config:

encryption_keypairs
Indicates which certificates will be used for encryption capabilities:

# Encryption
'encryption_keypairs': [
    {
        'key_file': BASE_DIR + '/certificates/private.key',
        'cert_file': BASE_DIR + '/certificates/public.cert',
    },
],

As you can see, there is seemingly no difference, but the fact that the former is a little more detailed (IMO), it makes it seem like that's the preferred option.

Interestingly, djangosaml package states this in their docs:

The key_file and cert_file options reference the two parts of a standard x509 certificate. You need it to sign your metadata. For assertion encryption/decryption support please configure another set of key_file and cert_file, but as inner attributes of encryption_keypairs option.

If this is true, then this is a pretty important omission from pysaml2 docs as these configurations do different things. I'd be happy to submit a PR, but I need someone more familiar with the project to confirm this is the case.

[dino8890]

Based on the generated metadata, it seems encryption_keypairs is used for encryption only, and the former key_file and cert_file is used for signing. This invalidates the statement in the documentation:

This is currently used both to encrypt/sign assertions and as the client key in an HTTPS session.

(emphasis mine)

I'll dig into the source code to confirm this is actually the case.