Step 2 - Configuring SAM Profile

To make it easier for business applications to request management of users, keys and devices along with signing operations, the ADSS SAM Service uses SAM Profiles. A SAM profile defines the format and characteristics of the keys (e.g. which public key algorithm and key length to be used) and define characteristics of user devices (e.g. which public key algorithm and key length to be used, device has bio-metric support) that will be used when this profile is referenced in a user keys generation, device registration and signing request from a client application.

To create or edit a SAM Profile click on SAM Profiles and the following screen is shown:

A new profile can be created by clicking the '+' button. An existing profile can be edited by clicking the Edit button. If you want to create a new profile by copying large part of an existing profile then click Make a Copy. The following screen is shown:

After performing the required configurations, click on the Next arrow (>), it will display the following screen:

The configuration items are as follows:

Items

Description

Status

A SAM profile may be marked Active or Inactive.

Note: An inactive profile will not be used to process requests generated by client application.

Profile ID

A mandatory field which provides a system-defined unique identifier for this profile.

Profile Name

A mandatory unique name defined by the ADSS Server Administrator for easier recognition of the profile within the ADSS Unity Console.

Profile Description

This can be used to describe the profile in more detail (e.g. in which circumstances will this SAM profile be used). This is for information purposes only.

User Signature Key Pair Settings

This section defines the configurations that control User key pair generation and signature generation mechanism.

Crypto Profile

Select whether to generate and store the user key/certificate within the ADSS Server database (software mode), Azure Key Vault or to store the key/certificate on a hardware security module (HSM) pre-configured within ADSS Server Key Manager.

When a configured hardware crypto profile is Not Available in the ADSS Server Key Manager (i.e. record is shown with orange highlighting) then the relevant crypto profile will not be available here for configurations.

Key Algorithm

Defines the key algorithm to be used for generating User Key Pairs. These algorithms are supported:

RSA
ECDSA
Dilithium

Note:

The default value is RSA
The keys generated using PQC algorithm, i.e. Dilithium, are created solely through software and not via HSMs.
The Dilithium algorithm will be only be used for document signing purposes.
The below mentioned signature types are supported for Dilithium:

PKCS1
CMS
CAdES Baseline (Only if CA key is RSA/EC)
CAdES Extended (Only if CA key is RSA/EC)

Currently the PQC algorithm (Dilithium) is only for proof of concept (POC).

Curve Type

Select the Curve Type that should be applied while generating User Key Pairs. ADSS Server supports the following curve types:

NIST P
SEC2 K
Brainpool R
Brainpool T

Note:

The Curve Type drop-down will be available only when ECDSA algorithm is selected in key algorithm field.
Utimaco CryptoServer CP5 HSM does not support SEC2 K curve type.

Key Length

Defines the key length to be used for generating User Key Pairs. These key lengths are supported:

RSA keys are: 2048, 3072, 4096 and 8192
ECDSA keys in terms of their respective curve types are:

For NIST P: 224, 256, 384 and 521
For SEC2 K: 256
For Brainpool R & Brainpool T: 224, 256, 320, 384 and 512

Note: The default value is 2048 for RSA and 256 for ECDSA.

In case where SAD_FORMAT is set to JSON in Global Settings > Advance Settings, the Key Length must be greater than 256 when ECDSA is selected as the Key Algorithm.

Security Level

The Security Level drop-down will be available when either Dilithium is selected in the 'Algorithm' field. This drop-down allows the user to choose the security level for the selected key algorithm. The security levels for Dilithium is defined below:

Dilithium: 2,3 and 5.

KAK Algorithm

Defines the key algorithm to be used for generating User Key Authorisation Key (KAK). If user keys are being generated in a Utimaco CryptoServer CP5 HSM then a KAK is required to authorise/activate the user key inside the HSM. The KAK itself is generated in a software crypto source. The KAK is not required if user keys are being generated in a Software crypto source or any other HSM.

Note: Only RSA algorithm is supported for KAK.

KAK Length

Defines the key length to be used for generating User Key Authorisation Key (KAK). These key lengths (bits) are supported:

2048
3072
4096
8192

Note: The default value is 2048.

Padding Scheme

Defines which signature padding scheme to be used for generating user's signature.

These padding schemes are supported:

PKCS1 (PKCS#1 v1.5)
PSS (PKCS#1 v2.1)

Note: The default value is PKCS1.

Compute hash at signing time

Enable this option if the Business Application is sending the data for signing instead of a hash. In this case, SAM Service will compute the hash using the algorithm selected in Hash Algorithm drop-down.

Keep this option unchecked if Business Application is sending the hash instead of data. In this case, SAM Service does not need to compute any hash.

Note: Keep the following points under consideration while operating with this checkbox:

By default, input data is not hashed and this option is unchecked.
The user can enable or disable this checkbox while using the PSS padding scheme.

Hashing Algorithm

Sets the hash algorithm to use if the input data is to be hashed. These algorithms are supported:

SHA224
SHA256
SHA384
SHA512
SHA3-224
SHA3-256
SHA3-384
SHA3-512

Note:

The default value is SHA256.
All crypto profiles are supported in case of SHA3 except nCipher nShield CC.

Enable bulk signing

If selected then bulk signing is allowed. The input data may contain one or more hash values up to the limit specified below.

Note: The default is not to allow bulk signing. Set value 0 for unlimited.

Number of hashes allowed to sign

Define the maximum number of hash values allowed in a single input data message. This option is only available if bulk signing is enabled.

Note: The default value is 0 and this allows an unlimited number of hash values.

Require user authorisation for every transaction

If this radio button is enabled, the user will have to provide authorisation for each signing request on Go>Sign mobile app or using any other mechanisms according to the SCAL e.g. PIN/OTP etc.

Normally, this option should be selected to produce digital signatures.

Note: By default, SAM Service requires authorisation on every transaction and this radio is not displayed. But, if eSeals will also be enabled in license then this option is displayed on the screen along with the option mentioned below. This allows the user to select whether he/she configuring profile for signatures or seals.

Require user authorisation only once until SAD expiry time

If this radio button is enabled, the user will have to provide authorisation only once.

This option should be selected to produce electronic seals where user will provide authorisation for a large number of signatures once and the resulting SAD could be used for sub-sequent requests. These requests can be sent in batches and user will not be asked to provide authorisation while processing these batches. The process will continue until the signatures count or SAD expiry reaches. After that, the user will have to provide authorisation again to sign further requests.

Note: This feature is license controlled and it won't be available to the user if eSeals would not be enabled in the license.

Remove key from HSM after signing

If this checkbox is enabled, the signing key will be deleted from the HSM after each eSeal signing operation. Once the key is removed, the respective key handles of the eSeal signing key are also deleted from the cache.

The below points must be kept in mind while operating with this checkbox:

The checkbox will be unchecked by default.
The checkbox will only be available if the user has enabled the 'Require user authorisation only once until SAD expiry time' radio button.
In the case of non-CC HSMs, static or dynamic KEK are stored in the cache, and HSMs are also removed.
Since the eSeals signing key and its respective handles will be deleted from the HSM, and imported back into the HSM whenever the next signing request is received, it will have an impact on the performance.

SAD Expiry

It defines the time period after which the SAD will be expired automatically. If SAD Expiry is not provided here, then, the system will use the SAD expiry provided in the SAM_REQUEST_EXPIRY_PERIOD property in Global Settings > Advance Settings. The user can define the SAD expiry according to the selected unit form the drop-down, or, by defining a customized date of expiry using the Custom Date option. See the image below:

Clicking on the calendar icon displays the following sceen:

From the above calendar, the user can select the required date and time of SAD expiry.

Note: Keep the following points under consideration:

It is an optional field
The maximum value that can be entered other then the custom date depends on the UNIT selected from the drop-down i.e. Seconds, Minutes, Hours, Days, Months and Years.
The maximum value of the date should be less than 31-12-9999. For example, If the Year is selected as a Unit from the drop-down, the maximum value that can be added in SAD Expiry field is calculated as:
Number of your current year - 9999
e.g. 2024 -9999 = 7975
Hence considering the above example, the maximum value that can be entered has to be between 1 - 7975.
The values of other UNITs will be calculated accordingly.

Authorisation Request Expiry

It defines the time period after which the authorization request received either by the Go-Sign mobile application or by an external IDP will expire automatically. If Authorisation Request Expiry is not provided here, then, the system will use the Authorisation Request Expiry provided in the SAM_REQUEST_EXPIRY_PERIOD property in Global Settings > Advance Settings.

Note: Keep the following points under consideration:

It is an optional field
The maximum value that can be entered other then the custom date depends on the UNIT selected from the drop-down i.e. Seconds, Minutes, Hours, Days, Months and Years.
The maximum value of the date should be less than 31-12-9999. For example, If the Year is selected as a Unit from the drop-down, the maximum value that can be added in SAD Expiry field is calculated as:
Number of your current year - 9999
e.g. 2024 -9999 = 7975
Hence considering the above example, the maximum value that can be entered has to be between 1 - 7975.
The values of other UNITs will be calculated accordingly.

Sole Control Assurance Level

It is drop-down field that allows to select the required SCAL (Sole Control Assurance Level) from SCAL1 and SCAL2.

Hash Algorithm for SAD

Sets the hash algorithm for SAD from drop-down. These algorithms are supported:

SHA224
SHA256
SHA384
SHA512

In case where SAD_FORMAT is set to JSON in Global Settings > Advance Settings, keep the following points under consideration:

The Hash Algorithm for SAD, and, the Key Length in User Authorisation Key Pair Settings must be same, in case where ECDSA is configured as Key Algorithm.
The Hash Algorithm for SAD must be greater than or equal to SHA256.

User Authorisation Key Pair Settings

This section defines the configurations that control authorisation key pair generation and authorisation mechanism.

Key Algorithm

Defines the key algorithm to be used for generating authorisation Key Pairs. These algorithms are supported:

RSA
ECDSA
Dilithium

Note:

The keys generated using PQC algorithm, i.e. Dilithium, are created solely through software and not via HSMs.
The Dilithium algorithm will be only be used for document signing purposes.
The below mentioned signature types are supported for Dilithium:

PKCS1
CMS
CAdES Baseline (Only if CA key is RSA/EC)
CAdES Extended (Only if CA key is RSA/EC)

The default value is ECDSA.
The Go>Sign Mobile Application will generate ECDSA key pairs using NIST-P curve type.

Currently the PQC algorithm (Dilithium) is only for proof of concept (POC).

Key Length

Defines the key length to be used for generating authorisation Key Pairs. These key lengths are supported:

2048, 3072, 4096 and 8192 bit keys are supported for RSA
224, 256, 384 and 521 bit keys are supported for ECDSA

Note: The default value is 2048 for RSA and 256 for ECDSA.

Hashing Algorithm

Defines the hash algorithm to be used for signing the Authorisation Request Message on the User Device. These algorithms are supported:

SHA224
SHA256
SHA384
SHA512
SHA3-224
SHA3-256
SHA3-384
SHA3-512

The default value is SHA256.

Since iOS does not support SHA3 hashing algorithm, hence, ADSS SAM device settings will not be having SHA3 options.

Clock Tolerance on Certificate Validity

ADSS SAM Service uses mobile device certificate in order to verify the signature created on SAD (Signature Activation Data). The mobile device certificate has a defined validity period as well, hence if the clock of the system that issued the certificate is not synchronized with the clock of ADSS SAM Service then there is a possibility of an error. In order to tackle this issue, we can configure Clock Tolerance where the user can set a value for certificate validity period that will be used by ADSS SAM Service while validating the mobile device certificate.

Note: It is an OPTIONAL field. Default value of the field can be set empty. If the value is set empty or set to '0', the system will use the current date/time of ADSS SAM Service.

Maximum devices allowed to a user

This field allows the user to set a limit on the number of mobile devices allowed to a user. The user will not be able to register more devices than this limit.

Note: The default value of this field is '0' that represents unlimited but actually its a large number 2147283647 i.e. the maximum number of devices that can be allowed to a user.

Device must have biometric recognition capability

Sets the requirement that the user must use biometric authentication on their Mobile Device to sign an Authorisation Request Message.

Device must have secure element

Sets the requirement that the user must have a Secure Element/Enclave on their User Device which will be used to generate authorisation keypair and for signing an Authorisation Request Messages.

If user has enabled the checkbox Delegated user authentication via external IdP under User Signature Key Pair Settings, then following screen will be shown:

The configuration items for Delegated user authentication via external IdP checkbox are as follows:

Items	Description
Delegated user authentication via external IdP	If this checkbox is enabled, the clients will be allowed to delegate user authentication to an external IdP during SAD generation. The business application will get the user authenticated by an IdP and add the assertion received from IdP to SAD (Signature Activation Data). The assertion will be verified by ADSS SAM Service during signing operation.
IdP Certificate	By using this field, an IdP Certificate can be uploaded from the file system that can verify the assertion signature created by IdP.
Clock Tolerance	ADSS SAM Service verifies the validity of assertion added to SAD. If the clock timings of external IdP and SAM Service are not synchronized, then an error can be returned. To tackle this issue, the user can enter the clock tolerance (in seconds) that will be used by ADSS SAM Service while validating the assertion. Note: This is an optional field. Default value of the field is '0' (means no clock tolerance required).
Assertion Type	This drop-down allows the user to select the required assertion type of the external IdP from list of supported assertion types (SAML, JWT etc) in ADSS Server. If IdP is SAML based, the SAML should be selected. and if the IdP is OpenID Connect based then JWT should be selected from the Assertion Type drop-down.
UserID from subject	If enabled, the user identifier will be picked from the Subject element for both SAML and JWT assertion.
Identify UserID from Attribute	If this radio button is enabled, the user identifier will be picked from the Attribute statement for both SAML and JWT assertion.
Attribute Name	This field will be available if Identify UserID from Attribute radio button is enabled. It allows the user to set the attribute name to identify the user from assertion.

The table of SAM profiles can be sorted in either Ascending or Descending order by selecting a table column from the drop down list. The list can be sorted by SAM Profile ID, SAM Profile Name, Created At time or Status.

Click on the Advanced Search button on SAM Profiles main page will display following screen:

This helps to locate a particular SAM profile the ADSS SAM Service may have configured. The SAM signing profile can be searched based on Status, SAM Profile ID, SAM Profile Name, Key Algorithm, Key Length, Security Level and Crypto Profile. The Security Level field will only be available if Dilithium is selected in the Algorithm field.

If "_" character is used in the search then it will act as wildcard.

The Duplicate profile will be created without the Name and Description of the selected Profile. The Unique ID generates automatically or the next available ID will be assigned to the Profile.