4 XML cryptographic libraries

The SSL package provides several libraries dealing with cryptographic operations of XML documents. These libraries depend on the sgml package. These libraries are part of this package because the sgml package has no external dependencies and will thus be available in any SWI-Prolog installation while configuring and building this ssl package is much more involved.

4.1 library(saml): SAML Authentication

See also

https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf

There are four primary integration points for applications to use this code: 1) You must declare at least one service provider (SP) 2) You must declare at least one identity provider (IdP) per SP 3) Finally, you can call saml_authenticate(+SP, +IdP, +Callback, +Request) to obtain assertions The asynchronous nature of the SAML process means that a callback must be used. Assuming that the IdP was able to provide at least some valid assertions about the user, after calling Callback with 2 extra arguments (a list of the assertion terms and the URL being request by the user), the user will be redirected back to their original URL. It is therefore up to the callback to ensure that this does not simply trigger another round of SAML negotiations - for example, by throwing http_reply(forbidden(RequestURL)) if the assertions are not strong enough 4) Finally, your SP metadata will be available from the web server directly. This is required to configure the IdP. This will be available at './metadata.xml', relative to the LocationSpec provided when the SP was declared.

Configuring an SP: To declare an SP, use the declaration :-saml_sp(+ServiceProvider: atom, +LocationSpec: term, +PrivateKeySpec: term, +Password: atom +CertificateSpec: term, +Options: list).

The ServiceProvider is the identifier of your service. Ideally, this should be a fully-qualified URI The LocationSpec is a location that the HTTP dispatch layer will understand for example '.' or root('saml'). The Private KeySpec is a 'file specifier' that resolves to a private key (see below for specifiers) The Password is a password used for reading the private key. If the key is not encrypted, any atom can be supplied as it will be ignored The CertificateSpec is a file specifier that resolves to a certificate holding the public key corresponding to PrivateKeySPec There are currently no implemented options (the list is ignored).

Configuring an IdP: To declare an IdP, use the declaration :-saml_idp(+ServiceProvider: atom, +MetadataSpec: term). ServiceProvider is the identifier used when declaring your SP. You do not need to declare them in a particular order, but both must be present in the system before running saml_authenticate/4. MetadataSpec is a file specifier that resolves to the metadata for the IdP. Most IdPs will be able to provide this on request

File Specifiers: The following specifiers are supported for locating files:

• file(Filename): The local file Filename
• resource(Resource): The prolog resource Resource. See resource/3
• url(URL): The file identified by the HTTP (or HTTPS if you have the HTTPS plugin loaded) URL

This library uses SAML to exchange messages with an Identity Provider to establish assertions about the current user's session. It operates only as the service end, not the identity provider end.

4.2 library(xmlenc): XML encryption library

See also

- https://www.w3.org/TR/xmlenc-core1/
- https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language

This library is a partial implementation of the XML encryption standard. It implements the decryption part, which is needed by SAML clients.

[det]decrypt_xml(+DOMIn, -DOMOut, :KeyCallback, +Options)

KeyCallback

may be called as follows: call(KeyCallback, name, KeyName, Key) call(KeyCallback, public_key, public_key(RSA), Key) call(KeyCallback, certificate, Certificate, Key)

[det]load_certificate_from_base64_string(+String, -Certificate)

Loads a certificate from a string, adding newlines and header where appropriate so that OpenSSL 1.0.1+ will be able to parse it

4.3 library(xmldsig): XML Digital signature

See also

- http://www.di-mgt.com.au/xmldsig.html
- https://www.bmt-online.org/geekisms/RSA_verify
- http://stackoverflow.com/questions/5576777/whats-the-difference-between-nid-sha-and-nid-sha1-in-openssl

This library deals with XMLDSIG, RSA signed XML documents.

[det]xmld_signed_DOM(+DOM, -SignedDOM, +Options)

Translate an XML DOM structure in a signed version. Options:

key_file(+File)

File holding the private key needed to sign

key_password(+Password)

String holding the password to op the private key.

The SignedDOM must be emitted using xml_write/3 or xml_write_canonical/3. If xml_write/3 is used, the option layout(false) is needed to avoid changing the layout of the SignedInfo element and the signed DOM, which will cause the signature to be invalid.

[det]xmld_verify_signature(+DOM, +SignatureDOM, -Certificate, +Options)

Confirm that an ds:Signature element contains a valid signature. Certificate is bound to the certificate that appears in the element if the signature is valid. It is up to the caller to determine if the certificate is trusted or not.

Note: The DOM and SignatureDOM must have been obtained using the load_structure/3 option keep_prefix(true) otherwise it is impossible to generate an identical document for checking the signature. See also xml_write_canonical/3.