Skip to content

Commit ab93bae

Browse files
umuserumuser
authored
Update javadocs and changelong (#143)
* SLIB-120 - update javadocs on exceptions * SLIB-120 - update javadocs for REST-layer classes * SLIB-120 - update javadocs for common interactions * SLIB-120 - update javadocs for utils * SLIB-120 - update javadocs; fix constants access level for CertificateParser * SLIB-120 - update changelog for v3.1 release * SLIB-120 - fix typos; improve javadoc descriptions * SLIB-120 - improve documentation about setting up SmartIDClient with SSL certificates. * SLIB-120 - add task todos
1 parent dae3845 commit ab93bae

90 files changed

Lines changed: 1966 additions & 421 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 95 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,129 @@
11
# Changelog
2+
23
All notable changes to this project will be documented in this file.
34
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
45

5-
Changes mentioned under 3.1.x version have not been published yet. Will be released when v3.1 is stable.
6-
7-
## [3.1.17] - 2025-10-07
8-
- Updated SmartIdRestConnector to use v3.1 notification-based signature endpoint
9-
10-
## [3.1.16] - 2025-10-04
11-
- Updated SmartIdRestConnector to use v3.1 notification-based certificate choice endpoint
12-
- Added AccountUnusableException to handle ACCOUNT_UNUSABLE endResult from session status response
13-
14-
## [3.1.15] - 2025-09-17
15-
- Added CallbackUrlUtil to generate callback URL with token and provides method to validate sessionSecretDigest
16-
- Updated DeviceLinkAuthenticationResponseValidator to also validate userChallenge and userChallengeVerifier same device flows.
17-
18-
## [3.1.14] - 2025-09-17
19-
- Updated notification-based authentication session request creation to be usable with Smart-ID API v3.1
20-
- Removed verificationCodeChoice interactions and related handling
21-
- Removed AuthenticationHash.
22-
23-
## [3.1.13] - 2025-09-08
24-
- Added endpoint for creating linked signature session `POST /v3/signature/notification/linked/{document-number}`.
25-
- Added builder to create linked signature session request `LinkedSignatureSessionRequestBuilder`.
26-
27-
## [3.1.12] - 2025-09-08
28-
- Removed HashType and update SignableHash and SignableData to use HashAlgorithm
29-
30-
## [3.1.11] - 2025-08-25
31-
- Updated CertificateChoiceResponseMapper
32-
- Renamed to CertificateChoiceResponseValidator
33-
- Added CertificateValidator as dependency
34-
35-
## [3.1.10] - 2025-08-28
36-
- Updated exception message of `DocumentUnusableException`
37-
38-
## [3.1.9] - 2025-07-20
39-
- Extracted common certificate validation logic into `CertificateValidator` and will be used by `AuthenticationResponseValidator` and `SignatureResponseValidator`.
40-
41-
## [3.1.8] - 2025-07-15
42-
- Added new exception `SmartIdRequestSetupException` to handle cases when invalid values are provided for building session request objects.
43-
44-
## [3.1.7] - 2025-07-10
6+
## [3.1-?] - TBD
457

46-
- Renamed dynamic-link certificate choice to device-link certificate choice.
47-
- Updated certificate choice endpoint to use /device-link/ paths.
48-
- Added `initialCallbackUrl` field with regex validation.
49-
- Added `deviceLinkBase` to session response.
8+
### Structural changes
509

51-
## [3.1.6] - 2025-07-08
10+
- Moved Smart-ID v3 related classes from ee.sk.smartid.v3 package to root ee.sk.smartid package.
11+
- Removed all Smart-ID v2 related classes, tests, and documentation.
12+
- Updated README to reflect removal of v2-related information.
5213

53-
### Added
54-
- Session-status (signature)
55-
- `signature.value` must match `^[A-Za-z0-9+/]+={0,2}$`.
56-
- Allowed `flowType`: QR · App2App · Web2App · Notification.
57-
- Fixed `signatureAlgorithm` to `rsassa-pss`.
58-
- `signatureAlgorithmParameters`
59-
- `hashAlgorithm`: `SHA-256/384/512, SHA3-256/384/512`.
60-
- `maskGenAlgorithm.algorithm`: `id-mgf1` & its `hashAlgorithm` must equal the main hash.
61-
- `saltLength`: 32 / 48 / 64 bytes to match chosen hash.
62-
- `trailerField`: `0xbc`.
63-
64-
- Certificate
65-
- Must be a Smart-ID *signature* certificate:
66-
- `CertificatePolicies (2.5.29.32)` contain either `qualified``1.3.6.1.4.1.10015.17.2`, `0.4.0.194112.1.2`or `non-qualified``1.3.6.1.4.1.10015.17.1`, `0.4.0.2042.1.1`.
67-
- `KeyUsage (2.5.29.15)` – NonRepudiation bit set.
68-
- `QC-Statement (1.3.6.1.5.5.7.1.3)` contains `0.4.0.1862.1.6.1`.
69-
70-
## [3.1.5] - 2025-06-30
14+
### Dynamic-link auth to device-link auth changes
7115

72-
- Renamed dynamic-link signature to device-link signature.
73-
- Updated signature endpoints to use /device-link/ paths.
16+
- Renamed dynamic-link authentication to device-link authentication.
17+
- Updated authentication endpoints to use /device-link/ paths.
18+
- Replaced `randomChallenge` with `rpChallenge` (Base64, length 44–88).
7419
- Replaced signature algorithm list with fixed `rsassa-pss`.
7520
- Added required `signatureAlgorithmParameters.hashAlgorithm` field with validation.
7621
- Converted interaction list to Base64 string and ensured no duplicates.
7722
- Added `initialCallbackUrl` field with regex validation.
7823
- Added `deviceLinkBase` to session response.
24+
- Added new exception `SmartIdRequestSetupException` to handle cases when invalid values are provided for building session request objects.
25+
- Replaced old dynamic content and authCode generation logic to match Smart-ID v3.1 authCode specification.
26+
- Introduced a `DeviceLinkBuilder` to generate device links.
27+
- Validates required parameters such as `deviceLinkBase`, `version`, `deviceLinkType`, `sessionType`, `lang`, `elapsedSeconds` and `sessionToken`.
28+
- Ensures `elapsedSeconds` is only used for QR_CODE flows.
29+
- Moved `deviceLinkBase` to required input (no more default).
30+
- Handles both unprotected device-link generation and HMAC-SHA256 based authCode calculation as per specification.
31+
- New payload structure includes required and optional fields as per documentation.
32+
- `schemeName` is now configurable (default is `"smart-id"`).
33+
- Does not store `sessionSecret`, ensures it must be passed to the build method.
34+
- Removed deprecated dynamic link and QR code generation logic from old builders and helpers.
7935

80-
## [3.1.4] - 2025-07-05
81-
82-
### Changed
8336
- Updates to session status response
84-
- Updated USER_REFUSED_INTERACTION responses and updated error handling for these cases.
85-
- Added new `endResult` error responses (`PROTOCOL_FAILURE`, `EXPECTED_LINKED_SESSION`, `SERVER_ERROR`) with handling
86-
- Added new fields: `userChallenge`, `flowType`, `signatureAlgorithmParameters`
87-
- Renamed `interactionFlowUsed` to `interactionTypeUsed`.
37+
- Updated USER_REFUSED_INTERACTION responses and updated error handling for these cases.
38+
- Added new `endResult` error responses (`PROTOCOL_FAILURE`, `EXPECTED_LINKED_SESSION`, `SERVER_ERROR`) with handling
39+
- Added new fields: `userChallenge`, `flowType`, `signatureAlgorithmParameters`
40+
- Renamed `interactionFlowUsed` to `interactionTypeUsed`.
41+
- Updated exception message of `DocumentUnusableException`
42+
- Added AccountUnusableException to handle ACCOUNT_UNUSABLE endResult from session status response
8843
- Updated AuthenticationSessionRequest and related classes to records.
8944
- Refactored loading of trusted CA certificates from AuthenticationResponseValidator to their own class `DefaultTrustedCACertStore`.
90-
- Created to builder-classes for loading trusted CA certificates
91-
- `FileTrustedCACertStoreBuilder` for loading trust anchors and intermediate CA certificates from truststore
92-
- `DefaultTrustedCACertStoreBuilder` for creating DefaultTrustedCACertStore with preloaded certificates, also validates provided certificates
93-
- Refactored AuthenticationResponseMapper to be used as singleton instead of static class and added it as dependency for AuthenticationResponseValidator
94-
- Update AuthenticationResponseValidator
95-
- update signature value validation
96-
- added additional certificate validations (validate certificate chain and certificate purpose)
45+
- Created to builder-classes for loading trusted CA certificates
46+
- `FileTrustedCACertStoreBuilder` for loading trust anchors and intermediate CA certificates from truststore
47+
- `DefaultTrustedCACertStoreBuilder` for creating DefaultTrustedCACertStore with preloaded certificates, also validates provided certificates
48+
- Update AuthenticationResponseValidator to DeviceLinkAuthenticationResponseValidator
49+
- update signature value validation
50+
- added additional certificate validations (validate certificate chain and certificate purpose)
51+
- added validation for userChallenge and userChallengeVerifier in case of same device flows
52+
- added validators QualifiedAuthenticationCertificatePurposeValidator and NonQualifiedAuthenticationCertificatePurposeValidator to validate
53+
certificate purpose based on requested certificate level.
9754

98-
## [3.1.3] - 2025-06-13
55+
- Added CallbackUrlUtil to generate callback URL with token and provides method to validate sessionSecretDigest
9956

100-
### Added
57+
### Added handling for querying certificate by document number
10158

10259
- Added new endpoint: `POST /v3/signature/certificate/{document-number}`.
103-
104-
### Removed
105-
60+
- Added new builder CertificateByDocumentNumberRequestBuilder to create the request
61+
- Add new request objects CertificateByDocumentNumberRequest and response CertificateResponse
10662
- Removed notification-based certificate choice request with document number.
10763

108-
## [3.1.2] - 2025-06-05
109-
110-
### Changed
111-
112-
- Replaced old dynamic content and authCode generation logic to match Smart-ID v3.1 authCode specification.
113-
- Introduced a `DeviceLinkBuilder` to generate device-links.
114-
- Validates required parameters such as `deviceLinkBase`, `version`, `deviceLinkType`, `sessionType`, `lang`, `elapsedSeconds` and `sessionToken`.
115-
- Ensures `elapsedSeconds` is only used for QR_CODE flows.
116-
- Moved `deviceLinkBase` to required input (no more default).
117-
- Handles both unprotected device-link generation and HMAC-SHA256 based authCode calculation as per specification.
118-
- New payload structure includes required and optional fields as per documentation.
119-
- `schemeName` is now configurable (default is `"smart-id"`).
120-
- Does not store `sessionSecret`, ensures it must be passed to the build method.
121-
- Removed deprecated dynamic link and QR code generation logic from old builders and helpers.
122-
123-
## [3.1.1] - 2025-06-02
64+
### Updated dynamic-link signature to device-link signature
12465

125-
### Changed
126-
127-
- Renamed dynamic-link authentication to device-link authentication.
128-
- Updated authentication endpoints to use /device-link/ paths.
129-
- Replaced `randomChallenge` with `rpChallenge` (Base64, length 44–88).
66+
- Renamed dynamic-link signature to device-link signature.
67+
- Updated signature endpoints to use /device-link/ paths.
13068
- Replaced signature algorithm list with fixed `rsassa-pss`.
13169
- Added required `signatureAlgorithmParameters.hashAlgorithm` field with validation.
13270
- Converted interaction list to Base64 string and ensured no duplicates.
13371
- Added `initialCallbackUrl` field with regex validation.
13472
- Added `deviceLinkBase` to session response.
73+
- Removed HashType and update SignableHash and SignableData to use HashAlgorithm
74+
- Update signature session-status validations
75+
- Signature
76+
- `signature.value` must match `^[A-Za-z0-9+/]+={0,2}$`.
77+
- Allowed `flowType`: QR · App2App · Web2App · Notification.
78+
- Fixed `signatureAlgorithm` to `rsassa-pss`.
79+
- `signatureAlgorithmParameters`
80+
- `hashAlgorithm`: `SHA-256/384/512, SHA3-256/384/512`.
81+
- `maskGenAlgorithm.algorithm`: `id-mgf1` & its `hashAlgorithm` must equal the main hash.
82+
- `saltLength`: 32 / 48 / 64 bytes to match chosen hash algorithm octet length.
83+
- `trailerField`: `0xbc`.
84+
85+
- Certificate
86+
- Must be a Smart-ID *signature* certificate:
87+
- `CertificatePolicies (2.5.29.32)` contain either `qualified``1.3.6.1.4.1.10015.17.2`, `0.4.0.194112.1.2`or
88+
`non-qualified``1.3.6.1.4.1.10015.17.1`, `0.4.0.2042.1.1`.
89+
- `KeyUsage (2.5.29.15)` – NonRepudiation bit set.
90+
- `QC-Statement (1.3.6.1.5.5.7.1.3)` contains `0.4.0.1862.1.6.1`.
91+
92+
- Extracted common certificate validation logic into `CertificateValidator` and will be used by `AuthenticationResponseValidator` and
93+
`SignatureResponseValidator`.
94+
95+
## Update dynamic-link certificate choice to device-link certificate choice
13596

136-
## [3.1] - 2025-05-20
97+
- Renamed dynamic-link certificate choice to device-link certificate choice.
98+
- Updated certificate choice endpoint to use /device-link/ paths.
99+
- Added `initialCallbackUrl` field with regex validation.
100+
- Added `deviceLinkBase` to session response.
101+
- Updated CertificateChoiceResponseMapper
102+
- Renamed to CertificateChoiceResponseValidator
103+
- Added CertificateValidator as dependency
137104

138-
### Changed
139-
- Moved Smart-ID v3 related classes from ee.sk.smartid.v3 package to root ee.sk.smartid package.
140-
- Removed all Smart-ID v2 related classes, tests, and documentation.
141-
- Updated README to reflect removal of v2-related information.
105+
## Added linked signature session support
106+
107+
- Added endpoint for creating linked signature session `POST /v3/signature/notification/linked/{document-number}`.
108+
- Added builder to create linked signature session request `LinkedSignatureSessionRequestBuilder`.
109+
- Added request LinkedSignatureSessionRequest and LinkedSignatureSessionResponse.
110+
111+
### Updated notification-based authentication to work with Smart-ID API v3.1
112+
113+
- Updated notification-based authentication session request creation to be usable with Smart-ID API v3.1
114+
- Removed verificationCodeChoice interactions and related handling
115+
- Removed AuthenticationHash.
116+
- Added NotificationAuthenticationResponseValidator
117+
118+
### Updated notification-based certificate choice to work with Smart-ID API v3.1
119+
120+
- Updated SmartIdRestConnector to use v3.1 notification-based certificate choice endpoint
121+
- Added NotificationCertificateChoiceSessionRequest
122+
123+
### Updated notification-based signature to work with Smart-ID API v3.1
124+
125+
- Updated SmartIdRestConnector to use v3.1 notification-based signature endpoint
126+
- Added NotificationSignatureSessionRequest
142127

143128
## [3.0] - 2023-10-14
144129

‎README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,18 +148,46 @@ logging.level.ee.sk.smartid.rest.LoggingFilter: trace
148148
[Configure to use with Smart-ID Demo environment](https://sk-eid.github.io/smart-id-documentation/environments.html#_demo)
149149
NB! Smart-ID Basic level accounts (certificate level ADVANCED) are not supported for DEMO
150150

151+
### Setting up SSL connection to Smart-ID API
152+
153+
Live SSL certificates of Smart-ID service provider (SK) can be found here: https://sk-eid.github.io/smart-id-documentation/https_pinning.html#_rp_api_smart_id_com_certificates
154+
Demo SSL certificates can be found here: https://sk-eid.github.io/smart-id-documentation/https_pinning.html#_sid_demo_sk_ee_certificates
155+
156+
Recommended way is to use truststore and provide it to the client.
157+
151158
```java
159+
// Read truststore containing Smart-ID service provider (SK) SSL certificates
152160
InputStream is = SmartIdClient.class.getResourceAsStream("demo_server_trusted_ssl_certs.jks");
153161
KeyStore trustStore = KeyStore.getInstance("JKS");
154162
trustStore.load(is, "changeit".toCharArray());
155163

164+
// Initialize SmartIdClient and set connection parameters.
156165
var smartIdClient = new SmartIdClient();
166+
// set relying party details
157167
client.setRelyingPartyUUID("00000000-0000-4000-8000-000000000000");
158168
client.setRelyingPartyName("DEMO");
169+
// set Smart-ID API host URL
159170
client.setHostUrl("https://sid.demo.sk.ee/smart-id-rp/v3/");
171+
// set the trust store containing SK SSL certificates
160172
client.setTrustStore(trustStore);
161173
```
162174

175+
### Provide SSL certificates to the client
176+
177+
Also it is possible to add trusted certificates one by one.
178+
179+
```java
180+
// Initialize SmartIdClient and set connection parameters.
181+
var smartIdClient = new SmartIdClient();
182+
// set relying party details
183+
client.setRelyingPartyUUID("00000000-0000-4000-8000-000000000000");
184+
client.setRelyingPartyName("DEMO");
185+
// set Smart-ID API host URL
186+
client.setHostUrl("https://sid.demo.sk.ee/smart-id-rp/v3/");
187+
// add trusted SSL certificates
188+
client.setTrustedCertificates("-----BEGIN CERTIFICATE-----\nMIIFIjCCBAqgAwIBAgIQBH3ZvDVJl5qtCPwQJSruuj...");
189+
```
190+
163191
## Device-link flows
164192

165193
Device-link flows are more secure way to make sure user that started the authentication or signing is in control of the device or in the proximity of the device.

‎src/main/java/ee/sk/smartid/AuthenticationCertificateLevel.java‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* #%L
55
* Smart ID sample Java client
66
* %%
7-
* Copyright (C) 2018 - 2024 SK ID Solutions AS
7+
* Copyright (C) 2018 - 2025 SK ID Solutions AS
88
* %%
99
* Permission is hereby granted, free of charge, to any person obtaining a copy
1010
* of this software and associated documentation files (the "Software"), to deal
@@ -28,8 +28,18 @@
2828

2929
import java.util.Arrays;
3030

31+
/**
32+
* Represents of authentication certificate levels.
33+
*/
3134
public enum AuthenticationCertificateLevel {
35+
36+
/**
37+
* Smart-ID basic certificate level. Use if you want to allow non-qualified and qualified accounts.
38+
*/
3239
ADVANCED(1),
40+
/**
41+
* Smart-ID highest certificate level. Use if you want to only allow qualified accounts.
42+
*/
3343
QUALIFIED(2);
3444

3545
private final int level;

0 commit comments

Comments
 (0)