Skip to content

Latest commit

 

History

History
437 lines (307 loc) · 21.7 KB

13 - Signature Activation Protocol.md

File metadata and controls

437 lines (307 loc) · 21.7 KB
Raw

Signature Activation Protocol for Federated Signing

Version 1.2 - 2024-12-04

Registration number: 2019-317

Copyright © The Swedish Agency for Digital Government (Digg), 2015-2024. All Rights Reserved.

Table of Contents

  1. Introduction

    1.1. Requirement keywords

    1.2. XML namespace references

    1.3. Structure

  2. Signature Activation Protocol

    2.1. Scope

    2.2. Data Exchange

  3. Data elements

    3.1. SADRequest

    3.1.1. Syntax

    3.1.2. Example

    3.2. Signature Activation Data

    3.2.1. SAD JSON Web Token

    3.2.1.1. Registered JWT Claims

    3.2.1.2. SAD Extension Claim

    3.2.2. Example

    3.2.3 Verification of a SAD

  4. Schemas

  5. Normative References

  6. Changes between versions

1. Introduction

This document specifies a Signature Activation Protocol (SAP) and its data elements for implementation of Sole Control Assurance Level 2 (SCAL2) according the European standards prEN 419241 - Trustworthy Systems Supporting Server Signing - Part 1 and 2 (prEN 419 241-1 [RSIG-PP-1] and prEN 419 241-2 [RSIG-PP-2]).

The Signature Activation Protocol (SAP) defined in this document is used to exchange data between a signature service and a delegated authenticating authority such as a SAML Identity Provider. The function of the SAP is to authenticate the intent of a signer to sign a particular document, or collection of documents, through exchange of the following data elements.

  • Signature Activation Data (SAD) - Signed data, asserting the signer's agreement to sign specific data.
  • SADRequest - Request for a SAD.

The SAP specified in this document is specifically designed to be used with a signing service operating in accordance with the federated signing specification [DSS-Ext].

1.1. Requirement keywords

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in [RFC2119].

These keywords are capitalized when used to unambiguously specify requirements over protocol features and behavior that affect the interoperability and security of implementations. When these words are not capitalized, they are meant in their natural-language sense.

1.2. XML namespace references

The prefix sap: stands for the Signature Activation Protocol XML Schema namespace http://id.elegnamnden.se/csig/1.1/sap/ns (https://docs.swedenconnect.se/schemas/csig/1.1/EidCsigSAP-1.1.xsd).

The prefix saml2: stands for the OASIS SAML 2 Assertion Schema namespace urn:oasis:names:tc:SAML:2.0:assertion.

The prefix saml2p: stands for the OASIS SAML 2 Protocol Schema namespace urn:oasis:names:tc:SAML:2.0:protocol.

1.3. Structure

This specification uses the following typographical conventions in text: <Eid2Element>, <ns:ForeignElement>, Attribute, Datatype, OtherCode.

2. Signature Activation Protocol

2.1. Scope

The scope of the Signature Activation Protocol (SAP) is to support request for and delivery of the Signature Activation Data (SAD) to the Signature Activation Module (SAM). The SAM is a tamper resistant module inside the Remote Signing Service which validates the SAD in order to ensure that:

  • the signer is properly authenticated,
  • the signer agrees to sign the data to be signed, and,
  • the correct signing key for this signer and this instance of signing is properly identified.

The federated signing model does not use pre-assigned signing keys. Instead, a new signing key is generated for each sign request and then permanently deleted. This particular use-case is recognised by prEN 419 241-1 [RSIG-PP-1] and prEN 419 241-2 [RSIG-PP-2], which under these conditions allows the signature key reference to be implicit and derived from the signer's identity. For the present implementation of the SAP the following data is included in the SAD:

  • the signer's identity,
  • information about how the signer was authenticated and by whom, and,
  • reference to the signature request, binding this instance of authentication to the specific instance of signing, the data being signed and the agreement to sign.

This implements the scenario where the Identity Provider is the sole entity which can verify the signer's private credentials via the SIC (Signer’s Interaction Component). This instance of authentication is used by the Identity Provider to generate the SAD in accordance with section 5.10 of [RSIG-PP-1].

