Skip to content

Commit 3bf14df

Browse files
committed
Improve the documentation regarding verifications
Closes #275
1 parent 3e22f74 commit 3bf14df

2 files changed

Lines changed: 20 additions & 8 deletions

File tree

‎docs/usage/examples.rst‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -198,23 +198,28 @@ contains the following:
198198
</XRDS>
199199
200200
The structure of the file should be fairly self-evident. Only links with @rel="urn:oasis:names:tc:SAML:2.0:metadata"
201-
will be parsed. If a KeyInfo with a X509Certificate element (usual base64-encoded certificate format) then this
202-
certificate is used to validate the signature on the downloaded SAML metadata. Note that while 'load' supports validation
203-
based on certificate fingerprint the XRD format does not and you will have to include Base64-encoded certificates if
204-
you want validation to work.
201+
will be parsed. The X509Certificate elements (base64-encoded certificates) in a link's KeyInfo are the trusted signers
202+
of the metadata it points to: the downloaded metadata is only loaded if it is signed by one of them, so during a key
203+
rollover a link can list both the old and the new certificate. The certificate is used as such, not via its
204+
fingerprint, so this also works for metadata whose signature does not carry the signing certificate, as is common for
205+
MDQ responses.
206+
207+
.. warning::
208+
209+
A link without a certificate is loaded **without** signature verification.
205210

206211
Example 4 - Sign using a PKCS#11 module
207212
---------------------------------------
208213

209-
Fetch SWAMID metadata (and validate the signature using a certificate matching the given SHA256 fingerprint), select
214+
Fetch SWAMID metadata (and validate the signature using the SWAMID signing certificate in swamid-2.0.crt), select
210215
the Identity Providers, tidy it up a bit and sign with the key with the label 'signer' in the PKCS#11 module
211216
/usr/lib/libsofthsm.so. If a certificate is found in the same PKCS#11 object, that certificate is included in
212217
the Signature object.
213218

214219
.. code-block:: yaml
215220
216221
- load:
217-
- http://mds.swamid.se/md/swamid-2.0.xml A6:78:5A:37:C9:C9:0C:25:AD:5F:1F:69:22:EF:76:7B:C9:78:67:67:3A:AF:4F:8B:EA:A1:A7:6D:A3:A8:E5:85
222+
- http://mds.swamid.se/md/swamid-2.0.xml verify swamid-2.0.crt
218223
- select: "!//md:EntityDescriptor[md:IDPSSODescriptor]"
219224
- xslt:
220225
stylesheet: tidy.xsl

‎src/pyff/builtins.py‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -694,11 +694,18 @@ def load(req: Plumbing.Request, *opts):
694694
- ``as``: name the resource, e.g. to refer to it in later pipeline steps.
695695
- ``verify``: check the XML signature of the resource, using either a PEM certificate file or a SHA-1
696696
fingerprint of the signing certificate. With a fingerprint, the certificate embedded in the signature is
697-
used and the fingerprint pins it. ``verify`` may be repeated to support key rollovers; a signature by any
698-
one of the given certificates (or fingerprints) is accepted. Certificates and fingerprints cannot be mixed.
697+
used and the fingerprint pins it, so a document whose signature carries no certificate - common for MDQ
698+
responses - can only be verified with the certificate file. Other fingerprints, eg SHA-256, are not
699+
supported. ``verify`` may be repeated to support key rollovers; a signature by any one of the given
700+
certificates (or fingerprints) is accepted. Certificates and fingerprints cannot be mixed.
699701
- ``via``: name of a ``when`` clause in the same pipeline that is applied to the loaded metadata, for
700702
example to remove entities with ``fork merge remove``.
701703
- ``cleanup``: name of a ``when`` clause used to pre-process the parsed metadata before it is validated.
704+
705+
A resource may also be an XRD or eIDAS MDSL file listing metadata URLs. Each listed URL is loaded and verified
706+
with the certificates given for it in the file, as if with ``verify``; any one of them is accepted, so a key
707+
rollover can list both. An XRD link without a certificate is loaded unverified; an MDSL entry without one is
708+
skipped.
702709
"""
703710
_opts = dict(list(zip(opts[::2], opts[1::2])))
704711
_opts.setdefault('timeout', 120)

0 commit comments

Comments
 (0)