Merge branch 'release/0.1.2'

Author: michallis

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "smart-id-rust-client"
-version = "0.1.0"
+version = "0.1.2"
 description = "Smart ID Rust Client"
 homepage = "https://smart-id.com"
 authors = ["Michallis Pashidis <[email protected]>"]

Cargo.toml

@@ -16,6 +16,17 @@ authentication and mobile digital signing using Smart-ID.</div>
 
 </div>
 
+# Introduction
+The library can be used for easy integration with the Smart-ID API. 
+It provides a simple interface for mobile authentication and mobile digital signing using Smart-ID.
+Additional utilities has been provided for easy integration with the Smart-ID API:
+- generate digest and calculate verification code
+- helper structs
+- interactions with the mobile end-user
+
+## Status
+Beta version - under development!
+
 ## Documentation
 
 [Smart-ID Documentation](https://github.com/SK-EID/smart-id-documentation)

README.MD

@@ -1 +1,60 @@
-# Introduction
+# Introduction
+
+This document describes the relying party service interface protocol of Smart-ID server and
+provides information for integration. The interface offers the entry point to Smart-ID main use
+cases, i.e. authentication and signing.
+
+The interface is to be used by relaying parties - parties who wish to use Smart-ID services,
+i.e. ask end users to perform authentication and signing operations.
+
+## 1.1 Glossary
+
+* Smart-ID account - A person has to register a Smart-ID account to use services provided by the Smart-ID
+  system. Account binds a Smart-ID app instance (installed on a person's mobile device)
+  to a person's identity in the Smart-ID system. In the course of account creation and
+  registration, the identity of the account owner (person) is proofed by a Registration
+  Authority (RA) and the relation between the identity and a key pair is certified by a
+  Certificate Authority (CA). An account has a signature key pair and an authentication
+  key pair.
+* Smart-ID app - A technical component of the Smart-ID system. A mobile app instance installed on a
+  person's mobile device that provides access to Smart-ID functionality for persons.
+* Smart-ID provider - An organization that is legally responsible for the Smart-ID system.
+* Smart-ID server - A technical component of the Smart-ID system. Server-side counterpart of the Smart-ID
+  app. Handles backend operations and provides API-s to Relying Party (RP).
+* Smart-ID system - A technical and organizational environment, which enables digital authentication and
+  issuing of digital signatures of persons in an electronic environment. The Smart-ID
+  system provides services that allow persons (Smart-ID account owners) to authenticate
+  themselves to RPs, to give digital signatures requested by RPs, and to manage their
+  Smart-ID accounts.
+* Authentication key pair (or authentication key) - Key pair, which is used to digitally authenticate a person.
+* Certificate Authority (CA) - An entity that issues certificates for Smart-ID account owners.
+* Key pair - Pair of keys, which are required for digital signature scheme. There are two kinds of key
+  pairs (or shortly, keys) in the Smart-ID system, authentication key pair and signature key
+  pair. The word pair refers to to the private and public keys of each key pair used in an
+  assymetric cryptographic algorithm, here RSA.
+* Mobile device - A tablet computer or smartphone that runs a mobile device operating system (Apple iOS,
+  Google Android).
+* Person - A natural person who uses the Smart-ID system to authenticate herself to an RP and to
+  issue digital signatures requested by RP.
+* Registration Authority (RA) - An entity responsible for recording or verifying some or all of the information (particularly
+  the identities of subjects) needed by a CA to issue certificates and CRLs and to perform
+  other certificate management functions.
+* Relying Party (RP) - An organization or service, for example a bank, which is using the Smart-ID service to
+  authenticate its users and to get them to sign the documents.
+* Relying Party request - A request from an RP that requires some kind of operation in the Smart-ID backend
+  system. It may or may not create a transaction.
+* Signature key pair (or signature key) - Key pair, which is used to give digital signatures of a person.
+
+
+## 1.2. References
+
+* **ETSI319412-1** ETSI. Electronic Signatures and Infrastructures (ESI); Certificate Profiles;
+  Part 1: Overview and common data structures. 2015. URL: <http://www.etsi.org/deliver/etsi_en/319400_319499/31941201/01.01.00_30/en_31941201v010100v.pdf>.
+* **rfc2616** R. Fielding et al. Hypertext Transfer Protocol – HTTP/1.1. RFC 2616 (Draft Standard).
+  Obsoleted by RFCs 7230, 7231, 7232, 7233, 7234, 7235, updated by RFCs 2817, 5785,
+  6266, 6585. Internet Engineering Task Force, June 1999. URL: <https://tools.ietf.org/html/rfc2616>.
+* **rfc4122** P. Leach, M. Mealling, and R. Salz. A Universally Unique IDentifier (UUID) URN
+  Namespace. RFC 4122 (Standards Track). Internet Engineering Task Force, July 2005.
+  URL: <https://tools.ietf.org/html/rfc4122>.
+* **rfc4648** S. Josefsson. The Base16, Base32, and Base64 Data Encodings. RFC 4648
+  (Proposed Standard). Internet Engineering Task Force, Oct. 2006. URL: <https://tools.ietf.org/html/rfc4648>.

docs/src/intro.md

@@ -1,28 +1,49 @@
 # Verification Code
 
-[https://github.com/SK-EID/smart-id-documentation?tab=readme-ov-file#23132-computing-the-verification-code](https://github.com/SK-EID/smart-id-documentation?tab=readme-ov-file#23132-computing-the-verification-code)
+> Source: [https://github.com/SK-EID/smart-id-documentation?tab=readme-ov-file#23132-computing-the-verification-code](https://github.com/SK-EID/smart-id-documentation?tab=readme-ov-file#23132-computing-the-verification-code)
 
-## 2.3.13.2 Computing the verification code
-The RP must compute a verification code for each authentication and siging request, so the user can bind together the session on the browser or RP app and the authentication request on the Smart-ID app. The VC is computed as follows:
+#### 2.3.13.2 Computing the verification code
+
+The RP must compute a verification code for each authentication and siging request, so the
+user can bind together the session on the browser or RP app and the authentication request
+on the Smart-ID app. The VC is computed as follows:
 
 `integer(SHA256(hash)[-2:-1]) mod 10000`
 
-Calculate SHA256 from the hash to be signed, extract 2 rightmost bytes from the result, interpret them as a big-endian unsigned integer and take the last 4 digits in decimal form for display. SHA256 is always used here, no matter what algorithm was used to calculate the original hash.
+Calculate SHA256 from the hash to be signed, extract 2 rightmost bytes from the result,
+interpret them as a big-endian unsigned integer and take the last 4 digits in decimal form for
+display. SHA256 is always used here, no matter what algorithm was used to calculate the
+original hash.
+
+Please mind that hash is a real hash byte value (for example, the byte array returned
+from the `md.digest()` call), not the Base64 form used for transport or the popular hexadecimal
+representation.
+
+The VC value must be displayed to the user in the browser together with a message asking
+the end user to verify the code matches with the one displayed on their mobile device. The
+user must not proceed if these don't match.
+
+[^1]: See https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html
 
-Please mind that hash is a real hash byte value (for example, the byte array returned from the md.digest() call), not the Base64 form used for transport or the popular hexadecimal representation.
+#### 2.3.13.3 Verifying the authentication response
 
-The VC value must be displayed to the user in the browser together with a message asking the end user to verify the code matches with the one displayed on their mobile device. The user must not proceed if these don't match.
+After receiving the transaction response from the Session status API call, the following
+algorithm must be used to decide, if the authentication result is trustworthy and what the identity
+of the authenticating end user is.
 
-## 2.3.13.3 Verifying the authentication response
-After receiving the transaction response from the Session status API call, the following algorithm must be used to decide, if the authentication result is trustworthy and what the identity of the authenticating end user is.
+- `result.endResult` has the value `OK`.
+- The certificate from `cert.value` is valid:
+    - The certificate is trusted (signed by a trusted CA).
+    - The certificate has not expired.
+- The person's certificate given in the `cert.value` is of required or higher assurance level
+  as requested.
+- The identity of the authenticated person is in the `subject` field or `subjectAltName`
+  extension of the X.509 certificate.
+- `signature.value` is the valid signature over the same `hash`, which was submitted by
+  the RP verified using the public key from `cert.value`.
 
-result.endResult has the value OK.
-The certificate from cert.value is valid:
-The certificate is trusted (signed by a trusted CA).
-The certificate has not expired.
-The person's certificate given in the cert.value is of required or higher assurance level as requested.
-The identity of the authenticated person is in the subject field or subjectAltName extension of the X.509 certificate.
-signature.value is the valid signature over the same hash, which was submitted by the RP verified using the public key from cert.value.
-It is strongly recommended to have these steps performed using standard cryptographic libraries.
+It is strongly recommended to have these steps performed using standard cryptographic
+libraries.
 
-After successful authentication, the RP must invalidate the old user's browser or API session identifier and generate a new one.
+After successful authentication, the RP must invalidate the old user's browser or API
+session identifier and generate a new one.

docs/src/verfiication.md

@@ -1,5 +1,5 @@
-use tracing::{error, info};
-use smart_id_rust_client::{authenticate_by_semantic_identifier, generate_verification_number, get_certificate_by_semantic_identifier, get_config_from_env, sha_digest, sign_by_semantic_identifier};
+use tracing::{error, info, warn};
+use smart_id_rust_client::{authenticate_by_semantic_identifier, generate_verification_number, get_certificate_by_semantic_identifier, get_config_from_env, SessionSignature, SessionStatus, sha_digest, sign_by_semantic_identifier};
 use smart_id_rust_client::common::{CountryCode, HashType, IdentityType, Interaction, ResultState, SemanticsIdentifier};
 use smart_id_rust_client::config::{SmartIDConfig, SmartIDConfigBuilder};
 use anyhow::Result;
@@ -22,10 +22,10 @@ async fn main() -> Result<()> {
 
 
     /// Example get Certificate
-    let _ = uc_get_certificate_choice(&cfg).await;
+    //let _ = uc_get_certificate_choice(&cfg).await;
 
     /// Example authenticate user
-    let _ = uc_authenticate_by_semantic_identifier(&cfg).await;
+    //let _ = uc_authenticate_by_semantic_identifier(&cfg).await;
 
     /// Example sign document digest
     let _ = uc_sign_by_semantic_identifier(&cfg).await;
@@ -34,12 +34,15 @@ async fn main() -> Result<()> {
 }
 
 async fn uc_get_certificate_choice(cfg: &SmartIDConfig) -> Result<()> {
+
     /// Create the semantic identifier
     let sem_id = SemanticsIdentifier::new_from_enum(IdentityType::PNO, CountryCode::BE, "81092402747");
+
+    /// Verify if a certificate exists for given id
     let res = get_certificate_by_semantic_identifier(&cfg, sem_id).await;
     match res {
         Ok(r) => {
-            let cert = r.cert.unwrap().value.unwrap();
+            let cert = validate_response_success(r).map(|res| res.cert.unwrap().value.unwrap())?;
             info!("Smart ID Certificate {:#?}", cert);
             Ok(())
         }
@@ -63,18 +66,14 @@ async fn uc_authenticate_by_semantic_identifier(cfg: &SmartIDConfig) -> Result<(
 
     /// Ask user for authentication
     let res = authenticate_by_semantic_identifier(&cfg, sem_id, interactions, b64_hash, hash_type).await;
+
     match res {
         Ok(r) => {
-            info!("Smart ID Authentication DUMP RESPONSE {:#?}", r);
-            if r.state == "COMPLETE" && ResultState::from(r.result.end_result).eq(&ResultState::OK) {
-                let cert = r.cert.unwrap().value.unwrap();
-                info!("Smart ID Authentication Result {:#?}", cert);
-                Ok(())
-            } else {
-                Err(anyhow::anyhow!("Error UC authenticate"))
-            }
+            let session_result = validate_response_success(r).map(|res| res.result)?;
+            info!("Smart ID Authentication result {:#?}", session_result);
+            Ok(())
         }
-        Err(e) => Err(anyhow::anyhow!("Error UC Authenticate: {:?}", e))
+        Err(_) => Err(anyhow::anyhow!("Error during authentication"))
     }
 }
 
@@ -98,15 +97,25 @@ async fn uc_sign_by_semantic_identifier(cfg: &SmartIDConfig) -> Result<()> {
     let res = sign_by_semantic_identifier(&cfg, sem_id, interactions, b64_hash, hash_type).await;
     match res {
         Ok(r) => {
-            info!("Smart ID SIGN DUMP RESPONSE {:#?}", r);
-            if r.state == "COMPLETE" && ResultState::from(r.result.end_result).eq(&ResultState::OK) {
-                let siganture = r.signature.unwrap().value.unwrap();
-                info!("Smart ID SIGN Result {:#?}", siganture);
-                Ok(())
-            } else {
-                Err(anyhow::anyhow!("Error UC SIGN"))
+            match validate_response_success(r).map(|res| res.signature)? {
+                None => {
+                    warn!("No signature");
+                    Ok(())
+                }
+                Some(signature) => {
+                    info!("Smart ID signature result {:#?}", signature);
+                    Ok(())
+                }
             }
         }
-        Err(e) => Err(anyhow::anyhow!("Error UC SIGN: {:?}", e))
+        Err(_) => Err(anyhow::anyhow!("Error signing digest"))
+    }
+}
+
+fn validate_response_success(response: SessionStatus) -> Result<SessionStatus> {
+    if response.state == "COMPLETE" && ResultState::from(response.result.end_result.clone()).eq(&ResultState::OK) {
+        Ok(response)
+    } else {
+        Err(anyhow::anyhow!("Error SmartID Response"))
     }
 }

examples/smart_id_client.rs

@@ -21,6 +21,9 @@ use crate::client_controller::{ctrl_authenticate_by_document_number, ctrl_authen
 /// Common models are exposed
 pub use models::common;
 pub use crate::models::session::SessionStatus;
+pub use crate::models::session::SessionSignature;
+pub use crate::models::session::SessionCertificate;
+pub use crate::models::session::SessionResult;
 pub use utils::verification::{generate_verification_number, sha_digest};