2.2. Data exchange

This document specifies exchange of two data elements:

  • SADRequest
  • SAD

The SADRequest SHALL have the format defined in section 3.1. When a Remote Signing Service request a SAD from the Identity Provider, it MUST include the SADRequest element as a request extension by including it as a child element to a <saml2p:Extensions> element in the <saml2p:AuthnRequest>.

When an Identity Provider returns a SAD, as defined in section 3.2, in a SAML Assertion, it MUST be included as a single string value of a sad attribute identified by the attribute name urn:oid:1.2.752.201.3.12 as defined in the attribute specification [EidAttributes].

3. Data elements

The SAD requested in the SAP binds the documents to be signed to the intent by the signer to sign. This is accomplished by the interaction of a number of independent information attributes and elements as follows:

  • Sign request ID. Identifies the sign request for signing specific documents. This sign request is sent to the signing service from the service provider requesting the signature. The sign request bound by this identifier contains all detailed data about what is being signed.
  • LoA. The level of assurance declaration asserting the level of security used to authenticate the user.
  • Number of documents to sign. Ensures that the user is aware whether more than one document is being signed. This allows adaptations of the signing UI displayed by the Identity Provider.
  • Identity of the signer. Allows verification that the signature is bound to the appropriate signer.
  • SAD Request ID. Unique identifier for the SADRequest element. This identifier is later included in the SAD in order to accomplish a binding between the request and the issued SAD.

The SAD request and the SAD specified in this section specifies the data that needs to be exchanged in addition to other protocol elements specified by SAML as well as the federated signing specification [DSS-Ext].

3.1. SADRequest

3.1.1. Syntax

The SAD Request is provided in a <sap:SADRequest> element. The element has the following elements and attributes:

<RequesterID> [Required]

Specifies the SAML entityID of the requesting entity. The value for this element should be the same identifier as given in the <saml2:Issuer> element of the <saml2p:AuthnRequest> that encapsulates the <sap:SADRequest> extension.

<SignRequestID> [Required]

Specifies the value of the RequestID attribute of the associated SignRequest.

<DocCount> [Required]

The number of requested signatures in the associated sign request.

<RequestedVersion> [Optional Default="1.0"]

The requested version of the SAD.

<RequestParams> [Optional]

Optional parameters provided as name-value pairs. This specification does not define any parameters. The use of parameters may be defined in profiles of this specification or may be negotiated by other means between a remote signing service and an Identity Provider.

ID [Required]

Attribute holding a unique identifier for the SADRequest.

The following schema fragment defines the <sap:SADRequest> element:

<xs:element name="SADRequest" type="sap:SADRequestType" />

<xs:complexType name="SADRequestType">
  <xs:sequence>
    <xs:element name="RequesterID" type="xs:string" />
    <xs:element name="SignRequestID" type="xs:string" />
    <xs:element name="DocCount" type="xs:int" />
    <xs:element name="RequestedVersion" type="xs:string" minOccurs="0" default="1.0" />
    <xs:element name="RequestParams" minOccurs="0">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="Parameter" type="sap:ParameterType" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
      </xs:complexType>
    </xs:element>
  </xs:sequence>
  <xs:attribute name="ID" type="xs:ID" use="required" />
</xs:complexType>

<xs:complexType name="ParameterType">
  <xs:simpleContent>
    <xs:extension base="xs:string">
      <xs:attribute name="name" type="xs:string" use="required" />
    </xs:extension>
  </xs:simpleContent>
</xs:complexType>

3.1.2. Example

<sap:SADRequest ID="_a74a068d0548a919e503e5f9ef901851" xmlns:sap="http://id.elegnamnden.se/csig/1.1/sap/ns">
  <sap:RequesterID>http://www.example.com/sigservice</sap:RequesterID>
  <sap:SignRequestID>f6e7d061a23293b0053dc7b038a04dad</sap:SignRequestID>
  <sap:DocCount>1</sap:DocCount>
  <sap:RequestedVersion>1.0</sap:RequestedVersion>
  <sap:RequestParams>
    <sap:Parameter name="ParamName">paramValue</sap:Parameter>
  </sap:RequestParams>
</sap:SADRequest>

Example of a SADRequest.

3.2. Signature Activation Data

3.2.1. SAD JSON Web Token

This section specifies a JSON Web Token (JWT) in accordance with [RFC7519] as the SAD container, binding the data as defined in section 2.1.

The SAD JWT MUST have the form of a signed JWS (JSON Web Signature).

3.2.1.1. Registered JWT Claims

The data signed by the SAD JWT is carried in the JWS payload in the form of JWT claims using registered claim names (as specified in [RFC7519]) in addition to one private claim name (seElnSadext) specified in section 3.2.1.2. The following table defines the use of registered claims.

name Content
sub Subject - holds the attribute value of the signer's unique identifier.
aud Audience - holds the entityID of the Signature Service which is the legitimate recipient of this SAD. This value corresponds to the <sap:RequesterID> element of the SAD request.
iss Issuer - holds the entityID of the IdP that generated this SAD.
exp Expiry - specifies the time when this SAD is no longer valid (epoch time/seconds since 1970-01-01).
iat Issued At - specifies the time when this SAD was issued (epoch time/seconds since 1970-01-01).
jti  Unique identifier of this SAD.

3.2.1.2. SAD Extension Claim

A private claim name is defined in this specification which extends the registered claims with additional SAD data:

seElnSadext

The claim identified by this name has the value of a JSON object holding name-value pairs in accordance with the following table:

Name Type Content
ver String The version of this claim, default 1.0 (Optional).
irt String In Response To - holds the identifier of the SAD request (ID attribute) that was used to request this SAD.
attr String Attribute - holds the URI identifier of the attribute specifying the users unique identifier value.
loa String LevelOfAssurance - holds the URI identifier of the level of assurance (LoA) used to authenticate the signer.
reqid String RequestID - holds the ID of the sign request associated with this SAD. Inclusion of this ID assert that the authenticated subject agrees to sign the docuements identified by this sign reqeust.
docs Integer Specifies the number of documents to be signed in the associated sign request.

3.2.2. Example

The following example illustrates a claim binding the following claim values:

Registered Claims

Name Value
sub 197802031877
aud https://sandbox.swedenconnect.se/eid2cssp
iss http://dev.test.swedenconnect.se/idp
exp 1666128029 (Oct 18, 2022, 23:20:29 CET)
iat 1666127729 (Oct 18, 2022, 23:15:29 CET)
jti  NbnmpGA1gwtL3AgtKPfe77Ia

seElnSadext Claim

Name Value
ver 1.0
irt 752c30b3-30c1-49f0-ab04-a28909dc3b67
attr urn:oid:1.2.752.29.4.13
loa http://id.elegnamnden.se/loa/1.0/loa3
reqid 70fabf30-d474-4d21-8463-2c6811005ce0
docs 4

JWS Header

The Header of the JWS specifies that it is a JWT by the "typ" parameter and the signature algoritm through the "alg" parameter. In this example the header is {"typ":"JWT","alg":"RS256"}. The Base64 URL-encoded header is:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9

JWS Payload

The JWS payload holding the JWT claims is represented by the following JSON object:

{
    "sub": "197802031877",
    "aud": "https://sandbox.swedenconnect.se/eid2cssp",
    "iss": "http://dev.test.swedenconnect.se/idp",
    "exp": 1666128029,
    "iat": 1666127729,
    "jti": "NbnmpGA1gwtL3AgtKPfe77Ia",
    "seElnSadext": {
        "ver": "1.0",
        "irt": "752c30b3-30c1-49f0-ab04-a28909dc3b67",
        "attr": "urn:oid:1.2.752.29.4.13",
        "loa": "http://id.elegnamnden.se/loa/1.0/loa3",
        "reqid": "70fabf30-d474-4d21-8463-2c6811005ce0",
        "docs": 4
    }
}

This payload is represented by the following Base64 URL-encoded string:

eyJzdWIiOiIxOTc4MDIwMzE4NzciLCJhdWQiOiJodHRwczovL3NhbmRib3guc3dlZGVuY29ubmVjdC5zZS9laWQyY3NzcCIsImlzcyI6Imh0dHA6Ly9kZXYudGVzdC5zd2VkZW5jb25uZWN0LnNlL2lkcCIsImV4cCI6MTY2NjEyODAyOSwiaWF0IjoxNjY2MTI3NzI5LCJqdGkiOiJOYm5tcEdBMWd3dEwzQWd0S1BmZTc3SWEiLCJzZUVsblNhZGV4dCI6eyJ2ZXIiOiIxLjAiLCJpcnQiOiI3NTJjMzBiMy0zMGMxLTQ5ZjAtYWIwNC1hMjg5MDlkYzNiNjciLCJhdHRyIjoidXJuOm9pZDoxLjIuNzUyLjI5LjQuMTMiLCJsb2EiOiJodHRwOi8vaWQuZWxlZ25hbW5kZW4uc2UvbG9hLzEuMC9sb2EzIiwicmVxaWQiOiI3MGZhYmYzMC1kNDc0LTRkMjEtODQ2My0yYzY4MTEwMDVjZTAiLCJkb2NzIjo0fX0

JWT

The complete SAD JWT including signature:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxOTc4MDIwMzE4NzciLCJhdWQiOiJodHRwczovL3NhbmRib3guc3dlZGVuY29ubmVjdC5zZS9laWQyY3NzcCIsImlzcyI6Imh0dHA6Ly9kZXYudGVzdC5zd2VkZW5jb25uZWN0LnNlL2lkcCIsImV4cCI6MTY2NjEyODAyOSwiaWF0IjoxNjY2MTI3NzI5LCJqdGkiOiJOYm5tcEdBMWd3dEwzQWd0S1BmZTc3SWEiLCJzZUVsblNhZGV4dCI6eyJ2ZXIiOiIxLjAiLCJpcnQiOiI3NTJjMzBiMy0zMGMxLTQ5ZjAtYWIwNC1hMjg5MDlkYzNiNjciLCJhdHRyIjoidXJuOm9pZDoxLjIuNzUyLjI5LjQuMTMiLCJsb2EiOiJodHRwOi8vaWQuZWxlZ25hbW5kZW4uc2UvbG9hLzEuMC9sb2EzIiwicmVxaWQiOiI3MGZhYmYzMC1kNDc0LTRkMjEtODQ2My0yYzY4MTEwMDVjZTAiLCJkb2NzIjo0fX0.Qn-K-5V5-979GMITVSXgqWOrSVQfYFUMLv0P8PLUMSZzF6s6Zk05SOztH3XGN-4AjmjQeBHcqylpzoqG26eIXW7kuJZB9zodhAyTcvOogQj62XUFsoun5wfWpou8v8-Cpw1G4cwFZdMKt-oRbN43ViZ8u7EIZHBjzYMxfJNgMv2YGmzMQDPQLmtIW-f_O0nE_NPcFsaweYGJXcEWxi7fE3wzNnOR2rPBgQ3L0oehF2mP9dhenlptKrugH6Ru6eLZH66yFaAtR5RRA2m1wh2fXnwXJWO0-8jrvIZiZ9GLDt9W0r1Hs5Le--KPeuPcStli0nIi5YVLoAiGUaHc-Eb_DILwdqYpHS6mxJL3lb8j8u5JsIdEj9FEpqD8MlCbVM4HaWDL_wIiU16QVUOrxPUjoo3wyxLYhW6x3WnQ2an8fhIgahck7m9gS6_rVHKG1OAL_jn4h5jZzP-gX9yZeNcfTmhSiEdwrObydZ4dKx7JGEbmKn4EK1-8Pc65SOj9Zg5jTsRsl6uo9dMoJ-35Tb-x5IKsGs9Y1_94NCuqJH_a7HgC8nORfHBDOTPjzG008FLEFHSRmql6hYSYEd9F3kvR5816KixZpLT_BEED1m4RNdufa8nYEgEroi6X_AvmjpZKiwXCgnJyW6_80IIV89EMViiQ-BjTSSt8AK5KxxpTLkA

3.2.3. Verification of a SAD

The recipient of a requested SAD MUST verify it as part of the SAML response processing by asserting the following:

  • That the signature of the SAD JWT verifies correctly using the signature certificate of the issuing Identity Provider (found in the Identity Provider metadata).
  • That the version of the SAD (seElnSadext.ver) matches the <sap:RequestedVersion> element of the <sap:SADRequest>.
  • That the audience (aud) matches the entityID of the recipient, i.e., matches the <sap:RequesterID> element from the <sap:SADRequest>.
  • That the issuer (iss) value matches the issuer entityID of the assertion containing the SAD (*).
  • That the SAD is valid by checking the expiry (exp) and issued-at (iat) values (allowing for a reasonable clock skew).
  • That the in-response-to (seElnSadExt.irt) value matches that ID of the corresponding <sap:SADRequest>.
  • That the subject (sub) value is also represented in the SAML assertion as an attribute having the name given by the seElnSadExt.attr field.
  • That the level of assurance (seElnSadEx.loa) value matches the value given in the <saml2:AuthnContextClassRef> element of the assertion.
  • That the request ID (seElnSadEx.reqid) value matches the ID for the sign request (which is passed in the <sap:SignRequestID> element of the <sap:SADRequest>).
  • That the number of documents specified in the SAD (seElnSadEx.docs) matches the <sap:DocCount> element of the <sap:SADRequest>.

If any of the above verification steps fail, the Signature Service MUST reject the assertion.

[*]: In the case where a Signature Service communicates with a Proxy Identity Provider that forwards requests to an authenticating Identity Provider that issues a SAD, the iss-value of the SAD will differ from the issuer of the assertion that is received by the Signature Service. In these cases the Signature Service should compare the iss-value with the value found in the <saml2:AuthenticatingAuthority> element of the assertion, or with relevant local policy and out-of-band configuration data.

4. Schemas

The following XML schema defines the http://id.elegnamnden.se/csig/1.1/sap/ns name space:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
    targetNamespace="http://id.elegnamnden.se/csig/1.1/sap/ns"
    xmlns:sap="http://id.elegnamnden.se/csig/1.1/sap/ns">

  <xs:annotation>
    <xs:documentation>
      Schema location URL: https://docs.swedenconnect.se/schemas/csig/1.1/EidCsigSAP-1.1.xsd
    </xs:documentation>
  </xs:annotation>

  <xs:element name="SADRequest" type="sap:SADRequestType" />

  <xs:complexType name="SADRequestType">
    <xs:sequence>
      <xs:element name="RequesterID" type="xs:string" />
      <xs:element name="SignRequestID" type="xs:string" />
      <xs:element name="DocCount" type="xs:int" />
      <xs:element name="RequestedVersion" type="xs:string" minOccurs="0" default="1.0" />
      <xs:element minOccurs="0" name="RequestParams">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Parameter" type="sap:ParameterType" minOccurs="0" maxOccurs="unbounded" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="ID" type="xs:ID" use="required" />
  </xs:complexType>

  <xs:complexType name="ParameterType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute name="name" type="xs:string" use="required" />
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>

5. Normative References

[RFC2119]

Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, March 1997.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015.

[EidAttributes]

Attribute Specification for the Swedish eID Framework.

[DSS-Ext]

DSS Extension for Federated Central Signing Services.

[RSIG-PP-1]

European Standard prEN 419241-1 - Trustworthy Systems Supporting Server Signing - Part 1: General System Security Requirements

[RSIG-PP-2]

European Standard prEN 419241-2 - Trustworthy Systems Supporting Server Signing - Part 2: Protection profile for QSCD for Server Signing

6. Changes between versions

Changes between version 1.1 and 1.2:

  • The protocol logic was clarified by removing references to sign message (which was never present in the actual protocol) and replacing this with a clarification of the semantics of including the Sign Request ID in SAD to assert the acceptance to sign the documents referenced in that Sign Request.

  • Updated examples where the use of "signmessage" LoA URI:s was removed.

  • Updated broken links.

Changes between version 1.0 and 1.1:

  • The RequestedVersion element of the SADRequestType is now marked as optional in the schema definition.