From 70d8d7b3d5faa776f509a52a9a12ec7da6018c91 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 9 Aug 2024 11:33:44 -0700 Subject: [PATCH 01/47] Draft for DBSC(E) --- DBSC-E/DeviceRegistration.svg | 1 + DBSC-E/DeviceRegistration.txt | 10 ++ DBSC-E/IDPCallsPrivateLocalKeyHelper.svg | 1 + DBSC-E/IDPCallsPrivateLocalKeyHelper.txt | 92 +++++++++++ DBSC-E/IDPCallsPublicLocalKeyHelper.svg | 1 + DBSC-E/IDPCallsPublicLocalKeyHelper.txt | 48 ++++++ .../IDPSameAsRP-CallsPublicLocalKeyHelper.svg | 1 + .../IDPSameAsRP-CallsPublicLocalKeyHelper.txt | 45 ++++++ DBSC-E/KeyGeneration.md | 91 +++++++++++ DBSC-E/Overview.md | 146 ++++++++++++++++++ README.md | 98 +++++++++--- 11 files changed, 512 insertions(+), 22 deletions(-) create mode 100644 DBSC-E/DeviceRegistration.svg create mode 100644 DBSC-E/DeviceRegistration.txt create mode 100644 DBSC-E/IDPCallsPrivateLocalKeyHelper.svg create mode 100644 DBSC-E/IDPCallsPrivateLocalKeyHelper.txt create mode 100644 DBSC-E/IDPCallsPublicLocalKeyHelper.svg create mode 100644 DBSC-E/IDPCallsPublicLocalKeyHelper.txt create mode 100644 DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.svg create mode 100644 DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.txt create mode 100644 DBSC-E/KeyGeneration.md create mode 100644 DBSC-E/Overview.md diff --git a/DBSC-E/DeviceRegistration.svg b/DBSC-E/DeviceRegistration.svg new file mode 100644 index 0000000..9e11a70 --- /dev/null +++ b/DBSC-E/DeviceRegistration.svg @@ -0,0 +1 @@ +title%20Device%20registration%0A%0Aautonumber%201%0Aparticipant%20%22Device%20registration%20client%22%20as%20D%0Aparticipant%20%22Attestation%20service%22%20as%20A%0A%0Anote%20over%20D%2C%20A%3A%20Provisioning%20...%0AD-%3E%3EA%3A%20Register%20device%20(DeviceKey%2C%20AIK%20for%20KG%2C%20AIK%20for%20TPM%2C%20AIK%20for%20Software)%0AA-%3E%3ED%3A%20200%20OK%0A%0ADevice registration clientAttestation serviceDevice registrationProvisioning ...Register device (DeviceKey, AIK for KG, AIK for TPM, AIK for Software)1 200 OK2  \ No newline at end of file diff --git a/DBSC-E/DeviceRegistration.txt b/DBSC-E/DeviceRegistration.txt new file mode 100644 index 0000000..c95015f --- /dev/null +++ b/DBSC-E/DeviceRegistration.txt @@ -0,0 +1,10 @@ +title Device registration + +autonumber 1 +participant "Device registration client" as D +participant "Attestation service" as A + +note over D, A: Provisioning ... +D->>A: Register device (DeviceKey, AIK for KG, AIK for TPM, AIK for Software) +A->>D: 200 OK + diff --git a/DBSC-E/IDPCallsPrivateLocalKeyHelper.svg b/DBSC-E/IDPCallsPrivateLocalKeyHelper.svg new file mode 100644 index 0000000..299c993 --- /dev/null +++ b/DBSC-E/IDPCallsPrivateLocalKeyHelper.svg @@ -0,0 +1 @@ +title%20IdP%20calls%20a%20private%20Local%20Key%20Helper%0A%0Aautonumber%201%0Aparticipant%20%22Relying%20Party%22%20as%20W%0Aparticipant%20%22IdP%22%20as%20I%0Aparticipant%20%22Browser%22%20as%20B%0Aparticipant%20%22Local%20Key%20Helper%22%20as%20P%0A%0Anote%20over%20W%2C%20P%3A%20IdP%20life...%0AB-%3E%3EI%3A%20Any%20request%0AI-%3E%3EB%3A%20Any%20response%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0AB-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0Anote%20over%20W%2C%20P%3A%20Sign%20in...%0AW-%3E%3EB%3A%20Start%20sign%20in%20(302)%5CnSec-Session-Registration%3A%20path%2C%20RPChallenge%2C...%20%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0AB-%3E%3EB%3A%20Check%20for%20cached%20HelperId%20for%20IDPURL%0A%0Aalt%20Cached%20HelperId%20present%20(99.99%25%20cases)%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0A%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPURL%2C%20IDPURL%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnonce%7D%5Cnx-ms-DeviceCredential1%7Bnonce%7D%5Cnx-ms-RefreshTokenCredential2%7Bnonce%7D%5Cnx-ms-DeviceCredential2%7Bnonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%20%20%20%20opt%20nonce%20is%20stale%0A%20%20%20%20%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%20%20%20%20%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnew_nonce%7D%5Cnx-ms-DeviceCredential1%7Bnew_nonce%7D%5Cnx-ms-RefreshTokenCredential2%7Bnew_nonce%7D%5Cnx-ms-DeviceCredential2%7Bnew_nonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20end%0A%0Aelse%20No%20cached%20HelperId%20present%0A%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnonce%7D%5Cnx-ms-DeviceCredential1%7Bnonce%7D%5Cnx-ms-RefreshTokenCredential2%7Bnonce%7D%5Cnx-ms-DeviceCredential2%7Bnonce%7D%20...%20%5Cn%5CnSec-Session-HelperDiscoveryNeeded%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%0A%20%20%20%20note%20over%20I%2C%20B%3A%20No%20binding%20info%20present%2C%20but%20the%20reequest%20has%20GenerratKey%2C%20so%20IdP%20issues%20helper%20id%20list%0A%0A%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5Cn%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0A%20%20%20%20B-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%5D)%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPURL%2C%20IDPURL%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnew_nonce%7D%5Cnx-ms-DeviceCredential1%7Bnew_nonce%7D%5Cn%20x-ms-RefreshTokenCredential2%7Bnew_nonce%7D%5Cn%20x-ms-DeviceCredential2%7Bnew_nonce%7D%20...%20%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%0Aend%0A%0Aopt%20SSO%20information%20is%20not%20sufficient%0A%20%20%20%20I-%3E%3EB%3A%20Sign%20in%20ceremony%0A%20%20%20%20B-%3E%3EI%3A%20Sign%20done%0Aend%0A%0AI-%3E%3EB%3A%20Authorization%20code%2C%20KeyId%0A%0A%0Anote%20over%20W%2C%20B%3A%20Since%20DBSC%20session%20has%20been%20initialized%20already%20for%20RP%2C%20browser%20needs%20to%20generate%20JWT%20on%20redirect%20back%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(path%2C%20RPChallenge%2C%20extraParams)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0Anote%20over%20W%2C%20B%3A%20JWT%20is%20appended%20by%20the%20browser%20before%20returning%20the%20response%20from%20IDP%20back%20to%20the%20RP%0AB-%3E%3EW%3A%20Authorization%20code%2C%20KeyId%2C%20JWT%0AW-%3E%3EI%3A%20(confidential%20client%20request)%20redeem%20authorization%20code%0AI-%3E%3EW%3A%20(confidential%20client%20response)%20return%20id_token%0AW-%3E%3EW%3A%20parse%20id_token%20and%20validate%20binding%2C%20match%20with%20the%20JWT%20from%20the%20previous%0AW-%3E%3EB%3A%20Bound%20AuthCookie%0A%0Anote%20over%20W%2C%20P%3A%20Refresh%20DBSC...%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(sessionID)%0AW-%3E%3EB%3A%20Challenge%2C%20**extraParams**%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(sessionID%2C%20RPChallenge%2C%20**extraParams**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(JWT)%0AW-%3E%3EW%3A%20Validate%20JWT%20(w%2Fpublic%20key%20on%20file)%0AW-%3E%3EB%3A%20AuthCookie%0ARelying PartyIdPBrowserLocal Key HelperIdP calls a private Local Key HelperIdP life...Any request1 Any response2 Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime3 Sign in...Start sign in (302)4 Sec-Session-Registration: path, RPChallenge,... Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsCheck for cached HelperId for IDPURL5 currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...])6 Pre-gen key and attest (RPURL, IDPURL, extraParams...)7 Generate Key8 create binding statement S(publicKey, AIK)9 Return: KeyId, 10 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)11 Load sign-in (follow the 302)12 x-ms-RefreshTokenCredential1{nonce}x-ms-DeviceCredential1{nonce}x-ms-RefreshTokenCredential2{nonce}x-ms-DeviceCredential2{nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]302 to IdP with qs parameter sso_nonce=new_nonce13 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsLoad sign-in14 x-ms-RefreshTokenCredential1{new_nonce}x-ms-DeviceCredential1{new_nonce}x-ms-RefreshTokenCredential2{new_nonce}x-ms-DeviceCredential2{new_nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Load sign-in (follow the 302)15 x-ms-RefreshTokenCredential1{nonce}x-ms-DeviceCredential1{nonce}x-ms-RefreshTokenCredential2{nonce}x-ms-DeviceCredential2{nonce} ... Sec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParamsNo binding info present, but the reequest has GenerratKey, so IdP issues helper id list302 to IdP with qs parameter sso_nonce=new_nonce16 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime17 currentHelperId = Evaluate policy for (IdP, [HelperId1])18 Pre-gen key and attest (RPURL, IDPURL, extraParams...)19 Generate Key20 create binding statement S(publicKey, AIK)21 Return: KeyId, 22 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)23 Load sign-in24 x-ms-RefreshTokenCredential1{new_nonce}x-ms-DeviceCredential1{new_nonce} x-ms-RefreshTokenCredential2{new_nonce} x-ms-DeviceCredential2{new_nonce} ... Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Sign in ceremony25 Sign done26 Authorization code, KeyId27 Since DBSC session has been initialized already for RP, browser needs to generate JWT on redirect backRequest Sign JWT (path, RPChallenge, extraParams)28 Return JWT Signature29 JWT is appended by the browser before returning the response from IDP back to the RPAuthorization code, KeyId, JWT30 (confidential client request) redeem authorization code31 (confidential client response) return id_token32 parse id_token and validate binding, match with the JWT from the previous33 Bound AuthCookie34 Refresh DBSC...GET /securesession/refresh (sessionID)35 Challenge, extraParams36 Request Sign JWT (sessionID, RPChallenge, extraParams)37 Return JWT Signature38 GET /securesession/refresh (JWT)39 Validate JWT (w/public key on file)40 AuthCookie41 alt[Cached HelperId present (99.99% cases)][No cached HelperId present]loop[For each device]opt[nonce is stale]loop[For each device]opt[SSO information is not sufficient] \ No newline at end of file diff --git a/DBSC-E/IDPCallsPrivateLocalKeyHelper.txt b/DBSC-E/IDPCallsPrivateLocalKeyHelper.txt new file mode 100644 index 0000000..dddf3bf --- /dev/null +++ b/DBSC-E/IDPCallsPrivateLocalKeyHelper.txt @@ -0,0 +1,92 @@ +title IdP calls a private Local Key Helper + +autonumber 1 +participant "Relying Party" as W +participant "IdP" as I +participant "Browser" as B +participant "Local Key Helper" as P + +note over W, P: IdP life... +B->>I: Any request +I->>B: Any response\nSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTime +B->>B: Cache HelperId for IDPURL for HelperCacheTime + +note over W, P: Sign in... +W->>B: Start sign in (302)\nSec-Session-Registration: path, RPChallenge,... \nSec-Session-GenerateKey: RPURL, IDPURL, extraParams +B->>B: Check for cached HelperId for IDPURL + +alt Cached HelperId present (99.99% cases) + + B->>B: currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...]) + + B->>P: Pre-gen key and attest (RPURL, IDPURL, extraParams...) + + P->>P: Generate Key + + loop For each device + P->>P: create binding statement S(publicKey, AIK) + end + + P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>B: Remember this key is for RP (and maybe path) + + B->>I: Load sign-in (follow the 302)\n\nx-ms-RefreshTokenCredential1{nonce}\nx-ms-DeviceCredential1{nonce}\nx-ms-RefreshTokenCredential2{nonce}\nx-ms-DeviceCredential2{nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + + opt nonce is stale + I->>B: 302 to IdP with qs parameter sso_nonce=new_nonce\nSec-Session-GenerateKey: RPURL, IDPURL, extraParams + B->>I: Load sign-in\n\nx-ms-RefreshTokenCredential1{new_nonce}\nx-ms-DeviceCredential1{new_nonce}\nx-ms-RefreshTokenCredential2{new_nonce}\nx-ms-DeviceCredential2{new_nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + end + +else No cached HelperId present + + + B->>I: Load sign-in (follow the 302)\n\nx-ms-RefreshTokenCredential1{nonce}\nx-ms-DeviceCredential1{nonce}\nx-ms-RefreshTokenCredential2{nonce}\nx-ms-DeviceCredential2{nonce} ... \n\nSec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParams + + note over I, B: No binding info present, but the reequest has GenerratKey, so IdP issues helper id list + + I->>B: 302 to IdP with qs parameter sso_nonce=new_nonce\n\nSec-Session-GenerateKey: RPURL, IDPURL, extraParams\nSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTime + B->>B: Cache HelperId for IDPURL for HelperCacheTime + + B->>B: currentHelperId = Evaluate policy for (IdP, [HelperId1]) + B->>P: Pre-gen key and attest (RPURL, IDPURL, extraParams...) + + P->>P: Generate Key + + loop For each device + P->>P: create binding statement S(publicKey, AIK) + end + + P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>B: Remember this key is for RP (and maybe path) + + B->>I: Load sign-in\n\nx-ms-RefreshTokenCredential1{new_nonce}\nx-ms-DeviceCredential1{new_nonce}\n x-ms-RefreshTokenCredential2{new_nonce}\n x-ms-DeviceCredential2{new_nonce} ... \n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + + +end + +opt SSO information is not sufficient + I->>B: Sign in ceremony + B->>I: Sign done +end + +I->>B: Authorization code, KeyId + + +note over W, B: Since DBSC session has been initialized already for RP, browser needs to generate JWT on redirect back +B->>P: Request Sign JWT (path, RPChallenge, extraParams) +P->>B: Return JWT Signature +note over W, B: JWT is appended by the browser before returning the response from IDP back to the RP +B->>W: Authorization code, KeyId, JWT +W->>I: (confidential client request) redeem authorization code +I->>W: (confidential client response) return id_token +W->>W: parse id_token and validate binding, match with the JWT from the previous +W->>B: Bound AuthCookie + +note over W, P: Refresh DBSC... +B->>W: GET /securesession/refresh (sessionID) +W->>B: Challenge, **extraParams** +B->>P: Request Sign JWT (sessionID, RPChallenge, **extraParams**) +P->>B: Return JWT Signature +B->>W: GET /securesession/refresh (JWT) +W->>W: Validate JWT (w/public key on file) +W->>B: AuthCookie diff --git a/DBSC-E/IDPCallsPublicLocalKeyHelper.svg b/DBSC-E/IDPCallsPublicLocalKeyHelper.svg new file mode 100644 index 0000000..76f6759 --- /dev/null +++ b/DBSC-E/IDPCallsPublicLocalKeyHelper.svg @@ -0,0 +1 @@ +title%20IdP%20calls%20a%20public%20Local%20Key%20Helper%0A%0Aautonumber%201%0Aparticipant%20%22Relying%20Party%22%20as%20W%0Aparticipant%20%22IdP%22%20as%20I%0Aparticipant%20%22Browser%22%20as%20B%0Aparticipant%20%22Local%20Key%20Helper%22%20as%20P%0Aparticipant%20%22AttestationService%22%20as%20A%0A%0Anote%20over%20W%2C%20A%3A%20Sign%20in...%0AW-%3E%3EB%3A%20Start%20sign%20in%20(302)%0AB-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%0A%0AI-%3E%3EB%3A%20Sec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0AB-%3E%3EB%3A%20currentHelperId%20%3D%20%5CnEvaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%2C%20HelperId2%2C...%5D)%0AB-%3E%3EP%3A%20Pre-gen%20key%20and%20%5Cnattest%20(RPUrl%2C%20IDPUrl%2C%20%5Cnchallenge%3Dnonce%2C%20extraParams...)%0A%0AP-%3E%3EP%3A%20Generate%20Key%0A%0AP-%3E%3EA%3A%20Get%20Binding%20Statement%20%5Cn(publicKey%2C%20AIK%2C%20challenge%3Dnonce)%0AA-%3E%3EP%3A%20Return%20binding%20statement%20%5Cn%7B%20nonce%2C%20thumbprint(publicKey)%2C%20extraClaims...%20%7D%0AP-%3E%3EB%3A%20KeyId%2C%20%5CnReturn%20binding%20statement%20%5Cn%7B%20nonce%2C%20thumbprint(publicKey)%2C%20extraClaims...%20%7D%0AB-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0AB-%3E%3EI%3A%20Sec-Session-Keys%3A%20KeyId%2C%20%5CnBinding%20statement%20%5Cn%7B%20nonce%2C%20thumbprint(publicKey)%2C%20extraClaims...%20%7D%0AI-%3E%3EI%3A%20validate%20signature%20on%20the%20binding%20statement%20%5Cn%26%20nonce%2C%20store%20thumbprint%0A%0AI-%3E%3EB%3A%20Sign%20in%20ceremony%0AB-%3E%3EI%3A%20Sign%20done%0A%0AI-%3E%3EB%3A%20Auth%20tokens%20(with%20thumbprint)%2C%20%5CnKeyId%0AB-%3E%3EW%3A%20Auth%20tokens%20(with%20thumbprint)%2C%20%5CnKeyId%0A%0Anote%20over%20W%2C%20A%3A%20Initiate%20DBSC%20...%0AW-%3E%3EB%3A%20StartSession%20%5Cn(challenge%3Dnonce%2C%20token%3F%2C%20KeyId%3F%2C%20**extraParams...**)%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20%5Cn(uri%2C%20challenge%3Dnonce%2C%5Cn%20token%3F%2C%20keyId%3F%2C%20**extraParams...**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20POST%20%2Fsecuresession%2Fstartsession%20(JWT%2C%20tokens)%0AW-%3E%3EW%3A%20Validate%20JWT%2C%20%5Cn(w%2F%20match%20thumbprint%20%5Cnin%20the%20tokens)%0AW-%3E%3EB%3A%20AuthCookie%0A%0Anote%20over%20W%2C%20A%3A%20Refresh%20DBSC...%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(sessionID)%0AW-%3E%3EB%3A%20Challenge%2C%20**extraParams...**%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(sessionID%2C%20**extraParams...**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(JWT)%0AW-%3E%3EW%3A%20Validate%20JWT%20%5Cn(w%2Fpublic%20key%20on%20file)%0AW-%3E%3EB%3A%20AuthCookie%0ARelying PartyIdPBrowserLocal Key HelperAttestationServiceIdP calls a public Local Key HelperSign in...Start sign in (302)1 Load sign-in (follow the 302)2 Sec-Session-GenerateKey: 3 RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimecurrentHelperId = 4 Evaluate policy for (IdP, [HelperId1, HelperId2,...])Pre-gen key and 5 attest (RPUrl, IDPUrl, challenge=nonce, extraParams...)Generate Key6 Get Binding Statement 7 (publicKey, AIK, challenge=nonce)Return binding statement 8 { nonce, thumbprint(publicKey), extraClaims... }KeyId, 9 Return binding statement { nonce, thumbprint(publicKey), extraClaims... }Remember this key is for RP (and maybe path)10 Sec-Session-Keys: KeyId, 11 Binding statement { nonce, thumbprint(publicKey), extraClaims... }validate signature on the binding statement 12 & nonce, store thumbprintSign in ceremony13 Sign done14 Auth tokens (with thumbprint), 15 KeyIdAuth tokens (with thumbprint), 16 KeyIdInitiate DBSC ...StartSession 17 (challenge=nonce, token?, KeyId?, extraParams...)Request Sign JWT 18 (uri, challenge=nonce, token?, keyId?, extraParams...)Return JWT Signature19 POST /securesession/startsession (JWT, tokens)20 Validate JWT, 21 (w/ match thumbprint in the tokens)AuthCookie22 Refresh DBSC...GET /securesession/refresh (sessionID)23 Challenge, extraParams...24 Request Sign JWT (sessionID, extraParams...)25 Return JWT Signature26 GET /securesession/refresh (JWT)27 Validate JWT 28 (w/public key on file)AuthCookie29  \ No newline at end of file diff --git a/DBSC-E/IDPCallsPublicLocalKeyHelper.txt b/DBSC-E/IDPCallsPublicLocalKeyHelper.txt new file mode 100644 index 0000000..6581265 --- /dev/null +++ b/DBSC-E/IDPCallsPublicLocalKeyHelper.txt @@ -0,0 +1,48 @@ +title IdP calls a public Local Key Helper + +autonumber 1 +participant "Relying Party" as W +participant "IdP" as I +participant "Browser" as B +participant "Local Key Helper" as P +participant "AttestationService" as A + +note over W, A: Sign in... +W->>B: Start sign in (302) +B->>I: Load sign-in (follow the 302) + +I->>B: Sec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2], HelperCacheTime +B->>B: currentHelperId = \nEvaluate policy for (IdP, [HelperId1, HelperId2,...]) +B->>P: Pre-gen key and \nattest (RPUrl, IDPUrl, \nchallenge=nonce, extraParams...) + +P->>P: Generate Key + +P->>A: Get Binding Statement \n(publicKey, AIK, challenge=nonce) +A->>P: Return binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } +P->>B: KeyId, \nReturn binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } +B->>B: Remember this key is for RP (and maybe path) +B->>I: Sec-Session-Keys: KeyId, \nBinding statement \n{ nonce, thumbprint(publicKey), extraClaims... } +I->>I: validate signature on the binding statement \n& nonce, store thumbprint + +I->>B: Sign in ceremony +B->>I: Sign done + +I->>B: Auth tokens (with thumbprint), \nKeyId +B->>W: Auth tokens (with thumbprint), \nKeyId + +note over W, A: Initiate DBSC ... +W->>B: StartSession \n(challenge=nonce, token?, KeyId?, **extraParams...**) +B->>P: Request Sign JWT \n(uri, challenge=nonce,\n token?, keyId?, **extraParams...**) +P->>B: Return JWT Signature +B->>W: POST /securesession/startsession (JWT, tokens) +W->>W: Validate JWT, \n(w/ match thumbprint \nin the tokens) +W->>B: AuthCookie + +note over W, A: Refresh DBSC... +B->>W: GET /securesession/refresh (sessionID) +W->>B: Challenge, **extraParams...** +B->>P: Request Sign JWT (sessionID, **extraParams...**) +P->>B: Return JWT Signature +B->>W: GET /securesession/refresh (JWT) +W->>W: Validate JWT \n(w/public key on file) +W->>B: AuthCookie diff --git a/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.svg b/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.svg new file mode 100644 index 0000000..f37009c --- /dev/null +++ b/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.svg @@ -0,0 +1 @@ +title%20IdP%20same%20as%20RP%2C%20calls%20a%20public%20Local%20Key%20Helper%0A%0Aautonumber%201%0Aparticipant%20%22Relying%20Party%22%20as%20W%0Aparticipant%20%22IdP%22%20as%20I%0Aparticipant%20%22Browser%22%20as%20B%0Aparticipant%20%22Local%20Key%20Helper%22%20as%20P%0Aparticipant%20%22AttestationService%22%20as%20A%0A%0Anote%20over%20W%2C%20A%3A%20Sign%20in...%0AW-%3E%3EB%3A%20Start%20sign%20in%20(302)%20%5Cn%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20nonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0A%0AB-%3E%3EB%3A%20currentHelperId%20%3D%20%5CnEvaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%2C%20HelperId2%2C...%5D)%0AB-%3E%3EP%3A%20Pre-gen%20key%20and%20%5Cnattest%20(RPUrl%2C%20IDPUrl%2C%20nonce%2C%20extratParams...)%0A%0AP-%3E%3EP%3A%20Generate%20Key%0A%0AP-%3E%3EA%3A%20Get%20Binding%20Statement%20%5Cn%20(publicKey%2C%20AIK%2C%20nonce)%0AA-%3E%3EP%3A%20Return%20binding%20statement%20%5Cn%7B%20nonce%2C%20thumbprint(publicKey)%2C%20extraClaims...%20%7D%0AP-%3E%3EB%3A%20KeyId%2C%20%5CnReturn%20binding%20statement%20%5Cn%7B%20nonce%2C%20thumbprint(publicKey)%2C%20extraClaims...%20%7D%0AB-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0AB-%3E%3EI%3A%20Load%20sign-in%20%5CnSec-Session-Keys%3A%20KeyId%2C%20%5CnBinding%20statement%20%7B%20nonce%2C%20%20thumbprint(publicKey)%2C%20extraClaims...%20%7D%0AI-%3E%3EI%3A%20validate%20signature%20%5Cnon%20the%20binding%20statement%20and%20nonce%2C%20%5Cnstore%20thumbprint%0A%0AI-%3E%3EB%3A%20Sign%20in%20ceremony%0AB-%3E%3EI%3A%20Sign%20done%0A%0AI-%3E%3EW%3A%20API(Auth%20tokens%20with%20thumbprint%2C%20KeyId)%0A%0Anote%20over%20W%2C%20A%3A%20Initiate%20DBSC%20...%0AW-%3E%3EB%3A%20200%20OK%20%5CnSec-Session-Registration%3A%20%5Cnpath%2C%20RPChallenge%2C%20token%3F%2C%20KeyId%2C%20extraParams%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(uri%2C%20challenge%2C%20token%3F%2C%20keyId%3F%2C%20**extraParams...**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20POST%20%2Fsecuresession%2Fstartsession%20(JWT%2C%20tokens)%0AW-%3E%3EW%3A%20Validate%20JWT%2C%20%5Cn(w%2F%20match%20thumbprint%20in%20the%20tokens)%0AW-%3E%3EB%3A%20AuthCookie%0A%0Anote%20over%20W%2C%20A%3A%20Refresh%20DBSC...%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(sessionID)%0AW-%3E%3EB%3A%20Challenge%2C%20**extraParams...**%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(sessionID%2C%20**extraParams...**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(JWT)%0AW-%3E%3EW%3A%20Validate%20JWT%20(w%2Fpublic%20key%20on%20file)%0AW-%3E%3EB%3A%20AuthCookie%0ARelying PartyIdPBrowserLocal Key HelperAttestationServiceIdP same as RP, calls a public Local Key HelperSign in...Start sign in (302) 1 Sec-Session-GenerateKey: RPUrl, IDPUrl, nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimecurrentHelperId = 2 Evaluate policy for (IdP, [HelperId1, HelperId2,...])Pre-gen key and 3 attest (RPUrl, IDPUrl, nonce, extratParams...)Generate Key4 Get Binding Statement 5  (publicKey, AIK, nonce)Return binding statement 6 { nonce, thumbprint(publicKey), extraClaims... }KeyId, 7 Return binding statement { nonce, thumbprint(publicKey), extraClaims... }Remember this key is for RP (and maybe path)8 Load sign-in 9 Sec-Session-Keys: KeyId, Binding statement { nonce,  thumbprint(publicKey), extraClaims... }validate signature 10 on the binding statement and nonce, store thumbprintSign in ceremony11 Sign done12 API(Auth tokens with thumbprint, KeyId)13 Initiate DBSC ...200 OK 14 Sec-Session-Registration: path, RPChallenge, token?, KeyId, extraParamsRequest Sign JWT (uri, challenge, token?, keyId?, extraParams...)15 Return JWT Signature16 POST /securesession/startsession (JWT, tokens)17 Validate JWT, 18 (w/ match thumbprint in the tokens)AuthCookie19 Refresh DBSC...GET /securesession/refresh (sessionID)20 Challenge, extraParams...21 Request Sign JWT (sessionID, extraParams...)22 Return JWT Signature23 GET /securesession/refresh (JWT)24 Validate JWT (w/public key on file)25 AuthCookie26  \ No newline at end of file diff --git a/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.txt b/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.txt new file mode 100644 index 0000000..229824f --- /dev/null +++ b/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.txt @@ -0,0 +1,45 @@ +title IdP same as RP, calls a public Local Key Helper + +autonumber 1 +participant "Relying Party" as W +participant "IdP" as I +participant "Browser" as B +participant "Local Key Helper" as P +participant "AttestationService" as A + +note over W, A: Sign in... +W->>B: Start sign in (302) \n\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2], HelperCacheTime + +B->>B: currentHelperId = \nEvaluate policy for (IdP, [HelperId1, HelperId2,...]) +B->>P: Pre-gen key and \nattest (RPUrl, IDPUrl, challenge=nonce, extratParams...) + +P->>P: Generate Key + +P->>A: Get Binding Statement \n (publicKey, AIK, challenge=nonce) +A->>P: Return binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } +P->>B: KeyId, \nReturn binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } +B->>B: Remember this key is for RP (and maybe path) +B->>I: Load sign-in \nSec-Session-Keys: KeyId, \nBinding statement \n{ nonce, thumbprint(publicKey), extraClaims... } +I->>I: validate signature \non the binding statement and nonce, \nstore thumbprint + +I->>B: Sign in ceremony +B->>I: Sign done + +I->>W: API(Auth tokens with thumbprint, KeyId) + +note over W, A: Initiate DBSC ... +W->>B: 200 OK \nSec-Session-Registration: \npath, RPChallenge, token?, KeyId, extraParams +B->>P: Request Sign JWT (uri, challenge, token?, keyId?, **extraParams...**) +P->>B: Return JWT Signature +B->>W: POST /securesession/startsession (JWT, tokens) +W->>W: Validate JWT, \n(w/ match thumbprint in the tokens) +W->>B: AuthCookie + +note over W, A: Refresh DBSC... +B->>W: GET /securesession/refresh (sessionID) +W->>B: Challenge, **extraParams...** +B->>P: Request Sign JWT (sessionID, **extraParams...**) +P->>B: Return JWT Signature +B->>W: GET /securesession/refresh (JWT) +W->>W: Validate JWT (w/public key on file) +W->>B: AuthCookie diff --git a/DBSC-E/KeyGeneration.md b/DBSC-E/KeyGeneration.md new file mode 100644 index 0000000..d504a8a --- /dev/null +++ b/DBSC-E/KeyGeneration.md @@ -0,0 +1,91 @@ +### Local key helper on Windows + +On Windows, a Local key helper is a COM class. A COM interface that the local key helper implements is TBD (working name for this document is ILocalKeyHelper) + +#### Deployment of a 3rd party local key helper. + +Local key helpers will be deployed using registry. + +The base registry key is: + +``` +[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\\\LocalKeyHelperList] +``` + +i.e. + +``` +[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\LocalKeyHelperList] + +[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\LocalKeyHelperList] +``` + +Every local key helper has a child key in the above registry key. The entry for the local key is a registry key with the name equals to the local key helper id, the default value stores activation ID, prefixed by an activation scheme. + +``` +[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\\\LocalKeyHelperList\] +@=":" +``` + +Here is example: + +``` +[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\LocalKeyHelperList\login.contoso.com] +@="progid:App.Component.1.0" + +[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\LocalKeyHelperList\login.fabrikam.com] +@="clsid:3AD05D77-6885-4BAF-A727-D30690A2A28A" +``` + +Currently the supported schemes are: + +1. clsid: \ - CLSID of a COM class that implements the Local Key Helper. +2. progid:\ - [a programic identifier](https://learn.microsoft.com/en-us/windows/win32/com/-progid--key) of the local key helper. + +This scheme can be extended by other schemes in future. +The local key helper registry key can have extra values, which we can use for in future. + +Here is a visual example how Local key helper is organized: + +![Local key helper registry key](./images/keyhelper-reg.png) + +When the browser needs to communicate with a local key helper. It uses its ID to locate the registry key, then reads the default value of this registry key and activates the object by the activation scheme (CLSID or ProgId according to the document). After activation it queries ILocalKeyHelper interface and invokes corresponding methods. + +#### Well-known local key helpers on Windows + +A well-known local key helper list on Windows is a list of helperId to clsid, that either harcoded or predefined in the browser settings. + +### **Attestation Service**: + +A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. Before defining the attestation service, let us get familiar with the building blocks of binding and proof of binding. + +There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the _binding key_, the _attestation key_, and the _binding statement_. + +#### **Binding Key**: + +A _binding key_ is an asymmetric key pair that is used to bind an auth cookie.It is identified by a key ID and it is the responsibility of the browser to remember which key ID corresponds to which Local Key Helper and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. + +This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware running on the device. In the context DBSC(E), the binding key is generated during the device registration process, and hence is guaranteed to be attack free if generated in a clean room environment. + +#### **Binding Statement**: + +Additonal to the binding key, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. + +#### **Attestation Key** + +An _attestation key_ is generated during the device registration process and has the following properties: + + 1. It signs only the private/other keys that reside in the same secure enclave as the attestation key. + 2. It cannot sign any external payload, or if it signs, it cannot generate an output that can be interpreted as an attestation statement. + +Since the attestation key can be uploaded only once to the backend at the moment of device registration, in the clean room, and there is no need to change this key unless the device loses it (Could be due to key rotation or similar operations). + +#### **Binding Statement - Generation and Validation**: + +The **attestation key**, hence, can be used to attest that the **binding key** belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an **attestation statement**. Depending on the specific implementation, this **attestation statement** itself can be a **binding statement**, or it can be sent to an attestation service to produce the final binding statement. + +The validation of the **binding statement** authenticates the device by using device ID to find the corresponding attestation key. The validation component verifies the **attestation statement**, and it can understand that such a statement cannot be generated, unless the private key resides in the same secure enclave when signed by the **attestation key**. Hence, a valid attestation statement means that both the attestation key and the binding key belong to the same device. The validation component can be part of the attestation service for public local key helpers, or part of an IdP for private local key helper. + +This is not the only way to ensure that the binding key and the device key belong to the same device, and having the **attestation key** and the **attestation service** is not mandatory for producing a **binding statement**. That is why the protocol specifics of checking the binding are out of scope for this document. The focus of DBSC(E) is to only establish important properties of the binding statement. + +Binding statements can be long-lived or short-lived. If an IdP can perform proof of device, it can use long-lived binding statements based on attestation keys to avoid extra network calls. IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements to prevent forgery of the binding statement from a different device. To avoid binding statement forgery, a short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement. diff --git a/DBSC-E/Overview.md b/DBSC-E/Overview.md new file mode 100644 index 0000000..92cd1a4 --- /dev/null +++ b/DBSC-E/Overview.md @@ -0,0 +1,146 @@ +# Device Bound Session Credentials for Enterprise - explainer + +This is the repository for Device Bound Session Credentials for Enterprise. You're welcome to +[contribute](CONTRIBUTING.md)! + +## Authors + +- [Sameera Gajjarapu](sameera.gajjarapu@microsoft.com), Microsoft +- [Alexander Tokerev](alextok@microsoft.com), Microsoft + +## Contributors + +- [Olga Dalton](), Microsoft +- [Kristian Monsen](), Google +- [Phil Leblanc](), Google +- [Sebastian](), Google +- [Arnar Birgisson](), Google +- [Pamela Dingle](), Microsoft +- [Paul Garner](), Microsoft +- [Erik Anderson](), Microsoft +- [Will Bartlett](), Microsoft +- [Kai Song](), Microsoft +- [Amit Gusain](), Microsoft + +## Participate (to come) + +- [Issue tracker]() +- [Discussion forum] + +## Overview + +Device Bound Session Credentials for Enterprise - DBSC(E), is not a separate proposal but an addition to existing [DBSC](https://github.com/wicg/dbsc) proposal to enhance the key generation mechanism and security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. + +## Why DBSC(E)? + +While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during the web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own credentials (asymmetric key pair) to the web application, there by stealing the session. Any upcoming sessions after this, even with DBSC, will not be reliable. + +DBSC(E) aims to mitigate this risk by introducing the concept of credential generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the device. It guaratees any given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as "clean room"). With DBSC(E), the malware will not be able to compromise a device even during signin/login. Device registration is also expected to be a once-in-a-lifetime operation, and hence the user will not be required to perform this operation again, reducing the chances of malware compromising the device. + +## How does it integrate with DBSC? + +DBSC(E) is not intended to be a separate proposal from DBSC, it is rather building on existing DBSC, and adds the binding specific details to the protocol. It is expected that the DBSC(E) proposal will be integrated into the DBSC proposal in the specification. In the high-level design, we have folded the DBSC proposal into the end to end flow, for and end-to-end illustration of cookie binding. Please read the [DBSC proposal](https://githuub.com/wicg/dbsc) before you proceed. + +## Terminology + +### **Browser**: + +In this document, "Browser" refers to a functionality in a web browser that is responsible for the DBSC protocol. This functionality will be implemented by Edge, Chrome (or their common engine), and other browsers that choose to implement DBSC/DBSC(E). + +### **Relying Party (RP)**: + +A web application that uses DBSC(E) protocol for cookie binding. + +### **Identity Provider (IdP)**: + +IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. + +### **Device Registration Client**: + +A process where the user registers the device with the IdP. This process is expected to be a once-in-a-lifetime operation. + +The device registration is a process that establishes a trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. + +A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. + +One device registration client can manage multiple devices on the same physical device. There also can be multiple device registration clients on the same device. The device registration client can be owned and supported by: + +- Operating system - the device gets registered when the OS is installed. +- Browser - the device gets registered when the browser is installed. +- Device management software (MDM provider) - the device gets registered when the MDM is enrolled. +- Third-party software vendor - the device gets registered according to the vendor rules. + +DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol amd is only concerned with the keys generated in a "clean room" state and the management of the generated keys to prove device binding. + +### **Local Key Helper**: + +**Local Key Helper** is an integral part of the the **Device Registration Client** , a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. + +From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) + +- _Public local key helper_ or _third party_: Can be accessed by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP through a well-defined public protocol. A third party local key helper has a special deployment mechanism. +- _Private local key helper_ or _well known_ : Can be specific to an IdP. Typically owned by the IdP and will have a private protocol to communicate with the IdP. Comes with either OS or built into the browser. It assumed that well-known key helpers are **trusted and enabled by default** in a browser. A browser knows how to activate a well-known key helper. + +The Local Key Helper is responsible for: + +- Generation of the binding key and producing binding statements (see below) +- Producing signatures with the binding key +- Cleanup of the binding key and its artifacts (when the user clears the browser session or the key is unused for a long time). + +#### Platform Examples: + +Please refer to the Windows Local Key Helper [here](./KeyGeneration.md#local-key-helper-on-windows) for an example of a Local Key Helper. + +Note: We plan to provide a reference implementation of the Local Key Helper for major platforms here in the future. + +### **Attestation Service**: + +A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. DBSC relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. + +## High-Level Design + +DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an existing policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. + +The high-level design is divided into two parts: + +1. Key generation and validation before the session starts (DBSC(E) is focused on this part). +2. DBSC protocol applied with the generated keys (DBSC is focused on this part). + +Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. We differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. + +### Device Registration (Pre-Session) + +Any enterprise user is expected to either use a device issued by their organization or register their personal device with the organization. The device registration is expected to be a once-in-a-lifetime operation, and the user is expected to perform this operation in a clean room environment. + +![DeviceRegistration](./DeviceRegistration.svg) + +### DBSC(E) Highlevel design + +As mentioned above, since an enterprise can choose to have its own Authentication service (IdP) determine the key generation, or have a third party generate the keys, we will cover both the use cases below. + +#### IDP Calls Public Local Key Helper + +Note: To map this design with the existing DBSC + +- Steps 1-16 specify the key generation process for a public local key helper +- Steps 17-29 are [DBSC](https://github.com/wicg/dbsc), added for completeness. + +![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) + +Highlights: + +1. **Session initiation with special headers (steps 1-4):** When a user starts a sign-in process, or initiates a session, the IdP will call the browser to generate a key for the session. It is expected that the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser, to indicate that the session is expected to be DBSC(E) compliant. + + - The `Sec-Session-GenerateKey` header contains the URL of the webpage(RP), the URL of the IdP (authentication service in most cases), a `nonce`, and any extra parameters that the IdP wants to send to the Local Key Helper. + - As the Local Key Helper is public, implying it can be different from the IdP, and potentially can be from a different vendor, `nonce` is essential to prevent the clock skew difference between the IdP and the Local Key Helper. The `nonce` is expected to be a random number generated by the IdP. + - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. + + TBD: May need more on `HelperId`. + +1. **Key and Binding Statement Generation (steps 5-9):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. + + - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. + - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the `binding statement`. It is intentionally left undefined, and can be customized. + - TBD define under which conditions: Local Key Helper can optionally signal the browser to cache the Binding Statement in the browser. This is to avoid repeated calls to the Local Key Helper for the same IdP. The browser can cache the Binding Statement for a certain time, and if the IdP requests a new key within that time, the browser can return the cached Binding Statement. + +1. **Sign In/Session Initiation (steps 10-14)**: The `Binding Statement`, with the `KeyId` is expected to be returned to the IdP witha new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement---generation-and-validation) the signature on the `Binding Statement`, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony and generate the auth tokens, that embed the thumbprint of the public key. The `KeyId` is expected to be returned to the Relying Party, and the IdP will use the `KeyId` to identify the key to be used for the session. diff --git a/README.md b/README.md index 575026c..783afb4 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,17 @@ This is the repository for Device Bound Session Credentials. You're welcome to [contribute](CONTRIBUTING.md)! ## Authors: + - [Kristian Monsen](kristianm@google.com), Google - [Arnar Birgisson](arnarb@google.com), Google ## Participate (to come) + - [Issue tracker](https://github.com/WICG/dbsc/issues) - [Discussion forum] ## Table of Contents + @@ -35,27 +38,33 @@ This is the repository for Device Bound Session Credentials. You're welcome to ## Introduction + Device Bound Session Credentials (DBSC) aims to reduce account hijacking caused by cookie theft. It does so by introducing a protocol and browser infrastructure to maintain and prove possession of a cryptographic key. The main challenge with cookies as an authentication mechanism is that they only lend themselves to bearer-token schemes. On desktop operating systems, application isolation is lacking and local malware can generally access anything that the browser itself can, and the browser must be able to access cookies. On the other hand, authentication with a private key allows for the use of system-level protection against key exfiltration. -DBSC offers an API for websites to control the lifetime of such keys, behind the abstraction of a session, and a protocol for periodically and automatically proving possession of those keys to the website's servers. There is a seperate key for each session, and it should not be possible to detect two different session keys are from one device. One of the key goals is to enable drop-in integration with common types of current auth infrastructure. By device-binding the private key and with appropriate intervals of the proofs, the browser can limit malware's ability to offload its abuse off of the user's device, significantly increasing the chance that either the browser or server can detect and mitigate cookie theft. +DBSC offers an API for websites to control the lifetime of such keys, behind the abstraction of a session, and a protocol for periodically and automatically proving possession of those keys to the website's servers. There is a seperate key for each session, and it should not be possible to detect two different session keys are from one device. One of the key goals is to enable drop-in integration with common types of current auth infrastructure. By device-binding the private key and with appropriate intervals of the proofs, the browser can limit malware's ability to offload its abuse off of the user's device, significantly increasing the chance that either the browser or server can detect and mitigate cookie theft. DBSC is bound to a device with cryptographic keys that cannot be exported from the user’s device under normal circumstances, this is called device binding in the rest of this document. DBSC provides an API that servers can use to create a session bound to a device, and this session can periodically be refreshed with an optional cryptographic proof the session is still bound to the original device. At sign-in, the API informs the browser that a session starts, which triggers the key creation. It then instructs the browser that any time a request is made while that session is active, the browser should ensure the presence of certain cookies. If these cookies are not present, DBSC will hold network requests while querying the configured endpoint for updated cookies. ### Goals + Reduce session theft by offering an alternative to long-lived cookie bearer tokens, that allows session authentication that is bound to the user's device. This makes the internet safer for users in that it is less likely their identity is abused, since malware is forced to act locally and thus becomes easier to detect and mitigate. At the same time the goal is to disrupt the cookie theft ecosystem and force it to adapt to new protections. ### Non-goals -DBSC will not prevent temporary access to the browser session while the attacker is resident on the user’s device. The private key should be stored as safe as modern desktop operating systems allow, preventing exfiltration of the session private key, but the signing capability will still be available for any program running as the user on the user’s device. + +DBSC will not prevent temporary access to the browser session while the attacker is resident on the user’s device. The private key should be stored as safe as modern desktop operating systems allow, preventing exfiltration of the session private key, but the signing capability will still be available for any program running as the user on the user’s device. ### What makes Device Bound Session Credentials different + DBSC is not the first proposal towards these goals, with a notable one being [Token Binding](https://en.wikipedia.org/wiki/Token_Binding). This proposal offers two important features that we believe makes it easier to deploy than previous proposals. DBSC provides application-level binding and browser initiated refreshes that can make sure devices are still bound to the original device. #### Application-level binding + For websites, device binding is most useful for securing authenticated sessions of users. DBSC allows websites to closely couple the setup of bound sessions with user sign-in mechanisms, makes session and key lifetimes explicit and controllable, and allows servers to design infrastructure that places verification of session credentials close to where user credentials (cookies) are processed in their infrastructure. Alternatives such as Token Binding gain much from e.g. integrating with TLS, but this can make integration harder in environments where e.g. TLS channel termination is far removed from the application logic behind user sign-in and session management. #### Browser-initiated refreshes + Other proposals have explored lower-level APIs for websites to create and use protected private keys, e.g. via WebCrypto or APIs similar to WebAuthn. While this works in theory, it puts a very large burden on the website to integrate with. In particular, since the cost of using protected keys is high, websites must design some infrastructure for collecting signatures only as often as needed. This means either high-touch integrations where the keys are only used to protect sensitive operations (like making a purchase), or a general ability to divert arbitrary requests to some endpoint that collects and verifies a signature and then retries the original request. The former doesn't protect the whole session and violates the principle of secure by default, while the latter can be prohibitively expensive for large websites built from multiple components by multiple teams, and may require non-trivial rewrites of web and RPC frameworks. @@ -63,65 +72,83 @@ This means either high-touch integrations where the keys are only used to protec DBSC instead allows a website to consolidate the session binding to a few points: At sign-in, it informs the browser that a session starts, which triggers the key creation. It then instructs the browser that any time a request is made while that session is active, the browser should ensure the presence of certain cookies. The browser does this by calling a dedicated refresh endpoint (specified by the website) whenever such cookies are needed, presenting that endpoint with a proof of possession of the private key. That endpoint in turn, using existing standard Set-Cookie headers, provides the browser with short-term cookies needed to make other requests. This provides two important benefits: + 1. Session binding logic is consolidated in the sign-in mechanism, and the new dedicated refresh endpoint. All other parts of the website continue to see cookies as their only authentication credentials, the only difference is that those cookies are short-lived. This allows deployment on complex existing setups, often with no changes to non-auth related endpoints. 1. If a browser is about to make a request where it has been instructed to include such a cookie, but doesn't have one, it defers making that request until the refresh is done. While this may add latency to such cases, it also means non-auth endpoints do not need to tolerate unauthenticated requests or respond with any kind of retry logic or redirects. This again allows deployment with minimal changes to existing endpoints. Note that the latency introduced by deferring of requests can be mitigated by the browser in other ways, which we discuss later. ### TPM considerations + DBSC depends on user devices having a way of signing challenges while protecting private keys from exfiltration by malware. This usually means the browser needs to have access to a Trusted Platform Module (TPM) on the device, which is not always available. TPMs also have a reputation for having high latency and not being dependable. Having a TPM is a requirement for installing Windows 11, and can be available on previous versions. All our studies are for public key cryptography using ECDSA_P256 algorithm. - Chrome has done studies to understand TPM availability to understand the feasibility of secure sessions. Current data shows about 60%, and currently growing, of Windows users would be offered protections. Studies have also been done on the current populations of TPMs, both for latency and for predictability. Currently the latency is (P50: 200ms/ P95: 600ms) for signing operations. The error rate is very low, currently around 0.001%. +Chrome has done studies to understand TPM availability to understand the feasibility of secure sessions. Current data shows about 60%, and currently growing, of Windows users would be offered protections. Studies have also been done on the current populations of TPMs, both for latency and for predictability. Currently the latency is (P50: 200ms/ P95: 600ms) for signing operations. The error rate is very low, currently around 0.001%. Based on this research, TPMs are widely available, with a latency and consistency that is acceptable for the proposed usage. ### Privacy considerations + An important high-level goal of this protocol is to introduce no additional surface for user tracking: implementing this API (for a browser) or enabling it (for a website) should not entail any significant user privacy tradeoffs. There are a few obvious considerations to ensure we achieve that goal: + - Lifetime of a session/key material: This should provide no additional client data storage (i.e., a pseudo-cookie). As such, we require that browsers MUST clear sessions and keys when clearing other site data (like cookies). - Cross-site/cross-origin data leakage: It should be impossible for a site to use this API to circumvent the same origin policy, 3P cookie policies, etc. (More on this below.) - Implementing this API should not meaningfully increase the entropy of heuristic device fingerprinting signals. (For example, it should not leak any stable TPM-based device identifier.) - This API—which allows background "pings" to the refresh endpoint when the user is not directly active—must not enable long-term tracking of a user when they have navigated away from the connected site. - Each session has a separate new key created, and it should not be possible to detect that different sessions are from the same device. +### Enterprise support + +While DBSC addresses a general problem of session hijacking, and can be applicable to any _browser_ consumer, it is possible to expand this protocol to better support enterprise use cases. By adding specifics to key generation and enabling the switch if there is a specific policy administered on the device, we can provide a more secure environment for enterprise users. This is the goal of DBSC(E), which is an extension to DBSC. The high-level design of DBSC(E) is described in the [DBSC(E) Overview](DBSC-E/Overview.md). + +DBSC-E provides a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. + ## High level overview + ![High level diagram](reg_and_refresh.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=A4QwTgLglgxloDsIAIBEAVACgWVckAzshAFCiSzwhJoBCYA9gO4ECmYehyARmeNHEQpUAZXYA3dpyJMScktwC0APiYAuZASgBzBIqgJkAMwA2zEkxXcNAJgAMd5EwD0W3awAm+wzAZJWSAA0yGCsBMB+bMgGMCYArh5hyAAWrCCJYMQMmhD8mqwwcaH5BFp+AHTIyAA6CAASaRkaqKIFimKlUH6KAEqs2lAEEGAg0H4abJ1+APpQiUhQRlDsALzl68EwySAmJgHarGvrLbUAFFs7ewgHIawAjnFQoR7GDJnAYFDio6zIANasACeyA+DAYRmQ4JBDFKYTKCAAlCQEAwIL8GJJMtYeIwWOxoggoNAfkRJvCeAYPAZtLVuIRPJDDKl0viPmEAjBWAoVBANKEHmEUDBQj9-kDQE8SBArHzWBAioZgHFuCZYGLAcjUejMTwNMK0mjkAApADq6Cczguu32XKUyl5-Ligs0OkMpvQUplt3lYDdZpdulGRVtKnUyEwAHkRObXAVg2SughXLlIAm-DUELUWgBvVA7bSoNTrcrBVAQQHAQuod2oYLFgC+2eLgVQAMBVYAPEqVbBpm3lKh6y1kJrDRj8WGhm9ft3VTB1cFBSAewRkiV4RYvfZHC5fAw-st8AgXmnDABJAAitIYHmBMXiiVJvmA6Ihe4PSVObx0BmQAGoQVGZIEVqWpmSaNBWmlABhMEPw0EA4ggZJpnfZYTgQbgb0BZpUFzU9ZnmaAlikIt1iHVASBWFYRAYABbX5oAYwDYQIYtqNHbV8WxOI2EyWJYD+IhVQQP5XneIDkFceiCj8NEkG5ZRsS2AoxMWSFPgGBA-1AZDbgeJ4kiwuJj2QNCuR2FBjNM8zkBRFBHUMjxFLDABxABRGMCBk3x-AUywlNsBwLV8+TSFYEwomsl5bMc55FOU1IYDUiE4oZcyiFYAAPQZSEs-THmeMy4MPNk2BoagXns5BsuAJyXI0DyvJ8uSAlIALsW3ELWoUiKojSmKSt+OjBi0a4NJqrK6vi+yuKxWUBSGZBEiMdgiqYZIoD2JxfgOIUhrY9YGuQJqpLYQpQlPZxQiMS61zAxp2FwsQYHaOFE0UM8PA0ABtU9kEvABdFpN0CgAWOwAEZQPqR6wGetoOnhRRoO2a1rlYCZ3pmOY2sWZYwCOEszLRq4DiJkHZshHVlJFQ13RC0mbUUh17idJa3D9D1pUC70FWNf1OaDUJjtO2MLvZKYkxuu6M3Ap7IJet6pd6MIIgQNhfvdYHKKp8dMjDb5VQ8UVQShKEIlYxNQesLrdyGo8T2x88r0w7CCViBIkgIZ9X2K-dliIL9NN-ADdOAmH5fhxW5RRoaEKQlDzIwrDb1w-DncIvGSI4Mjygozjqe4rGJfXRMaqGZdVVXTxgkuuIGNqb8tJ2ArBVFzyzpavz2q3YKXG85jQrakgAmcsegA) The general flow of a secure session is as follows: + 1. The website requests that the browser start a new session, providing an HTTP endpoint to negotiate registration parameters. 1. The browser creates a device-bound key pair, and calls the registration HTTP endpoint to set up the session and register the public key. 1. The server responds with a session identifier, and instructions on how to maintain the session. This is a (possibly empty) list of cookie names that the browser is expected to ensure exist, and their associated scope (origins+path). 1. At a later time the session is closed by either the server requesting to close the session or the user clears the keys by clearing site data. As long as that session is active, the browser performs the following refresh as needed: + 1. For any request within an applicable scope, the browser checks if the necessary cookies exist. If they exist, continue as normal. 1. If not, the browser defers such requests while performing the following. -1. The browser contacts the HTTP endpoint for the session, providing the session identifier and, if requested by the server, the necessary proof of possession of the associated private key. +1. The browser contacts the HTTP endpoint for the session, providing the session identifier and, if requested by the server, the necessary proof of possession of the associated private key. 1. If the server is satisfied with the proof, it uses regular Set-Cookie headers to establish the necessary cookies with an appropriate Max-Age. The response can also include an updated set of instructions, e.g. if the server wishes to change which cookies are subject to this logic. 1. If any requests were deferred in step 2, the browser now makes those requests including the updated set of cookies. 1. The browser may choose to proactively refresh cookies that are about to expire, if it predicts the user may soon need them. This is purely a latency optimization, and not required. There is an option for the server to opt out of the browser defering requests. If so it will instead: + 1. Sign any requests that would be defered, use the most recent challange. If there is not one, use the current timestamp. The browser may cache these signatures. 1. The server can respond with 401 if it wants the request signed with a new challenge. 1. The server can also serve challenges ahead of time on any response with the Sec-Session-Challenge header. 1. Once the browser get an instruction to set the missing cookie it will stop signing requests. -We do not reccomend this option for most deployments, but it is possibly for those that want to potentially save a network roundtrip in some circumstances. - + We do not reccomend this option for most deployments, but it is possibly for those that want to potentially save a network roundtrip in some circumstances. ### Start Session + ![Start session diagram](header_setup.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=MoUwTgbuC0B8CqBncACAggcxAOwC4C4VQBjaURRASwHttoAlEDSxXMAQ1xuwCgeMw1AK4AHFMlyjxICtxRgQARyEzcPJKkw5ccUJHD4ACgHlgAFRQB6ZMSELks2tdzswuB1Vo9s1XCBTUUGAoGsFaeAA0ekEAxADuABYgnPgA3gBEAEaU2AAmORjQ7AA2GPgAdJXpAL7qyGFYeAA8ZOBB+KA6AMLU1ADWlCCE7EK4CQD6xL0DIN6+-oGooeiNuFFt4PFJKRke3NCUudqUAGaDYBVVtTi5fD5+AUEh9SvaW8kE5J7YKCwoPnEUOxiFwoDwgA) #### Session Registration Header + The session start process is initiated by the server attaching a header with Sec-Session-Registration and appropriate parameters, this looks like: + ```http HTTP/1.1 200 OK Sec-Session-Registration: (RS256 ES256);challenge="nonce";path="StartSession" ``` + This is a structured header with a list of token arguments representing the allowed algorithms (possibilities are ES256 and RS256). The list have multiple string attributes, "path" is required describing the endpoint to use, "challenge" is to provide a nonce for the registration JWT. There is also an optional string attribute called authorization. There can be more than one registration on one response: + ```http HTTP/1.1 200 OK Sec-Session-Registration: (ES256 RS256);path="path1";challenge="nonce";authorization="authcode" @@ -131,6 +158,7 @@ Sec-Session-Registration: (ES256);path="path2";challenge="nonce" The authorization value is optional. If present, it will be sent to the registration endpoint in the `Authorization` header, and included in the registration JWT. This allows passing a bearer token that allows the server to link registration with some preceding sign in flow, as an alternative to the more traditional use of cookies. While this can also facilitate integration with some existing infrastructure, e.g. ones based on OAuth 2.0, this parameter is general and is not limited to the similarly named [Authorization Code](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1) in OAuth 2.0. #### Session Registration JWT + The browser responds to the session start by selecting a compatible signature algorithm and creating a device-bound private key for the new session. It then makes the following HTTP request (assuming the endpoint URL is https://auth.example.com/securesession): ```http @@ -143,7 +171,9 @@ Cookie: whatever_cookies_apply_to_this_request=value; Sec-Session-Response: registration JWT ``` + The JWT is signed with the newly created private key, and needs to contain the following values: + ```json // Header { @@ -161,6 +191,7 @@ The JWT is signed with the newly created private key, and needs to contain the f ``` #### Session Registration instructions JSON + If the request is properly authorized, the server establishes whatever state represents the session server-side, and returns the following response. ```http @@ -183,24 +214,30 @@ Set-Cookie: auth_cookie=abcdef0123; Domain=example.com; Max-Age=600; Secure; Htt "include_site": true, "defer_requests": true, // optional and true by default - "scope_specification" : [ - { "type": "include", "domain": "trusted.example.com", "path": "/only_trusted_path" }, + "scope_specification": [ + { + "type": "include", + "domain": "trusted.example.com", + "path": "/only_trusted_path" + }, { "type": "exclude", "domain": "untrusted.example.com", "path": "/" }, { "type": "exclude", "domain": "*.example.com", "path": "/static" } ] }, - "credentials": [{ - "type": "cookie", - // This specifies the exact cookie that this config applies to. Attributes - // match the cookie attributes in RFC 6265bis and are parsed similarly to - // a normal Set-Cookie line, using the same default values. - // These SHOULD be equivalent to the Set-Cookie line accompanying this - // response. - "name": "auth_cookie", - "attributes": "Domain=example.com; Path=/; Secure; SameSite=None" - // Attributes Max-Age, Expires and HttpOnly are ignored - }] + "credentials": [ + { + "type": "cookie", + // This specifies the exact cookie that this config applies to. Attributes + // match the cookie attributes in RFC 6265bis and are parsed similarly to + // a normal Set-Cookie line, using the same default values. + // These SHOULD be equivalent to the Set-Cookie line accompanying this + // response. + "name": "auth_cookie", + "attributes": "Domain=example.com; Path=/; Secure; SameSite=None" + // Attributes Max-Age, Expires and HttpOnly are ignored + } + ] } ``` @@ -213,11 +250,14 @@ Sec-Session-Challenge: challenge="nonce" Subsequently, as long as the browser considers this session "active", it follows the steps above, namely by refreshing the auth_cookie whenever needed, as covered in the next section. -Note if multiple cookies are required, the browser returns multiple Set-Cookie headers, with corresponding entries in the "credentials" array in the response body. +Note if multiple cookies are required, the browser returns multiple Set-Cookie headers, with corresponding entries in the "credentials" array in the response body. ### Maintaining a session + As long as the named cookie is not expired the browser will keep sending requests as normal. Once the cookie is expired the browser will hold all requests for the scope of the cookie, except where the server excluded the paths in the registration, while refreshing the cookie. This is where the browser driven protocol makes a difference, if not for this there would be potentially many requests without the required cookie. + #### Refresh procedure + ![Refresh diagram](refresh_v2.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=A4QwTgLglgxloDsIAICqBnApmZBBA5pkgFCiSzwhLIASmANgCbIBKmAjgK6boTqnhocRCgDK2AG7ZixBAHsImZHKk4M2PISQAacWFUBiAO4ALTCAgAucenRQ5CZDDlyA1lCUhOEEwH1nbh7ImAAewFBgmIzE6jgERBAAtAB8dEysHNy86JbIAOIAogAqwSEgALbA9JgAdM7lAPTAYAqYMIqMvpFcPBDE+C2cwBkAZpHoJshYtvYIMVhxWknJeqqWAAoA8qIlDVgwnOM8dg4NkWM8JsSr2CmxmgmWNEVF68gALAAMAIyyrcqqNALB46G5gYxmCzWNqJGwnBCJADCJhA9GqCEIlhq2Jq8w08SQKTBG22u32hx4x1mZ0wFwmf0UAI09wJEF0kmwEPMVgA3gAicQwWFUhyJNjoYAOLHYvkAX2uHLAd2BrKeLzeACZPp8GUoVMyVUt2fpOaZudCkoiXO5MLkvD5-NaPABeCSo7jEIjReSM-VqQ0JY2GM1QtjVEBYZBmdLdLJ8ZBGKA+JxOnjIc7jMzRFlLImK3KFEqhCpVWr1JotRTtKJdTK9YhAA) @@ -241,6 +281,7 @@ Sec-Session-Challenge: session_identifier="session_id",challenge="nonce" ``` The server can also serve challenges ahead of time attached to any response as an optimization, for example: + ```http HTTP/1.1 XXX Sec-Session-Challenge: session_identifier="session_id",challenge="nonce" @@ -254,11 +295,12 @@ Sec-Session-Response: refresh JWT ``` The JWT contains: + ```json { "jti": "nonce", "aud": "the URL to which the Sec-Session-Response will be sent", - "sub": "the session ID corresponding to the binding key", + "sub": "the session ID corresponding to the binding key" } ``` @@ -270,6 +312,7 @@ Content-Type: application/json Cache-Control: no-store Set-Cookie: auth_cookie=abcdef0123; Domain=example.com; Max-Age=600; Secure; HttpOnly; ``` + The contents is a json with the same specifications as during the registration. On receiving this response, the browser releases any requests that were deferred pending this refresh, including the new cookie. Note: @@ -279,16 +322,20 @@ The server may issue a different Max-Age, or scope for the short-term cookie. The server may set or update other cookies not subject to session refreshes in this response, as in any response. If instead the server decides to end the session it can respond with: + ```json { "session_identifier": "session_id", "continue": false - } +} ``` + In this case the browser should stop triggering any refreshes for this request, release any deferred requests without the short-term cookie, and clean up and delete the associated session state including the binding key. #### Ending a session + The session can end in several ways: + - The server can end the session during a refresh by answering with {“continue”: false} during a refresh - The server can at any time send a header with Clear-Site-Data: "storage" - The user can clear site data, which will locally clear cookies and any registered session keys for the site @@ -296,11 +343,15 @@ The session can end in several ways: It is important that the user is always in control and can delete the session keys if wanted. ## Interactions with other APIs + ### Login Status API + ### Interaction with Inactive Documents (BFCache, Prerendering) + When a session is ended for any reason, any inactive documents which had access to that session's credentials should be destroyed. This ensures that pages in BFCache or that are pre-rendering that contain information guarded by those credentials are not presented after the session has ended. ## Alternative JavaScript API for StartSession + ![Start session diagram](dbsc_js_v2.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=A4QwTgLglgxloDsIAIDqBTARsgCiA5ugFCiSzwhLICqAzumMgIKFInjRyIoDKDAbgyJF8YAPYBXYMh4QOyerVpQxCIhmx5CAWgB8dBs1YQAXMgQh+UfCAhiwAOnowJYdIuWqncyAAoHAQCURAhiEOjIYoKMBows6EgAxADuABbotiYAwm62EQDW6ACeyKBQYESxRgkQenxg0SY4API8ACrIAPTOru7ungjdPhAhYRFRhlXxSAA09dEp6ZkA3gBEmFAIACab+NogADb4JgEOqwC+RPMMelPGJgASbW04yABMAAwfo+GR0TT0OLGOYCBiLDKmPi1LJiMT5KDoMwgCQQVIAfRgsPh6AAvPxDhJiBpcAR0AAebR3GpmYDiAC2UHoDjctDEB0E-iCRASWx+43+xK06BBDTBaQhJj4ShUCGQjPMYmSyBAMGggiIQA) @@ -316,6 +367,7 @@ The API consists of a new interface, SecureSession, an instance of which is obta - A promise with a string containing the session ID (which may be empty) When called, this method must: + - Generate and store a new, secure cryptographic key pair - Call the "endpoint" + /startsession as specified below in Start Session (HTTP Request/Response) - Return a promise which @@ -323,9 +375,11 @@ When called, this method must: - If that call fails, throws an exception (which may indicate the HTTP status of the failed call) Requirements: + - The endpoint must have the same origin as the JavaScript. Below is an example of the API being used: + ```javascript let promise = navigator.secureSession.start({ // Session start options From 5beef49a3c501984a7d763a8e3d7229fc8a5f384 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 9 Aug 2024 12:33:55 -0700 Subject: [PATCH 02/47] Update IDP with Public Local Key Helper Flow --- DBSC-E/Overview.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/DBSC-E/Overview.md b/DBSC-E/Overview.md index 92cd1a4..cb15c6e 100644 --- a/DBSC-E/Overview.md +++ b/DBSC-E/Overview.md @@ -132,15 +132,17 @@ Highlights: 1. **Session initiation with special headers (steps 1-4):** When a user starts a sign-in process, or initiates a session, the IdP will call the browser to generate a key for the session. It is expected that the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser, to indicate that the session is expected to be DBSC(E) compliant. - The `Sec-Session-GenerateKey` header contains the URL of the webpage(RP), the URL of the IdP (authentication service in most cases), a `nonce`, and any extra parameters that the IdP wants to send to the Local Key Helper. - - As the Local Key Helper is public, implying it can be different from the IdP, and potentially can be from a different vendor, `nonce` is essential to prevent the clock skew difference between the IdP and the Local Key Helper. The `nonce` is expected to be a random number generated by the IdP. + - As the Local Key Helper is public or thirdparty, and potentially can be from a different vendor, `nonce` is essential to prevent the clock skew difference between the IdP and the Local Key Helper. The `nonce` is expected to be a random number generated by the IdP. - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. - TBD: May need more on `HelperId`. - 1. **Key and Binding Statement Generation (steps 5-9):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. - - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. + - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](./KeyGeneration.md#binding-statement). - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the `binding statement`. It is intentionally left undefined, and can be customized. - TBD define under which conditions: Local Key Helper can optionally signal the browser to cache the Binding Statement in the browser. This is to avoid repeated calls to the Local Key Helper for the same IdP. The browser can cache the Binding Statement for a certain time, and if the IdP requests a new key within that time, the browser can return the cached Binding Statement. 1. **Sign In/Session Initiation (steps 10-14)**: The `Binding Statement`, with the `KeyId` is expected to be returned to the IdP witha new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement---generation-and-validation) the signature on the `Binding Statement`, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony and generate the auth tokens, that embed the thumbprint of the public key. The `KeyId` is expected to be returned to the Relying Party, and the IdP will use the `KeyId` to identify the key to be used for the session. + +1. **SignIn Succeeds with binding (steps 15-16)**: The IdP will return the auth tokens to the RP,with the thumbprint of the public key embedded in the token. + +1. **DBSC Protocol (steps 17-29)**: The DBSC protocol is applied with the generated keys. RP can now initiate a session with the acquired tokens and the browser generates a JWT with the Local Key Helper which embeds the binding info. The signed JWT is now returned along with the tokens to the RP, which is inturn embedded in any cookies generated and stored by the RT, binding them. All future transactions including a refresh session now will look for the binding info in the cookies, hence securing them against session hijacking. From d8bdefaf90472f5c2a4c4ddbd33aa2e0086154eb Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 9 Aug 2024 13:10:02 -0700 Subject: [PATCH 03/47] Update IDP=RP case --- DBSC-E/Overview.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/DBSC-E/Overview.md b/DBSC-E/Overview.md index cb15c6e..63a9fbd 100644 --- a/DBSC-E/Overview.md +++ b/DBSC-E/Overview.md @@ -120,7 +120,7 @@ As mentioned above, since an enterprise can choose to have its own Authenticatio #### IDP Calls Public Local Key Helper -Note: To map this design with the existing DBSC +For easy mapping with the existing DBSC proposal, please note: - Steps 1-16 specify the key generation process for a public local key helper - Steps 17-29 are [DBSC](https://github.com/wicg/dbsc), added for completeness. @@ -145,4 +145,16 @@ Highlights: 1. **SignIn Succeeds with binding (steps 15-16)**: The IdP will return the auth tokens to the RP,with the thumbprint of the public key embedded in the token. -1. **DBSC Protocol (steps 17-29)**: The DBSC protocol is applied with the generated keys. RP can now initiate a session with the acquired tokens and the browser generates a JWT with the Local Key Helper which embeds the binding info. The signed JWT is now returned along with the tokens to the RP, which is inturn embedded in any cookies generated and stored by the RT, binding them. All future transactions including a refresh session now will look for the binding info in the cookies, hence securing them against session hijacking. +1. **DBSC Protocol (steps 17-29)**: Once the sign in completes, with the intended IDP/Local Key Helper, the DBSC protocol is applied with the generated keys. RP can now initiate a session with the acquired tokens and the browser generates a JWT with the Local Key Helper which embeds the binding info. The signed JWT is now returned along with the tokens to the RP, which is inturn embedded in any cookies generated and stored by the RT, binding them. All future transactions including a refresh session now will look for the binding info in the cookies, hence securing them against session hijacking. + +#### IDP is RP and Calls Public Local Key Helper + +In some cases, we see the web service assuming dual roles of both the resource server and the authentication server (think of github client authenticated by github service). In such cases, DBSC(E) can be optimized to simplify the protocol and align with the perf goals for specific services. + +![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) + +Highlights (only the difference with IDPCallsPublicLocalKeyHelper): + +1. **Session establishment (Steps 1-10)**: Since RP is IDP, the session initiation with the headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` is optimized and initiated by the RP itself. +1. **Token Issuance (Steps 11-13)**: The tokens once generated, can be delivered to RP directly through an API instead of a header based response. +1. **DBSC Protocol (Steps 14-26)**: The `startSession` and `refreshSession` protocol remains the same as in the original DBSC proposal. From 421c8bfcb0be8560f8b24d70069e73b17db66d96 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 9 Aug 2024 13:25:11 -0700 Subject: [PATCH 04/47] Update IDP with Private Local Key Helper --- DBSC-E/Overview.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/DBSC-E/Overview.md b/DBSC-E/Overview.md index 63a9fbd..cf7bfa2 100644 --- a/DBSC-E/Overview.md +++ b/DBSC-E/Overview.md @@ -158,3 +158,9 @@ Highlights (only the difference with IDPCallsPublicLocalKeyHelper): 1. **Session establishment (Steps 1-10)**: Since RP is IDP, the session initiation with the headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` is optimized and initiated by the RP itself. 1. **Token Issuance (Steps 11-13)**: The tokens once generated, can be delivered to RP directly through an API instead of a header based response. 1. **DBSC Protocol (Steps 14-26)**: The `startSession` and `refreshSession` protocol remains the same as in the original DBSC proposal. + +#### IDP Calls Private Local Key Helper + +A special case is for enterprises that already have `well-known` Local Key Helpers, which are expected to be trusted and enabled by default in a browser. Here, since the browser can trust a given IDP (based on the URL and a policy mapping) and can trust the IDP to invoke the appropriate Local Key Helper (refer [Local key helper on Windows](./KeyGeneration.md#local-key-helper-on-windows)), there are a few optimizations that can be made to the protocol, in skipping the nonce and reducing the number of round trips between the IDP and the Local Key Helper. + +![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) From aca33c34f3a71a1b2c4d93b2c29df427257308da Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 9 Aug 2024 13:39:58 -0700 Subject: [PATCH 05/47] Update TOC --- DBSC-E/Overview.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/DBSC-E/Overview.md b/DBSC-E/Overview.md index cf7bfa2..c7dd1fc 100644 --- a/DBSC-E/Overview.md +++ b/DBSC-E/Overview.md @@ -1,3 +1,31 @@ + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Device Bound Session Credentials for Enterprise - explainer](#device-bound-session-credentials-for-enterprise---explainer) + - [Authors](#authors) + - [Contributors](#contributors) + - [Participate (to come)](#participate-to-come) + - [Overview](#overview) + - [Why DBSC(E)?](#why-dbsce) + - [How does it integrate with DBSC?](#how-does-it-integrate-with-dbsc) + - [Terminology](#terminology) + - [**Browser**:](#browser) + - [**Relying Party (RP)**:](#relying-party-rp) + - [**Identity Provider (IdP)**:](#identity-provider-idp) + - [**Device Registration Client**:](#device-registration-client) + - [**Local Key Helper**:](#local-key-helper) + - [Platform Examples:](#platform-examples) + - [**Attestation Service**:](#attestation-service) + - [High-Level Design](#high-level-design) + - [Device Registration (Pre-Session)](#device-registration-pre-session) + - [DBSC(E) Highlevel design](#dbsce-highlevel-design) + - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) + - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) + - [IDP Calls Private Local Key Helper](#idp-calls-private-local-key-helper) + + + # Device Bound Session Credentials for Enterprise - explainer This is the repository for Device Bound Session Credentials for Enterprise. You're welcome to From 06cc8d0507b308d7404c82430c4e866e0bad6413 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 9 Aug 2024 14:17:43 -0700 Subject: [PATCH 06/47] Update folder name --- {DBSC-E => DBSC(E)}/DeviceRegistration.svg | 0 {DBSC-E => DBSC(E)}/DeviceRegistration.txt | 0 .../IDPCallsPrivateLocalKeyHelper.svg | 0 .../IDPCallsPrivateLocalKeyHelper.txt | 0 .../IDPCallsPublicLocalKeyHelper.svg | 0 .../IDPCallsPublicLocalKeyHelper.txt | 0 .../IDPSameAsRP-CallsPublicLocalKeyHelper.svg | 0 .../IDPSameAsRP-CallsPublicLocalKeyHelper.txt | 0 {DBSC-E => DBSC(E)}/KeyGeneration.md | 0 {DBSC-E => DBSC(E)}/Overview.md | 15 ++++++++------- README.md | 4 ++-- 11 files changed, 10 insertions(+), 9 deletions(-) rename {DBSC-E => DBSC(E)}/DeviceRegistration.svg (100%) rename {DBSC-E => DBSC(E)}/DeviceRegistration.txt (100%) rename {DBSC-E => DBSC(E)}/IDPCallsPrivateLocalKeyHelper.svg (100%) rename {DBSC-E => DBSC(E)}/IDPCallsPrivateLocalKeyHelper.txt (100%) rename {DBSC-E => DBSC(E)}/IDPCallsPublicLocalKeyHelper.svg (100%) rename {DBSC-E => DBSC(E)}/IDPCallsPublicLocalKeyHelper.txt (100%) rename {DBSC-E => DBSC(E)}/IDPSameAsRP-CallsPublicLocalKeyHelper.svg (100%) rename {DBSC-E => DBSC(E)}/IDPSameAsRP-CallsPublicLocalKeyHelper.txt (100%) rename {DBSC-E => DBSC(E)}/KeyGeneration.md (100%) rename {DBSC-E => DBSC(E)}/Overview.md (98%) diff --git a/DBSC-E/DeviceRegistration.svg b/DBSC(E)/DeviceRegistration.svg similarity index 100% rename from DBSC-E/DeviceRegistration.svg rename to DBSC(E)/DeviceRegistration.svg diff --git a/DBSC-E/DeviceRegistration.txt b/DBSC(E)/DeviceRegistration.txt similarity index 100% rename from DBSC-E/DeviceRegistration.txt rename to DBSC(E)/DeviceRegistration.txt diff --git a/DBSC-E/IDPCallsPrivateLocalKeyHelper.svg b/DBSC(E)/IDPCallsPrivateLocalKeyHelper.svg similarity index 100% rename from DBSC-E/IDPCallsPrivateLocalKeyHelper.svg rename to DBSC(E)/IDPCallsPrivateLocalKeyHelper.svg diff --git a/DBSC-E/IDPCallsPrivateLocalKeyHelper.txt b/DBSC(E)/IDPCallsPrivateLocalKeyHelper.txt similarity index 100% rename from DBSC-E/IDPCallsPrivateLocalKeyHelper.txt rename to DBSC(E)/IDPCallsPrivateLocalKeyHelper.txt diff --git a/DBSC-E/IDPCallsPublicLocalKeyHelper.svg b/DBSC(E)/IDPCallsPublicLocalKeyHelper.svg similarity index 100% rename from DBSC-E/IDPCallsPublicLocalKeyHelper.svg rename to DBSC(E)/IDPCallsPublicLocalKeyHelper.svg diff --git a/DBSC-E/IDPCallsPublicLocalKeyHelper.txt b/DBSC(E)/IDPCallsPublicLocalKeyHelper.txt similarity index 100% rename from DBSC-E/IDPCallsPublicLocalKeyHelper.txt rename to DBSC(E)/IDPCallsPublicLocalKeyHelper.txt diff --git a/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.svg b/DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.svg similarity index 100% rename from DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.svg rename to DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.svg diff --git a/DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.txt b/DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.txt similarity index 100% rename from DBSC-E/IDPSameAsRP-CallsPublicLocalKeyHelper.txt rename to DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.txt diff --git a/DBSC-E/KeyGeneration.md b/DBSC(E)/KeyGeneration.md similarity index 100% rename from DBSC-E/KeyGeneration.md rename to DBSC(E)/KeyGeneration.md diff --git a/DBSC-E/Overview.md b/DBSC(E)/Overview.md similarity index 98% rename from DBSC-E/Overview.md rename to DBSC(E)/Overview.md index c7dd1fc..2eb20be 100644 --- a/DBSC-E/Overview.md +++ b/DBSC(E)/Overview.md @@ -1,6 +1,7 @@ -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +**Table of Contents** _generated with [DocToc](https://github.com/thlorenz/doctoc)_ - [Device Bound Session Credentials for Enterprise - explainer](#device-bound-session-credentials-for-enterprise---explainer) - [Authors](#authors) @@ -71,19 +72,19 @@ DBSC(E) is not intended to be a separate proposal from DBSC, it is rather buildi ## Terminology -### **Browser**: +### Browser: In this document, "Browser" refers to a functionality in a web browser that is responsible for the DBSC protocol. This functionality will be implemented by Edge, Chrome (or their common engine), and other browsers that choose to implement DBSC/DBSC(E). -### **Relying Party (RP)**: +### Relying Party (RP): A web application that uses DBSC(E) protocol for cookie binding. -### **Identity Provider (IdP)**: +### Identity Provider (IdP): IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. -### **Device Registration Client**: +### Device Registration Client: A process where the user registers the device with the IdP. This process is expected to be a once-in-a-lifetime operation. @@ -100,7 +101,7 @@ One device registration client can manage multiple devices on the same physical DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol amd is only concerned with the keys generated in a "clean room" state and the management of the generated keys to prove device binding. -### **Local Key Helper**: +### Local Key Helper: **Local Key Helper** is an integral part of the the **Device Registration Client** , a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. @@ -121,7 +122,7 @@ Please refer to the Windows Local Key Helper [here](./KeyGeneration.md#local-key Note: We plan to provide a reference implementation of the Local Key Helper for major platforms here in the future. -### **Attestation Service**: +### Attestation Service: A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. DBSC relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. diff --git a/README.md b/README.md index 783afb4..e1ab325 100644 --- a/README.md +++ b/README.md @@ -100,9 +100,9 @@ There are a few obvious considerations to ensure we achieve that goal: ### Enterprise support -While DBSC addresses a general problem of session hijacking, and can be applicable to any _browser_ consumer, it is possible to expand this protocol to better support enterprise use cases. By adding specifics to key generation and enabling the switch if there is a specific policy administered on the device, we can provide a more secure environment for enterprise users. This is the goal of DBSC(E), which is an extension to DBSC. The high-level design of DBSC(E) is described in the [DBSC(E) Overview](DBSC-E/Overview.md). +While DBSC addresses a general problem of session hijacking, and can be applicable to any _browser_ consumer, it is possible to expand this protocol to better support enterprise use cases. By adding specifics to key generation and enabling the switch if there is a specific policy administered on the device, we can provide a more secure environment for enterprise users. This is the goal of DBSC(E), which is an extension to DBSC. The high-level design of DBSC(E) is described in the [DBSC(E) Overview](). -DBSC-E provides a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. +DBSC(E) removes the vulnerability DBSC has, where a malware, if already present in the device during the key generation, can take over the session even if it is eventually bound to the device. By assuring a clean state key generation and introducing device key chaining, DBSC(E) can mitigate this vulnerability: More details about the importance of DBSC are here: [Why DBSC(E)?](). ## High level overview From 5c7a61406319ced453fb66f02c826c31b9e88141 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 12 Aug 2024 11:28:52 -0700 Subject: [PATCH 07/47] Update highlevel design --- DBSC(E)/DBSC(E).svg | 1 + DBSC(E)/DBSC(E).txt | 44 ++++++++++++++++++++++++++++++++++++++++++++ DBSC(E)/Overview.md | 42 ++++++++++++++++++++++++------------------ 3 files changed, 69 insertions(+), 18 deletions(-) create mode 100644 DBSC(E)/DBSC(E).svg create mode 100644 DBSC(E)/DBSC(E).txt diff --git a/DBSC(E)/DBSC(E).svg b/DBSC(E)/DBSC(E).svg new file mode 100644 index 0000000..3a5910c --- /dev/null +++ b/DBSC(E)/DBSC(E).svg @@ -0,0 +1 @@ +participant%20%22TPM%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%22%20as%20w%0A%0A%0A%0Ab-%3Ew%3A%20sign-in%20flow%20%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%20%5Cn%5Cn%3Csize%3A10%3E%3Ccolor%3A%23blue%3ESec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%20%5Cn%3Ccolor%3A%23blue%3Eevaluate%20policy%20for%20%5Cn(HelperId...)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%2C%20authUrl%3F%2C%20challenge%2C%20extraParams%3F)%0Anote%20over%20b%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Eb%3A%20return%20public%20key%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(pubKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2Cpublic%20key%2C%20extraParams%3F..)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendTPMBrowserServersign-in flow 200 w/signed-in content, response includes header to start secure session.  Header: Sec-Session-Registration: session_identifier=..., challenge=...(challenge required for private key proof of possession) Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimebrowser initiates session bindingbased on header presence evaluate policy for (HelperId...)request create keypair (serverUrl, authUrl?, challenge, extraParams?)For Enterprise, this call will be platformbased & generates device attestationreturn public key &BindingStatement{challenge, thumbprint(pubKey), extraClaims?..}create JWT w/challengerequest sign JWT  (challenge,public key, extraParams?..)return JWT signaturePOST /securesession/startsession {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish session200 w/cookie and session IDbody includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookieGET /somecontent200 w/contentcheck if required cookies existGET /somecontent200 w/contentrequest deferred while we get cookies...GET /securesession/refresh header: Sec-Session-Id: [session ID]401Header: Sec-Session-Challenge: session_identifier=..., challenge=...create JWT w/challengerequest sign JWTreturn JWT signatureGET /securesession/refresh header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session IDbody includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent200 w/some contentalt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file diff --git a/DBSC(E)/DBSC(E).txt b/DBSC(E)/DBSC(E).txt new file mode 100644 index 0000000..6920b2d --- /dev/null +++ b/DBSC(E)/DBSC(E).txt @@ -0,0 +1,44 @@ +participant "TPM" as t +participant "Browser" as b +participant "Server" as w + + + +b->w: sign-in flow +w->b: 200 w/signed-in content, response includes header to start secure session. \nHeader: ""Sec-Session-Registration: session_identifier=..., challenge=...""\n(challenge required for private key proof of possession) \n\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2], HelperCacheTime +note over b: browser initiates session binding\nbased on header presence \nevaluate policy for \n(HelperId...) +b->t: request create keypair \n(serverUrl, authUrl?, challenge, extraParams?) +note over b: For Enterprise, this call will be platform\nbased & generates device attestation +t->b: return public key &\nBindingStatement\n{challenge, thumbprint(pubKey), extraClaims?..} +note over b: create JWT w/challenge +b->t:request sign JWT \n(challenge,public key, extraParams?..) +t->b: return JWT signature +b->w: POST /securesession/startsession \n\n""{"alg":..., "typ":"JWT", ...}{...,"key":""}"" +note over w: store public key, establish session +w->b: 200 w/cookie and session ID\nbody includes scope of cookies (origin + path)\n\nheader: ""Set-Cookie: auth_cookie""\nbody: ""{"session_identifier":...}"" +==Some time passes...== +note over b: user clicks link for path /somecontent +b->b: check if origin+path requires bound cookie +alt bound cookie not required +b->w: GET /somecontent +w->b: 200 w/content +else bound cookie required +b->b: check if required cookies exist +alt required cookie present and not expired +b->w: GET /somecontent +w->b: 200 w/content +else required cookie missing or expired +note over b: request deferred while we get cookies... +b->w: GET /securesession/refresh \nheader: ""Sec-Session-Id: [session ID]"" +w->b:401\n\nHeader: ""Sec-Session-Challenge: session_identifier=..., challenge=..."" +note over b: create JWT w/challenge +b->t:request sign JWT +t->b: return JWT signature +b->w: GET /securesession/refresh \nheader: ""Sec-Session-Response: [JWT]"" +note over w: validate proof of possesion +w->b:200 w/cookie and session ID\nbody includes scope of cookies (origin + path)\n\nheader: ""Set-Cookie: auth_cookie""\nbody: ""{"session_identifier":...}"" +note over b: secure session established, resume\noriginal request +b->w: GET /somecontent +w->b: 200 w/some content +end +end \ No newline at end of file diff --git a/DBSC(E)/Overview.md b/DBSC(E)/Overview.md index 2eb20be..70e87ec 100644 --- a/DBSC(E)/Overview.md +++ b/DBSC(E)/Overview.md @@ -70,21 +70,38 @@ DBSC(E) aims to mitigate this risk by introducing the concept of credential gene DBSC(E) is not intended to be a separate proposal from DBSC, it is rather building on existing DBSC, and adds the binding specific details to the protocol. It is expected that the DBSC(E) proposal will be integrated into the DBSC proposal in the specification. In the high-level design, we have folded the DBSC proposal into the end to end flow, for and end-to-end illustration of cookie binding. Please read the [DBSC proposal](https://githuub.com/wicg/dbsc) before you proceed. +## High-Level Design + +DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an existing policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. + +The high-level design is divided into two parts: + +1. Key generation and validation before the session starts (DBSC(E) is focused on this part). +2. DBSC protocol applied with the generated keys (DBSC is focused on this part). + +Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, ee differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. + +DBSC(E) Introduction (in contrast with DBSC): + +![DBSC(E) Highlevel Design](<./DBSC(E).svg>) + +Before we get into the specifics, we will introduce the terminology and design specifics for the key generation and validation below. + ## Terminology -### Browser: +### Browser In this document, "Browser" refers to a functionality in a web browser that is responsible for the DBSC protocol. This functionality will be implemented by Edge, Chrome (or their common engine), and other browsers that choose to implement DBSC/DBSC(E). -### Relying Party (RP): +### Relying Party (RP) A web application that uses DBSC(E) protocol for cookie binding. -### Identity Provider (IdP): +### Identity Provider (IdP) IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. -### Device Registration Client: +### Device Registration Client A process where the user registers the device with the IdP. This process is expected to be a once-in-a-lifetime operation. @@ -101,7 +118,7 @@ One device registration client can manage multiple devices on the same physical DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol amd is only concerned with the keys generated in a "clean room" state and the management of the generated keys to prove device binding. -### Local Key Helper: +### Local Key Helper **Local Key Helper** is an integral part of the the **Device Registration Client** , a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. @@ -126,26 +143,15 @@ Note: We plan to provide a reference implementation of the Local Key Helper for A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. DBSC relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. -## High-Level Design - -DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an existing policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. - -The high-level design is divided into two parts: - -1. Key generation and validation before the session starts (DBSC(E) is focused on this part). -2. DBSC protocol applied with the generated keys (DBSC is focused on this part). - -Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. We differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. - ### Device Registration (Pre-Session) Any enterprise user is expected to either use a device issued by their organization or register their personal device with the organization. The device registration is expected to be a once-in-a-lifetime operation, and the user is expected to perform this operation in a clean room environment. ![DeviceRegistration](./DeviceRegistration.svg) -### DBSC(E) Highlevel design +### DBSC(E) use cases -As mentioned above, since an enterprise can choose to have its own Authentication service (IdP) determine the key generation, or have a third party generate the keys, we will cover both the use cases below. +This section expands on the generic design to address different enterprise use cases: #### IDP Calls Public Local Key Helper From e170890eb0f49cfe322a7f2d31a261c9799585c0 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 12 Aug 2024 12:03:43 -0700 Subject: [PATCH 08/47] Update name --- DBSC(E)/Overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DBSC(E)/Overview.md b/DBSC(E)/Overview.md index 70e87ec..dbdba5f 100644 --- a/DBSC(E)/Overview.md +++ b/DBSC(E)/Overview.md @@ -35,7 +35,7 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' ## Authors - [Sameera Gajjarapu](sameera.gajjarapu@microsoft.com), Microsoft -- [Alexander Tokerev](alextok@microsoft.com), Microsoft +- [Alexander Tokarev](alextok@microsoft.com), Microsoft ## Contributors From 2b8b2467391e7607d27f6b9990ab88fd88403c59 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 12 Aug 2024 12:21:11 -0700 Subject: [PATCH 09/47] Update folder name --- {DBSC(E) => DBSCE}/DBSC(E).svg | 0 {DBSC(E) => DBSCE}/DBSC(E).txt | 0 {DBSC(E) => DBSCE}/DeviceRegistration.svg | 0 {DBSC(E) => DBSCE}/DeviceRegistration.txt | 0 .../IDPCallsPrivateLocalKeyHelper.svg | 0 .../IDPCallsPrivateLocalKeyHelper.txt | 0 .../IDPCallsPublicLocalKeyHelper.svg | 0 .../IDPCallsPublicLocalKeyHelper.txt | 0 .../IDPSameAsRP-CallsPublicLocalKeyHelper.svg | 0 .../IDPSameAsRP-CallsPublicLocalKeyHelper.txt | 0 {DBSC(E) => DBSCE}/KeyGeneration.md | 0 {DBSC(E) => DBSCE}/Overview.md | 42 +++++++++---------- 12 files changed, 21 insertions(+), 21 deletions(-) rename {DBSC(E) => DBSCE}/DBSC(E).svg (100%) rename {DBSC(E) => DBSCE}/DBSC(E).txt (100%) rename {DBSC(E) => DBSCE}/DeviceRegistration.svg (100%) rename {DBSC(E) => DBSCE}/DeviceRegistration.txt (100%) rename {DBSC(E) => DBSCE}/IDPCallsPrivateLocalKeyHelper.svg (100%) rename {DBSC(E) => DBSCE}/IDPCallsPrivateLocalKeyHelper.txt (100%) rename {DBSC(E) => DBSCE}/IDPCallsPublicLocalKeyHelper.svg (100%) rename {DBSC(E) => DBSCE}/IDPCallsPublicLocalKeyHelper.txt (100%) rename {DBSC(E) => DBSCE}/IDPSameAsRP-CallsPublicLocalKeyHelper.svg (100%) rename {DBSC(E) => DBSCE}/IDPSameAsRP-CallsPublicLocalKeyHelper.txt (100%) rename {DBSC(E) => DBSCE}/KeyGeneration.md (100%) rename {DBSC(E) => DBSCE}/Overview.md (88%) diff --git a/DBSC(E)/DBSC(E).svg b/DBSCE/DBSC(E).svg similarity index 100% rename from DBSC(E)/DBSC(E).svg rename to DBSCE/DBSC(E).svg diff --git a/DBSC(E)/DBSC(E).txt b/DBSCE/DBSC(E).txt similarity index 100% rename from DBSC(E)/DBSC(E).txt rename to DBSCE/DBSC(E).txt diff --git a/DBSC(E)/DeviceRegistration.svg b/DBSCE/DeviceRegistration.svg similarity index 100% rename from DBSC(E)/DeviceRegistration.svg rename to DBSCE/DeviceRegistration.svg diff --git a/DBSC(E)/DeviceRegistration.txt b/DBSCE/DeviceRegistration.txt similarity index 100% rename from DBSC(E)/DeviceRegistration.txt rename to DBSCE/DeviceRegistration.txt diff --git a/DBSC(E)/IDPCallsPrivateLocalKeyHelper.svg b/DBSCE/IDPCallsPrivateLocalKeyHelper.svg similarity index 100% rename from DBSC(E)/IDPCallsPrivateLocalKeyHelper.svg rename to DBSCE/IDPCallsPrivateLocalKeyHelper.svg diff --git a/DBSC(E)/IDPCallsPrivateLocalKeyHelper.txt b/DBSCE/IDPCallsPrivateLocalKeyHelper.txt similarity index 100% rename from DBSC(E)/IDPCallsPrivateLocalKeyHelper.txt rename to DBSCE/IDPCallsPrivateLocalKeyHelper.txt diff --git a/DBSC(E)/IDPCallsPublicLocalKeyHelper.svg b/DBSCE/IDPCallsPublicLocalKeyHelper.svg similarity index 100% rename from DBSC(E)/IDPCallsPublicLocalKeyHelper.svg rename to DBSCE/IDPCallsPublicLocalKeyHelper.svg diff --git a/DBSC(E)/IDPCallsPublicLocalKeyHelper.txt b/DBSCE/IDPCallsPublicLocalKeyHelper.txt similarity index 100% rename from DBSC(E)/IDPCallsPublicLocalKeyHelper.txt rename to DBSCE/IDPCallsPublicLocalKeyHelper.txt diff --git a/DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.svg b/DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.svg similarity index 100% rename from DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.svg rename to DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.svg diff --git a/DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.txt b/DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.txt similarity index 100% rename from DBSC(E)/IDPSameAsRP-CallsPublicLocalKeyHelper.txt rename to DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.txt diff --git a/DBSC(E)/KeyGeneration.md b/DBSCE/KeyGeneration.md similarity index 100% rename from DBSC(E)/KeyGeneration.md rename to DBSCE/KeyGeneration.md diff --git a/DBSC(E)/Overview.md b/DBSCE/Overview.md similarity index 88% rename from DBSC(E)/Overview.md rename to DBSCE/Overview.md index dbdba5f..c28396f 100644 --- a/DBSC(E)/Overview.md +++ b/DBSCE/Overview.md @@ -1,26 +1,24 @@ -**Table of Contents** _generated with [DocToc](https://github.com/thlorenz/doctoc)_ - - [Device Bound Session Credentials for Enterprise - explainer](#device-bound-session-credentials-for-enterprise---explainer) - [Authors](#authors) - [Contributors](#contributors) - - [Participate (to come)](#participate-to-come) + - [Participate (TBD links)](#participate-tbd-links) - [Overview](#overview) - [Why DBSC(E)?](#why-dbsce) - [How does it integrate with DBSC?](#how-does-it-integrate-with-dbsc) + - [High-Level Design](#high-level-design) - [Terminology](#terminology) - - [**Browser**:](#browser) - - [**Relying Party (RP)**:](#relying-party-rp) - - [**Identity Provider (IdP)**:](#identity-provider-idp) - - [**Device Registration Client**:](#device-registration-client) - - [**Local Key Helper**:](#local-key-helper) + - [Browser](#browser) + - [Relying Party (RP)](#relying-party-rp) + - [Identity Provider (IdP)](#identity-provider-idp) + - [Device Registration Client](#device-registration-client) + - [Local Key Helper](#local-key-helper) - [Platform Examples:](#platform-examples) - - [**Attestation Service**:](#attestation-service) - - [High-Level Design](#high-level-design) + - [Attestation Service:](#attestation-service) - [Device Registration (Pre-Session)](#device-registration-pre-session) - - [DBSC(E) Highlevel design](#dbsce-highlevel-design) + - [DBSC(E) use cases](#dbsce-use-cases) - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) - [IDP Calls Private Local Key Helper](#idp-calls-private-local-key-helper) @@ -51,14 +49,14 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' - [Kai Song](), Microsoft - [Amit Gusain](), Microsoft -## Participate (to come) +## Participate (TBD links) - [Issue tracker]() - [Discussion forum] ## Overview -Device Bound Session Credentials for Enterprise - DBSC(E), is not a separate proposal but an addition to existing [DBSC](https://github.com/wicg/dbsc) proposal to enhance the key generation mechanism and security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. +Device Bound Session Credentials for Enterprise - DBSC(E), is not a separate protocol but an addition to the existing [DBSC](https://github.com/wicg/dbsc) proposal to enhance the key generation mechanism and security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. ## Why DBSC(E)? @@ -68,7 +66,7 @@ DBSC(E) aims to mitigate this risk by introducing the concept of credential gene ## How does it integrate with DBSC? -DBSC(E) is not intended to be a separate proposal from DBSC, it is rather building on existing DBSC, and adds the binding specific details to the protocol. It is expected that the DBSC(E) proposal will be integrated into the DBSC proposal in the specification. In the high-level design, we have folded the DBSC proposal into the end to end flow, for and end-to-end illustration of cookie binding. Please read the [DBSC proposal](https://githuub.com/wicg/dbsc) before you proceed. +DBSC(E) is not intended to be a separate proposal from DBSC, it is rather building on existing DBSC, and adds the binding specific details to the protocol. It is expected that the DBSC(E) proposal will be integrated into the DBSC proposal in the specification. In the high-level design, we have folded the DBSC proposal into the end to end flow. Please read the [DBSC proposal](https://githuub.com/wicg/dbsc) before you proceed. ## High-Level Design @@ -95,18 +93,19 @@ In this document, "Browser" refers to a functionality in a web browser that is r ### Relying Party (RP) -A web application that uses DBSC(E) protocol for cookie binding. +A web application that uses DBSC(E) protocol for cookie binding. This is referred to as `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). ### Identity Provider (IdP) -IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. +IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. IDP and RP are same for the consumer use case and is referred to as `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). ### Device Registration Client -A process where the user registers the device with the IdP. This process is expected to be a once-in-a-lifetime operation. +This is a pre-requisite for DBSC(E) to work. -The device registration is a process that establishes a trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. +Device Registration Client is a process where the user registers the device with the IdP and is expected to be a once-in-a-lifetime operation. +The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. One device registration client can manage multiple devices on the same physical device. There also can be multiple device registration clients on the same device. The device registration client can be owned and supported by: @@ -120,6 +119,7 @@ DBSC(E) aims to support most of these scenarios. It does not define the device r ### Local Key Helper +DBSC(E) introduced the concept of `Local Key Helper` which can be mapped to the `TPM` or any `Key generation helper` for the consumer case. **Local Key Helper** is an integral part of the the **Device Registration Client** , a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) @@ -133,7 +133,7 @@ The Local Key Helper is responsible for: - Producing signatures with the binding key - Cleanup of the binding key and its artifacts (when the user clears the browser session or the key is unused for a long time). -#### Platform Examples: +#### Platform Examples Please refer to the Windows Local Key Helper [here](./KeyGeneration.md#local-key-helper-on-windows) for an example of a Local Key Helper. @@ -151,13 +151,13 @@ Any enterprise user is expected to either use a device issued by their organizat ### DBSC(E) use cases -This section expands on the generic design to address different enterprise use cases: +This section expands on the [generic design](#high-level-design) to address different enterprise use cases: #### IDP Calls Public Local Key Helper For easy mapping with the existing DBSC proposal, please note: -- Steps 1-16 specify the key generation process for a public local key helper +- Steps 1-16 specify the key generation process for a public local key helper. - Steps 17-29 are [DBSC](https://github.com/wicg/dbsc), added for completeness. ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) From dcacb11a9bdaa3b0e51124b6e62e1087715d3e92 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 15 Aug 2024 11:38:06 -0700 Subject: [PATCH 10/47] Update high level design and some text --- DBSCE/DBSC(E).svg | 2 +- DBSCE/DBSC(E).txt | 33 ++++++++------ DBSCE/Overview.md | 108 +++++++++++++++++++++++++++------------------- 3 files changed, 85 insertions(+), 58 deletions(-) diff --git a/DBSCE/DBSC(E).svg b/DBSCE/DBSC(E).svg index 3a5910c..6fa4ae6 100644 --- a/DBSCE/DBSC(E).svg +++ b/DBSCE/DBSC(E).svg @@ -1 +1 @@ -participant%20%22TPM%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%22%20as%20w%0A%0A%0A%0Ab-%3Ew%3A%20sign-in%20flow%20%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%20%5Cn%5Cn%3Csize%3A10%3E%3Ccolor%3A%23blue%3ESec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%20%5Cn%3Ccolor%3A%23blue%3Eevaluate%20policy%20for%20%5Cn(HelperId...)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%2C%20authUrl%3F%2C%20challenge%2C%20extraParams%3F)%0Anote%20over%20b%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Eb%3A%20return%20public%20key%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(pubKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2Cpublic%20key%2C%20extraParams%3F..)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendTPMBrowserServersign-in flow 200 w/signed-in content, response includes header to start secure session.  Header: Sec-Session-Registration: session_identifier=..., challenge=...(challenge required for private key proof of possession) Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimebrowser initiates session bindingbased on header presence evaluate policy for (HelperId...)request create keypair (serverUrl, authUrl?, challenge, extraParams?)For Enterprise, this call will be platformbased & generates device attestationreturn public key &BindingStatement{challenge, thumbprint(pubKey), extraClaims?..}create JWT w/challengerequest sign JWT  (challenge,public key, extraParams?..)return JWT signaturePOST /securesession/startsession {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish session200 w/cookie and session IDbody includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookieGET /somecontent200 w/contentcheck if required cookies existGET /somecontent200 w/contentrequest deferred while we get cookies...GET /securesession/refresh header: Sec-Session-Id: [session ID]401Header: Sec-Session-Challenge: session_identifier=..., challenge=...create JWT w/challengerequest sign JWTreturn JWT signatureGET /securesession/refresh header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session IDbody includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent200 w/some contentalt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file +%0Aparticipant%20%22%3Ccolor%3A%23blue%3EAttestation%20Service%22%20as%20s%0Aparticipant%20%22%3Ccolor%3A%23blue%3ELocalKeyHelper%2FTPM%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%5Cn%3Ccolor%3A%23blue%3ERP%2FIDP%22%20as%20w%0A%0Aautonumber%201%0Ab-%3Ew%3A%20sign-in%20flow%20%0Aw-%3Eb%3A%20%3Ccolor%3A%23blue%3E302%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%2C%20..%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%3Ccolor%3A%23blue%3Ebrowser%20pre-generates%20keys%5Cnbased%20on%20headers%5Cn%5Cn%3Ccolor%3A%23blue%3EcurrentHelperId%3D%5Cnevaluate%20policy%20for%20%5Cn(Server%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%2Cchallenge%2CextraParams%3F)%5Cn%20pre%20generates%20key%20and%20attestation%0At-%3Et%3A%20%3Ccolor%3A%23blue%3EgenerateKey()%0Anote%20over%20t%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Es%3A%20%3Ccolor%3A%23blue%3EgenerateBindingStatement%5Cn(publicKey%2C%20AIK%2C%20challenge)%0As-%3Et%3A%20%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%7D%0At-%3Eb%3A%20return%20public%20key%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20%3Ccolor%3A%23blue%3ECache%20the%20key%20for%20server%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3ELoad%20sign-in%5CnSec-Session-Keys%3A%20KeyId%2C%5CnBinding%20Statement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims...%7D%0Aw-%3Ew%3A%20%3Ccolor%3A%23blue%3Evalidate%20signature%20on%20the%20%5Cnbinding%20statement%20and%20challenge%5Cnstore%20thumbprint%2C%20KeyId%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%2C%5Cn%3Ccolor%3A%23blue%3EKeyId%2C%20extraParams%3C%2Fcolor%3E%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2Cpublic%20key%2C%20extraParams%3F..)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%5Cn%3Ccolor%3A%23blue%3Evalidate%20the%20JWT%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn%3Ccolor%3A%23blue%3E%22extraParams%22%3A%3Ccustom..%3E%7D%22%22%20%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%5Cn%3Ccolor%3A%23blue%3Echallenge%2C%20extraParams...%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendAttestation ServiceLocalKeyHelper/TPMBrowserServerRP/IDPsign-in flow 1 3022 Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2, ..], HelperCacheTimebrowser pre-generates keysbased on headerscurrentHelperId=evaluate policy for (Server, [HelperId1, HelperId2...])request create keypair 3 (serverUrl,challenge,extraParams?) pre generates key and attestationgenerateKey()4 For Enterprise, this call will be platformbased & generates device attestationgenerateBindingStatement5 (publicKey, AIK, challenge)BindingStatement6 {challenge, thumbprint(publicKey), extraClaims}return public key &7 BindingStatement{challenge, thumbprint(publicKey), extraClaims?..}Cache the key for serverLoad sign-in8 Sec-Session-Keys: KeyId,Binding Statement{challenge, thumbprint(publicKey), extraClaims...}validate signature on the 9 binding statement and challengestore thumbprint, KeyId200 w/signed-in content, response includes header to start secure session.  10 Header: Sec-Session-Registration: session_identifier=..., challenge=...,KeyId, extraParams(challenge required for private key proof of possession)browser initiates session bindingbased on header presencecreate JWT w/challengerequest sign JWT  11 (challenge,public key, extraParams?..)return JWT signature12 POST /securesession/startsession 13 {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish sessionvalidate the JWT200 w/cookie and session ID14 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookie15 GET /somecontent16 200 w/content17 check if required cookies exist18 GET /somecontent19 200 w/content20 request deferred while we get cookies...GET /securesession/refresh 21 header: Sec-Session-Id: [session ID]40122 Header: Sec-Session-Challenge: session_identifier=..., challenge=..."extraParams":<custom..>} create JWT w/challengerequest sign JWT23 challenge, extraParams...return JWT signature24 GET /securesession/refresh 25 header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session ID26 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent27 200 w/some content28 alt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file diff --git a/DBSCE/DBSC(E).txt b/DBSCE/DBSC(E).txt index 6920b2d..7f9b626 100644 --- a/DBSCE/DBSC(E).txt +++ b/DBSCE/DBSC(E).txt @@ -1,20 +1,29 @@ -participant "TPM" as t -participant "Browser" as b -participant "Server" as w - +participant "Attestation Service" as s +participant "LocalKeyHelper/TPM" as t +participant "Browser" as b +participant "Server\nRP/IDP" as w +autonumber 1 b->w: sign-in flow -w->b: 200 w/signed-in content, response includes header to start secure session. \nHeader: ""Sec-Session-Registration: session_identifier=..., challenge=...""\n(challenge required for private key proof of possession) \n\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2], HelperCacheTime -note over b: browser initiates session binding\nbased on header presence \nevaluate policy for \n(HelperId...) -b->t: request create keypair \n(serverUrl, authUrl?, challenge, extraParams?) -note over b: For Enterprise, this call will be platform\nbased & generates device attestation -t->b: return public key &\nBindingStatement\n{challenge, thumbprint(pubKey), extraClaims?..} +w->b: 302\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2, ..], HelperCacheTime +note over b:browser pre-generates keys\nbased on headers\n\ncurrentHelperId=\nevaluate policy for \n(Server, [HelperId1, HelperId2...]) +b->t: request create keypair \n(serverUrl,challenge,extraParams?)\n pre generates key and attestation +t->t: generateKey() +note over t: For Enterprise, this call will be platform\nbased & generates device attestation +t->s: generateBindingStatement\n(publicKey, AIK, challenge) +s->t: BindingStatement\n{challenge, thumbprint(publicKey), extraClaims} +t->b: return public key &\nBindingStatement\n{challenge, thumbprint(publicKey), extraClaims?..} +note over b: Cache the key for server +b->w: Load sign-in\nSec-Session-Keys: KeyId,\nBinding Statement\n{challenge, thumbprint(publicKey), extraClaims...} +w->w: validate signature on the \nbinding statement and challenge\nstore thumbprint, KeyId +w->b: 200 w/signed-in content, response includes header to start secure session. \nHeader: ""Sec-Session-Registration: session_identifier=..., challenge=..."",\nKeyId, extraParams\n(challenge required for private key proof of possession) +note over b: browser initiates session binding\nbased on header presence note over b: create JWT w/challenge b->t:request sign JWT \n(challenge,public key, extraParams?..) t->b: return JWT signature b->w: POST /securesession/startsession \n\n""{"alg":..., "typ":"JWT", ...}{...,"key":""}"" -note over w: store public key, establish session +note over w: store public key, establish session\nvalidate the JWT w->b: 200 w/cookie and session ID\nbody includes scope of cookies (origin + path)\n\nheader: ""Set-Cookie: auth_cookie""\nbody: ""{"session_identifier":...}"" ==Some time passes...== note over b: user clicks link for path /somecontent @@ -30,9 +39,9 @@ w->b: 200 w/content else required cookie missing or expired note over b: request deferred while we get cookies... b->w: GET /securesession/refresh \nheader: ""Sec-Session-Id: [session ID]"" -w->b:401\n\nHeader: ""Sec-Session-Challenge: session_identifier=..., challenge=..."" +w->b:401\n\nHeader: ""Sec-Session-Challenge: session_identifier=..., challenge=...""\n"extraParams":}"" note over b: create JWT w/challenge -b->t:request sign JWT +b->t:request sign JWT\nchallenge, extraParams... t->b: return JWT signature b->w: GET /securesession/refresh \nheader: ""Sec-Session-Response: [JWT]"" note over w: validate proof of possesion diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index c28396f..784f4d9 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -56,33 +56,18 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' ## Overview -Device Bound Session Credentials for Enterprise - DBSC(E), is not a separate protocol but an addition to the existing [DBSC](https://github.com/wicg/dbsc) proposal to enhance the key generation mechanism and security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. +Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to the existing [DBSC](https://github.com/wicg/dbsc) proposal. It refines the key generation mechanism resulting in additional security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. ## Why DBSC(E)? -While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during the web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own credentials (asymmetric key pair) to the web application, there by stealing the session. Any upcoming sessions after this, even with DBSC, will not be reliable. +While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during the initial web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own credentials (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. -DBSC(E) aims to mitigate this risk by introducing the concept of credential generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the device. It guaratees any given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as "clean room"). With DBSC(E), the malware will not be able to compromise a device even during signin/login. Device registration is also expected to be a once-in-a-lifetime operation, and hence the user will not be required to perform this operation again, reducing the chances of malware compromising the device. +DBSC(E) aims to mitigate this risk by introducing the concept of credential generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the device. It guaratees any given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as "clean room"). With DBSC(E), the malware will not be able to compromise a device even during signin/login. Device registration is also expected to be a once-in-a-lifetime operation, and hence the user will not be required to perform this operation again, reducing opportunities for malware to extract session credentials the device. ## How does it integrate with DBSC? DBSC(E) is not intended to be a separate proposal from DBSC, it is rather building on existing DBSC, and adds the binding specific details to the protocol. It is expected that the DBSC(E) proposal will be integrated into the DBSC proposal in the specification. In the high-level design, we have folded the DBSC proposal into the end to end flow. Please read the [DBSC proposal](https://githuub.com/wicg/dbsc) before you proceed. -## High-Level Design - -DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an existing policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. - -The high-level design is divided into two parts: - -1. Key generation and validation before the session starts (DBSC(E) is focused on this part). -2. DBSC protocol applied with the generated keys (DBSC is focused on this part). - -Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, ee differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. - -DBSC(E) Introduction (in contrast with DBSC): - -![DBSC(E) Highlevel Design](<./DBSC(E).svg>) - Before we get into the specifics, we will introduce the terminology and design specifics for the key generation and validation below. ## Terminology @@ -105,8 +90,7 @@ This is a pre-requisite for DBSC(E) to work. Device Registration Client is a process where the user registers the device with the IdP and is expected to be a once-in-a-lifetime operation. -The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. -A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. +The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. One device registration client can manage multiple devices on the same physical device. There also can be multiple device registration clients on the same device. The device registration client can be owned and supported by: @@ -120,7 +104,7 @@ DBSC(E) aims to support most of these scenarios. It does not define the device r ### Local Key Helper DBSC(E) introduced the concept of `Local Key Helper` which can be mapped to the `TPM` or any `Key generation helper` for the consumer case. -**Local Key Helper** is an integral part of the the **Device Registration Client** , a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. +**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) @@ -135,9 +119,11 @@ The Local Key Helper is responsible for: #### Platform Examples -Please refer to the Windows Local Key Helper [here](./KeyGeneration.md#local-key-helper-on-windows) for an example of a Local Key Helper. +- Windows: Please refer to the Windows Local Key Helper [here](./KeyGeneration.md#local-key-helper-on-windows) for an example of a Local Key Helper. +- MacOS: TBD +- Android:TBD -Note: We plan to provide a reference implementation of the Local Key Helper for major platforms here in the future. +Note: Above are examples of Local Key Helpers that can be used for DBSC(E) key generation. Any platform is free to build a version of this, as long as the API is consistent with the protocol. ### Attestation Service: @@ -149,53 +135,85 @@ Any enterprise user is expected to either use a device issued by their organizat ![DeviceRegistration](./DeviceRegistration.svg) -### DBSC(E) use cases +## High-Level Design -This section expands on the [generic design](#high-level-design) to address different enterprise use cases: +DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an existing policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. -#### IDP Calls Public Local Key Helper +The high-level design is divided into two parts: -For easy mapping with the existing DBSC proposal, please note: +1. Key generation and validation before the session starts (DBSC(E) is focused on this part). +2. DBSC protocol applied with the generated keys (DBSC is focused on this part). -- Steps 1-16 specify the key generation process for a public local key helper. -- Steps 17-29 are [DBSC](https://github.com/wicg/dbsc), added for completeness. +Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, ee differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. -![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) +DBSC(E) (in contrast with DBSC): + +![DBSC(E) Highlevel Design](<./DBSC(E).svg>) Highlights: -1. **Session initiation with special headers (steps 1-4):** When a user starts a sign-in process, or initiates a session, the IdP will call the browser to generate a key for the session. It is expected that the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser, to indicate that the session is expected to be DBSC(E) compliant. +Note: All references to RP, IDP are equivalent to `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). + +1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - - The `Sec-Session-GenerateKey` header contains the URL of the webpage(RP), the URL of the IdP (authentication service in most cases), a `nonce`, and any extra parameters that the IdP wants to send to the Local Key Helper. - - As the Local Key Helper is public or thirdparty, and potentially can be from a different vendor, `nonce` is essential to prevent the clock skew difference between the IdP and the Local Key Helper. The `nonce` is expected to be a random number generated by the IdP. + - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce`(challenge) and any extra parameters that the IdP wants to send to the Local Key Helper. + - As the Local Key Helper is public or thirdparty, and potentially can be from a different vendor, `nonce`(challenge) is essential to prevent the clock skew difference between the IdP and the Local Key Helper. The `nonce`(challenge) is expected to be a random number generated by the IdP. - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. -1. **Key and Binding Statement Generation (steps 5-9):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. +1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce`(challenge) sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. - - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](./KeyGeneration.md#binding-statement). + - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce`(challenge) and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](./KeyGeneration.md#binding-statement). - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the `binding statement`. It is intentionally left undefined, and can be customized. - - TBD define under which conditions: Local Key Helper can optionally signal the browser to cache the Binding Statement in the browser. This is to avoid repeated calls to the Local Key Helper for the same IdP. The browser can cache the Binding Statement for a certain time, and if the IdP requests a new key within that time, the browser can return the cached Binding Statement. + - Local Key Helper can optionally signal the browser to cache the Binding Statement in the browser. This is to avoid repeated calls to the Local Key Helper for the same IdP. The browser can cache the Binding Statement for a certain time, and if the IdP requests a new key within that time, the browser can return the cached Binding Statement. TBD define under which conditions. -1. **Sign In/Session Initiation (steps 10-14)**: The `Binding Statement`, with the `KeyId` is expected to be returned to the IdP witha new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement---generation-and-validation) the signature on the `Binding Statement`, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony and generate the auth tokens, that embed the thumbprint of the public key. The `KeyId` is expected to be returned to the Relying Party, and the IdP will use the `KeyId` to identify the key to be used for the session. +1. **Sign In/Session Initiation (steps 8-9):** The `Binding Statement`, with the `KeyId` is expected to be returned to the IdP witha new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement---generation-and-validation) the signature on the `Binding Statement`, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. -1. **SignIn Succeeds with binding (steps 15-16)**: The IdP will return the auth tokens to the RP,with the thumbprint of the public key embedded in the token. +1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with additional params introduced for DBSC(E) customization. -1. **DBSC Protocol (steps 17-29)**: Once the sign in completes, with the intended IDP/Local Key Helper, the DBSC protocol is applied with the generated keys. RP can now initiate a session with the acquired tokens and the browser generates a JWT with the Local Key Helper which embeds the binding info. The signed JWT is now returned along with the tokens to the RP, which is inturn embedded in any cookies generated and stored by the RT, binding them. All future transactions including a refresh session now will look for the binding info in the cookies, hence securing them against session hijacking. +### DBSC(E) use cases + +This section expands on the [generic design](#high-level-design) to address different enterprise use cases: #### IDP is RP and Calls Public Local Key Helper -In some cases, we see the web service assuming dual roles of both the resource server and the authentication server (think of github client authenticated by github service). In such cases, DBSC(E) can be optimized to simplify the protocol and align with the perf goals for specific services. +This is the same use case elaborated in the high level design [above](#high-level-design). However, we have separated the IdP/RP components of the server for the enterprise use case in the below diagram. ![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) -Highlights (only the difference with IDPCallsPublicLocalKeyHelper): +Highlights: + +- Auth tokens are not mentioned in the DBSC(E) high level design, as they are optional for the consumer use case. However, for the enterprise use case, the IdP can generate the auth tokens and embed the thumbprint of the public key in the token. +- The token can be delivered to the RP directly through an API instead of a header based response. +- The tokens also contain the thumpbrint of the public key, and the RP can validate the thumbprint of the public key from the token. + +#### IDP Calls Public Local Key Helper + +In Enterprise, it is a valid use case to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where these are separate entities and probably from different vendors below. -1. **Session establishment (Steps 1-10)**: Since RP is IDP, the session initiation with the headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` is optimized and initiated by the RP itself. -1. **Token Issuance (Steps 11-13)**: The tokens once generated, can be delivered to RP directly through an API instead of a header based response. -1. **DBSC Protocol (Steps 14-26)**: The `startSession` and `refreshSession` protocol remains the same as in the original DBSC proposal. +For easy mapping with the existing DBSC proposal, please note: + +- Steps 1-16 specify the key generation process for a public local key helper. +- Steps 17-29 are [DBSC](https://github.com/wicg/dbsc), added for completeness. + +![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) #### IDP Calls Private Local Key Helper -A special case is for enterprises that already have `well-known` Local Key Helpers, which are expected to be trusted and enabled by default in a browser. Here, since the browser can trust a given IDP (based on the URL and a policy mapping) and can trust the IDP to invoke the appropriate Local Key Helper (refer [Local key helper on Windows](./KeyGeneration.md#local-key-helper-on-windows)), there are a few optimizations that can be made to the protocol, in skipping the nonce and reducing the number of round trips between the IDP and the Local Key Helper. +A special case is for enterprises that already have `well-known` Local Key Helpers, which are expected to be trusted and enabled by default in a browser. Here, since the browser can trust a given IDP (based on the URL and a policy mapping) and can trust the IDP to invoke the appropriate Local Key Helper (refer [Local key helper on Windows](./KeyGeneration.md#local-key-helper-on-windows)), there are a few optimizations that can be made to the protocol, in skipping the `nonce`(challenge) and reducing the number of round trips between the IDP and the Local Key Helper. ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) + +Highlights: + +- Since the IDP (a specific URL) is trusted in this use case, the browser can skip the `nonce`(challenge) and directly call the Local Key Helper. +- Attestation Service is optional as it is assumed that the IDP is trusted and can validate the binding statement. In other words, Attestation Service is assumed to be part of the IDP in this case. +- The headers are modeled after confidential client flow(OAuth2) implemented with [Microsoft IDP](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens) as an example. It is possible to replace `Microsoft` with `Okta` and achieve the same flow. + +### Cleanup of the binding keys and their artifacts + +For the health of the operating system and user privacy, it is important to clean up binding keys and their artifacts. If the number of keys grows too high, the performance of the OS can degrade. + +The cleanup can occur: + +- On demand, when the user decides to clear browser cookies. +- Automatically, when a key hasn't been used for a long time (N days) to keep the OS healthy. From ced647c87b786b55fd9b68c0dcbbddff85c13efa Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 15 Aug 2024 20:41:41 -0700 Subject: [PATCH 11/47] Undo auto formatting changes --- README.md | 100 +++++++++++++----------------------------------------- 1 file changed, 23 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index e1ab325..25a0aea 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,14 @@ This is the repository for Device Bound Session Credentials. You're welcome to [contribute](CONTRIBUTING.md)! ## Authors: - - [Kristian Monsen](kristianm@google.com), Google - [Arnar Birgisson](arnarb@google.com), Google ## Participate (to come) - - [Issue tracker](https://github.com/WICG/dbsc/issues) - [Discussion forum] ## Table of Contents - @@ -38,33 +35,27 @@ This is the repository for Device Bound Session Credentials. You're welcome to ## Introduction - Device Bound Session Credentials (DBSC) aims to reduce account hijacking caused by cookie theft. It does so by introducing a protocol and browser infrastructure to maintain and prove possession of a cryptographic key. The main challenge with cookies as an authentication mechanism is that they only lend themselves to bearer-token schemes. On desktop operating systems, application isolation is lacking and local malware can generally access anything that the browser itself can, and the browser must be able to access cookies. On the other hand, authentication with a private key allows for the use of system-level protection against key exfiltration. -DBSC offers an API for websites to control the lifetime of such keys, behind the abstraction of a session, and a protocol for periodically and automatically proving possession of those keys to the website's servers. There is a seperate key for each session, and it should not be possible to detect two different session keys are from one device. One of the key goals is to enable drop-in integration with common types of current auth infrastructure. By device-binding the private key and with appropriate intervals of the proofs, the browser can limit malware's ability to offload its abuse off of the user's device, significantly increasing the chance that either the browser or server can detect and mitigate cookie theft. +DBSC offers an API for websites to control the lifetime of such keys, behind the abstraction of a session, and a protocol for periodically and automatically proving possession of those keys to the website's servers. There is a seperate key for each session, and it should not be possible to detect two different session keys are from one device. One of the key goals is to enable drop-in integration with common types of current auth infrastructure. By device-binding the private key and with appropriate intervals of the proofs, the browser can limit malware's ability to offload its abuse off of the user's device, significantly increasing the chance that either the browser or server can detect and mitigate cookie theft. DBSC is bound to a device with cryptographic keys that cannot be exported from the user’s device under normal circumstances, this is called device binding in the rest of this document. DBSC provides an API that servers can use to create a session bound to a device, and this session can periodically be refreshed with an optional cryptographic proof the session is still bound to the original device. At sign-in, the API informs the browser that a session starts, which triggers the key creation. It then instructs the browser that any time a request is made while that session is active, the browser should ensure the presence of certain cookies. If these cookies are not present, DBSC will hold network requests while querying the configured endpoint for updated cookies. ### Goals - Reduce session theft by offering an alternative to long-lived cookie bearer tokens, that allows session authentication that is bound to the user's device. This makes the internet safer for users in that it is less likely their identity is abused, since malware is forced to act locally and thus becomes easier to detect and mitigate. At the same time the goal is to disrupt the cookie theft ecosystem and force it to adapt to new protections. ### Non-goals - -DBSC will not prevent temporary access to the browser session while the attacker is resident on the user’s device. The private key should be stored as safe as modern desktop operating systems allow, preventing exfiltration of the session private key, but the signing capability will still be available for any program running as the user on the user’s device. +DBSC will not prevent temporary access to the browser session while the attacker is resident on the user’s device. The private key should be stored as safe as modern desktop operating systems allow, preventing exfiltration of the session private key, but the signing capability will still be available for any program running as the user on the user’s device. ### What makes Device Bound Session Credentials different - DBSC is not the first proposal towards these goals, with a notable one being [Token Binding](https://en.wikipedia.org/wiki/Token_Binding). This proposal offers two important features that we believe makes it easier to deploy than previous proposals. DBSC provides application-level binding and browser initiated refreshes that can make sure devices are still bound to the original device. #### Application-level binding - For websites, device binding is most useful for securing authenticated sessions of users. DBSC allows websites to closely couple the setup of bound sessions with user sign-in mechanisms, makes session and key lifetimes explicit and controllable, and allows servers to design infrastructure that places verification of session credentials close to where user credentials (cookies) are processed in their infrastructure. Alternatives such as Token Binding gain much from e.g. integrating with TLS, but this can make integration harder in environments where e.g. TLS channel termination is far removed from the application logic behind user sign-in and session management. #### Browser-initiated refreshes - Other proposals have explored lower-level APIs for websites to create and use protected private keys, e.g. via WebCrypto or APIs similar to WebAuthn. While this works in theory, it puts a very large burden on the website to integrate with. In particular, since the cost of using protected keys is high, websites must design some infrastructure for collecting signatures only as often as needed. This means either high-touch integrations where the keys are only used to protect sensitive operations (like making a purchase), or a general ability to divert arbitrary requests to some endpoint that collects and verifies a signature and then retries the original request. The former doesn't protect the whole session and violates the principle of secure by default, while the latter can be prohibitively expensive for large websites built from multiple components by multiple teams, and may require non-trivial rewrites of web and RPC frameworks. @@ -72,83 +63,65 @@ This means either high-touch integrations where the keys are only used to protec DBSC instead allows a website to consolidate the session binding to a few points: At sign-in, it informs the browser that a session starts, which triggers the key creation. It then instructs the browser that any time a request is made while that session is active, the browser should ensure the presence of certain cookies. The browser does this by calling a dedicated refresh endpoint (specified by the website) whenever such cookies are needed, presenting that endpoint with a proof of possession of the private key. That endpoint in turn, using existing standard Set-Cookie headers, provides the browser with short-term cookies needed to make other requests. This provides two important benefits: - 1. Session binding logic is consolidated in the sign-in mechanism, and the new dedicated refresh endpoint. All other parts of the website continue to see cookies as their only authentication credentials, the only difference is that those cookies are short-lived. This allows deployment on complex existing setups, often with no changes to non-auth related endpoints. 1. If a browser is about to make a request where it has been instructed to include such a cookie, but doesn't have one, it defers making that request until the refresh is done. While this may add latency to such cases, it also means non-auth endpoints do not need to tolerate unauthenticated requests or respond with any kind of retry logic or redirects. This again allows deployment with minimal changes to existing endpoints. Note that the latency introduced by deferring of requests can be mitigated by the browser in other ways, which we discuss later. ### TPM considerations - DBSC depends on user devices having a way of signing challenges while protecting private keys from exfiltration by malware. This usually means the browser needs to have access to a Trusted Platform Module (TPM) on the device, which is not always available. TPMs also have a reputation for having high latency and not being dependable. Having a TPM is a requirement for installing Windows 11, and can be available on previous versions. All our studies are for public key cryptography using ECDSA_P256 algorithm. -Chrome has done studies to understand TPM availability to understand the feasibility of secure sessions. Current data shows about 60%, and currently growing, of Windows users would be offered protections. Studies have also been done on the current populations of TPMs, both for latency and for predictability. Currently the latency is (P50: 200ms/ P95: 600ms) for signing operations. The error rate is very low, currently around 0.001%. + Chrome has done studies to understand TPM availability to understand the feasibility of secure sessions. Current data shows about 60%, and currently growing, of Windows users would be offered protections. Studies have also been done on the current populations of TPMs, both for latency and for predictability. Currently the latency is (P50: 200ms/ P95: 600ms) for signing operations. The error rate is very low, currently around 0.001%. Based on this research, TPMs are widely available, with a latency and consistency that is acceptable for the proposed usage. ### Privacy considerations - An important high-level goal of this protocol is to introduce no additional surface for user tracking: implementing this API (for a browser) or enabling it (for a website) should not entail any significant user privacy tradeoffs. There are a few obvious considerations to ensure we achieve that goal: - - Lifetime of a session/key material: This should provide no additional client data storage (i.e., a pseudo-cookie). As such, we require that browsers MUST clear sessions and keys when clearing other site data (like cookies). - Cross-site/cross-origin data leakage: It should be impossible for a site to use this API to circumvent the same origin policy, 3P cookie policies, etc. (More on this below.) - Implementing this API should not meaningfully increase the entropy of heuristic device fingerprinting signals. (For example, it should not leak any stable TPM-based device identifier.) - This API—which allows background "pings" to the refresh endpoint when the user is not directly active—must not enable long-term tracking of a user when they have navigated away from the connected site. - Each session has a separate new key created, and it should not be possible to detect that different sessions are from the same device. -### Enterprise support - -While DBSC addresses a general problem of session hijacking, and can be applicable to any _browser_ consumer, it is possible to expand this protocol to better support enterprise use cases. By adding specifics to key generation and enabling the switch if there is a specific policy administered on the device, we can provide a more secure environment for enterprise users. This is the goal of DBSC(E), which is an extension to DBSC. The high-level design of DBSC(E) is described in the [DBSC(E) Overview](). - -DBSC(E) removes the vulnerability DBSC has, where a malware, if already present in the device during the key generation, can take over the session even if it is eventually bound to the device. By assuring a clean state key generation and introducing device key chaining, DBSC(E) can mitigate this vulnerability: More details about the importance of DBSC are here: [Why DBSC(E)?](). - ## High level overview - ![High level diagram](reg_and_refresh.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=A4QwTgLglgxloDsIAIBEAVACgWVckAzshAFCiSzwhJoBCYA9gO4ECmYehyARmeNHEQpUAZXYA3dpyJMScktwC0APiYAuZASgBzBIqgJkAMwA2zEkxXcNAJgAMd5EwD0W3awAm+wzAZJWSAA0yGCsBMB+bMgGMCYArh5hyAAWrCCJYMQMmhD8mqwwcaH5BFp+AHTIyAA6CAASaRkaqKIFimKlUH6KAEqs2lAEEGAg0H4abJ1+APpQiUhQRlDsALzl68EwySAmJgHarGvrLbUAFFs7ewgHIawAjnFQoR7GDJnAYFDio6zIANasACeyA+DAYRmQ4JBDFKYTKCAAlCQEAwIL8GJJMtYeIwWOxoggoNAfkRJvCeAYPAZtLVuIRPJDDKl0viPmEAjBWAoVBANKEHmEUDBQj9-kDQE8SBArHzWBAioZgHFuCZYGLAcjUejMTwNMK0mjkAApADq6Cczguu32XKUyl5-Ligs0OkMpvQUplt3lYDdZpdulGRVtKnUyEwAHkRObXAVg2SughXLlIAm-DUELUWgBvVA7bSoNTrcrBVAQQHAQuod2oYLFgC+2eLgVQAMBVYAPEqVbBpm3lKh6y1kJrDRj8WGhm9ft3VTB1cFBSAewRkiV4RYvfZHC5fAw-st8AgXmnDABJAAitIYHmBMXiiVJvmA6Ihe4PSVObx0BmQAGoQVGZIEVqWpmSaNBWmlABhMEPw0EA4ggZJpnfZYTgQbgb0BZpUFzU9ZnmaAlikIt1iHVASBWFYRAYABbX5oAYwDYQIYtqNHbV8WxOI2EyWJYD+IhVQQP5XneIDkFceiCj8NEkG5ZRsS2AoxMWSFPgGBA-1AZDbgeJ4kiwuJj2QNCuR2FBjNM8zkBRFBHUMjxFLDABxABRGMCBk3x-AUywlNsBwLV8+TSFYEwomsl5bMc55FOU1IYDUiE4oZcyiFYAAPQZSEs-THmeMy4MPNk2BoagXns5BsuAJyXI0DyvJ8uSAlIALsW3ELWoUiKojSmKSt+OjBi0a4NJqrK6vi+yuKxWUBSGZBEiMdgiqYZIoD2JxfgOIUhrY9YGuQJqpLYQpQlPZxQiMS61zAxp2FwsQYHaOFE0UM8PA0ABtU9kEvABdFpN0CgAWOwAEZQPqR6wGetoOnhRRoO2a1rlYCZ3pmOY2sWZYwCOEszLRq4DiJkHZshHVlJFQ13RC0mbUUh17idJa3D9D1pUC70FWNf1OaDUJjtO2MLvZKYkxuu6M3Ap7IJet6pd6MIIgQNhfvdYHKKp8dMjDb5VQ8UVQShKEIlYxNQesLrdyGo8T2x88r0w7CCViBIkgIZ9X2K-dliIL9NN-ADdOAmH5fhxW5RRoaEKQlDzIwrDb1w-DncIvGSI4Mjygozjqe4rGJfXRMaqGZdVVXTxgkuuIGNqb8tJ2ArBVFzyzpavz2q3YKXG85jQrakgAmcsegA) The general flow of a secure session is as follows: - 1. The website requests that the browser start a new session, providing an HTTP endpoint to negotiate registration parameters. 1. The browser creates a device-bound key pair, and calls the registration HTTP endpoint to set up the session and register the public key. 1. The server responds with a session identifier, and instructions on how to maintain the session. This is a (possibly empty) list of cookie names that the browser is expected to ensure exist, and their associated scope (origins+path). 1. At a later time the session is closed by either the server requesting to close the session or the user clears the keys by clearing site data. As long as that session is active, the browser performs the following refresh as needed: - 1. For any request within an applicable scope, the browser checks if the necessary cookies exist. If they exist, continue as normal. 1. If not, the browser defers such requests while performing the following. -1. The browser contacts the HTTP endpoint for the session, providing the session identifier and, if requested by the server, the necessary proof of possession of the associated private key. +1. The browser contacts the HTTP endpoint for the session, providing the session identifier and, if requested by the server, the necessary proof of possession of the associated private key. 1. If the server is satisfied with the proof, it uses regular Set-Cookie headers to establish the necessary cookies with an appropriate Max-Age. The response can also include an updated set of instructions, e.g. if the server wishes to change which cookies are subject to this logic. 1. If any requests were deferred in step 2, the browser now makes those requests including the updated set of cookies. 1. The browser may choose to proactively refresh cookies that are about to expire, if it predicts the user may soon need them. This is purely a latency optimization, and not required. There is an option for the server to opt out of the browser defering requests. If so it will instead: - 1. Sign any requests that would be defered, use the most recent challange. If there is not one, use the current timestamp. The browser may cache these signatures. 1. The server can respond with 401 if it wants the request signed with a new challenge. 1. The server can also serve challenges ahead of time on any response with the Sec-Session-Challenge header. 1. Once the browser get an instruction to set the missing cookie it will stop signing requests. - We do not reccomend this option for most deployments, but it is possibly for those that want to potentially save a network roundtrip in some circumstances. +We do not reccomend this option for most deployments, but it is possibly for those that want to potentially save a network roundtrip in some circumstances. -### Start Session +### Start Session ![Start session diagram](header_setup.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=MoUwTgbuC0B8CqBncACAggcxAOwC4C4VQBjaURRASwHttoAlEDSxXMAQ1xuwCgeMw1AK4AHFMlyjxICtxRgQARyEzcPJKkw5ccUJHD4ACgHlgAFRQB6ZMSELks2tdzswuB1Vo9s1XCBTUUGAoGsFaeAA0ekEAxADuABYgnPgA3gBEAEaU2AAmORjQ7AA2GPgAdJXpAL7qyGFYeAA8ZOBB+KA6AMLU1ADWlCCE7EK4CQD6xL0DIN6+-oGooeiNuFFt4PFJKRke3NCUudqUAGaDYBVVtTi5fD5+AUEh9SvaW8kE5J7YKCwoPnEUOxiFwoDwgA) #### Session Registration Header - The session start process is initiated by the server attaching a header with Sec-Session-Registration and appropriate parameters, this looks like: - ```http HTTP/1.1 200 OK Sec-Session-Registration: (RS256 ES256);challenge="nonce";path="StartSession" ``` - This is a structured header with a list of token arguments representing the allowed algorithms (possibilities are ES256 and RS256). The list have multiple string attributes, "path" is required describing the endpoint to use, "challenge" is to provide a nonce for the registration JWT. There is also an optional string attribute called authorization. There can be more than one registration on one response: - ```http HTTP/1.1 200 OK Sec-Session-Registration: (ES256 RS256);path="path1";challenge="nonce";authorization="authcode" @@ -158,7 +131,6 @@ Sec-Session-Registration: (ES256);path="path2";challenge="nonce" The authorization value is optional. If present, it will be sent to the registration endpoint in the `Authorization` header, and included in the registration JWT. This allows passing a bearer token that allows the server to link registration with some preceding sign in flow, as an alternative to the more traditional use of cookies. While this can also facilitate integration with some existing infrastructure, e.g. ones based on OAuth 2.0, this parameter is general and is not limited to the similarly named [Authorization Code](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1) in OAuth 2.0. #### Session Registration JWT - The browser responds to the session start by selecting a compatible signature algorithm and creating a device-bound private key for the new session. It then makes the following HTTP request (assuming the endpoint URL is https://auth.example.com/securesession): ```http @@ -171,9 +143,7 @@ Cookie: whatever_cookies_apply_to_this_request=value; Sec-Session-Response: registration JWT ``` - The JWT is signed with the newly created private key, and needs to contain the following values: - ```json // Header { @@ -191,7 +161,6 @@ The JWT is signed with the newly created private key, and needs to contain the f ``` #### Session Registration instructions JSON - If the request is properly authorized, the server establishes whatever state represents the session server-side, and returns the following response. ```http @@ -214,30 +183,24 @@ Set-Cookie: auth_cookie=abcdef0123; Domain=example.com; Max-Age=600; Secure; Htt "include_site": true, "defer_requests": true, // optional and true by default - "scope_specification": [ - { - "type": "include", - "domain": "trusted.example.com", - "path": "/only_trusted_path" - }, + "scope_specification" : [ + { "type": "include", "domain": "trusted.example.com", "path": "/only_trusted_path" }, { "type": "exclude", "domain": "untrusted.example.com", "path": "/" }, { "type": "exclude", "domain": "*.example.com", "path": "/static" } ] }, - "credentials": [ - { - "type": "cookie", - // This specifies the exact cookie that this config applies to. Attributes - // match the cookie attributes in RFC 6265bis and are parsed similarly to - // a normal Set-Cookie line, using the same default values. - // These SHOULD be equivalent to the Set-Cookie line accompanying this - // response. - "name": "auth_cookie", - "attributes": "Domain=example.com; Path=/; Secure; SameSite=None" - // Attributes Max-Age, Expires and HttpOnly are ignored - } - ] + "credentials": [{ + "type": "cookie", + // This specifies the exact cookie that this config applies to. Attributes + // match the cookie attributes in RFC 6265bis and are parsed similarly to + // a normal Set-Cookie line, using the same default values. + // These SHOULD be equivalent to the Set-Cookie line accompanying this + // response. + "name": "auth_cookie", + "attributes": "Domain=example.com; Path=/; Secure; SameSite=None" + // Attributes Max-Age, Expires and HttpOnly are ignored + }] } ``` @@ -250,14 +213,11 @@ Sec-Session-Challenge: challenge="nonce" Subsequently, as long as the browser considers this session "active", it follows the steps above, namely by refreshing the auth_cookie whenever needed, as covered in the next section. -Note if multiple cookies are required, the browser returns multiple Set-Cookie headers, with corresponding entries in the "credentials" array in the response body. +Note if multiple cookies are required, the browser returns multiple Set-Cookie headers, with corresponding entries in the "credentials" array in the response body. ### Maintaining a session - As long as the named cookie is not expired the browser will keep sending requests as normal. Once the cookie is expired the browser will hold all requests for the scope of the cookie, except where the server excluded the paths in the registration, while refreshing the cookie. This is where the browser driven protocol makes a difference, if not for this there would be potentially many requests without the required cookie. - #### Refresh procedure - ![Refresh diagram](refresh_v2.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=A4QwTgLglgxloDsIAICqBnApmZBBA5pkgFCiSzwhLIASmANgCbIBKmAjgK6boTqnhocRCgDK2AG7ZixBAHsImZHKk4M2PISQAacWFUBiAO4ALTCAgAucenRQ5CZDDlyA1lCUhOEEwH1nbh7ImAAewFBgmIzE6jgERBAAtAB8dEysHNy86JbIAOIAogAqwSEgALbA9JgAdM7lAPTAYAqYMIqMvpFcPBDE+C2cwBkAZpHoJshYtvYIMVhxWknJeqqWAAoA8qIlDVgwnOM8dg4NkWM8JsSr2CmxmgmWNEVF68gALAAMAIyyrcqqNALB46G5gYxmCzWNqJGwnBCJADCJhA9GqCEIlhq2Jq8w08SQKTBG22u32hx4x1mZ0wFwmf0UAI09wJEF0kmwEPMVgA3gAicQwWFUhyJNjoYAOLHYvkAX2uHLAd2BrKeLzeACZPp8GUoVMyVUt2fpOaZudCkoiXO5MLkvD5-NaPABeCSo7jEIjReSM-VqQ0JY2GM1QtjVEBYZBmdLdLJ8ZBGKA+JxOnjIc7jMzRFlLImK3KFEqhCpVWr1JotRTtKJdTK9YhAA) @@ -281,7 +241,6 @@ Sec-Session-Challenge: session_identifier="session_id",challenge="nonce" ``` The server can also serve challenges ahead of time attached to any response as an optimization, for example: - ```http HTTP/1.1 XXX Sec-Session-Challenge: session_identifier="session_id",challenge="nonce" @@ -295,12 +254,11 @@ Sec-Session-Response: refresh JWT ``` The JWT contains: - ```json { "jti": "nonce", "aud": "the URL to which the Sec-Session-Response will be sent", - "sub": "the session ID corresponding to the binding key" + "sub": "the session ID corresponding to the binding key", } ``` @@ -312,7 +270,6 @@ Content-Type: application/json Cache-Control: no-store Set-Cookie: auth_cookie=abcdef0123; Domain=example.com; Max-Age=600; Secure; HttpOnly; ``` - The contents is a json with the same specifications as during the registration. On receiving this response, the browser releases any requests that were deferred pending this refresh, including the new cookie. Note: @@ -322,20 +279,16 @@ The server may issue a different Max-Age, or scope for the short-term cookie. The server may set or update other cookies not subject to session refreshes in this response, as in any response. If instead the server decides to end the session it can respond with: - ```json { "session_identifier": "session_id", "continue": false -} + } ``` - In this case the browser should stop triggering any refreshes for this request, release any deferred requests without the short-term cookie, and clean up and delete the associated session state including the binding key. #### Ending a session - The session can end in several ways: - - The server can end the session during a refresh by answering with {“continue”: false} during a refresh - The server can at any time send a header with Clear-Site-Data: "storage" - The user can clear site data, which will locally clear cookies and any registered session keys for the site @@ -343,15 +296,11 @@ The session can end in several ways: It is important that the user is always in control and can delete the session keys if wanted. ## Interactions with other APIs - ### Login Status API - ### Interaction with Inactive Documents (BFCache, Prerendering) - When a session is ended for any reason, any inactive documents which had access to that session's credentials should be destroyed. This ensures that pages in BFCache or that are pre-rendering that contain information guarded by those credentials are not presented after the session has ended. ## Alternative JavaScript API for StartSession - ![Start session diagram](dbsc_js_v2.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=A4QwTgLglgxloDsIAIDqBTARsgCiA5ugFCiSzwhLICqAzumMgIKFInjRyIoDKDAbgyJF8YAPYBXYMh4QOyerVpQxCIhmx5CAWgB8dBs1YQAXMgQh+UfCAhiwAOnowJYdIuWqncyAAoHAQCURAhiEOjIYoKMBows6EgAxADuABbotiYAwm62EQDW6ACeyKBQYESxRgkQenxg0SY4API8ACrIAPTOru7ungjdPhAhYRFRhlXxSAA09dEp6ZkA3gBEmFAIACab+NogADb4JgEOqwC+RPMMelPGJgASbW04yABMAAwfo+GR0TT0OLGOYCBiLDKmPi1LJiMT5KDoMwgCQQVIAfRgsPh6AAvPxDhJiBpcAR0AAebR3GpmYDiAC2UHoDjctDEB0E-iCRASWx+43+xK06BBDTBaQhJj4ShUCGQjPMYmSyBAMGggiIQA) @@ -367,7 +316,6 @@ The API consists of a new interface, SecureSession, an instance of which is obta - A promise with a string containing the session ID (which may be empty) When called, this method must: - - Generate and store a new, secure cryptographic key pair - Call the "endpoint" + /startsession as specified below in Start Session (HTTP Request/Response) - Return a promise which @@ -375,11 +323,9 @@ When called, this method must: - If that call fails, throws an exception (which may indicate the HTTP status of the failed call) Requirements: - - The endpoint must have the same origin as the JavaScript. Below is an example of the API being used: - ```javascript let promise = navigator.secureSession.start({ // Session start options @@ -398,4 +344,4 @@ promise.catch((...) => { // not reachable, or broke protocol. }); -``` +``` \ No newline at end of file From 75d42585164077947f914b04582ca7ccb376f56e Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 15 Aug 2024 20:44:00 -0700 Subject: [PATCH 12/47] Add DBSC(E) section --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 25a0aea..5d785dd 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,12 @@ There are a few obvious considerations to ensure we achieve that goal: - This API—which allows background "pings" to the refresh endpoint when the user is not directly active—must not enable long-term tracking of a user when they have navigated away from the connected site. - Each session has a separate new key created, and it should not be possible to detect that different sessions are from the same device. +### Enterprise support + +While DBSC addresses a general problem of session hijacking, and can be applicable to any _browser_ consumer, it is possible to expand this protocol to better support enterprise use cases. By adding specifics to key generation and enabling the switch if there is a specific policy administered on the device, we can provide a more secure environment for enterprise users. This is the goal of DBSC(E), which is an extension to DBSC. The high-level design of DBSC(E) is described in the [DBSC(E) Overview](). + +DBSC(E) removes the vulnerability DBSC has, where a malware, if already present in the device during the key generation, can take over the session even if it is eventually bound to the device. By assuring a clean state key generation and introducing device key chaining, DBSC(E) can mitigate this vulnerability: More details about the importance of DBSC are here: [Why DBSC(E)?]() + ## High level overview ![High level diagram](reg_and_refresh.svg) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=A4QwTgLglgxloDsIAIBEAVACgWVckAzshAFCiSzwhJoBCYA9gO4ECmYehyARmeNHEQpUAZXYA3dpyJMScktwC0APiYAuZASgBzBIqgJkAMwA2zEkxXcNAJgAMd5EwD0W3awAm+wzAZJWSAA0yGCsBMB+bMgGMCYArh5hyAAWrCCJYMQMmhD8mqwwcaH5BFp+AHTIyAA6CAASaRkaqKIFimKlUH6KAEqs2lAEEGAg0H4abJ1+APpQiUhQRlDsALzl68EwySAmJgHarGvrLbUAFFs7ewgHIawAjnFQoR7GDJnAYFDio6zIANasACeyA+DAYRmQ4JBDFKYTKCAAlCQEAwIL8GJJMtYeIwWOxoggoNAfkRJvCeAYPAZtLVuIRPJDDKl0viPmEAjBWAoVBANKEHmEUDBQj9-kDQE8SBArHzWBAioZgHFuCZYGLAcjUejMTwNMK0mjkAApADq6Cczguu32XKUyl5-Ligs0OkMpvQUplt3lYDdZpdulGRVtKnUyEwAHkRObXAVg2SughXLlIAm-DUELUWgBvVA7bSoNTrcrBVAQQHAQuod2oYLFgC+2eLgVQAMBVYAPEqVbBpm3lKh6y1kJrDRj8WGhm9ft3VTB1cFBSAewRkiV4RYvfZHC5fAw-st8AgXmnDABJAAitIYHmBMXiiVJvmA6Ihe4PSVObx0BmQAGoQVGZIEVqWpmSaNBWmlABhMEPw0EA4ggZJpnfZYTgQbgb0BZpUFzU9ZnmaAlikIt1iHVASBWFYRAYABbX5oAYwDYQIYtqNHbV8WxOI2EyWJYD+IhVQQP5XneIDkFceiCj8NEkG5ZRsS2AoxMWSFPgGBA-1AZDbgeJ4kiwuJj2QNCuR2FBjNM8zkBRFBHUMjxFLDABxABRGMCBk3x-AUywlNsBwLV8+TSFYEwomsl5bMc55FOU1IYDUiE4oZcyiFYAAPQZSEs-THmeMy4MPNk2BoagXns5BsuAJyXI0DyvJ8uSAlIALsW3ELWoUiKojSmKSt+OjBi0a4NJqrK6vi+yuKxWUBSGZBEiMdgiqYZIoD2JxfgOIUhrY9YGuQJqpLYQpQlPZxQiMS61zAxp2FwsQYHaOFE0UM8PA0ABtU9kEvABdFpN0CgAWOwAEZQPqR6wGetoOnhRRoO2a1rlYCZ3pmOY2sWZYwCOEszLRq4DiJkHZshHVlJFQ13RC0mbUUh17idJa3D9D1pUC70FWNf1OaDUJjtO2MLvZKYkxuu6M3Ap7IJet6pd6MIIgQNhfvdYHKKp8dMjDb5VQ8UVQShKEIlYxNQesLrdyGo8T2x88r0w7CCViBIkgIZ9X2K-dliIL9NN-ADdOAmH5fhxW5RRoaEKQlDzIwrDb1w-DncIvGSI4Mjygozjqe4rGJfXRMaqGZdVVXTxgkuuIGNqb8tJ2ArBVFzyzpavz2q3YKXG85jQrakgAmcsegA) From 20c0b0649b1f31e3fb3a571ba2a172cffdbd7a2e Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 16 Aug 2024 09:14:03 -0700 Subject: [PATCH 13/47] Correct typos --- DBSCE/Overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 784f4d9..7476cfa 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -74,7 +74,7 @@ Before we get into the specifics, we will introduce the terminology and design s ### Browser -In this document, "Browser" refers to a functionality in a web browser that is responsible for the DBSC protocol. This functionality will be implemented by Edge, Chrome (or their common engine), and other browsers that choose to implement DBSC/DBSC(E). +In this document, "Browser" refers to the functionality in a web browser that is responsible for the DBSC protocol. This functionality will be implemented by Edge, Chrome (or their common engine), and other browsers that choose to implement DBSC/DBSC(E). ### Relying Party (RP) @@ -103,7 +103,7 @@ DBSC(E) aims to support most of these scenarios. It does not define the device r ### Local Key Helper -DBSC(E) introduced the concept of `Local Key Helper` which can be mapped to the `TPM` or any `Key generation helper` for the consumer case. +DBSC(E) introduces the concept of `Local Key Helper` which can be mapped to the `TPM` or any `Key generation helper` for the consumer case. **Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) @@ -127,7 +127,7 @@ Note: Above are examples of Local Key Helpers that can be used for DBSC(E) key g ### Attestation Service: -A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. DBSC relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. +A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. ### Device Registration (Pre-Session) From 9659fc4818ee38a9eaa6f909dffd4ca7ba6ca22b Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 16 Aug 2024 11:01:33 -0700 Subject: [PATCH 14/47] Update nonce and clock-skew desc --- DBSCE/Overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 7476cfa..f27f23b 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -144,7 +144,7 @@ The high-level design is divided into two parts: 1. Key generation and validation before the session starts (DBSC(E) is focused on this part). 2. DBSC protocol applied with the generated keys (DBSC is focused on this part). -Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, ee differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. +Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. DBSC(E) (in contrast with DBSC): @@ -157,7 +157,7 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce`(challenge) and any extra parameters that the IdP wants to send to the Local Key Helper. - - As the Local Key Helper is public or thirdparty, and potentially can be from a different vendor, `nonce`(challenge) is essential to prevent the clock skew difference between the IdP and the Local Key Helper. The `nonce`(challenge) is expected to be a random number generated by the IdP. + - As the Local Key Helper is public or thirdparty, and potentially can be from a different vendor, `nonce`(challenge) is essential to prevent the clock-skew between the IdP and the Local Key Helper, especially for short lived Binding statements. `nonce`(challenge) is expected to be generated by the IdP/RP as a part of the request, a random number with time sensitivity, and is expected to be embedded in the binding statement. IdP will be able to validate nonce to ensure the binding statement is freshly issued. - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. 1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce`(challenge) sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. From 4146174db2c6e232499814704c2828130fd4ef76 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 16 Aug 2024 16:53:12 -0700 Subject: [PATCH 15/47] Address feedback on wording --- DBSCE/Overview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index f27f23b..8a8a60b 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -56,11 +56,11 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' ## Overview -Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to the existing [DBSC](https://github.com/wicg/dbsc) proposal. It refines the key generation mechanism resulting in additional security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy true device binding for any browser session, hence protecting against session hijacking and credential theft. +Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to the existing [DBSC](https://github.com/wicg/dbsc) proposal. It refines the key generation mechanism resulting in additional security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy enhanced/customised device binding for any browser session, hence protecting against session hijacking and cookie theft. ## Why DBSC(E)? -While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during the initial web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own credentials (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. +While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during the initial web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own binding keys (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. DBSC(E) aims to mitigate this risk by introducing the concept of credential generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the device. It guaratees any given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as "clean room"). With DBSC(E), the malware will not be able to compromise a device even during signin/login. Device registration is also expected to be a once-in-a-lifetime operation, and hence the user will not be required to perform this operation again, reducing opportunities for malware to extract session credentials the device. @@ -144,7 +144,7 @@ The high-level design is divided into two parts: 1. Key generation and validation before the session starts (DBSC(E) is focused on this part). 2. DBSC protocol applied with the generated keys (DBSC is focused on this part). -Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and align with the perf goals for specific services. +Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, we differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the DBSC(E) protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and aligns with the perf goals for specific services. DBSC(E) (in contrast with DBSC): @@ -188,7 +188,7 @@ Highlights: #### IDP Calls Public Local Key Helper -In Enterprise, it is a valid use case to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where these are separate entities and probably from different vendors below. +In Enterprise, and some consumer use cases, it is a valid use case to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where these are separate entities and probably from different vendors below. For easy mapping with the existing DBSC proposal, please note: From 874b514ad40ea2f1c3b7f6ecfbc72cb484706148 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 19 Aug 2024 12:10:00 -0700 Subject: [PATCH 16/47] Address feedback --- DBSCE/DBSC(E).svg | 2 +- DBSCE/DBSC(E).txt | 2 +- DBSCE/Overview.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/DBSCE/DBSC(E).svg b/DBSCE/DBSC(E).svg index 6fa4ae6..24bce9c 100644 --- a/DBSCE/DBSC(E).svg +++ b/DBSCE/DBSC(E).svg @@ -1 +1 @@ -%0Aparticipant%20%22%3Ccolor%3A%23blue%3EAttestation%20Service%22%20as%20s%0Aparticipant%20%22%3Ccolor%3A%23blue%3ELocalKeyHelper%2FTPM%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%5Cn%3Ccolor%3A%23blue%3ERP%2FIDP%22%20as%20w%0A%0Aautonumber%201%0Ab-%3Ew%3A%20sign-in%20flow%20%0Aw-%3Eb%3A%20%3Ccolor%3A%23blue%3E302%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%2C%20..%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%3Ccolor%3A%23blue%3Ebrowser%20pre-generates%20keys%5Cnbased%20on%20headers%5Cn%5Cn%3Ccolor%3A%23blue%3EcurrentHelperId%3D%5Cnevaluate%20policy%20for%20%5Cn(Server%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%2Cchallenge%2CextraParams%3F)%5Cn%20pre%20generates%20key%20and%20attestation%0At-%3Et%3A%20%3Ccolor%3A%23blue%3EgenerateKey()%0Anote%20over%20t%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Es%3A%20%3Ccolor%3A%23blue%3EgenerateBindingStatement%5Cn(publicKey%2C%20AIK%2C%20challenge)%0As-%3Et%3A%20%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%7D%0At-%3Eb%3A%20return%20public%20key%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20%3Ccolor%3A%23blue%3ECache%20the%20key%20for%20server%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3ELoad%20sign-in%5CnSec-Session-Keys%3A%20KeyId%2C%5CnBinding%20Statement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims...%7D%0Aw-%3Ew%3A%20%3Ccolor%3A%23blue%3Evalidate%20signature%20on%20the%20%5Cnbinding%20statement%20and%20challenge%5Cnstore%20thumbprint%2C%20KeyId%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%2C%5Cn%3Ccolor%3A%23blue%3EKeyId%2C%20extraParams%3C%2Fcolor%3E%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2Cpublic%20key%2C%20extraParams%3F..)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%5Cn%3Ccolor%3A%23blue%3Evalidate%20the%20JWT%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn%3Ccolor%3A%23blue%3E%22extraParams%22%3A%3Ccustom..%3E%7D%22%22%20%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%5Cn%3Ccolor%3A%23blue%3Echallenge%2C%20extraParams...%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendAttestation ServiceLocalKeyHelper/TPMBrowserServerRP/IDPsign-in flow 1 3022 Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2, ..], HelperCacheTimebrowser pre-generates keysbased on headerscurrentHelperId=evaluate policy for (Server, [HelperId1, HelperId2...])request create keypair 3 (serverUrl,challenge,extraParams?) pre generates key and attestationgenerateKey()4 For Enterprise, this call will be platformbased & generates device attestationgenerateBindingStatement5 (publicKey, AIK, challenge)BindingStatement6 {challenge, thumbprint(publicKey), extraClaims}return public key &7 BindingStatement{challenge, thumbprint(publicKey), extraClaims?..}Cache the key for serverLoad sign-in8 Sec-Session-Keys: KeyId,Binding Statement{challenge, thumbprint(publicKey), extraClaims...}validate signature on the 9 binding statement and challengestore thumbprint, KeyId200 w/signed-in content, response includes header to start secure session.  10 Header: Sec-Session-Registration: session_identifier=..., challenge=...,KeyId, extraParams(challenge required for private key proof of possession)browser initiates session bindingbased on header presencecreate JWT w/challengerequest sign JWT  11 (challenge,public key, extraParams?..)return JWT signature12 POST /securesession/startsession 13 {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish sessionvalidate the JWT200 w/cookie and session ID14 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookie15 GET /somecontent16 200 w/content17 check if required cookies exist18 GET /somecontent19 200 w/content20 request deferred while we get cookies...GET /securesession/refresh 21 header: Sec-Session-Id: [session ID]40122 Header: Sec-Session-Challenge: session_identifier=..., challenge=..."extraParams":<custom..>} create JWT w/challengerequest sign JWT23 challenge, extraParams...return JWT signature24 GET /securesession/refresh 25 header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session ID26 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent27 200 w/some content28 alt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file +%0Aparticipant%20%22%3Ccolor%3A%23blue%3EAttestation%20Service%22%20as%20s%0Aparticipant%20%22%3Ccolor%3A%23blue%3ELocalKeyHelper%2FTPM%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%5Cn%3Ccolor%3A%23blue%3ERP%2FIDP%22%20as%20w%0A%0Aautonumber%201%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3E%20initiate%20%3C%2Fcolor%3E%20sign-in%20flow%20%0Aw-%3Eb%3A%20%3Ccolor%3A%23blue%3E302%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%2C%20..%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%3Ccolor%3A%23blue%3Ebrowser%20pre-generates%20keys%5Cnbased%20on%20headers%5Cn%5Cn%3Ccolor%3A%23blue%3EcurrentHelperId%3D%5Cnevaluate%20policy%20for%20%5Cn(Server%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%2Cchallenge%2CextraParams%3F)%5Cn%20pre%20generates%20key%20and%20attestation%0At-%3Et%3A%20%3Ccolor%3A%23blue%3EgenerateKey()%0Anote%20over%20t%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Es%3A%20%3Ccolor%3A%23blue%3EgenerateBindingStatement%5Cn(publicKey%2C%20AIK%2C%20challenge)%0As-%3Et%3A%20%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%7D%0At-%3Eb%3A%20return%20public%20key%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20%3Ccolor%3A%23blue%3ECache%20the%20key%20for%20server%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3ELoad%20sign-in%5CnSec-Session-Keys%3A%20KeyId%2C%5CnBinding%20Statement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims...%7D%0Aw-%3Ew%3A%20%3Ccolor%3A%23blue%3Evalidate%20signature%20on%20the%20%5Cnbinding%20statement%20and%20challenge%5Cnstore%20thumbprint%2C%20KeyId%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%2C%5Cn%3Ccolor%3A%23blue%3EKeyId%2C%20extraParams%3C%2Fcolor%3E%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2Cpublic%20key%2C%20extraParams%3F..)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%5Cn%3Ccolor%3A%23blue%3Evalidate%20the%20JWT%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn%3Ccolor%3A%23blue%3E%22extraParams%22%3A%3Ccustom..%3E%7D%22%22%20%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%5Cn%3Ccolor%3A%23blue%3Echallenge%2C%20extraParams...%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendAttestation ServiceLocalKeyHelper/TPMBrowserServerRP/IDP initiate  sign-in flow 1 3022 Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2, ..], HelperCacheTimebrowser pre-generates keysbased on headerscurrentHelperId=evaluate policy for (Server, [HelperId1, HelperId2...])request create keypair 3 (serverUrl,challenge,extraParams?) pre generates key and attestationgenerateKey()4 For Enterprise, this call will be platformbased & generates device attestationgenerateBindingStatement5 (publicKey, AIK, challenge)BindingStatement6 {challenge, thumbprint(publicKey), extraClaims}return public key &7 BindingStatement{challenge, thumbprint(publicKey), extraClaims?..}Cache the key for serverLoad sign-in8 Sec-Session-Keys: KeyId,Binding Statement{challenge, thumbprint(publicKey), extraClaims...}validate signature on the 9 binding statement and challengestore thumbprint, KeyId200 w/signed-in content, response includes header to start secure session.  10 Header: Sec-Session-Registration: session_identifier=..., challenge=...,KeyId, extraParams(challenge required for private key proof of possession)browser initiates session bindingbased on header presencecreate JWT w/challengerequest sign JWT  11 (challenge,public key, extraParams?..)return JWT signature12 POST /securesession/startsession 13 {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish sessionvalidate the JWT200 w/cookie and session ID14 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookie15 GET /somecontent16 200 w/content17 check if required cookies exist18 GET /somecontent19 200 w/content20 request deferred while we get cookies...GET /securesession/refresh 21 header: Sec-Session-Id: [session ID]40122 Header: Sec-Session-Challenge: session_identifier=..., challenge=..."extraParams":<custom..>} create JWT w/challengerequest sign JWT23 challenge, extraParams...return JWT signature24 GET /securesession/refresh 25 header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session ID26 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent27 200 w/some content28 alt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file diff --git a/DBSCE/DBSC(E).txt b/DBSCE/DBSC(E).txt index 7f9b626..89dfa1c 100644 --- a/DBSCE/DBSC(E).txt +++ b/DBSCE/DBSC(E).txt @@ -5,7 +5,7 @@ participant "Browser" as b participant "Server\nRP/IDP" as w autonumber 1 -b->w: sign-in flow +b->w: initiate sign-in flow w->b: 302\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2, ..], HelperCacheTime note over b:browser pre-generates keys\nbased on headers\n\ncurrentHelperId=\nevaluate policy for \n(Server, [HelperId1, HelperId2...]) b->t: request create keypair \n(serverUrl,challenge,extraParams?)\n pre generates key and attestation diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 8a8a60b..76b7131 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -62,7 +62,7 @@ Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during the initial web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own binding keys (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. -DBSC(E) aims to mitigate this risk by introducing the concept of credential generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the device. It guaratees any given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as "clean room"). With DBSC(E), the malware will not be able to compromise a device even during signin/login. Device registration is also expected to be a once-in-a-lifetime operation, and hence the user will not be required to perform this operation again, reducing opportunities for malware to extract session credentials the device. +DBSC(E) aims to mitigate this risk by introducing the concept of key generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the device. Enterprises are free to decide when and how to have the device bound keys generated and DBSC(E) allows for the possibility for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)). With DBSC(E), the malware makes it harder to compromise a device even during signin/login. Device registration is also expected to be a once-in-a-lifetime operation, and hence the user will not be required to perform this operation again, reducing opportunities for malware to extract session credentials the device. ## How does it integrate with DBSC? @@ -82,7 +82,7 @@ A web application that uses DBSC(E) protocol for cookie binding. This is referre ### Identity Provider (IdP) -IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. IDP and RP are same for the consumer use case and is referred to as `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). +IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. IDP and RP are same for the certain consumer/enterprise use cases and is referred to as `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). ### Device Registration Client @@ -109,7 +109,7 @@ DBSC(E) introduces the concept of `Local Key Helper` which can be mapped to the From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) - _Public local key helper_ or _third party_: Can be accessed by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP through a well-defined public protocol. A third party local key helper has a special deployment mechanism. -- _Private local key helper_ or _well known_ : Can be specific to an IdP. Typically owned by the IdP and will have a private protocol to communicate with the IdP. Comes with either OS or built into the browser. It assumed that well-known key helpers are **trusted and enabled by default** in a browser. A browser knows how to activate a well-known key helper. +- _Private local key helper_ or _well known_ : Can be specific to an IdP. Typically owned by the IdP and will have a private protocol to communicate with the IdP. Comes with either OS or built into the browser. It assumed that well-known key helpers are **trusted and enabled by default** in a browser and/or a given IDP. A browser knows how to activate a well-known key helper. The Local Key Helper is responsible for: From 8ed3c801d7448fbe37fb67868521951c2111a706 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 19 Aug 2024 12:33:15 -0700 Subject: [PATCH 17/47] Address feedback --- DBSCE/Overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 76b7131..9af2648 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -108,7 +108,7 @@ DBSC(E) introduces the concept of `Local Key Helper` which can be mapped to the From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) -- _Public local key helper_ or _third party_: Can be accessed by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP through a well-defined public protocol. A third party local key helper has a special deployment mechanism. +- _Public local key helper_ or _third party_: Can be accessed by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP through as defined in DBSC(E) protocol. A third party local key helper has a special deployment mechanism. We expect to loosely define the API and deployment mechanism in the upcoming specification, and will leave the specific implementation details to the vendors. However, we have provided examples of how this can look for a few platforms [below](#platform-examples). - _Private local key helper_ or _well known_ : Can be specific to an IdP. Typically owned by the IdP and will have a private protocol to communicate with the IdP. Comes with either OS or built into the browser. It assumed that well-known key helpers are **trusted and enabled by default** in a browser and/or a given IDP. A browser knows how to activate a well-known key helper. The Local Key Helper is responsible for: From c9e6774b0bd927244987f6e78fdcc3468b030b46 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 23 Aug 2024 22:25:29 -0700 Subject: [PATCH 18/47] Addressing feedback --- DBSCE/Overview.md | 20 +++++++++++--------- README.md | 4 ++-- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 9af2648..5846d95 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -33,7 +33,7 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' ## Authors - [Sameera Gajjarapu](sameera.gajjarapu@microsoft.com), Microsoft -- [Alexander Tokarev](alextok@microsoft.com), Microsoft +- [Aleksander Tokarev](alextok@microsoft.com), Microsoft ## Contributors @@ -60,9 +60,9 @@ Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to ## Why DBSC(E)? -While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during the initial web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own binding keys (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. +While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during any web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own binding keys (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. -DBSC(E) aims to mitigate this risk by introducing the concept of key generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the device. Enterprises are free to decide when and how to have the device bound keys generated and DBSC(E) allows for the possibility for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)). With DBSC(E), the malware makes it harder to compromise a device even during signin/login. Device registration is also expected to be a once-in-a-lifetime operation, and hence the user will not be required to perform this operation again, reducing opportunities for malware to extract session credentials the device. +DBSC(E) aims to mitigate this risk by introducing the concept of key generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the key. Enterprises can decide when and how to generate device bound keys, however, DBSC(E) allows for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, and hence the user will not be required to perform this operation again, reducing opportunities for malware to extract session credentials of the device.DBSC(E) makes it impossible for malware to compromise a device during signin/login, but DBSC(E) doesn't protect a given session if the malware is present during the device registration. ## How does it integrate with DBSC? @@ -82,13 +82,13 @@ A web application that uses DBSC(E) protocol for cookie binding. This is referre ### Identity Provider (IdP) -IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. IDP and RP are same for the certain consumer/enterprise use cases and is referred to as `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). +IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft Entra ID or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. IDP and RP are same for the certain consumer/enterprise use cases and is referred to as `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). ### Device Registration Client This is a pre-requisite for DBSC(E) to work. -Device Registration Client is a process where the user registers the device with the IdP and is expected to be a once-in-a-lifetime operation. +Device Registration Client is a process where the user or administrator registers the device with the IdP and is expected to be a once-in-a-lifetime protected operation. The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. @@ -99,12 +99,14 @@ One device registration client can manage multiple devices on the same physical - Device management software (MDM provider) - the device gets registered when the MDM is enrolled. - Third-party software vendor - the device gets registered according to the vendor rules. -DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol amd is only concerned with the keys generated in a "clean room" state and the management of the generated keys to prove device binding. +DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" state and the management of the generated keys to prove device binding. + ### Local Key Helper -DBSC(E) introduces the concept of `Local Key Helper` which can be mapped to the `TPM` or any `Key generation helper` for the consumer case. -**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. It can be Public or Private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. +DBSC(E) introduces the concept of `Local Key Helper`. + +**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) @@ -127,7 +129,7 @@ Note: Above are examples of Local Key Helpers that can be used for DBSC(E) key g ### Attestation Service: -A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. +A service that is responsible for verifying that the binding key is issued by the expected device and providing the attestation of the key to the IdP. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. ### Device Registration (Pre-Session) diff --git a/README.md b/README.md index 5d785dd..156e9e2 100644 --- a/README.md +++ b/README.md @@ -87,9 +87,9 @@ There are a few obvious considerations to ensure we achieve that goal: ### Enterprise support -While DBSC addresses a general problem of session hijacking, and can be applicable to any _browser_ consumer, it is possible to expand this protocol to better support enterprise use cases. By adding specifics to key generation and enabling the switch if there is a specific policy administered on the device, we can provide a more secure environment for enterprise users. This is the goal of DBSC(E), which is an extension to DBSC. The high-level design of DBSC(E) is described in the [DBSC(E) Overview](). +While DBSC addresses a general problem of session hijacking, and can be applicable to any _browser_ consumer, it is possible to expand this protocol to better support enterprise use cases. By adding specifics to key generation, we can provide a more secure environment for enterprise users. This is the goal of DBSC(E), which is an extension to DBSC. The high-level design of DBSC(E) is described in the [DBSC(E) Overview](). -DBSC(E) removes the vulnerability DBSC has, where a malware, if already present in the device during the key generation, can take over the session even if it is eventually bound to the device. By assuring a clean state key generation and introducing device key chaining, DBSC(E) can mitigate this vulnerability: More details about the importance of DBSC are here: [Why DBSC(E)?]() +DBSC(E) removes the vulnerability DBSC has, where a malware, if already present in the device during the key generation, can potentially take over the session. DBSC(E) proposes to mitigate this vulnerability by introducing device key chaining: More details about the importance of DBSC are here: [Why DBSC(E)?]() ## High level overview ![High level diagram](reg_and_refresh.svg) From 4b167e038a1fc0e6834439d6156ae87796674ed5 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 26 Aug 2024 10:50:56 -0700 Subject: [PATCH 19/47] Addressing feedback --- DBSCE/Overview.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 5846d95..89b1278 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -82,7 +82,7 @@ A web application that uses DBSC(E) protocol for cookie binding. This is referre ### Identity Provider (IdP) -IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft Entra ID or google.com authenticating with google. Note: The protocol doesn't change if the IdP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. IDP and RP are same for the certain consumer/enterprise use cases and is referred to as `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). +IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft Entra ID or google.com authenticating with google. Note: The protocol doesn't change if the IDP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. In the original [DBSC design](https://githuub.com/wicg/dbsc), IDP and RP are the same entity, and referred to as `server`. ### Device Registration Client @@ -119,19 +119,19 @@ The Local Key Helper is responsible for: - Producing signatures with the binding key - Cleanup of the binding key and its artifacts (when the user clears the browser session or the key is unused for a long time). -#### Platform Examples +#### Platform Requirements - Windows: Please refer to the Windows Local Key Helper [here](./KeyGeneration.md#local-key-helper-on-windows) for an example of a Local Key Helper. - MacOS: TBD - Android:TBD -Note: Above are examples of Local Key Helpers that can be used for DBSC(E) key generation. Any platform is free to build a version of this, as long as the API is consistent with the protocol. +Note: Above are platform specifications for Local Key Helpers that can be used for DBSC(E) key generation. Any platform is free to build a version of this, as long as the API is consistent with the protocol. A detailed protocol will be documented under the DBSC(E) spec. ### Attestation Service: A service that is responsible for verifying that the binding key is issued by the expected device and providing the attestation of the key to the IdP. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. -### Device Registration (Pre-Session) +### Device Registration Any enterprise user is expected to either use a device issued by their organization or register their personal device with the organization. The device registration is expected to be a once-in-a-lifetime operation, and the user is expected to perform this operation in a clean room environment. @@ -159,7 +159,7 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce`(challenge) and any extra parameters that the IdP wants to send to the Local Key Helper. - - As the Local Key Helper is public or thirdparty, and potentially can be from a different vendor, `nonce`(challenge) is essential to prevent the clock-skew between the IdP and the Local Key Helper, especially for short lived Binding statements. `nonce`(challenge) is expected to be generated by the IdP/RP as a part of the request, a random number with time sensitivity, and is expected to be embedded in the binding statement. IdP will be able to validate nonce to ensure the binding statement is freshly issued. + - As the Local Key Helper is public or third party, and potentially can be from a different vendor, `nonce`(challenge) is essential to prevent replay of cached binding key/binding statements from a different device and to prevent the clock-skew between the IdP and the Local Key Helper, especially for short lived Binding statements. `nonce`(challenge) is expected to be generated by the IdP/RP as a part of the request, a random number with time sensitivity, and is expected to be embedded in the binding statement. IdP will be able to validate nonce to ensure the binding statement is freshly issued. - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. 1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce`(challenge) sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. @@ -184,13 +184,13 @@ This is the same use case elaborated in the high level design [above](#high-leve Highlights: -- Auth tokens are not mentioned in the DBSC(E) high level design, as they are optional for the consumer use case. However, for the enterprise use case, the IdP can generate the auth tokens and embed the thumbprint of the public key in the token. +- Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of identity token. In such case, the IdP can generate the auth tokens and embed the thumbprint of the public key in the token. - The token can be delivered to the RP directly through an API instead of a header based response. - The tokens also contain the thumpbrint of the public key, and the RP can validate the thumbprint of the public key from the token. #### IDP Calls Public Local Key Helper -In Enterprise, and some consumer use cases, it is a valid use case to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where these are separate entities and probably from different vendors below. +In many use cases, it is also a valid to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where these are separate entities and probably from different vendors below. For easy mapping with the existing DBSC proposal, please note: @@ -207,9 +207,9 @@ A special case is for enterprises that already have `well-known` Local Key Helpe Highlights: -- Since the IDP (a specific URL) is trusted in this use case, the browser can skip the `nonce`(challenge) and directly call the Local Key Helper. -- Attestation Service is optional as it is assumed that the IDP is trusted and can validate the binding statement. In other words, Attestation Service is assumed to be part of the IDP in this case. -- The headers are modeled after confidential client flow(OAuth2) implemented with [Microsoft IDP](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens) as an example. It is possible to replace `Microsoft` with `Okta` and achieve the same flow. +- Since proof of device is made with SSO headers, the browser can skip the `nonce`(challenge) and directly call the Local Key Helper. +- IDP can validate the binding statement, i.e., the binding key belongs to the correct device. +- The headers are modeled with [Microsoft IDP](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens) as an example. It is possible to replace `Microsoft` with `Okta` and achieve the same flow if Okta complies with the device registration. ### Cleanup of the binding keys and their artifacts @@ -217,5 +217,6 @@ For the health of the operating system and user privacy, it is important to clea The cleanup can occur: +- When cookies are expired. - On demand, when the user decides to clear browser cookies. - Automatically, when a key hasn't been used for a long time (N days) to keep the OS healthy. From 960ef9aa9d10bdfe3efc2e4fd2fca8ae5acc099f Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 26 Aug 2024 12:26:14 -0700 Subject: [PATCH 20/47] Move key generation definitions to overview. --- DBSCE/KeyGeneration.md | 34 -------------------------------- DBSCE/Overview.md | 44 ++++++++++++++++++++++++++++++++++++------ 2 files changed, 38 insertions(+), 40 deletions(-) diff --git a/DBSCE/KeyGeneration.md b/DBSCE/KeyGeneration.md index d504a8a..bfe3c0a 100644 --- a/DBSCE/KeyGeneration.md +++ b/DBSCE/KeyGeneration.md @@ -55,37 +55,3 @@ When the browser needs to communicate with a local key helper. It uses its ID to A well-known local key helper list on Windows is a list of helperId to clsid, that either harcoded or predefined in the browser settings. -### **Attestation Service**: - -A service that is responsible for verifying the device registration and providing the attestation to the IdP. The attestation service can be owned by the IdP or a third party. Before defining the attestation service, let us get familiar with the building blocks of binding and proof of binding. - -There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the _binding key_, the _attestation key_, and the _binding statement_. - -#### **Binding Key**: - -A _binding key_ is an asymmetric key pair that is used to bind an auth cookie.It is identified by a key ID and it is the responsibility of the browser to remember which key ID corresponds to which Local Key Helper and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. - -This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware running on the device. In the context DBSC(E), the binding key is generated during the device registration process, and hence is guaranteed to be attack free if generated in a clean room environment. - -#### **Binding Statement**: - -Additonal to the binding key, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. - -#### **Attestation Key** - -An _attestation key_ is generated during the device registration process and has the following properties: - - 1. It signs only the private/other keys that reside in the same secure enclave as the attestation key. - 2. It cannot sign any external payload, or if it signs, it cannot generate an output that can be interpreted as an attestation statement. - -Since the attestation key can be uploaded only once to the backend at the moment of device registration, in the clean room, and there is no need to change this key unless the device loses it (Could be due to key rotation or similar operations). - -#### **Binding Statement - Generation and Validation**: - -The **attestation key**, hence, can be used to attest that the **binding key** belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an **attestation statement**. Depending on the specific implementation, this **attestation statement** itself can be a **binding statement**, or it can be sent to an attestation service to produce the final binding statement. - -The validation of the **binding statement** authenticates the device by using device ID to find the corresponding attestation key. The validation component verifies the **attestation statement**, and it can understand that such a statement cannot be generated, unless the private key resides in the same secure enclave when signed by the **attestation key**. Hence, a valid attestation statement means that both the attestation key and the binding key belong to the same device. The validation component can be part of the attestation service for public local key helpers, or part of an IdP for private local key helper. - -This is not the only way to ensure that the binding key and the device key belong to the same device, and having the **attestation key** and the **attestation service** is not mandatory for producing a **binding statement**. That is why the protocol specifics of checking the binding are out of scope for this document. The focus of DBSC(E) is to only establish important properties of the binding statement. - -Binding statements can be long-lived or short-lived. If an IdP can perform proof of device, it can use long-lived binding statements based on attestation keys to avoid extra network calls. IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements to prevent forgery of the binding statement from a different device. To avoid binding statement forgery, a short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement. diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 89b1278..069ea0e 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -101,6 +101,11 @@ One device registration client can manage multiple devices on the same physical DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" state and the management of the generated keys to prove device binding. +### Device Registration + +Any enterprise user is expected to either use a device issued by their organization or register their personal device with an organization. The device registration is expected to be a once-in-a-lifetime protected operation, and the user is expected to perform this operation with a clean room environment. + +![DeviceRegistration](./DeviceRegistration.svg) ### Local Key Helper @@ -127,15 +132,42 @@ The Local Key Helper is responsible for: Note: Above are platform specifications for Local Key Helpers that can be used for DBSC(E) key generation. Any platform is free to build a version of this, as long as the API is consistent with the protocol. A detailed protocol will be documented under the DBSC(E) spec. -### Attestation Service: +### Attestation Service A service that is responsible for verifying that the binding key is issued by the expected device and providing the attestation of the key to the IdP. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. -### Device Registration +#### Key Generation Specifics -Any enterprise user is expected to either use a device issued by their organization or register their personal device with the organization. The device registration is expected to be a once-in-a-lifetime operation, and the user is expected to perform this operation in a clean room environment. +This section defines the artifacts of binding and how they help establish proof of binding. -![DeviceRegistration](./DeviceRegistration.svg) +There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the [binding key](#binding-key), the [attestation key](#attestation-key), and the [binding statement](#binding-statement). + +#### **Binding Key**: + +A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a key ID and it is the responsibility of the browser to remember key ID mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. + +This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key)which is created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), if the binding key is generated during the [device registration process in a clean room](#device-registration), it is protected from any malware trying to infilterate the session. + +#### **Attestation Key** + +An _attestation key_ is generated during the device registration process and has the following properties: + + 1. It signs only the private/other keys that reside in the same secure enclave as the attestation key. + 2. It cannot sign any external payload, or if it signs, it cannot generate an output that can be interpreted as an attestation statement. + +Since the attestation key can be uploaded only once to the backend at the moment of device registration, in the clean room, and there is no need to change this key unless the device loses it (Could be due to key rotation or similar operations). + +The **attestation key**, hence, can be used to attest that the **binding key** belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an **attestation statement**. Depending on the specific implementation, this **attestation statement** itself can be a **binding statement**, or it can be sent to an attestation service to produce the final binding statement. + +#### **Binding Statement - Generation and Validation** + +Additonal to the binding key, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. + +The validation of the **binding statement** authenticates the device by using device ID to find the corresponding attestation key. The validation component verifies the **attestation statement**, and it can understand that such a statement cannot be generated, unless the private key resides in the same secure enclave when signed by the **attestation key**. Hence, a valid attestation statement means that both the attestation key and the binding key belong to the same device. The validation component can be part of the attestation service for public local key helpers, or part of an IdP for private local key helper. + +This is not the only way to ensure that the binding key and the device key belong to the same device, and having the **attestation key** and the **attestation service** is not mandatory for producing a **binding statement**. That is why the protocol specifics of checking the binding are out of scope for this document. The focus of DBSC(E) is to only establish important properties of the binding statement. + +Binding statements can be long-lived or short-lived. If an IdP can perform proof of device, it can use long-lived binding statements based on attestation keys to avoid extra network calls. IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements to prevent forgery of the binding statement from a different device. To avoid binding statement forgery, a short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement. ## High-Level Design @@ -146,7 +178,7 @@ The high-level design is divided into two parts: 1. Key generation and validation before the session starts (DBSC(E) is focused on this part). 2. DBSC protocol applied with the generated keys (DBSC is focused on this part). -Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, we differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own local key helper as a part of the IdP. We also optimize the DBSC(E) protocol for RP and IdP as the same service (google client authenticated by google service as an example), since it simplifies the protocol and aligns with the perf goals for specific services. +Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, we differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own private local key helpers. DBSC(E) protocol also provides multiple extension points that simplify and improve performance for specific scenarios. The [DBSC(E) use cases](#dbsce-use-cases) section expands on some of these scenarios. DBSC(E) (in contrast with DBSC): @@ -186,7 +218,7 @@ Highlights: - Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of identity token. In such case, the IdP can generate the auth tokens and embed the thumbprint of the public key in the token. - The token can be delivered to the RP directly through an API instead of a header based response. -- The tokens also contain the thumpbrint of the public key, and the RP can validate the thumbprint of the public key from the token. +- The tokens also contain the thumpbrint of the public key, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. #### IDP Calls Public Local Key Helper From fdacec8cb47f4388334584e6ae117faa434f5060 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 26 Aug 2024 12:34:57 -0700 Subject: [PATCH 21/47] Update TOC --- DBSCE/Overview.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 069ea0e..ebf2a3f 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -8,20 +8,25 @@ - [Overview](#overview) - [Why DBSC(E)?](#why-dbsce) - [How does it integrate with DBSC?](#how-does-it-integrate-with-dbsc) - - [High-Level Design](#high-level-design) - [Terminology](#terminology) - [Browser](#browser) - [Relying Party (RP)](#relying-party-rp) - [Identity Provider (IdP)](#identity-provider-idp) - [Device Registration Client](#device-registration-client) + - [Device Registration](#device-registration) - [Local Key Helper](#local-key-helper) - - [Platform Examples:](#platform-examples) - - [Attestation Service:](#attestation-service) - - [Device Registration (Pre-Session)](#device-registration-pre-session) + - [Platform Requirements](#platform-requirements) + - [Attestation Service](#attestation-service) + - [Key Generation Specifics](#key-generation-specifics) + - [**Binding Key**](#binding-key) + - [**Attestation Key**](#attestation-key) + - [**Binding Statement**](#binding-statement) + - [High-Level Design](#high-level-design) - [DBSC(E) use cases](#dbsce-use-cases) - - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) + - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) - [IDP Calls Private Local Key Helper](#idp-calls-private-local-key-helper) + - [Cleanup of the binding keys and their artifacts](#cleanup-of-the-binding-keys-and-their-artifacts) @@ -142,13 +147,13 @@ This section defines the artifacts of binding and how they help establish proof There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the [binding key](#binding-key), the [attestation key](#attestation-key), and the [binding statement](#binding-statement). -#### **Binding Key**: +##### **Binding Key** A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a key ID and it is the responsibility of the browser to remember key ID mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key)which is created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), if the binding key is generated during the [device registration process in a clean room](#device-registration), it is protected from any malware trying to infilterate the session. -#### **Attestation Key** +##### **Attestation Key** An _attestation key_ is generated during the device registration process and has the following properties: @@ -159,7 +164,7 @@ Since the attestation key can be uploaded only once to the backend at the moment The **attestation key**, hence, can be used to attest that the **binding key** belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an **attestation statement**. Depending on the specific implementation, this **attestation statement** itself can be a **binding statement**, or it can be sent to an attestation service to produce the final binding statement. -#### **Binding Statement - Generation and Validation** +##### **Binding Statement** Additonal to the binding key, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. From e7af10dfe28039b830d66d3a5278465345e1bf08 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 26 Aug 2024 21:01:12 -0700 Subject: [PATCH 22/47] Address feedback --- DBSCE/Overview.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index ebf2a3f..02b9cff 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -18,9 +18,9 @@ - [Platform Requirements](#platform-requirements) - [Attestation Service](#attestation-service) - [Key Generation Specifics](#key-generation-specifics) - - [**Binding Key**](#binding-key) - - [**Attestation Key**](#attestation-key) - - [**Binding Statement**](#binding-statement) + - [Binding Key](#binding-key) + - [Attestation Key](#attestation-key) + - [Binding Statement](#binding-statement) - [High-Level Design](#high-level-design) - [DBSC(E) use cases](#dbsce-use-cases) - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) @@ -116,12 +116,14 @@ Any enterprise user is expected to either use a device issued by their organizat DBSC(E) introduces the concept of `Local Key Helper`. -**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. +**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. DBSC(E) defines browser interaction with _Local key helpers_ for each platform. Those details are outlined in [KeyGeneration.md](./KeyGeneration.md). -From the deployment point of view there are two types of local key helpers: _well-known_(_private_) and _third party_(_public_) +From the deployment point of view there are two types of local key helpers: _private_ and _public_ -- _Public local key helper_ or _third party_: Can be accessed by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP through as defined in DBSC(E) protocol. A third party local key helper has a special deployment mechanism. We expect to loosely define the API and deployment mechanism in the upcoming specification, and will leave the specific implementation details to the vendors. However, we have provided examples of how this can look for a few platforms [below](#platform-examples). -- _Private local key helper_ or _well known_ : Can be specific to an IdP. Typically owned by the IdP and will have a private protocol to communicate with the IdP. Comes with either OS or built into the browser. It assumed that well-known key helpers are **trusted and enabled by default** in a browser and/or a given IDP. A browser knows how to activate a well-known key helper. +- _Public local key helper_: Expected to have a well-documented implementation and can be used by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP as defined in DBSC(E) protocol. +- _Private local key helper_ : Is specific to an IdP. Can be only used by a specific IDP that owns the implementation and will have a private protocol to communicate with the IdP. Comes with either OS or built into the browser. + +Additionally, some _Local key helpers_ are classified as `well-known` (a special case of `private`) and will be **enabled by default** in a browser and/or a given IDP. A browser knows how to activate a well-known key helper without needing an admin-side configuration. The Local Key Helper is responsible for: @@ -147,24 +149,24 @@ This section defines the artifacts of binding and how they help establish proof There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the [binding key](#binding-key), the [attestation key](#attestation-key), and the [binding statement](#binding-statement). -##### **Binding Key** +##### Binding Key A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a key ID and it is the responsibility of the browser to remember key ID mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. -This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key)which is created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), if the binding key is generated during the [device registration process in a clean room](#device-registration), it is protected from any malware trying to infilterate the session. +This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key)which is created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), however, as long as the [device registration process is executed with a clean room environment](#device-registration), binding key can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. -##### **Attestation Key** +##### Attestation Key An _attestation key_ is generated during the device registration process and has the following properties: 1. It signs only the private/other keys that reside in the same secure enclave as the attestation key. 2. It cannot sign any external payload, or if it signs, it cannot generate an output that can be interpreted as an attestation statement. -Since the attestation key can be uploaded only once to the backend at the moment of device registration, in the clean room, and there is no need to change this key unless the device loses it (Could be due to key rotation or similar operations). +The attestation key also can be uploaded only once to the backend at the moment of device registration, in the clean room, and there is no need to change this key unless the device loses it (Could be due to key rotation or similar operations). The **attestation key**, hence, can be used to attest that the **binding key** belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an **attestation statement**. Depending on the specific implementation, this **attestation statement** itself can be a **binding statement**, or it can be sent to an attestation service to produce the final binding statement. -##### **Binding Statement** +##### Binding Statement Additonal to the binding key, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. From 6925b9716e8014e5c28df744df1bccd5ff656770 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Tue, 27 Aug 2024 13:09:07 -0700 Subject: [PATCH 23/47] Update DBSCE/Overview.md Co-authored-by: Tim Cappalli --- DBSCE/Overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 02b9cff..3da6d6e 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -193,7 +193,7 @@ DBSC(E) (in contrast with DBSC): Highlights: -Note: All references to RP, IDP are equivalent to `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). +Note: All references to RP, IDP are equivalent to `server` in the original [DBSC design](https://github.com/wicg/dbsc). 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. From fd96c6627b2c54e9ae50ef20b3701d071248cc98 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Tue, 27 Aug 2024 13:15:44 -0700 Subject: [PATCH 24/47] Add draft notice for KeyGeneration file --- DBSCE/KeyGeneration.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/DBSCE/KeyGeneration.md b/DBSCE/KeyGeneration.md index bfe3c0a..5a4caa8 100644 --- a/DBSCE/KeyGeneration.md +++ b/DBSCE/KeyGeneration.md @@ -1,3 +1,7 @@ + +!!! DRAFT - Please note this page is still in draft as we work on platform specific details + + ### Local key helper on Windows On Windows, a Local key helper is a COM class. A COM interface that the local key helper implements is TBD (working name for this document is ILocalKeyHelper) From 8f4ba8038784b5542c3fbbdd65f0d3b3eea4d03b Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Tue, 27 Aug 2024 13:54:01 -0700 Subject: [PATCH 25/47] Update introduction --- DBSCE/Overview.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 3da6d6e..ed439ce 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -65,9 +65,9 @@ Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to ## Why DBSC(E)? -While the original DBSC proposal is focused on providing a mechanism for browsers to bind session credentials to a device, it still remains vulnerable to malware that can run on a device during any web application signin/login. If a malware happens to be already running in the device, it can force the user to login, and provide its own binding keys (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. +While the original DBSC proposal enables browsers to bind session cookies to a device, it still remains vulnerable to on devie malware. Such a malware can inject its own binding keys if it is present during signin/session establishment, or it can force the user to signin, and provide its own binding keys (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. Hence a temporary malware presence in the system can result in permanent session compromise in certain cases. -DBSC(E) aims to mitigate this risk by introducing the concept of key generation (asymmetric device-bound key) during the device registration and binds all the future sessions to the key. Enterprises can decide when and how to generate device bound keys, however, DBSC(E) allows for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, and hence the user will not be required to perform this operation again, reducing opportunities for malware to extract session credentials of the device.DBSC(E) makes it impossible for malware to compromise a device during signin/login, but DBSC(E) doesn't protect a given session if the malware is present during the device registration. +DBSC(E) aims to mitigate this risk by introducing the concept of once-in-a-lifetime protected [device registration](#device-registration) operation and binds all the future sessions to a binding key that can be cryptographically proven to be on the same device. DBSC(E) allows for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an enterprise registering a device before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, hence the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. DBSC(E) makes it impossible for malware to compromise a device during signin/login, but DBSC(E) doesn't protect a given session if the malware is present during the device registration or if the malware is persistent on the device and uses device-bound sessions to exfiltrate application data rather than the sessions. ## How does it integrate with DBSC? @@ -104,7 +104,9 @@ One device registration client can manage multiple devices on the same physical - Device management software (MDM provider) - the device gets registered when the MDM is enrolled. - Third-party software vendor - the device gets registered according to the vendor rules. -DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" state and the management of the generated keys to prove device binding. +DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" and the management of the generated keys to prove device binding. + +TODO: Add a definition of cleanroom and examples ### Device Registration @@ -116,7 +118,7 @@ Any enterprise user is expected to either use a device issued by their organizat DBSC(E) introduces the concept of `Local Key Helper`. -**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IdP/OS) or can be installed by a provider in compliance with the protocol expanded below. DBSC(E) defines browser interaction with _Local key helpers_ for each platform. Those details are outlined in [KeyGeneration.md](./KeyGeneration.md). +**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IDP/OS) or can be installed by a provider in compliance with the protocol expanded below. DBSC(E) defines browser interaction with _Local key helpers_ for each platform. Those details are outlined in [KeyGeneration.md](./KeyGeneration.md). From the deployment point of view there are two types of local key helpers: _private_ and _public_ @@ -127,13 +129,13 @@ Additionally, some _Local key helpers_ are classified as `well-known` (a special The Local Key Helper is responsible for: -- Generation of the binding key and producing binding statements (see below) -- Producing signatures with the binding key -- Cleanup of the binding key and its artifacts (when the user clears the browser session or the key is unused for a long time). +- Generation of the [binding key](#binding-key) and producing [binding statements](#binding-statement) (see below). +- Producing signatures with the binding key. +- Cleanup of the [binding key](#binding-key) and its artifacts (when the user clears the browser session or the key is unused for a long time). #### Platform Requirements -- Windows: Please refer to the Windows Local Key Helper [here](./KeyGeneration.md#local-key-helper-on-windows) for an example of a Local Key Helper. +- [Windows](./KeyGeneration.md#local-key-helper-on-windows) - MacOS: TBD - Android:TBD @@ -153,7 +155,7 @@ There are three artifacts that are generated during/after the device registratio A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a key ID and it is the responsibility of the browser to remember key ID mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. -This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key)which is created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), however, as long as the [device registration process is executed with a clean room environment](#device-registration), binding key can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. +This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key) which is created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), however, as long as the [device registration process is executed with a clean room environment](#device-registration), binding key can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. ##### Attestation Key @@ -193,7 +195,7 @@ DBSC(E) (in contrast with DBSC): Highlights: -Note: All references to RP, IDP are equivalent to `server` in the original [DBSC design](https://github.com/wicg/dbsc). +Note: All references to RP, IDP are equivalent to `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. From 8f519da7adc085d21b30e03d7dc8d5691eddbe39 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Tue, 27 Aug 2024 15:02:48 -0700 Subject: [PATCH 26/47] Update nonce for Public Local Key Helper case --- DBSCE/Overview.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index ed439ce..d6af3c1 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -195,17 +195,19 @@ DBSC(E) (in contrast with DBSC): Highlights: -Note: All references to RP, IDP are equivalent to `server` in the original [DBSC design](https://githuub.com/wicg/dbsc). +Note: All references to RP, IDP are equivalent to `server` in the original [DBSC design](https://github.com/wicg/dbsc). 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce`(challenge) and any extra parameters that the IdP wants to send to the Local Key Helper. - - As the Local Key Helper is public or third party, and potentially can be from a different vendor, `nonce`(challenge) is essential to prevent replay of cached binding key/binding statements from a different device and to prevent the clock-skew between the IdP and the Local Key Helper, especially for short lived Binding statements. `nonce`(challenge) is expected to be generated by the IdP/RP as a part of the request, a random number with time sensitivity, and is expected to be embedded in the binding statement. IdP will be able to validate nonce to ensure the binding statement is freshly issued. + - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. + - For all _public local key helpers_, e.d., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _shortlived_. If `nonce` is not shortlived, it is possible to steal the `bindingStatement` and the `bindingKey` from a device controlled by the attacker and to be able to bind the cookies to the malicious `bindingKey`. The allowance for long lived `nonce` is possible with _private local key helpers_ and covered [later](#idp-calls-private-local-key-helper). + - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the binding statement, the IDP will be able to validate `nonce` to ensure the `binding statement` is issued recently. + - `nonce` is generated by the IdP/RP as a part of the request, a random number with time sensitivity, and must be embedded in the binding statement. IdP will be able to validate nonce to ensure the binding statement is freshly issued. - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. -1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce`(challenge) sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. +1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. - - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce`(challenge) and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](./KeyGeneration.md#binding-statement). + - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](./KeyGeneration.md#binding-statement). - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the `binding statement`. It is intentionally left undefined, and can be customized. - Local Key Helper can optionally signal the browser to cache the Binding Statement in the browser. This is to avoid repeated calls to the Local Key Helper for the same IdP. The browser can cache the Binding Statement for a certain time, and if the IdP requests a new key within that time, the browser can return the cached Binding Statement. TBD define under which conditions. @@ -242,13 +244,13 @@ For easy mapping with the existing DBSC proposal, please note: #### IDP Calls Private Local Key Helper -A special case is for enterprises that already have `well-known` Local Key Helpers, which are expected to be trusted and enabled by default in a browser. Here, since the browser can trust a given IDP (based on the URL and a policy mapping) and can trust the IDP to invoke the appropriate Local Key Helper (refer [Local key helper on Windows](./KeyGeneration.md#local-key-helper-on-windows)), there are a few optimizations that can be made to the protocol, in skipping the `nonce`(challenge) and reducing the number of round trips between the IDP and the Local Key Helper. +A special case is for enterprises that already have `well-known` Local Key Helpers, which are expected to be trusted and enabled by default in a browser. Here, since the browser can trust a given IDP (based on the URL and a policy mapping) and can trust the IDP to invoke the appropriate Local Key Helper (refer [Local key helper on Windows](./KeyGeneration.md#local-key-helper-on-windows)), there are a few optimizations that can be made to the protocol, in skipping the `nonce` and reducing the number of round trips between the IDP and the Local Key Helper. ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) Highlights: -- Since proof of device is made with SSO headers, the browser can skip the `nonce`(challenge) and directly call the Local Key Helper. +- Since proof of device is made with SSO headers, the browser can skip the `nonce` and directly call the Local Key Helper. - IDP can validate the binding statement, i.e., the binding key belongs to the correct device. - The headers are modeled with [Microsoft IDP](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens) as an example. It is possible to replace `Microsoft` with `Okta` and achieve the same flow if Okta complies with the device registration. From 009221e2f8539d757d41cda6449ac626d9a9f1e4 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Tue, 27 Aug 2024 15:29:37 -0700 Subject: [PATCH 27/47] Update PrivateLocalKeyHelper with generic headers --- DBSCE/IDPCallsPrivateLocalKeyHelper.svg | 2 +- DBSCE/IDPCallsPrivateLocalKeyHelper.txt | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/DBSCE/IDPCallsPrivateLocalKeyHelper.svg b/DBSCE/IDPCallsPrivateLocalKeyHelper.svg index 299c993..5db2dba 100644 --- a/DBSCE/IDPCallsPrivateLocalKeyHelper.svg +++ b/DBSCE/IDPCallsPrivateLocalKeyHelper.svg @@ -1 +1 @@ -title%20IdP%20calls%20a%20private%20Local%20Key%20Helper%0A%0Aautonumber%201%0Aparticipant%20%22Relying%20Party%22%20as%20W%0Aparticipant%20%22IdP%22%20as%20I%0Aparticipant%20%22Browser%22%20as%20B%0Aparticipant%20%22Local%20Key%20Helper%22%20as%20P%0A%0Anote%20over%20W%2C%20P%3A%20IdP%20life...%0AB-%3E%3EI%3A%20Any%20request%0AI-%3E%3EB%3A%20Any%20response%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0AB-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0Anote%20over%20W%2C%20P%3A%20Sign%20in...%0AW-%3E%3EB%3A%20Start%20sign%20in%20(302)%5CnSec-Session-Registration%3A%20path%2C%20RPChallenge%2C...%20%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0AB-%3E%3EB%3A%20Check%20for%20cached%20HelperId%20for%20IDPURL%0A%0Aalt%20Cached%20HelperId%20present%20(99.99%25%20cases)%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0A%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPURL%2C%20IDPURL%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnonce%7D%5Cnx-ms-DeviceCredential1%7Bnonce%7D%5Cnx-ms-RefreshTokenCredential2%7Bnonce%7D%5Cnx-ms-DeviceCredential2%7Bnonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%20%20%20%20opt%20nonce%20is%20stale%0A%20%20%20%20%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%20%20%20%20%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnew_nonce%7D%5Cnx-ms-DeviceCredential1%7Bnew_nonce%7D%5Cnx-ms-RefreshTokenCredential2%7Bnew_nonce%7D%5Cnx-ms-DeviceCredential2%7Bnew_nonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20end%0A%0Aelse%20No%20cached%20HelperId%20present%0A%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnonce%7D%5Cnx-ms-DeviceCredential1%7Bnonce%7D%5Cnx-ms-RefreshTokenCredential2%7Bnonce%7D%5Cnx-ms-DeviceCredential2%7Bnonce%7D%20...%20%5Cn%5CnSec-Session-HelperDiscoveryNeeded%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%0A%20%20%20%20note%20over%20I%2C%20B%3A%20No%20binding%20info%20present%2C%20but%20the%20reequest%20has%20GenerratKey%2C%20so%20IdP%20issues%20helper%20id%20list%0A%0A%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5Cn%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0A%20%20%20%20B-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%5D)%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPURL%2C%20IDPURL%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5Cnx-ms-RefreshTokenCredential1%7Bnew_nonce%7D%5Cnx-ms-DeviceCredential1%7Bnew_nonce%7D%5Cn%20x-ms-RefreshTokenCredential2%7Bnew_nonce%7D%5Cn%20x-ms-DeviceCredential2%7Bnew_nonce%7D%20...%20%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%0Aend%0A%0Aopt%20SSO%20information%20is%20not%20sufficient%0A%20%20%20%20I-%3E%3EB%3A%20Sign%20in%20ceremony%0A%20%20%20%20B-%3E%3EI%3A%20Sign%20done%0Aend%0A%0AI-%3E%3EB%3A%20Authorization%20code%2C%20KeyId%0A%0A%0Anote%20over%20W%2C%20B%3A%20Since%20DBSC%20session%20has%20been%20initialized%20already%20for%20RP%2C%20browser%20needs%20to%20generate%20JWT%20on%20redirect%20back%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(path%2C%20RPChallenge%2C%20extraParams)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0Anote%20over%20W%2C%20B%3A%20JWT%20is%20appended%20by%20the%20browser%20before%20returning%20the%20response%20from%20IDP%20back%20to%20the%20RP%0AB-%3E%3EW%3A%20Authorization%20code%2C%20KeyId%2C%20JWT%0AW-%3E%3EI%3A%20(confidential%20client%20request)%20redeem%20authorization%20code%0AI-%3E%3EW%3A%20(confidential%20client%20response)%20return%20id_token%0AW-%3E%3EW%3A%20parse%20id_token%20and%20validate%20binding%2C%20match%20with%20the%20JWT%20from%20the%20previous%0AW-%3E%3EB%3A%20Bound%20AuthCookie%0A%0Anote%20over%20W%2C%20P%3A%20Refresh%20DBSC...%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(sessionID)%0AW-%3E%3EB%3A%20Challenge%2C%20**extraParams**%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(sessionID%2C%20RPChallenge%2C%20**extraParams**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(JWT)%0AW-%3E%3EW%3A%20Validate%20JWT%20(w%2Fpublic%20key%20on%20file)%0AW-%3E%3EB%3A%20AuthCookie%0ARelying PartyIdPBrowserLocal Key HelperIdP calls a private Local Key HelperIdP life...Any request1 Any response2 Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime3 Sign in...Start sign in (302)4 Sec-Session-Registration: path, RPChallenge,... Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsCheck for cached HelperId for IDPURL5 currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...])6 Pre-gen key and attest (RPURL, IDPURL, extraParams...)7 Generate Key8 create binding statement S(publicKey, AIK)9 Return: KeyId, 10 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)11 Load sign-in (follow the 302)12 x-ms-RefreshTokenCredential1{nonce}x-ms-DeviceCredential1{nonce}x-ms-RefreshTokenCredential2{nonce}x-ms-DeviceCredential2{nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]302 to IdP with qs parameter sso_nonce=new_nonce13 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsLoad sign-in14 x-ms-RefreshTokenCredential1{new_nonce}x-ms-DeviceCredential1{new_nonce}x-ms-RefreshTokenCredential2{new_nonce}x-ms-DeviceCredential2{new_nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Load sign-in (follow the 302)15 x-ms-RefreshTokenCredential1{nonce}x-ms-DeviceCredential1{nonce}x-ms-RefreshTokenCredential2{nonce}x-ms-DeviceCredential2{nonce} ... Sec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParamsNo binding info present, but the reequest has GenerratKey, so IdP issues helper id list302 to IdP with qs parameter sso_nonce=new_nonce16 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime17 currentHelperId = Evaluate policy for (IdP, [HelperId1])18 Pre-gen key and attest (RPURL, IDPURL, extraParams...)19 Generate Key20 create binding statement S(publicKey, AIK)21 Return: KeyId, 22 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)23 Load sign-in24 x-ms-RefreshTokenCredential1{new_nonce}x-ms-DeviceCredential1{new_nonce} x-ms-RefreshTokenCredential2{new_nonce} x-ms-DeviceCredential2{new_nonce} ... Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Sign in ceremony25 Sign done26 Authorization code, KeyId27 Since DBSC session has been initialized already for RP, browser needs to generate JWT on redirect backRequest Sign JWT (path, RPChallenge, extraParams)28 Return JWT Signature29 JWT is appended by the browser before returning the response from IDP back to the RPAuthorization code, KeyId, JWT30 (confidential client request) redeem authorization code31 (confidential client response) return id_token32 parse id_token and validate binding, match with the JWT from the previous33 Bound AuthCookie34 Refresh DBSC...GET /securesession/refresh (sessionID)35 Challenge, extraParams36 Request Sign JWT (sessionID, RPChallenge, extraParams)37 Return JWT Signature38 GET /securesession/refresh (JWT)39 Validate JWT (w/public key on file)40 AuthCookie41 alt[Cached HelperId present (99.99% cases)][No cached HelperId present]loop[For each device]opt[nonce is stale]loop[For each device]opt[SSO information is not sufficient] \ No newline at end of file +title%20IdP%20calls%20a%20private%20Local%20Key%20Helper%0A%0Aautonumber%201%0Aparticipant%20%22Relying%20Party%22%20as%20W%0Aparticipant%20%22IdP%22%20as%20I%0Aparticipant%20%22Browser%22%20as%20B%0Aparticipant%20%22Local%20Key%20Helper%22%20as%20P%0A%0Anote%20over%20W%2C%20P%3A%20IdP%20life...%0AB-%3E%3EI%3A%20Any%20request%0AI-%3E%3EB%3A%20Any%20response%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0AB-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0Anote%20over%20W%2C%20P%3A%20Sign%20in...%0AW-%3E%3EB%3A%20Start%20sign%20in%20(302)%5CnSec-Session-Registration%3A%20path%2C%20RPChallenge%2C...%20%5CnSec-Session-GenerateKey%3A%20RPUrl%2C%20IDPUrl%2C%20extraParams%0AB-%3E%3EB%3A%20Check%20for%20cached%20HelperId%20for%20IDPUrl%0A%0Aalt%20Cached%20HelperId%20present%20(99.99%25%20cases)%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0A%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPUrl%2C%20IDPUrl%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5CnSSOHeaders1%7Bnonce%7D%5CnSSOHeaders2%7Bnonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%20%20%20%20opt%20nonce%20is%20stale%0A%20%20%20%20%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%20%20%20%20%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5CnSSOHeaders1%7Bnew_nonce%7D%5CnSSOHeaders2%7Bnew_nonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20end%0A%0Aelse%20No%20cached%20HelperId%20present%0A%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5CnSSOHeaders1%7Bnonce%7D%5CnSSOHeaders2%7Bnonce%7D%20...%20%5Cn%5CnSec-Session-HelperDiscoveryNeeded%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%0A%20%20%20%20note%20over%20I%2C%20B%3A%20No%20binding%20info%20present%2C%20but%20the%20reequest%20has%20GenerratKey%2C%20so%20IdP%20issues%20helper%20id%20list%0A%0A%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5Cn%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0A%20%20%20%20B-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%5D)%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPURL%2C%20IDPURL%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5CnSSOHeaders1%7Bnew_nonce%7D%5CnSSOHeaders2%7Bnew_nonce%7D%20...%20%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%0Aend%0A%0Aopt%20SSO%20information%20is%20not%20sufficient%0A%20%20%20%20I-%3E%3EB%3A%20Sign%20in%20ceremony%0A%20%20%20%20B-%3E%3EI%3A%20Sign%20done%0Aend%0A%0AI-%3E%3EB%3A%20Authorization%20code%2C%20KeyId%0A%0A%0Anote%20over%20W%2C%20B%3A%20Since%20DBSC%20session%20has%20been%20initialized%20already%20for%20RP%2C%20browser%20needs%20to%20generate%20JWT%20on%20redirect%20back%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(path%2C%20RPChallenge%2C%20extraParams)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0Anote%20over%20W%2C%20B%3A%20JWT%20is%20appended%20by%20the%20browser%20before%20returning%20the%20response%20from%20IDP%20back%20to%20the%20RP%0AB-%3E%3EW%3A%20Authorization%20code%2C%20KeyId%2C%20JWT%0AW-%3E%3EI%3A%20(confidential%20client%20request)%20redeem%20authorization%20code%0AI-%3E%3EW%3A%20(confidential%20client%20response)%20return%20id_token%0AW-%3E%3EW%3A%20parse%20id_token%20and%20validate%20binding%2C%20match%20with%20the%20JWT%20from%20the%20previous%0AW-%3E%3EB%3A%20Bound%20AuthCookie%0A%0Anote%20over%20W%2C%20P%3A%20Refresh%20DBSC...%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(sessionID)%0AW-%3E%3EB%3A%20Challenge%2C%20**extraParams**%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(sessionID%2C%20RPChallenge%2C%20**extraParams**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(JWT)%0AW-%3E%3EW%3A%20Validate%20JWT%20(w%2Fpublic%20key%20on%20file)%0AW-%3E%3EB%3A%20AuthCookie%0ARelying PartyIdPBrowserLocal Key HelperIdP calls a private Local Key HelperIdP life...Any request1 Any response2 Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime3 Sign in...Start sign in (302)4 Sec-Session-Registration: path, RPChallenge,... Sec-Session-GenerateKey: RPUrl, IDPUrl, extraParamsCheck for cached HelperId for IDPUrl5 currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...])6 Pre-gen key and attest (RPUrl, IDPUrl, extraParams...)7 Generate Key8 create binding statement S(publicKey, AIK)9 Return: KeyId, 10 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)11 Load sign-in (follow the 302)12 SSOHeaders1{nonce}SSOHeaders2{nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]302 to IdP with qs parameter sso_nonce=new_nonce13 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsLoad sign-in14 SSOHeaders1{new_nonce}SSOHeaders2{new_nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Load sign-in (follow the 302)15 SSOHeaders1{nonce}SSOHeaders2{nonce} ... Sec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParamsNo binding info present, but the reequest has GenerratKey, so IdP issues helper id list302 to IdP with qs parameter sso_nonce=new_nonce16 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime17 currentHelperId = Evaluate policy for (IdP, [HelperId1])18 Pre-gen key and attest (RPURL, IDPURL, extraParams...)19 Generate Key20 create binding statement S(publicKey, AIK)21 Return: KeyId, 22 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)23 Load sign-in24 SSOHeaders1{new_nonce}SSOHeaders2{new_nonce} ... Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Sign in ceremony25 Sign done26 Authorization code, KeyId27 Since DBSC session has been initialized already for RP, browser needs to generate JWT on redirect backRequest Sign JWT (path, RPChallenge, extraParams)28 Return JWT Signature29 JWT is appended by the browser before returning the response from IDP back to the RPAuthorization code, KeyId, JWT30 (confidential client request) redeem authorization code31 (confidential client response) return id_token32 parse id_token and validate binding, match with the JWT from the previous33 Bound AuthCookie34 Refresh DBSC...GET /securesession/refresh (sessionID)35 Challenge, extraParams36 Request Sign JWT (sessionID, RPChallenge, extraParams)37 Return JWT Signature38 GET /securesession/refresh (JWT)39 Validate JWT (w/public key on file)40 AuthCookie41 alt[Cached HelperId present (99.99% cases)][No cached HelperId present]loop[For each device]opt[nonce is stale]loop[For each device]opt[SSO information is not sufficient] \ No newline at end of file diff --git a/DBSCE/IDPCallsPrivateLocalKeyHelper.txt b/DBSCE/IDPCallsPrivateLocalKeyHelper.txt index dddf3bf..dbab4b8 100644 --- a/DBSCE/IDPCallsPrivateLocalKeyHelper.txt +++ b/DBSCE/IDPCallsPrivateLocalKeyHelper.txt @@ -12,14 +12,14 @@ I->>B: Any response\nSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCac B->>B: Cache HelperId for IDPURL for HelperCacheTime note over W, P: Sign in... -W->>B: Start sign in (302)\nSec-Session-Registration: path, RPChallenge,... \nSec-Session-GenerateKey: RPURL, IDPURL, extraParams -B->>B: Check for cached HelperId for IDPURL +W->>B: Start sign in (302)\nSec-Session-Registration: path, RPChallenge,... \nSec-Session-GenerateKey: RPUrl, IDPUrl, extraParams +B->>B: Check for cached HelperId for IDPUrl alt Cached HelperId present (99.99% cases) B->>B: currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...]) - B->>P: Pre-gen key and attest (RPURL, IDPURL, extraParams...) + B->>P: Pre-gen key and attest (RPUrl, IDPUrl, extraParams...) P->>P: Generate Key @@ -30,17 +30,17 @@ alt Cached HelperId present (99.99% cases) P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] B->>B: Remember this key is for RP (and maybe path) - B->>I: Load sign-in (follow the 302)\n\nx-ms-RefreshTokenCredential1{nonce}\nx-ms-DeviceCredential1{nonce}\nx-ms-RefreshTokenCredential2{nonce}\nx-ms-DeviceCredential2{nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>I: Load sign-in (follow the 302)\n\nSSOHeaders1{nonce}\nSSOHeaders2{nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] opt nonce is stale I->>B: 302 to IdP with qs parameter sso_nonce=new_nonce\nSec-Session-GenerateKey: RPURL, IDPURL, extraParams - B->>I: Load sign-in\n\nx-ms-RefreshTokenCredential1{new_nonce}\nx-ms-DeviceCredential1{new_nonce}\nx-ms-RefreshTokenCredential2{new_nonce}\nx-ms-DeviceCredential2{new_nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>I: Load sign-in\n\nSSOHeaders1{new_nonce}\nSSOHeaders2{new_nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] end else No cached HelperId present - B->>I: Load sign-in (follow the 302)\n\nx-ms-RefreshTokenCredential1{nonce}\nx-ms-DeviceCredential1{nonce}\nx-ms-RefreshTokenCredential2{nonce}\nx-ms-DeviceCredential2{nonce} ... \n\nSec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParams + B->>I: Load sign-in (follow the 302)\n\nSSOHeaders1{nonce}\nSSOHeaders2{nonce} ... \n\nSec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParams note over I, B: No binding info present, but the reequest has GenerratKey, so IdP issues helper id list @@ -59,7 +59,7 @@ else No cached HelperId present P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] B->>B: Remember this key is for RP (and maybe path) - B->>I: Load sign-in\n\nx-ms-RefreshTokenCredential1{new_nonce}\nx-ms-DeviceCredential1{new_nonce}\n x-ms-RefreshTokenCredential2{new_nonce}\n x-ms-DeviceCredential2{new_nonce} ... \n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>I: Load sign-in\n\nSSOHeaders1{new_nonce}\nSSOHeaders2{new_nonce} ... \n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] end From 2358c877752cee7434e46c3bb648823042acd65f Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Wed, 28 Aug 2024 12:55:07 -0700 Subject: [PATCH 28/47] Rework diagrams --- DBSCE/DBSC(E).svg | 2 +- DBSCE/DBSC(E).txt | 14 ++--- DBSCE/IDPCallsPrivateLocalKeyHelper.svg | 2 +- DBSCE/IDPCallsPrivateLocalKeyHelper.txt | 8 +-- DBSCE/Overview.md | 53 ++++++++++++------- ...KeyGeneration.md => PlatformKeyHelpers.md} | 0 6 files changed, 47 insertions(+), 32 deletions(-) rename DBSCE/{KeyGeneration.md => PlatformKeyHelpers.md} (100%) diff --git a/DBSCE/DBSC(E).svg b/DBSCE/DBSC(E).svg index 24bce9c..4598da6 100644 --- a/DBSCE/DBSC(E).svg +++ b/DBSCE/DBSC(E).svg @@ -1 +1 @@ -%0Aparticipant%20%22%3Ccolor%3A%23blue%3EAttestation%20Service%22%20as%20s%0Aparticipant%20%22%3Ccolor%3A%23blue%3ELocalKeyHelper%2FTPM%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%5Cn%3Ccolor%3A%23blue%3ERP%2FIDP%22%20as%20w%0A%0Aautonumber%201%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3E%20initiate%20%3C%2Fcolor%3E%20sign-in%20flow%20%0Aw-%3Eb%3A%20%3Ccolor%3A%23blue%3E302%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%2C%20..%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%3Ccolor%3A%23blue%3Ebrowser%20pre-generates%20keys%5Cnbased%20on%20headers%5Cn%5Cn%3Ccolor%3A%23blue%3EcurrentHelperId%3D%5Cnevaluate%20policy%20for%20%5Cn(Server%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%2Cchallenge%2CextraParams%3F)%5Cn%20pre%20generates%20key%20and%20attestation%0At-%3Et%3A%20%3Ccolor%3A%23blue%3EgenerateKey()%0Anote%20over%20t%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Es%3A%20%3Ccolor%3A%23blue%3EgenerateBindingStatement%5Cn(publicKey%2C%20AIK%2C%20challenge)%0As-%3Et%3A%20%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%7D%0At-%3Eb%3A%20return%20public%20key%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20%3Ccolor%3A%23blue%3ECache%20the%20key%20for%20server%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3ELoad%20sign-in%5CnSec-Session-Keys%3A%20KeyId%2C%5CnBinding%20Statement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims...%7D%0Aw-%3Ew%3A%20%3Ccolor%3A%23blue%3Evalidate%20signature%20on%20the%20%5Cnbinding%20statement%20and%20challenge%5Cnstore%20thumbprint%2C%20KeyId%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%2C%5Cn%3Ccolor%3A%23blue%3EKeyId%2C%20extraParams%3C%2Fcolor%3E%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2Cpublic%20key%2C%20extraParams%3F..)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%5Cn%3Ccolor%3A%23blue%3Evalidate%20the%20JWT%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn%3Ccolor%3A%23blue%3E%22extraParams%22%3A%3Ccustom..%3E%7D%22%22%20%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%5Cn%3Ccolor%3A%23blue%3Echallenge%2C%20extraParams...%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendAttestation ServiceLocalKeyHelper/TPMBrowserServerRP/IDP initiate  sign-in flow 1 3022 Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2, ..], HelperCacheTimebrowser pre-generates keysbased on headerscurrentHelperId=evaluate policy for (Server, [HelperId1, HelperId2...])request create keypair 3 (serverUrl,challenge,extraParams?) pre generates key and attestationgenerateKey()4 For Enterprise, this call will be platformbased & generates device attestationgenerateBindingStatement5 (publicKey, AIK, challenge)BindingStatement6 {challenge, thumbprint(publicKey), extraClaims}return public key &7 BindingStatement{challenge, thumbprint(publicKey), extraClaims?..}Cache the key for serverLoad sign-in8 Sec-Session-Keys: KeyId,Binding Statement{challenge, thumbprint(publicKey), extraClaims...}validate signature on the 9 binding statement and challengestore thumbprint, KeyId200 w/signed-in content, response includes header to start secure session.  10 Header: Sec-Session-Registration: session_identifier=..., challenge=...,KeyId, extraParams(challenge required for private key proof of possession)browser initiates session bindingbased on header presencecreate JWT w/challengerequest sign JWT  11 (challenge,public key, extraParams?..)return JWT signature12 POST /securesession/startsession 13 {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish sessionvalidate the JWT200 w/cookie and session ID14 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookie15 GET /somecontent16 200 w/content17 check if required cookies exist18 GET /somecontent19 200 w/content20 request deferred while we get cookies...GET /securesession/refresh 21 header: Sec-Session-Id: [session ID]40122 Header: Sec-Session-Challenge: session_identifier=..., challenge=..."extraParams":<custom..>} create JWT w/challengerequest sign JWT23 challenge, extraParams...return JWT signature24 GET /securesession/refresh 25 header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session ID26 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent27 200 w/some content28 alt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file +%0Aparticipant%20%22%3Ccolor%3A%23blue%3EAttestation%20Service%22%20as%20s%0Aparticipant%20%22%3Ccolor%3A%23blue%3ELocalKeyHelper%20(Replaces%20TPM)%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%5Cn%3Ccolor%3A%23blue%3ERP%2FIDP%22%20as%20w%0A%0Aautonumber%201%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3E%20user%20initiates%20%3C%2Fcolor%3E%20sign-in%20flow%20%3Ccolor%3A%23blue%3E%20in%20the%20browser%20%3C%2Fcolor%3E%20%0Aw-%3Eb%3A%20%3Ccolor%3A%23blue%3E302%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%2C%20..%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%3Ccolor%3A%23blue%3Ebrowser%20invokes%20local%20key%20helper%20%5Cnto%20pre-generate%20keys%20%20based%20on%20DBSC(E)%20headers%5Cn%5Cn%3Ccolor%3A%23blue%3EcurrentHelperId%3D%5Cnevaluate%20policy%20for%20%5Cn(Server%7BIDPUrl%2C%20RPUrl%7D%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%7BIDPUrl%2C%20RPUrl%7D%2C%20challenge%2C%20extraParams%3F)%5Cn%20pre%20generates%20key%20and%20attestation%0At-%3Et%3A%20%3Ccolor%3A%23blue%3EgenerateKey()%0Anote%20over%20t%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Es%3A%20%3Ccolor%3A%23blue%3EgenerateBindingStatement%5Cn(publicKey%2C%20AIK%2C%20challenge)%0As-%3Et%3A%20%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%7D%0At-%3Eb%3A%20return%20public%20key%20%3Ccolor%3A%23blue%3E(KeyId)%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20%3Ccolor%3A%23blue%3ECache%20the%20key%20for%20server%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3ELoad%20sign-in%5CnSec-Session-Keys%3A%20KeyId%2C%5CnBinding%20Statement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims...%7D%0Aw-%3Ew%3A%20%3Ccolor%3A%23blue%3Evalidate%20signature%20on%20the%20%5Cnbinding%20statement%20and%20challenge%5Cnstore%20thumbprint%2C%20KeyId%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%2C%5Cn%3Ccolor%3A%23blue%3EKeyId%2C%20extraParams%3C%2Fcolor%3E%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2C%20KeyId%2C%20extraParams%3F...)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%5Cn%3Ccolor%3A%23blue%3Evalidate%20the%20JWT%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn%3Ccolor%3A%23blue%3E%22extraParams%22%3A%3Ccustom..%3E%7D%22%22%20%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%5Cn%3Ccolor%3A%23blue%3E(challenge%2C%20KeyId%2C%20extraParams%3F...)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendAttestation ServiceLocalKeyHelper (Replaces TPM)BrowserServerRP/IDP user initiates  sign-in flow  in the browser  1 3022 Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2, ..], HelperCacheTimebrowser invokes local key helper to pre-generate keys  based on DBSC(E) headerscurrentHelperId=evaluate policy for (Server{IDPUrl, RPUrl}, [HelperId1, HelperId2...])request create keypair 3 (serverUrl{IDPUrl, RPUrl}, challenge, extraParams?) pre generates key and attestationgenerateKey()4 For Enterprise, this call will be platformbased & generates device attestationgenerateBindingStatement5 (publicKey, AIK, challenge)BindingStatement6 {challenge, thumbprint(publicKey), extraClaims}return public key (KeyId) &7 BindingStatement{challenge, thumbprint(publicKey), extraClaims?..}Cache the key for serverLoad sign-in8 Sec-Session-Keys: KeyId,Binding Statement{challenge, thumbprint(publicKey), extraClaims...}validate signature on the 9 binding statement and challengestore thumbprint, KeyId200 w/signed-in content, response includes header to start secure session.  10 Header: Sec-Session-Registration: session_identifier=..., challenge=...,KeyId, extraParams(challenge required for private key proof of possession)browser initiates session bindingbased on header presencecreate JWT w/challengerequest sign JWT  11 (challenge, KeyId, extraParams?...)return JWT signature12 POST /securesession/startsession 13 {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish sessionvalidate the JWT200 w/cookie and session ID14 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookie15 GET /somecontent16 200 w/content17 check if required cookies exist18 GET /somecontent19 200 w/content20 request deferred while we get cookies...GET /securesession/refresh 21 header: Sec-Session-Id: [session ID]40122 Header: Sec-Session-Challenge: session_identifier=..., challenge=..."extraParams":<custom..>} create JWT w/challengerequest sign JWT23 (challenge, KeyId, extraParams?...)return JWT signature24 GET /securesession/refresh 25 header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session ID26 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent27 200 w/some content28 alt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file diff --git a/DBSCE/DBSC(E).txt b/DBSCE/DBSC(E).txt index 89dfa1c..5c27b3e 100644 --- a/DBSCE/DBSC(E).txt +++ b/DBSCE/DBSC(E).txt @@ -1,26 +1,26 @@ participant "Attestation Service" as s -participant "LocalKeyHelper/TPM" as t +participant "LocalKeyHelper (Replaces TPM)" as t participant "Browser" as b participant "Server\nRP/IDP" as w autonumber 1 -b->w: initiate sign-in flow +b->w: user initiates sign-in flow in the browser w->b: 302\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2, ..], HelperCacheTime -note over b:browser pre-generates keys\nbased on headers\n\ncurrentHelperId=\nevaluate policy for \n(Server, [HelperId1, HelperId2...]) -b->t: request create keypair \n(serverUrl,challenge,extraParams?)\n pre generates key and attestation +note over b:browser invokes local key helper \nto pre-generate keys based on DBSC(E) headers\n\ncurrentHelperId=\nevaluate policy for \n(Server{IDPUrl, RPUrl}, [HelperId1, HelperId2...]) +b->t: request create keypair \n(serverUrl{IDPUrl, RPUrl}, challenge, extraParams?)\n pre generates key and attestation t->t: generateKey() note over t: For Enterprise, this call will be platform\nbased & generates device attestation t->s: generateBindingStatement\n(publicKey, AIK, challenge) s->t: BindingStatement\n{challenge, thumbprint(publicKey), extraClaims} -t->b: return public key &\nBindingStatement\n{challenge, thumbprint(publicKey), extraClaims?..} +t->b: return public key (KeyId) &\nBindingStatement\n{challenge, thumbprint(publicKey), extraClaims?..} note over b: Cache the key for server b->w: Load sign-in\nSec-Session-Keys: KeyId,\nBinding Statement\n{challenge, thumbprint(publicKey), extraClaims...} w->w: validate signature on the \nbinding statement and challenge\nstore thumbprint, KeyId w->b: 200 w/signed-in content, response includes header to start secure session. \nHeader: ""Sec-Session-Registration: session_identifier=..., challenge=..."",\nKeyId, extraParams\n(challenge required for private key proof of possession) note over b: browser initiates session binding\nbased on header presence note over b: create JWT w/challenge -b->t:request sign JWT \n(challenge,public key, extraParams?..) +b->t:request sign JWT \n(challenge, KeyId, extraParams?...) t->b: return JWT signature b->w: POST /securesession/startsession \n\n""{"alg":..., "typ":"JWT", ...}{...,"key":""}"" note over w: store public key, establish session\nvalidate the JWT @@ -41,7 +41,7 @@ note over b: request deferred while we get cookies... b->w: GET /securesession/refresh \nheader: ""Sec-Session-Id: [session ID]"" w->b:401\n\nHeader: ""Sec-Session-Challenge: session_identifier=..., challenge=...""\n"extraParams":}"" note over b: create JWT w/challenge -b->t:request sign JWT\nchallenge, extraParams... +b->t:request sign JWT\n(challenge, KeyId, extraParams?...) t->b: return JWT signature b->w: GET /securesession/refresh \nheader: ""Sec-Session-Response: [JWT]"" note over w: validate proof of possesion diff --git a/DBSCE/IDPCallsPrivateLocalKeyHelper.svg b/DBSCE/IDPCallsPrivateLocalKeyHelper.svg index 5db2dba..0df3d73 100644 --- a/DBSCE/IDPCallsPrivateLocalKeyHelper.svg +++ b/DBSCE/IDPCallsPrivateLocalKeyHelper.svg @@ -1 +1 @@ -title%20IdP%20calls%20a%20private%20Local%20Key%20Helper%0A%0Aautonumber%201%0Aparticipant%20%22Relying%20Party%22%20as%20W%0Aparticipant%20%22IdP%22%20as%20I%0Aparticipant%20%22Browser%22%20as%20B%0Aparticipant%20%22Local%20Key%20Helper%22%20as%20P%0A%0Anote%20over%20W%2C%20P%3A%20IdP%20life...%0AB-%3E%3EI%3A%20Any%20request%0AI-%3E%3EB%3A%20Any%20response%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0AB-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0Anote%20over%20W%2C%20P%3A%20Sign%20in...%0AW-%3E%3EB%3A%20Start%20sign%20in%20(302)%5CnSec-Session-Registration%3A%20path%2C%20RPChallenge%2C...%20%5CnSec-Session-GenerateKey%3A%20RPUrl%2C%20IDPUrl%2C%20extraParams%0AB-%3E%3EB%3A%20Check%20for%20cached%20HelperId%20for%20IDPUrl%0A%0Aalt%20Cached%20HelperId%20present%20(99.99%25%20cases)%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0A%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPUrl%2C%20IDPUrl%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5CnSSOHeaders1%7Bnonce%7D%5CnSSOHeaders2%7Bnonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%20%20%20%20opt%20nonce%20is%20stale%0A%20%20%20%20%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%20%20%20%20%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5CnSSOHeaders1%7Bnew_nonce%7D%5CnSSOHeaders2%7Bnew_nonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20end%0A%0Aelse%20No%20cached%20HelperId%20present%0A%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5CnSSOHeaders1%7Bnonce%7D%5CnSSOHeaders2%7Bnonce%7D%20...%20%5Cn%5CnSec-Session-HelperDiscoveryNeeded%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%0A%20%20%20%20note%20over%20I%2C%20B%3A%20No%20binding%20info%20present%2C%20but%20the%20reequest%20has%20GenerratKey%2C%20so%20IdP%20issues%20helper%20id%20list%0A%0A%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5Cn%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0A%20%20%20%20B-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%5D)%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPURL%2C%20IDPURL%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5CnSSOHeaders1%7Bnew_nonce%7D%5CnSSOHeaders2%7Bnew_nonce%7D%20...%20%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%0Aend%0A%0Aopt%20SSO%20information%20is%20not%20sufficient%0A%20%20%20%20I-%3E%3EB%3A%20Sign%20in%20ceremony%0A%20%20%20%20B-%3E%3EI%3A%20Sign%20done%0Aend%0A%0AI-%3E%3EB%3A%20Authorization%20code%2C%20KeyId%0A%0A%0Anote%20over%20W%2C%20B%3A%20Since%20DBSC%20session%20has%20been%20initialized%20already%20for%20RP%2C%20browser%20needs%20to%20generate%20JWT%20on%20redirect%20back%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(path%2C%20RPChallenge%2C%20extraParams)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0Anote%20over%20W%2C%20B%3A%20JWT%20is%20appended%20by%20the%20browser%20before%20returning%20the%20response%20from%20IDP%20back%20to%20the%20RP%0AB-%3E%3EW%3A%20Authorization%20code%2C%20KeyId%2C%20JWT%0AW-%3E%3EI%3A%20(confidential%20client%20request)%20redeem%20authorization%20code%0AI-%3E%3EW%3A%20(confidential%20client%20response)%20return%20id_token%0AW-%3E%3EW%3A%20parse%20id_token%20and%20validate%20binding%2C%20match%20with%20the%20JWT%20from%20the%20previous%0AW-%3E%3EB%3A%20Bound%20AuthCookie%0A%0Anote%20over%20W%2C%20P%3A%20Refresh%20DBSC...%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(sessionID)%0AW-%3E%3EB%3A%20Challenge%2C%20**extraParams**%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(sessionID%2C%20RPChallenge%2C%20**extraParams**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(JWT)%0AW-%3E%3EW%3A%20Validate%20JWT%20(w%2Fpublic%20key%20on%20file)%0AW-%3E%3EB%3A%20AuthCookie%0ARelying PartyIdPBrowserLocal Key HelperIdP calls a private Local Key HelperIdP life...Any request1 Any response2 Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime3 Sign in...Start sign in (302)4 Sec-Session-Registration: path, RPChallenge,... Sec-Session-GenerateKey: RPUrl, IDPUrl, extraParamsCheck for cached HelperId for IDPUrl5 currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...])6 Pre-gen key and attest (RPUrl, IDPUrl, extraParams...)7 Generate Key8 create binding statement S(publicKey, AIK)9 Return: KeyId, 10 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)11 Load sign-in (follow the 302)12 SSOHeaders1{nonce}SSOHeaders2{nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]302 to IdP with qs parameter sso_nonce=new_nonce13 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsLoad sign-in14 SSOHeaders1{new_nonce}SSOHeaders2{new_nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Load sign-in (follow the 302)15 SSOHeaders1{nonce}SSOHeaders2{nonce} ... Sec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParamsNo binding info present, but the reequest has GenerratKey, so IdP issues helper id list302 to IdP with qs parameter sso_nonce=new_nonce16 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime17 currentHelperId = Evaluate policy for (IdP, [HelperId1])18 Pre-gen key and attest (RPURL, IDPURL, extraParams...)19 Generate Key20 create binding statement S(publicKey, AIK)21 Return: KeyId, 22 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)23 Load sign-in24 SSOHeaders1{new_nonce}SSOHeaders2{new_nonce} ... Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Sign in ceremony25 Sign done26 Authorization code, KeyId27 Since DBSC session has been initialized already for RP, browser needs to generate JWT on redirect backRequest Sign JWT (path, RPChallenge, extraParams)28 Return JWT Signature29 JWT is appended by the browser before returning the response from IDP back to the RPAuthorization code, KeyId, JWT30 (confidential client request) redeem authorization code31 (confidential client response) return id_token32 parse id_token and validate binding, match with the JWT from the previous33 Bound AuthCookie34 Refresh DBSC...GET /securesession/refresh (sessionID)35 Challenge, extraParams36 Request Sign JWT (sessionID, RPChallenge, extraParams)37 Return JWT Signature38 GET /securesession/refresh (JWT)39 Validate JWT (w/public key on file)40 AuthCookie41 alt[Cached HelperId present (99.99% cases)][No cached HelperId present]loop[For each device]opt[nonce is stale]loop[For each device]opt[SSO information is not sufficient] \ No newline at end of file +title%20IdP%20calls%20a%20private%20Local%20Key%20Helper%0A%0Aautonumber%201%0Aparticipant%20%22Relying%20Party%22%20as%20W%0Aparticipant%20%22IdP%22%20as%20I%0Aparticipant%20%22Browser%22%20as%20B%0Aparticipant%20%22Local%20Key%20Helper%22%20as%20P%0A%0Anote%20over%20W%2C%20P%3A%20IdP%20life...%0AB-%3E%3EI%3A%20Any%20request%0AI-%3E%3EB%3A%20Any%20response%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0AB-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0Anote%20over%20W%2C%20P%3A%20Sign%20in...%0AW-%3E%3EB%3A%20Start%20sign%20in%20(302)%5CnSec-Session-Registration%3A%20path%2C%20RPChallenge%2C...%20%5CnSec-Session-GenerateKey%3A%20RPUrl%2C%20IDPUrl%2C%20extraParams%0AB-%3E%3EB%3A%20Check%20for%20cached%20HelperId%20for%20IDPUrl%0A%0Aalt%20Cached%20HelperId%20present%20(99.99%25%20cases)%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0A%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPUrl%2C%20IDPUrl%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5CnUserAuthHeader1%7Bnonce%7D%5CnDeviceAuthHeader%7Bnonce%7D%5Cn%5CnUserAuthHeader1%7Bnonce%7D%5CnDeviceAuthHeader%7Bnonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%20%20%20%20opt%20nonce%20is%20stale%0A%20%20%20%20%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%20%20%20%20%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5CnUserAuthHeader1%7Bnew_nonce%7D%5CnDeviceAuthHeader1%7Bnew_nonce%7D%5Cn%5CnUserAuthHeader2%7Bnew_nonce%7D%5CnDeviceAuthHeader2%7Bnew_nonce%7D%20...%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20end%0A%0Aelse%20No%20cached%20HelperId%20present%0A%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%20(follow%20the%20302)%5Cn%5CnUserAuthHeader1%7Bnonce%7D%5CnDeviceAuthHeader1%7Bnonce%7D%5Cn%5CnUserAuthHeader2%7Bnonce%7D%5CnDeviceAuthHeader2%7Bnonce%7D%20...%20%5Cn%5CnSec-Session-HelperDiscoveryNeeded%3A%20RPURL%2C%20IDPURL%2C%20extraParams%0A%0A%20%20%20%20note%20over%20I%2C%20B%3A%20No%20binding%20info%20present%2C%20but%20the%20reequest%20has%20GenerratKey%2C%20so%20IdP%20issues%20helper%20id%20list%0A%0A%20%20%20%20I-%3E%3EB%3A%20302%20to%20IdP%20with%20qs%20parameter%20sso_nonce%3Dnew_nonce%5Cn%5CnSec-Session-GenerateKey%3A%20RPURL%2C%20IDPURL%2C%20extraParams%5CnSec-Session-HelperIdList%3A%20%5BHelperId1%2C%20HelperId2%5D%2C%20HelperCacheTime%0A%20%20%20%20B-%3E%3EB%3A%20Cache%20HelperId%20for%20IDPURL%20for%20HelperCacheTime%0A%0A%20%20%20%20B-%3E%3EB%3A%20currentHelperId%20%3D%20Evaluate%20policy%20for%20(IdP%2C%20%5BHelperId1%5D)%0A%20%20%20%20B-%3E%3EP%3A%20Pre-gen%20key%20and%20attest%20(RPURL%2C%20IDPURL%2C%20extraParams...)%0A%0A%20%20%20%20P-%3E%3EP%3A%20Generate%20Key%0A%0A%20%20%20%20loop%20For%20each%20device%0A%20%20%20%20%20%20%20%20P-%3E%3EP%3A%20create%20binding%20statement%20S(publicKey%2C%20AIK)%0A%20%20%20%20end%0A%0A%20%20%20%20P-%3E%3EB%3A%20Return%3A%20KeyId%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%20%20%20%20B-%3E%3EB%3A%20Remember%20this%20key%20is%20for%20RP%20(and%20maybe%20path)%0A%0A%20%20%20%20B-%3E%3EI%3A%20Load%20sign-in%5Cn%5CnUserAuthHeader1%7Bnew_nonce%7D%5CnDeviceAuthHeader1%7Bnew_nonce%7D%5Cn%20UserAuthHeader2%7Bnew_nonce%7D%5Cn%20DeviceAuthHeader2%7Bnew_nonce%7D%20...%20%5Cn%5CnSec-Session-BindingInfo%3A%20KeyId%2C%20PublicKey%2C%20%5Cnarray%20of%20binding%20statements%20%5BBindingStatement1%20%7BextraClaims....%7D%2C%20%5CnBindingStatement2%20%7BextraCalims...%7D%5D%0A%0A%0Aend%0A%0Aopt%20SSO%20information%20is%20not%20sufficient%0A%20%20%20%20I-%3E%3EB%3A%20Sign%20in%20ceremony%0A%20%20%20%20B-%3E%3EI%3A%20Sign%20done%0Aend%0A%0AI-%3E%3EB%3A%20Authorization%20code%2C%20KeyId%0A%0A%0Anote%20over%20W%2C%20B%3A%20Since%20DBSC%20session%20has%20been%20initialized%20already%20for%20RP%2C%20browser%20needs%20to%20generate%20JWT%20on%20redirect%20back%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(path%2C%20RPChallenge%2C%20extraParams)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0Anote%20over%20W%2C%20B%3A%20JWT%20is%20appended%20by%20the%20browser%20before%20returning%20the%20response%20from%20IDP%20back%20to%20the%20RP%0AB-%3E%3EW%3A%20Authorization%20code%2C%20KeyId%2C%20JWT%0AW-%3E%3EI%3A%20(confidential%20client%20request)%20redeem%20authorization%20code%0AI-%3E%3EW%3A%20(confidential%20client%20response)%20return%20id_token%0AW-%3E%3EW%3A%20parse%20id_token%20and%20validate%20binding%2C%20match%20with%20the%20JWT%20from%20the%20previous%0AW-%3E%3EB%3A%20Bound%20AuthCookie%0A%0Anote%20over%20W%2C%20P%3A%20Refresh%20DBSC...%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(sessionID)%0AW-%3E%3EB%3A%20Challenge%2C%20**extraParams**%0AB-%3E%3EP%3A%20Request%20Sign%20JWT%20(sessionID%2C%20RPChallenge%2C%20**extraParams**)%0AP-%3E%3EB%3A%20Return%20JWT%20Signature%0AB-%3E%3EW%3A%20GET%20%2Fsecuresession%2Frefresh%20(JWT)%0AW-%3E%3EW%3A%20Validate%20JWT%20(w%2Fpublic%20key%20on%20file)%0AW-%3E%3EB%3A%20AuthCookie%0ARelying PartyIdPBrowserLocal Key HelperIdP calls a private Local Key HelperIdP life...Any request1 Any response2 Sec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime3 Sign in...Start sign in (302)4 Sec-Session-Registration: path, RPChallenge,... Sec-Session-GenerateKey: RPUrl, IDPUrl, extraParamsCheck for cached HelperId for IDPUrl5 currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...])6 Pre-gen key and attest (RPUrl, IDPUrl, extraParams...)7 Generate Key8 create binding statement S(publicKey, AIK)9 Return: KeyId, 10 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)11 Load sign-in (follow the 302)12 UserAuthHeader1{nonce}DeviceAuthHeader{nonce}UserAuthHeader1{nonce}DeviceAuthHeader{nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]302 to IdP with qs parameter sso_nonce=new_nonce13 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsLoad sign-in14 UserAuthHeader1{new_nonce}DeviceAuthHeader1{new_nonce}UserAuthHeader2{new_nonce}DeviceAuthHeader2{new_nonce} ...Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Load sign-in (follow the 302)15 UserAuthHeader1{nonce}DeviceAuthHeader1{nonce}UserAuthHeader2{nonce}DeviceAuthHeader2{nonce} ... Sec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParamsNo binding info present, but the reequest has GenerratKey, so IdP issues helper id list302 to IdP with qs parameter sso_nonce=new_nonce16 Sec-Session-GenerateKey: RPURL, IDPURL, extraParamsSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTimeCache HelperId for IDPURL for HelperCacheTime17 currentHelperId = Evaluate policy for (IdP, [HelperId1])18 Pre-gen key and attest (RPURL, IDPURL, extraParams...)19 Generate Key20 create binding statement S(publicKey, AIK)21 Return: KeyId, 22 array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Remember this key is for RP (and maybe path)23 Load sign-in24 UserAuthHeader1{new_nonce}DeviceAuthHeader1{new_nonce} UserAuthHeader2{new_nonce} DeviceAuthHeader2{new_nonce} ... Sec-Session-BindingInfo: KeyId, PublicKey, array of binding statements [BindingStatement1 {extraClaims....}, BindingStatement2 {extraCalims...}]Sign in ceremony25 Sign done26 Authorization code, KeyId27 Since DBSC session has been initialized already for RP, browser needs to generate JWT on redirect backRequest Sign JWT (path, RPChallenge, extraParams)28 Return JWT Signature29 JWT is appended by the browser before returning the response from IDP back to the RPAuthorization code, KeyId, JWT30 (confidential client request) redeem authorization code31 (confidential client response) return id_token32 parse id_token and validate binding, match with the JWT from the previous33 Bound AuthCookie34 Refresh DBSC...GET /securesession/refresh (sessionID)35 Challenge, extraParams36 Request Sign JWT (sessionID, RPChallenge, extraParams)37 Return JWT Signature38 GET /securesession/refresh (JWT)39 Validate JWT (w/public key on file)40 AuthCookie41 alt[Cached HelperId present (99.99% cases)][No cached HelperId present]loop[For each device]opt[nonce is stale]loop[For each device]opt[SSO information is not sufficient] \ No newline at end of file diff --git a/DBSCE/IDPCallsPrivateLocalKeyHelper.txt b/DBSCE/IDPCallsPrivateLocalKeyHelper.txt index dbab4b8..7fdbad9 100644 --- a/DBSCE/IDPCallsPrivateLocalKeyHelper.txt +++ b/DBSCE/IDPCallsPrivateLocalKeyHelper.txt @@ -30,17 +30,17 @@ alt Cached HelperId present (99.99% cases) P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] B->>B: Remember this key is for RP (and maybe path) - B->>I: Load sign-in (follow the 302)\n\nSSOHeaders1{nonce}\nSSOHeaders2{nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>I: Load sign-in (follow the 302)\n\nUserAuthHeader1{nonce}\nDeviceAuthHeader{nonce}\n\nUserAuthHeader1{nonce}\nDeviceAuthHeader{nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] opt nonce is stale I->>B: 302 to IdP with qs parameter sso_nonce=new_nonce\nSec-Session-GenerateKey: RPURL, IDPURL, extraParams - B->>I: Load sign-in\n\nSSOHeaders1{new_nonce}\nSSOHeaders2{new_nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>I: Load sign-in\n\nUserAuthHeader1{new_nonce}\nDeviceAuthHeader1{new_nonce}\n\nUserAuthHeader2{new_nonce}\nDeviceAuthHeader2{new_nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] end else No cached HelperId present - B->>I: Load sign-in (follow the 302)\n\nSSOHeaders1{nonce}\nSSOHeaders2{nonce} ... \n\nSec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParams + B->>I: Load sign-in (follow the 302)\n\nUserAuthHeader1{nonce}\nDeviceAuthHeader1{nonce}\n\nUserAuthHeader2{nonce}\nDeviceAuthHeader2{nonce} ... \n\nSec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParams note over I, B: No binding info present, but the reequest has GenerratKey, so IdP issues helper id list @@ -59,7 +59,7 @@ else No cached HelperId present P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] B->>B: Remember this key is for RP (and maybe path) - B->>I: Load sign-in\n\nSSOHeaders1{new_nonce}\nSSOHeaders2{new_nonce} ... \n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] + B->>I: Load sign-in\n\nUserAuthHeader1{new_nonce}\nDeviceAuthHeader1{new_nonce}\n UserAuthHeader2{new_nonce}\n DeviceAuthHeader2{new_nonce} ... \n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] end diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index d6af3c1..7050504 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -95,7 +95,12 @@ This is a pre-requisite for DBSC(E) to work. Device Registration Client is a process where the user or administrator registers the device with the IdP and is expected to be a once-in-a-lifetime protected operation. -The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. +The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. + +A clean room enviroment is a reliable, malware and exploit free state of a system. Examples can be: +- New device from the factory connected to a secure network during registration +- Company issued devices configured by admin for the employees +- A malware free device installing browser in a secure network One device registration client can manage multiple devices on the same physical device. There also can be multiple device registration clients on the same device. The device registration client can be owned and supported by: @@ -106,7 +111,6 @@ One device registration client can manage multiple devices on the same physical DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" and the management of the generated keys to prove device binding. -TODO: Add a definition of cleanroom and examples ### Device Registration @@ -122,10 +126,8 @@ DBSC(E) introduces the concept of `Local Key Helper`. From the deployment point of view there are two types of local key helpers: _private_ and _public_ -- _Public local key helper_: Expected to have a well-documented implementation and can be used by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP as defined in DBSC(E) protocol. -- _Private local key helper_ : Is specific to an IdP. Can be only used by a specific IDP that owns the implementation and will have a private protocol to communicate with the IdP. Comes with either OS or built into the browser. - -Additionally, some _Local key helpers_ are classified as `well-known` (a special case of `private`) and will be **enabled by default** in a browser and/or a given IDP. A browser knows how to activate a well-known key helper without needing an admin-side configuration. +- _Public local key helper_: Expected to have a well-documented API and can be used by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP as defined in DBSC(E) protocol. +- _Private local key helper_ : Is specific to an IdP. Can be only used by a specific IDP that owns the implementation and will have a private protocol to communicate with the IdP. The Local Key Helper is responsible for: @@ -135,11 +137,13 @@ The Local Key Helper is responsible for: #### Platform Requirements -- [Windows](./KeyGeneration.md#local-key-helper-on-windows) +This section prescribes the browser discovery process of a given local key helper for a few well known platforms: + +- [Windows](./PlatformKeyHelpers.md#local-key-helper-on-windows) - MacOS: TBD - Android:TBD -Note: Above are platform specifications for Local Key Helpers that can be used for DBSC(E) key generation. Any platform is free to build a version of this, as long as the API is consistent with the protocol. A detailed protocol will be documented under the DBSC(E) spec. +Note: Above are platform specifications for Local Key Helpers that can be used for DBSC(E) key generation. Any vendor can ship their local key helper in compliance with the DBSC(E). ### Attestation Service @@ -151,12 +155,6 @@ This section defines the artifacts of binding and how they help establish proof There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the [binding key](#binding-key), the [attestation key](#attestation-key), and the [binding statement](#binding-statement). -##### Binding Key - -A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a key ID and it is the responsibility of the browser to remember key ID mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. - -This **binding key** is the same as defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key) which is created in a secure enclave (TPM or Keyguard) on the original device. However, please note that in the context of the DBSC proposal, the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), however, as long as the [device registration process is executed with a clean room environment](#device-registration), binding key can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. - ##### Attestation Key An _attestation key_ is generated during the device registration process and has the following properties: @@ -164,9 +162,21 @@ An _attestation key_ is generated during the device registration process and has 1. It signs only the private/other keys that reside in the same secure enclave as the attestation key. 2. It cannot sign any external payload, or if it signs, it cannot generate an output that can be interpreted as an attestation statement. +TBD: Generalize this for various platforms. + The attestation key also can be uploaded only once to the backend at the moment of device registration, in the clean room, and there is no need to change this key unless the device loses it (Could be due to key rotation or similar operations). -The **attestation key**, hence, can be used to attest that the **binding key** belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an **attestation statement**. Depending on the specific implementation, this **attestation statement** itself can be a **binding statement**, or it can be sent to an attestation service to produce the final binding statement. +The _attestation key_, hence, can be used to attest that the [binding key](#binding-key) belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an _attestation statement_. Depending on the specific implementation, this _attestation statement_ itself can be a _binding statement_, or it can be sent to an attestation service to produce the final binding statement. + +##### Binding Key + +A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a _KeyId_ and it is the responsibility of the browser to remember _KeyId_ mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)) (TBD: add examples above), the key mapping is expected to be managed by the Browser and the Local Key Helper. + +This **binding key** for DBSC(E) is similar to the artifact defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key) which is created in a secure enclave (TPM or Keyguard) on the same device. + +>> TBD: Make this definition single - and link to it here if needed: +In the context of the original DBSC proposal(https://github/wicg/dbsc), the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), however, as long as the [device registration process is executed with a clean room environment](#device-registration), binding key can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. + ##### Binding Statement @@ -200,14 +210,15 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. - - For all _public local key helpers_, e.d., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _shortlived_. If `nonce` is not shortlived, it is possible to steal the `bindingStatement` and the `bindingKey` from a device controlled by the attacker and to be able to bind the cookies to the malicious `bindingKey`. The allowance for long lived `nonce` is possible with _private local key helpers_ and covered [later](#idp-calls-private-local-key-helper). - - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the binding statement, the IDP will be able to validate `nonce` to ensure the `binding statement` is issued recently. - - `nonce` is generated by the IdP/RP as a part of the request, a random number with time sensitivity, and must be embedded in the binding statement. IdP will be able to validate nonce to ensure the binding statement is freshly issued. + - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _shortlived_. If `bindingStatement` is not shortlived, it is possible for the attacker to generate the `bindingStatement` and the `bindingKey` from a device controlled by the attacker and use them to bind the victim's cookies to the malicious `bindingKey`. The enforcement of a shortlived binding statement is achieved through `nonce`. + - The allowance for long lived `bindingStatement` is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of posession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). + - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the `bindingStatement`, the IDP will be able to validate `nonce` to ensure the `binding statement` is issued recently. + - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, and MUST be time sensitive and MUST be verifiable by the issuer. - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. 1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. - - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](./KeyGeneration.md#binding-statement). + - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](#binding-statement). - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the `binding statement`. It is intentionally left undefined, and can be customized. - Local Key Helper can optionally signal the browser to cache the Binding Statement in the browser. This is to avoid repeated calls to the Local Key Helper for the same IdP. The browser can cache the Binding Statement for a certain time, and if the IdP requests a new key within that time, the browser can return the cached Binding Statement. TBD define under which conditions. @@ -248,8 +259,12 @@ A special case is for enterprises that already have `well-known` Local Key Helpe ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) +A _private local key helper_ is a special use case. In this case the IDP owns the local key helper [implementation](#local-key-helper), and can use a private protocol to communicate with the local key helper. + Highlights: + + - Since proof of device is made with SSO headers, the browser can skip the `nonce` and directly call the Local Key Helper. - IDP can validate the binding statement, i.e., the binding key belongs to the correct device. - The headers are modeled with [Microsoft IDP](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens) as an example. It is possible to replace `Microsoft` with `Okta` and achieve the same flow if Okta complies with the device registration. diff --git a/DBSCE/KeyGeneration.md b/DBSCE/PlatformKeyHelpers.md similarity index 100% rename from DBSCE/KeyGeneration.md rename to DBSCE/PlatformKeyHelpers.md From 7bc374584f753e68cb5ef136ff0bc028aa14b362 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Wed, 28 Aug 2024 16:25:32 -0700 Subject: [PATCH 29/47] Add more precision to Why DBSC(E) section , add platform proposals --- DBSCE/LocalKeyHelper-Android.md | 89 +++++++++++++++++ DBSCE/LocalKeyHelper-Mac.md | 96 +++++++++++++++++++ ...eyHelpers.md => LocalKeyHelper-Windows.md} | 4 - DBSCE/Overview.md | 15 +-- 4 files changed, 193 insertions(+), 11 deletions(-) create mode 100644 DBSCE/LocalKeyHelper-Android.md create mode 100644 DBSCE/LocalKeyHelper-Mac.md rename DBSCE/{PlatformKeyHelpers.md => LocalKeyHelper-Windows.md} (94%) diff --git a/DBSCE/LocalKeyHelper-Android.md b/DBSCE/LocalKeyHelper-Android.md new file mode 100644 index 0000000..36cbd26 --- /dev/null +++ b/DBSCE/LocalKeyHelper-Android.md @@ -0,0 +1,89 @@ +!!! DRAFT - Please note this page is still in draft as we work on platform specific details + + +### Local Key Helper on Android +On android platform a Local Key Helper is a protocol interface (`ILocalKeyHelper.java`), and its implementation (`LocalKeyHelperImpl.java`) is yet to be determined. + +Local KeyHelpers on the Android platform are implemented using [content providers](https://developer.android.com/guide/topics/providers/content-providers). These content providers allow browser applications, such as Chrome, to interact with them by querying and accessing specific APIs defined by the Local KeyHelpers. + +#### Content Provider Authority +Each Local KeyHelper defines a content provider with a authority such as `com.contoso.localkeyhelper`. Different APIs are implemented as separate paths on this content provider. + +#### Browser Interaction with Local KeyHelpers +To interact with Local KeyHelpers, browser applications must define a `` inside the `` tag in their manifest file with the same authority `com.contoso.localkeyhelper`. This allows the browser to query the Local KeyHelpers. + +##### Example Manifest Entry +```xml + + + +``` +To get the installed applications that provide a content provider with authority "com.contoso.localkeyhelper" and select a specific package "com.contoso.localkeyhelper.entra" to query the content provider, you can use the following Java code: + +```java +PackageManager packageManager = getPackageManager(); +List installedPackages = packageManager.getInstalledPackages(PackageManager.GET_PROVIDERS); + +for (PackageInfo packageInfo : installedPackages) { + ProviderInfo[] providers = packageInfo.providers; + if (providers != null) { + for (ProviderInfo provider : providers) { + if ("com.contoso.localkeyhelper".equals(provider.authority)) { + // select specific package to query + } + } + } +} +``` + + +#### Implementing the ContentProvider in Local KeyHelper +Each Local KeyHelper must implement a ContentProvider to handle the interactions. Below is an example of how to implement a ContentProvider in a Local KeyHelper. + +##### Example ContentProvider Implementation + +```java +public class LocalKeyHelperProvider extends ContentProvider { + public static final String AUTHORITY = "com.contoso.localkeyhelper"; + private static final UriMatcher uriMatcher = new UriMatcher(UriMatcher.NO_MATCH); + + static { + uriMatcher.addURI(AUTHORITY, "keyhelper1/api1", 1); + // Add more paths as needed + } + + @Override + public boolean onCreate() { + return true; + } + + @Nullable + @Override + public Cursor query(@NonNull Uri uri, @Nullable String[] projection, @Nullable String selection, @Nullable String[] selectionArgs, @Nullable String sortOrder) { + switch (uriMatcher.match(uri)) { + // call the Implementation specific api based on the path + default: + throw new IllegalArgumentException("Unknown URI: " + uri); + } + } +} +``` + +#### Browser Interaction with the ContentProvider +Browser applications can interact with the Local KeyHelper's ContentProvider by querying it. Below is an example of how a browser application can query the ContentProvider. + +##### Example Code to Query the ContentProvider + +```java +Uri uri = Uri.parse("content://com.contoso.localkeyhelper/keyhelper1/api1"); +Cursor cursor = getContentResolver().query(uri, null, null, null, null); +if (cursor != null) { + try { + if (cursor.moveToFirst()) { + // Read the data from the cursor + } + } finally { + cursor.close(); + } +} +``` \ No newline at end of file diff --git a/DBSCE/LocalKeyHelper-Mac.md b/DBSCE/LocalKeyHelper-Mac.md new file mode 100644 index 0000000..66f41f4 --- /dev/null +++ b/DBSCE/LocalKeyHelper-Mac.md @@ -0,0 +1,96 @@ +!!! DRAFT - Please note this page is still in draft as we work on platform specific details + + +### Local key helper on Mac + +On macOS, a Local Key Helper is a protocol (`LocalKeyHelper.h`), and its implementation (`LocalKeyHelperImpl.h`/`LocalKeyHelperImpl.m`) is yet to be determined. + +The Local Key Helper will be implemented and shipped as an XPC service on macOS. It will be signed with app sandbox entitlement for securety requirement. + +To start the Local Key Helper XPC service, the service plist (property list) needs to be defined and registered in the launchAgent. This will ensure the service starts up when a idP sends a service connections. + +Here is an example of the Local Key Helper XPC service plist: + +```xml + + + + + Label + com.contoso.LocalKeyHelper + Program + /pathToXcpService/LocalKepHelper.xpc/Contents/MacOS/LocalKepHelper + KeepAlive + + MachServices + + com.contoso.LocalKeyHelper + + + + +``` + +When the browser (e.g. Chrome) communicates with this service, it needs to establish a service connection first. +Here is an example of starting a new connection with the Local Key Helper: + +```objective-c +// Start a new connection by providing the Local Key Helper defined in the plist +NSXPCConnection* localKeyhelper = [[NSXPCConnection alloc] initWithMachServiceName:@"com.contoso.LocalKeyHelper"]; + +// Make the connection conform to the defined Local Key Helper protocol +[localKeyhelper setRemoteObjectInterface:[NSXPCInterface interfaceWithProtocol:@protocol(LocalKeyHelper)]]; +``` + +The browser (e.g. Chrome) can then call the methods defined in the LocalKeyHelper protocol, and the implementations will be provided by the XPC service. + +**Note:** + +- It is important to define the LocalKeyHelper protocol exactly the same way in both the browser and the XPC service provider. This allows for easy extension of the protocol in the future (e.g. using a dictionary as an input parameter instead of a strict object type). +- The input and output parameters of the XPC service should follow the `NSSecureCoding` protocol. +- Un-sandboxed applications can communicate directly to the XPC service. + +#### Define Available Local Key Helpers +To inform the browser about the Local Key Helper to use, the manifest file is created within the browser's root folder during the LocalKeyHelper's installation (e.g. `/Library/Google/Chrome/LocalKeyHelpers`). This folder contains the following 2 types of files: + +**1st type: files that define the Local Key Helpers** + +i.e. +```` +com.provider1.LocalKeyHelper.json (if helper was installed) +com.provider2.LocalKeyHelper.json (if helper was installed) +com.provider3.LocalKeyHelper.json (if helper was installed) +```` +For example: +```` +com.contoso.LocalKeyHelper.json +```` + +Within the file: + +```json + { + "provider": "contoso", + "xpc": // Local key helper type + { + "service": "com.contoso.LocalKeyHelper", // Service name/API activation id + "version": "0.0.1", // Helper service version + "Idp_resource":"com.contoso.LocalKeyHelper.idP.json" // File path to IdP URL allow-list + } + } +``` + +**2nd type: files that defines the allow-list for IdP URLs:** + +For example: +```` +com.contoso.LocalKeyHelper.idP.json +```` + +```json + { + "urls": ["*.contoso1.com", "login.contoso1.net", "login.contoso2.com"], + } +``` + +The MDM service can do post script to update the URLs in this file without touching the Local Key Helpers file. diff --git a/DBSCE/PlatformKeyHelpers.md b/DBSCE/LocalKeyHelper-Windows.md similarity index 94% rename from DBSCE/PlatformKeyHelpers.md rename to DBSCE/LocalKeyHelper-Windows.md index 5a4caa8..bfe3c0a 100644 --- a/DBSCE/PlatformKeyHelpers.md +++ b/DBSCE/LocalKeyHelper-Windows.md @@ -1,7 +1,3 @@ - -!!! DRAFT - Please note this page is still in draft as we work on platform specific details - - ### Local key helper on Windows On Windows, a Local key helper is a COM class. A COM interface that the local key helper implements is TBD (working name for this document is ILocalKeyHelper) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 7050504..5604b4e 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -65,9 +65,11 @@ Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to ## Why DBSC(E)? -While the original DBSC proposal enables browsers to bind session cookies to a device, it still remains vulnerable to on devie malware. Such a malware can inject its own binding keys if it is present during signin/session establishment, or it can force the user to signin, and provide its own binding keys (asymmetric key pair) to the web application, there by gaining the ability to steal the session. Any upcoming sessions after this, even with DBSC, will not be reliable. Hence a temporary malware presence in the system can result in permanent session compromise in certain cases. +While the original DBSC proposal enables browsers to bind session cookies to a device, it still remains vulnerable to "on device" malware. Such a malware, if present on the device, can inject its own binding keys when the DBSC session is established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a signin session, and potentially hijack all subsequent sessions. Any upcoming sessions after this, even with DBSC, will not be reliable. Hence a temporary malware presence in the system can result in permanent session compromise in certain cases. -DBSC(E) aims to mitigate this risk by introducing the concept of once-in-a-lifetime protected [device registration](#device-registration) operation and binds all the future sessions to a binding key that can be cryptographically proven to be on the same device. DBSC(E) allows for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an enterprise registering a device before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, hence the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. DBSC(E) makes it impossible for malware to compromise a device during signin/login, but DBSC(E) doesn't protect a given session if the malware is present during the device registration or if the malware is persistent on the device and uses device-bound sessions to exfiltrate application data rather than the sessions. +DBSC(E) aims to mitigate this risk by introducing the concept of once-in-a-lifetime protected [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) allows for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an organization registering a device before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, hence the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. + +Therefore, if a device registration is executed in a clean room and precedes any sign in sessions, DBSC(E) makes it impossible for a malware to bind session cookies to malicious binding keys during any sign in operation. However, it is to be noted that, DBSC(E) doesn't protect a given session if the malware is present during the device registration or if the malware is persistent on the device and uses device-bound sessions to exfiltrate application data rather than the sessions. ## How does it integrate with DBSC? @@ -111,10 +113,9 @@ One device registration client can manage multiple devices on the same physical DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" and the management of the generated keys to prove device binding. - ### Device Registration -Any enterprise user is expected to either use a device issued by their organization or register their personal device with an organization. The device registration is expected to be a once-in-a-lifetime protected operation, and the user is expected to perform this operation with a clean room environment. +The device registration is expected to be a once-in-a-lifetime protected operation, and the user is expected to perform this operation with a clean room environment. ![DeviceRegistration](./DeviceRegistration.svg) @@ -139,9 +140,9 @@ The Local Key Helper is responsible for: This section prescribes the browser discovery process of a given local key helper for a few well known platforms: -- [Windows](./PlatformKeyHelpers.md#local-key-helper-on-windows) -- MacOS: TBD -- Android:TBD +- [Windows](./LocalKeyHelper-Windows.md) +- [MacOS](./LocalKeyHelper-Mac.md) +- [Android](./LocalKeyHelper-Android.md) Note: Above are platform specifications for Local Key Helpers that can be used for DBSC(E) key generation. Any vendor can ship their local key helper in compliance with the DBSC(E). From b319b660e171bc3e8bfe8abf91256f63411c5c05 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 29 Aug 2024 14:25:33 -0700 Subject: [PATCH 30/47] Address wording and add `DRAFT` for Private local key helper --- DBSCE/Overview.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 5604b4e..6397d84 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -65,11 +65,11 @@ Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to ## Why DBSC(E)? -While the original DBSC proposal enables browsers to bind session cookies to a device, it still remains vulnerable to "on device" malware. Such a malware, if present on the device, can inject its own binding keys when the DBSC session is established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a signin session, and potentially hijack all subsequent sessions. Any upcoming sessions after this, even with DBSC, will not be reliable. Hence a temporary malware presence in the system can result in permanent session compromise in certain cases. +While the original DBSC proposal enables browsers to bind session cookies to a device, it still remains vulnerable to "on device" malware. Such a malware, if present on the device, can inject its own binding keys when the DBSC session is established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a new signin operation, and potentially hijack all subsequent sessions. Any upcoming sessions after this, even with DBSC, will not be reliable. Hence a temporary malware presence in the system can result in permanent session compromise in certain cases. -DBSC(E) aims to mitigate this risk by introducing the concept of once-in-a-lifetime protected [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) allows for a given session to be bound to the device, if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an organization registering a device before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, hence the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. +DBSC(E) aims to mitigate this risk by introducing the concept of once-in-a-lifetime protected [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) is able to provide this risk mitigation if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an organization registering a device before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, hence the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. -Therefore, if a device registration is executed in a clean room and precedes any sign in sessions, DBSC(E) makes it impossible for a malware to bind session cookies to malicious binding keys during any sign in operation. However, it is to be noted that, DBSC(E) doesn't protect a given session if the malware is present during the device registration or if the malware is persistent on the device and uses device-bound sessions to exfiltrate application data rather than the sessions. +Therefore, if a device registration is executed in a clean room and precedes any sign in sessions, DBSC(E) makes it impossible for a malware to bind session cookies to malicious binding keys during a sign in operation that implements DBSC(E). However, it is to be noted that, DBSC(E) doesn't protect a given session if the malware is present during the device registration or if the malware is persistent on the device and uses device-bound sessions to exfiltrate application data rather than the sessions. ## How does it integrate with DBSC? @@ -95,7 +95,7 @@ IdP is an authentication server that can be either external to the Relying Party This is a pre-requisite for DBSC(E) to work. -Device Registration Client is a process where the user or administrator registers the device with the IdP and is expected to be a once-in-a-lifetime protected operation. +Device Registration is a process where the user or administrator registers the device with the IdP and is expected to be a once-in-a-lifetime protected operation. The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. @@ -113,7 +113,6 @@ One device registration client can manage multiple devices on the same physical DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" and the management of the generated keys to prove device binding. -### Device Registration The device registration is expected to be a once-in-a-lifetime protected operation, and the user is expected to perform this operation with a clean room environment. @@ -154,7 +153,7 @@ A service that is responsible for verifying that the binding key is issued by th This section defines the artifacts of binding and how they help establish proof of binding. -There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the [binding key](#binding-key), the [attestation key](#attestation-key), and the [binding statement](#binding-statement). +There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the [attestation key](#attestation-key), the [binding key](#binding-key), and the [binding statement](#binding-statement). ##### Attestation Key @@ -178,7 +177,6 @@ This **binding key** for DBSC(E) is similar to the artifact defined in the DBSC >> TBD: Make this definition single - and link to it here if needed: In the context of the original DBSC proposal(https://github/wicg/dbsc), the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), however, as long as the [device registration process is executed with a clean room environment](#device-registration), binding key can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. - ##### Binding Statement Additonal to the binding key, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. @@ -255,21 +253,13 @@ For easy mapping with the existing DBSC proposal, please note: ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) #### IDP Calls Private Local Key Helper +!!! DRAFT - Please note this section is still in draft as we work on platform specific details + Date: Wed, 4 Sep 2024 13:37:56 -0700 Subject: [PATCH 31/47] Address feedback, reword some of the key gen specifics --- DBSCE/LocalKeyHelper-Mac.md | 2 +- DBSCE/Overview.md | 93 ++++++++++++++++++------------------- 2 files changed, 45 insertions(+), 50 deletions(-) diff --git a/DBSCE/LocalKeyHelper-Mac.md b/DBSCE/LocalKeyHelper-Mac.md index 66f41f4..23c448c 100644 --- a/DBSCE/LocalKeyHelper-Mac.md +++ b/DBSCE/LocalKeyHelper-Mac.md @@ -5,7 +5,7 @@ On macOS, a Local Key Helper is a protocol (`LocalKeyHelper.h`), and its implementation (`LocalKeyHelperImpl.h`/`LocalKeyHelperImpl.m`) is yet to be determined. -The Local Key Helper will be implemented and shipped as an XPC service on macOS. It will be signed with app sandbox entitlement for securety requirement. +Each _Local key helper_ vendor will implement and ship as an XPC service on macOS. It will be signed with app sandbox entitlement for security requirement. To start the Local Key Helper XPC service, the service plist (property list) needs to be defined and registered in the launchAgent. This will ensure the service starts up when a idP sends a service connections. diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 6397d84..a5532c1 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -89,7 +89,7 @@ A web application that uses DBSC(E) protocol for cookie binding. This is referre ### Identity Provider (IdP) -IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft Entra ID or google.com authenticating with google. Note: The protocol doesn't change if the IDP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. In the original [DBSC design](https://githuub.com/wicg/dbsc), IDP and RP are the same entity, and referred to as `server`. +IdP is an authentication server that can be either external to the Relying Party or part of the Relying Party. Eg: Office.com authenticating with Microsoft Entra ID (external IDP) or google.com authenticating with google (no separate IDP). Note: The protocol doesn't change if the IDP is part of the Relying Party, except that some redirects between the IdP and the RP can be skipped or implemented by other means. In the original [DBSC design](https://githuub.com/wicg/dbsc), IDP and RP are the same entity, and referred to as `server`. ### Device Registration Client @@ -97,22 +97,23 @@ This is a pre-requisite for DBSC(E) to work. Device Registration is a process where the user or administrator registers the device with the IdP and is expected to be a once-in-a-lifetime protected operation. -The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. +The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key, [attestation key](#attestation-key) and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. A clean room enviroment is a reliable, malware and exploit free state of a system. Examples can be: -- New device from the factory connected to a secure network during registration -- Company issued devices configured by admin for the employees -- A malware free device installing browser in a secure network +- New device from the factory connected to a secure network during registration. +- Company issued devices configured by admin for the employees. +- A malware free device installing browser in a secure network. -One device registration client can manage multiple devices on the same physical device. There also can be multiple device registration clients on the same device. The device registration client can be owned and supported by: +One device registration client can manage multiple devices on the same physical device. There also can be multiple device registration clients on the same device. For example, a user can register a device to their organization as an employee and can simultaneously register the same device for a vendor organization. Both these registrations can either be managed by a single device registration client or through separate device registration clients depending on the implementation and separation between these organizations. + +The device registration client can be owned and supported by: - Operating system - the device gets registered when the OS is installed. - Browser - the device gets registered when the browser is installed. - Device management software (MDM provider) - the device gets registered when the MDM is enrolled. - Third-party software vendor - the device gets registered according to the vendor rules. -DBSC(E) aims to support most of these scenarios. It does not define the device registration protocol and is only concerned with the keys generated in a "clean room" and the management of the generated keys to prove device binding. - +DBSC(E) aims to support most of these scenarios. DBSC(E) does not define the device registration protocol, but is only concerned that the device registration is executed in a "clean room" and the management of the generated keys to prove device binding. The device registration is expected to be a once-in-a-lifetime protected operation, and the user is expected to perform this operation with a clean room environment. @@ -147,11 +148,15 @@ Note: Above are platform specifications for Local Key Helpers that can be used f ### Attestation Service -A service that is responsible for verifying that the binding key is issued by the expected device and providing the attestation of the key to the IdP. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. We have added details on the specifics of the binding artifacts generated during the device registration process, and the validation of the binding statement in the [DBSC(E) Key Generation](#key-generation-specifics) section. +Attestation service is responsible for +- verifying that the binding key is issued by the expected device. +- providing the attestation of the key to the IdP. -#### Key Generation Specifics +The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. An attestation service can be part of the IdP, or a separate service. -This section defines the artifacts of binding and how they help establish proof of binding. +This document does not define the implementation details of the Attestation Service. It defines the artifacts which are generated during the [Device Registration](#device-registration-client) and are necessary for the Attestation Service to validate the binding statement. + +#### Key Generation Specifics There are three artifacts that are generated during/after the device registration process, which are used to prove the device binding. These are the [attestation key](#attestation-key), the [binding key](#binding-key), and the [binding statement](#binding-statement). @@ -162,41 +167,40 @@ An _attestation key_ is generated during the device registration process and has 1. It signs only the private/other keys that reside in the same secure enclave as the attestation key. 2. It cannot sign any external payload, or if it signs, it cannot generate an output that can be interpreted as an attestation statement. -TBD: Generalize this for various platforms. +In addition, the _attestation key_ can be uploaded only once to the backend at the moment of device registration, in the clean room, and is seldom changed unless the device loses it (could be due to key rotation or similar operations). -The attestation key also can be uploaded only once to the backend at the moment of device registration, in the clean room, and there is no need to change this key unless the device loses it (Could be due to key rotation or similar operations). +The _attestation key_, hence, can be used to attest that the [binding key](#binding-key) belongs to the same device as the _attestation key_, by signing the public part of the _binding key_ (with the _attestation key_) and generating an _attestation statement_. Depending on the specific implementation, this _attestation statement_ itself can be a _binding statement_, or it can be sent to an [attestation service](#attestation-service) to produce the final _binding statement_. -The _attestation key_, hence, can be used to attest that the [binding key](#binding-key) belongs to the same device as the attestation key, by signing the public part of the binding key (with the attestation key) and generating an _attestation statement_. Depending on the specific implementation, this _attestation statement_ itself can be a _binding statement_, or it can be sent to an attestation service to produce the final binding statement. +Note: _Attestation Key_ is also referred as _AIK_ in the document in some of the flow diagrams below. ##### Binding Key -A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a _KeyId_ and it is the responsibility of the browser to remember _KeyId_ mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)) (TBD: add examples above), the key mapping is expected to be managed by the Browser and the Local Key Helper. +A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a _KeyId_ and it is the responsibility of the browser to remember _KeyId_ mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. -This **binding key** for DBSC(E) is similar to the artifact defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session) and is expected to be cryptographically attested by the [attestation key](#attestation-key) which is created in a secure enclave (TPM or Keyguard) on the same device. - ->> TBD: Make this definition single - and link to it here if needed: -In the context of the original DBSC proposal(https://github/wicg/dbsc), the binding key validation is not guaranteed to be attack free, as it can be generated by malware, if the malware is present on the device. In the context DBSC(E), however, as long as the [device registration process is executed with a clean room environment](#device-registration), binding key can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. +This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session). It is expected to be cryptographically attested by the [attestation key](#attestation-key) where the _attestation key_ is expected to be created in a secure enclave (TPM or Keyguard) on the same device. The original DBSC proposal(https://github/wicg/dbsc) does not guarantee the _binding key_ validation to be attack free, as it can be generated by a malware, [if the malware is present on the device](#why-dbsce). However, in DBSC(E), as long as the [device registration process is executed with a clean room environment](#device-registration), _binding key_ can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. ##### Binding Statement -Additonal to the binding key, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. +Additonal to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. -The validation of the **binding statement** authenticates the device by using device ID to find the corresponding attestation key. The validation component verifies the **attestation statement**, and it can understand that such a statement cannot be generated, unless the private key resides in the same secure enclave when signed by the **attestation key**. Hence, a valid attestation statement means that both the attestation key and the binding key belong to the same device. The validation component can be part of the attestation service for public local key helpers, or part of an IdP for private local key helper. +The validation of the _binding statement_ authenticates the device by using device ID to find the corresponding _attestation key_. The validation component verifies the _attestation statement_ or the _binding statement_ (difference illustrated [in the section above](#attestation-key)), and it can understand that such a statement cannot be generated, unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _attestation statement_ or _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. The validation component can be part of the _attestation service_ for public local key helpers, or part of an IdP for private local key helpers. -This is not the only way to ensure that the binding key and the device key belong to the same device, and having the **attestation key** and the **attestation service** is not mandatory for producing a **binding statement**. That is why the protocol specifics of checking the binding are out of scope for this document. The focus of DBSC(E) is to only establish important properties of the binding statement. +This is not the only way to ensure that the _binding key_ and the _device key_ belong to the same device, and having the _attestation key_ and the _attestation service_ is not mandatory for producing a _binding statement_. That is why the protocol specifics of checking the binding are out of scope for this document. The focus of DBSC(E) is to only establish important properties of the _binding statement_. -Binding statements can be long-lived or short-lived. If an IdP can perform proof of device, it can use long-lived binding statements based on attestation keys to avoid extra network calls. IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements to prevent forgery of the binding statement from a different device. To avoid binding statement forgery, a short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement. +Binding statements can be long-lived or short-lived. +- If an IdP performs fresh device authentication outside of DBSC(E) integration at the time of _binding key_ validation, then the _binding statement_ can be long lived, as the IdP ensures the device identity through other mechanisms. +- IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements. Otherwise, the attacker will be able to bind the victim's cookies to malicious keys from a different machine. A short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement, hence preventing the attack. ## High-Level Design -DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an existing policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. +DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an enterprise policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. The high-level design is divided into two parts: 1. Key generation and validation before the session starts (DBSC(E) is focused on this part). 2. DBSC protocol applied with the generated keys (DBSC is focused on this part). -Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, we differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Okta, Github to ship their own private local key helpers. DBSC(E) protocol also provides multiple extension points that simplify and improve performance for specific scenarios. The [DBSC(E) use cases](#dbsce-use-cases) section expands on some of these scenarios. +Since we want to integrate DBSC(E) with the original design and make it as widely applicable as possible for all enterprise users, we are adding high-level design for the most possible combinations in this document. The intent is to have a specification that can be implemented by any browser vendor, and can be used by any IdP, and any Local Key Helper. As we cover different use cases DBSC(E) can be applied for, we differentiate between private and public local key helpers, since there are implications to the protocol based on the type of local key helper. For example, we expect well establised IdPs like Microsoft, Github to ship their own private local key helpers. DBSC(E) protocol also provides multiple extension points that simplify and improve performance for specific scenarios. The [DBSC(E) use cases](#dbsce-use-cases) section expands on some of these scenarios. DBSC(E) (in contrast with DBSC): @@ -208,22 +212,21 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. - - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _shortlived_. If `bindingStatement` is not shortlived, it is possible for the attacker to generate the `bindingStatement` and the `bindingKey` from a device controlled by the attacker and use them to bind the victim's cookies to the malicious `bindingKey`. The enforcement of a shortlived binding statement is achieved through `nonce`. - - The allowance for long lived `bindingStatement` is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of posession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). - - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the `bindingStatement`, the IDP will be able to validate `nonce` to ensure the `binding statement` is issued recently. - - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, and MUST be time sensitive and MUST be verifiable by the issuer. - - The `Sec-Session-HelperIdList` header contains a list of helper IDs that the browser can use to generate the key. As we touched upon before, there could be multiple devices on a single physical device, and/or multiple device registration clients on a single device. The `HelperId` helps the browser to choose the right **Local Key Helper** to generate the key. The browser will evaluate the policy for the IdP and the helper IDs, and choose the appropriate helper ID to generate the key. The browser will then call the Local Key Helper to generate the key. + - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a _nonce_ and any extra parameters that the IdP wants to send to the Local Key Helper. _nonce_ is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. + - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, _nonce_ must be _shortlived_. If _binding statement_ is not shortlived, it is possible for the attacker to generate the _binding statement_ and the _binding key_ from a device controlled by the attacker and use them to bind the victim's cookies to the malicious _binding key_. The enforcement of a shortlived binding statement is achieved through _nonce_. + - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of posession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). + - _nonce_ also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the _nonce_ sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate _nonce_ to ensure the _binding statement_ is issued recently. + - _nonce_ is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. + - The `Sec-Session-HelperIdList` header contains an ordered list of helper IDs that the browser can use to generate the key. The browser typically picks the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. -1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. +1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the _nonce_ sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. - - Format of the Binding Statement: We expect the `binding statement` will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the `binding statement` is prescribed to include `nonce` and the thumbprint of the public key. The `binding statement` is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on `binding statement` can be found [here](#binding-statement). - - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the `binding statement`. It is intentionally left undefined, and can be customized. - - Local Key Helper can optionally signal the browser to cache the Binding Statement in the browser. This is to avoid repeated calls to the Local Key Helper for the same IdP. The browser can cache the Binding Statement for a certain time, and if the IdP requests a new key within that time, the browser can return the cached Binding Statement. TBD define under which conditions. + - Format of the Binding Statement: We expect the _binding statement_ will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the _binding statement_ is prescribed to include _nonce_ and the thumbprint of the public key. The _binding statement_ is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on _binding statement_ can be found [here](#binding-statement). + - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the _binding statement_. It is intentionally left undefined, and can be customized. -1. **Sign In/Session Initiation (steps 8-9):** The `Binding Statement`, with the `KeyId` is expected to be returned to the IdP witha new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement---generation-and-validation) the signature on the `Binding Statement`, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. +1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement) the signature on the _binding statement_, _nonce_ and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. -1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with additional params introduced for DBSC(E) customization. +1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with two caveats: The _local key helper_ is called for JWT generation and the additional params introduced for DBSC(E) customization can be optionally added. ### DBSC(E) use cases @@ -231,15 +234,15 @@ This section expands on the [generic design](#high-level-design) to address diff #### IDP is RP and Calls Public Local Key Helper -This is the same use case elaborated in the high level design [above](#high-level-design). However, we have separated the IdP/RP components of the server for the enterprise use case in the below diagram. +This is the same use case elaborated in the high level design [above](#high-level-design). However, we have separated the IdP/RP components of the server that applies to certain enterprise and consumer use cases in the below diagram. ![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) Highlights: -- Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of identity token. In such case, the IdP can generate the auth tokens and embed the thumbprint of the public key in the token. -- The token can be delivered to the RP directly through an API instead of a header based response. -- The tokens also contain the thumpbrint of the public key, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. +- Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of auth tokens and issue cookies based on those tokens. In such case, the IdP can generate the auth tokens and embed the thumbprint of the public key in the token. +- The tokens can be delivered to the RP directly through an API instead of a header based response. +- The tokens also contain the thumbbrint of the public key, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. The RP will also embed the thumbprint in the cookie for subsequent session validation. #### IDP Calls Public Local Key Helper @@ -252,14 +255,6 @@ For easy mapping with the existing DBSC proposal, please note: ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) -#### IDP Calls Private Local Key Helper -!!! DRAFT - Please note this section is still in draft as we work on platform specific details - Date: Wed, 4 Sep 2024 15:26:51 -0700 Subject: [PATCH 32/47] Update Private local key helper section --- DBSCE/Overview.md | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index a5532c1..f87c6ac 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -212,19 +212,20 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a _nonce_ and any extra parameters that the IdP wants to send to the Local Key Helper. _nonce_ is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. - - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, _nonce_ must be _shortlived_. If _binding statement_ is not shortlived, it is possible for the attacker to generate the _binding statement_ and the _binding key_ from a device controlled by the attacker and use them to bind the victim's cookies to the malicious _binding key_. The enforcement of a shortlived binding statement is achieved through _nonce_. + - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. + - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _short lived_. If _binding statement_ is not shortlived, it is possible for the attacker to generate the _binding statement_ and the _binding key_ from a device controlled by the attacker and use them to bind the victim's cookies to the malicious _binding key_. The enforcement of a shortlived binding statement is achieved through `nonce`. - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of posession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). - - _nonce_ also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the _nonce_ sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate _nonce_ to ensure the _binding statement_ is issued recently. - - _nonce_ is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. - - The `Sec-Session-HelperIdList` header contains an ordered list of helper IDs that the browser can use to generate the key. The browser typically picks the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. + - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate `nonce` to ensure the _binding statement_ is issued recently. + - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. + - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser typically prefers the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. -1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the _nonce_ sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. +1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. - - Format of the Binding Statement: We expect the _binding statement_ will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the _binding statement_ is prescribed to include _nonce_ and the thumbprint of the public key. The _binding statement_ is expected to be shortlived to prevent forgery of the binding statement from a different device. More details on _binding statement_ can be found [here](#binding-statement). + - Format of the Binding Statement: We expect the [_binding statement_](#binding-statement) will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the _binding statement_ is prescribed to include `nonce` and the thumbprint of the public key. The _binding statement_ is expected to be shortlived as covered in the previous section. More details on _binding statement_ can be found [here](#binding-statement). + - The [_attestation service_](#attestation-service) is also separate from the IDP - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the _binding statement_. It is intentionally left undefined, and can be customized. -1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement) the signature on the _binding statement_, _nonce_ and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. +1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. 1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with two caveats: The _local key helper_ is called for JWT generation and the additional params introduced for DBSC(E) customization can be optionally added. @@ -246,15 +247,29 @@ Highlights: #### IDP Calls Public Local Key Helper -In many use cases, it is also a valid to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where these are separate entities and probably from different vendors below. +In many use cases, it is also a valid to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where the IdP calls a _public Local Key Helper_ and is a separate service from the RP below. For easy mapping with the existing DBSC proposal, please note: - Steps 1-16 specify the key generation process for a public local key helper. - Steps 17-29 are [DBSC](https://github.com/wicg/dbsc), added for completeness. + ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) +#### IDP Calls Private Local Key Helper + +As referred in [Local Key Helper](#local-key-helper) section, it is possible for an IdP to implement a private local key helper and establish a private protocol to communicate. Any such private local key helper can only be used by the specific IDP that owns its implementation. + +In DBSC(E), the use of private local key helper for specific IDPs enables the below optimizations: + +- Since the IDP can trust the private local key helper, the `HelperId` discovery can be optimized by caching. An IDP can specify its preferred ordered list of `HelperId`s in any response, and can request the browser to cache its preference for a specific duration(`HelperCacheTime`). Also, such requests need not be initiated by the RP that implements DBSC(E), the IDP can specify its `HelperIdList` in any communication(request/response) within the browser context. +- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of presence of the device by its own proprietery mechanism (usually authentication) for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache those binding statements for further performance optimization. +- RP can combine the request for a DBSC(E) session as a part of IDP redirection during sign-in. If the key generation and sign in are successful, the browser can intercept the sign-in flow to generate (with local key helper, which is private to IdP) and append the new JWT proof to the response, before navigating to RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. + + +![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) + ### Cleanup of the binding keys and their artifacts For the health of the operating system and user privacy, it is important to clean up binding keys and their artifacts. If the number of keys grows too high, the performance of the OS can degrade. From c6509dea4a49a67172dcadf91e842263085bc87b Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Wed, 4 Sep 2024 16:00:18 -0700 Subject: [PATCH 33/47] Refine binding statement and binding key desc --- DBSCE/Overview.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index f87c6ac..02dd27f 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -148,11 +148,7 @@ Note: Above are platform specifications for Local Key Helpers that can be used f ### Attestation Service -Attestation service is responsible for -- verifying that the binding key is issued by the expected device. -- providing the attestation of the key to the IdP. - -The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to validate the binding statement and ensure that the binding key and the device key belong to the same device. An attestation service can be part of the IdP, or a separate service. +Attestation service is responsible for providing the attestation statement for the binding key. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to enable the IDP to validate the binding statement and ensure that the binding key and the device key belong to the same device. An attestation service can be part of the IdP, or a separate service. This document does not define the implementation details of the Attestation Service. It defines the artifacts which are generated during the [Device Registration](#device-registration-client) and are necessary for the Attestation Service to validate the binding statement. @@ -175,21 +171,19 @@ Note: _Attestation Key_ is also referred as _AIK_ in the document in some of the ##### Binding Key -A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a _KeyId_ and it is the responsibility of the browser to remember _KeyId_ mapping to _Local Key Helper_ and _RP_ and to use it for DBSC signatures and key management. As there could be multiple `devices` on a single physical device and or many device registration clients on a single device (mentioned [above](#device-registration-client)), the key mapping is expected to be managed by the Browser and the Local Key Helper. +A _binding key_ is an asymmetric key pair that is used to bind an auth cookie. It is identified by a _KeyId_ and it is the responsibility of the browser to remember the _KeyId_ mapping to _Local Key Helper_ and _RP_. The _Local Key helper_ uses the _KeyId_ for DBSC signatures and key management. -This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session). It is expected to be cryptographically attested by the [attestation key](#attestation-key) where the _attestation key_ is expected to be created in a secure enclave (TPM or Keyguard) on the same device. The original DBSC proposal(https://github/wicg/dbsc) does not guarantee the _binding key_ validation to be attack free, as it can be generated by a malware, [if the malware is present on the device](#why-dbsce). However, in DBSC(E), as long as the [device registration process is executed with a clean room environment](#device-registration), _binding key_ can be mapped to a specific device and the bound session is protected from any malware trying to infilterate it. +This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC proposal [here](https://github.com/WICG/dbsc?tab=readme-ov-file#maintaining-a-session). It is expected to be cryptographically attested by the [attestation key](#attestation-key) where the _attestation key_ is expected to be created in a secure enclave (TPM or Keyguard) on the same device. The original DBSC proposal(https://github/wicg/dbsc) does not guarantee the _binding key_ validation to be attack free, as it can be generated by a malware [if the malware is present on the device](#why-dbsce) and used on a different device. In DBSC(E), if [device registration process is executed with a clean room environment](#device-registration), the _binding key_ is ensured to be generated and used in the same device. ##### Binding Statement Additonal to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. -The validation of the _binding statement_ authenticates the device by using device ID to find the corresponding _attestation key_. The validation component verifies the _attestation statement_ or the _binding statement_ (difference illustrated [in the section above](#attestation-key)), and it can understand that such a statement cannot be generated, unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _attestation statement_ or _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. The validation component can be part of the _attestation service_ for public local key helpers, or part of an IdP for private local key helpers. - -This is not the only way to ensure that the _binding key_ and the _device key_ belong to the same device, and having the _attestation key_ and the _attestation service_ is not mandatory for producing a _binding statement_. That is why the protocol specifics of checking the binding are out of scope for this document. The focus of DBSC(E) is to only establish important properties of the _binding statement_. +The validation of the _binding statement_ authenticates the device by using device ID to find the corresponding _attestation key_. The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. Binding statements can be long-lived or short-lived. - If an IdP performs fresh device authentication outside of DBSC(E) integration at the time of _binding key_ validation, then the _binding statement_ can be long lived, as the IdP ensures the device identity through other mechanisms. -- IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements. Otherwise, the attacker will be able to bind the victim's cookies to malicious keys from a different machine. A short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement, hence preventing the attack. +- IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements. Otherwise, the attacker will be able to bind the victim's cookies to malicious keys from a different machine. A short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement, minimizing the attack window. ## High-Level Design From 12ae2069c7d09f87ff5098f502acbde0d825b66d Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 5 Sep 2024 11:36:50 -0700 Subject: [PATCH 34/47] Minor edit on language, feedback --- DBSCE/Overview.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 02dd27f..1d4ce9f 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -61,15 +61,17 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' ## Overview -Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to the existing [DBSC](https://github.com/wicg/dbsc) proposal. It refines the key generation mechanism resulting in additional security for enterprise use cases. It aims to provide a mechanism for enterprise and advanced browser customers to be able to deploy enhanced/customised device binding for any browser session, hence protecting against session hijacking and cookie theft. +Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to the existing [DBSC](https://github.com/wicg/dbsc) proposal. It refines the key generation mechanism resulting in additional security for enterprise use cases. It aims to provide a mechanism for enterprise customers to be able to deploy enhanced/customised device binding for any browser session, hence protecting against session hijacking and cookie theft. ## Why DBSC(E)? -While the original DBSC proposal enables browsers to bind session cookies to a device, it still remains vulnerable to "on device" malware. Such a malware, if present on the device, can inject its own binding keys when the DBSC session is established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a new signin operation, and potentially hijack all subsequent sessions. Any upcoming sessions after this, even with DBSC, will not be reliable. Hence a temporary malware presence in the system can result in permanent session compromise in certain cases. +While the original DBSC proposal enables browsers to bind session cookies to a device providing protection from network based attacks, it still remains vulnerable to "on device" malware. Temporary malware on the device can inject its own binding keys when the DBSC session is established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a new signin operation, and potentially hijack all subsequent sessions. -DBSC(E) aims to mitigate this risk by introducing the concept of once-in-a-lifetime protected [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) is able to provide this risk mitigation if the device registration is performed when there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an organization registering a device before giving a device to an employee. Device registration is also expected to be a once-in-a-lifetime protected operation, hence the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. +DBSC(E) aims to mitigate this risk by introducing the concept of `one-time protected` [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) is able to provide this risk mitigation if the device registration is a `protected` operation, which means there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an organization registering a device before giving a device to an employee. As device registration is expected to be a `one-time` operation, the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. -Therefore, if a device registration is executed in a clean room and precedes any sign in sessions, DBSC(E) makes it impossible for a malware to bind session cookies to malicious binding keys during a sign in operation that implements DBSC(E). However, it is to be noted that, DBSC(E) doesn't protect a given session if the malware is present during the device registration or if the malware is persistent on the device and uses device-bound sessions to exfiltrate application data rather than the sessions. +If device registration is executed in a clean room and precedes any sign in sessions malware would not be able to bind session cookies to malicious binding keys during a sign in operation that implements DBSC(E). + +Note: While DBSC(E) hardens security against temporary malware attacks, if the malware is persistent on the device, the malware can still exfiltrate data. ## How does it integrate with DBSC? @@ -95,7 +97,7 @@ IdP is an authentication server that can be either external to the Relying Party This is a pre-requisite for DBSC(E) to work. -Device Registration is a process where the user or administrator registers the device with the IdP and is expected to be a once-in-a-lifetime protected operation. +Device Registration is a process where the user or administrator registers the device with the IdP and is expected to be a one time protected operation. The device registration establishes trust between the device and a service that maintains a directory of all devices. This document does not cover the protocol of device registration, but it assumes that during device registration, some asymmetric keys are shared between the client and the service, typically a device key, [attestation key](#attestation-key) and some other keys necessary for the secure device communication. A client software component that performs the device registration is called a _device registration client_. As mentioned above, the key assumption in DBSC(E) is that device registration happened in a clean room environment, and it is the responsibility of the device owner to ensure this. @@ -115,17 +117,15 @@ The device registration client can be owned and supported by: DBSC(E) aims to support most of these scenarios. DBSC(E) does not define the device registration protocol, but is only concerned that the device registration is executed in a "clean room" and the management of the generated keys to prove device binding. -The device registration is expected to be a once-in-a-lifetime protected operation, and the user is expected to perform this operation with a clean room environment. - ![DeviceRegistration](./DeviceRegistration.svg) ### Local Key Helper DBSC(E) introduces the concept of `Local Key Helper`. -**Local Key Helper** is an integral part of the the **Device Registration Client**, a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IDP/OS) or can be installed by a provider in compliance with the protocol expanded below. DBSC(E) defines browser interaction with _Local key helpers_ for each platform. Those details are outlined in [KeyGeneration.md](./KeyGeneration.md). +**Local Key Helper** is an integral part of the the `Device Registration Client`, and is a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IDP/OS) or can be installed by a provider in compliance with the protocol expanded below. DBSC(E) defines browser interaction with _Local key helpers_ for each platform. Those details are outlined in [KeyGeneration.md](./KeyGeneration.md). -From the deployment point of view there are two types of local key helpers: _private_ and _public_ +There are two types of local key helpers: _private_ and _public_ - _Public local key helper_: Expected to have a well-documented API and can be used by any Identity Provider (IdP). Typically owned by a provider different from the IdP, communicates with the IdP as defined in DBSC(E) protocol. - _Private local key helper_ : Is specific to an IdP. Can be only used by a specific IDP that owns the implementation and will have a private protocol to communicate with the IdP. @@ -150,7 +150,7 @@ Note: Above are platform specifications for Local Key Helpers that can be used f Attestation service is responsible for providing the attestation statement for the binding key. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to enable the IDP to validate the binding statement and ensure that the binding key and the device key belong to the same device. An attestation service can be part of the IdP, or a separate service. -This document does not define the implementation details of the Attestation Service. It defines the artifacts which are generated during the [Device Registration](#device-registration-client) and are necessary for the Attestation Service to validate the binding statement. +This document does not define the implementation details of the Attestation Service. It defines the artifacts which are generated during the [Device Registration](#device-registration-client) and are necessary to validate the binding statement. #### Key Generation Specifics @@ -211,15 +211,15 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of posession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate `nonce` to ensure the _binding statement_ is issued recently. - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. - - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser typically prefers the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. + - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser must prefer the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. 1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. - Format of the Binding Statement: We expect the [_binding statement_](#binding-statement) will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the _binding statement_ is prescribed to include `nonce` and the thumbprint of the public key. The _binding statement_ is expected to be shortlived as covered in the previous section. More details on _binding statement_ can be found [here](#binding-statement). - - The [_attestation service_](#attestation-service) is also separate from the IDP + - The [_attestation service_](#attestation-service) is also separate from the IDP in this diagram. - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the _binding statement_. It is intentionally left undefined, and can be customized. -1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP will [validate](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. +1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP [validates](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. 1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with two caveats: The _local key helper_ is called for JWT generation and the additional params introduced for DBSC(E) customization can be optionally added. @@ -258,8 +258,8 @@ As referred in [Local Key Helper](#local-key-helper) section, it is possible for In DBSC(E), the use of private local key helper for specific IDPs enables the below optimizations: - Since the IDP can trust the private local key helper, the `HelperId` discovery can be optimized by caching. An IDP can specify its preferred ordered list of `HelperId`s in any response, and can request the browser to cache its preference for a specific duration(`HelperCacheTime`). Also, such requests need not be initiated by the RP that implements DBSC(E), the IDP can specify its `HelperIdList` in any communication(request/response) within the browser context. -- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of presence of the device by its own proprietery mechanism (usually authentication) for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache those binding statements for further performance optimization. -- RP can combine the request for a DBSC(E) session as a part of IDP redirection during sign-in. If the key generation and sign in are successful, the browser can intercept the sign-in flow to generate (with local key helper, which is private to IdP) and append the new JWT proof to the response, before navigating to RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. +- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of presence of the device by its own proprietery mechanism (usually authentication) for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache [TDD: Add more specifics here] those binding statements for further performance optimization. +- RP can combine the request for a DBSC(E) session as a part of IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the sign-in flow to generate (with local key helper, which is private to IdP) and append the new JWT proof to the response, before navigating to RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. [TDD: Follow up the conditions of redirection with google, is the URL enough or do we need the KeyId?] ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) From 12a70ac2b6155f86dbb0a260c310c0645e98e45d Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 6 Sep 2024 12:16:23 -0700 Subject: [PATCH 35/47] Update editable links --- DBSCE/Overview.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 1d4ce9f..77bb267 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -118,6 +118,7 @@ The device registration client can be owned and supported by: DBSC(E) aims to support most of these scenarios. DBSC(E) does not define the device registration protocol, but is only concerned that the device registration is executed in a "clean room" and the management of the generated keys to prove device binding. ![DeviceRegistration](./DeviceRegistration.svg) +[Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIBFIG4gMYwE6QOYgM7DQIagD2AdgFDkECuwZ1AtgEaRrQCM5ADgWqMiB6lg0AETwkqaBmx5CJUtGTgQkYaOgEccbr36CCwsQEFgwSHiIgy0HK0mQNW6Mcqli56MQSs4AGhcALmgABTRvXGtSEFJMaAA6RPJYAFoAPjTjYIAlLFxzNgATRBQYAAoJUoBpSABPAOMASSroADNiNiqAcQbmto7oABUQgFlelva2AGViVuAAd15IAEpyY3S02GCAJgAGXegAeSrKIA) ### Local Key Helper @@ -199,6 +200,7 @@ Since we want to integrate DBSC(E) with the original design and make it as widel DBSC(E) (in contrast with DBSC): ![DBSC(E) Highlevel Design](<./DBSC(E).svg>) +[Link to editable diagram](https://sequencediagram.org/index.html#initialData=FABwhgTgLglgxjcA7KACARAHjgewDY4QBcAxAEZ4CuApgHwCCUU1AzlGLDkqgMrUQA3eNXSowLVC1CRYCZGiy4CxclToAZHHDB4A0tQCeACWp4Q-VAAoAStRB4wcVqgAqABQCyASlHjUUaWh4RDAUDAAhCBwAdxZ+XwkyQNkQsPQ+QX4AHSRsfEJSChpaazcAegBJABE3BNRo4GAwSiguSgBbMgsARmAyAFpaaKJUPOVCtVpUSjiIVBgkGFgOZ0wypUIplhgAcyR+hdQAMwJo0Y2VIrp57igAC2pUMijYizWLqeBowbIRsYLVMUAMwABgATDk+HB+nwWNsuP0AOLUJD8Fb6AwjHKlACqEDwABpUNU3HjCag4HcdHgUTtqABeJBcJxE6gADygEDAbkgYHaLAAdEKcpDqNDYfD9iYzPwKgATdQwNhYpAAbWl5gg8u6RI1srlYKJQoAurrTJqAMKOB4uGDtajAJnMVA4AQWX7-S6TZ4xWY3AQ4ADWzgI2jwqGDBlQDxlcxyrVQIAg1H6dNRXOdkYkT3E1DlLu4VXCPAtlgAol5o9QwHL+CwRbkLhNinBKBBkyg9Vq5fSctQBDpKCtE-h4FGjoRUDlLBk3RAAN4kslE3H4gC+RPV5v1OtQXflYKFAuNXj6gygI2TAEcaGwKcnh5HwDA4438l7ipZZnOyYuasvUFXPANwpKk8BpJA6VZDkuR5Ll+QAfi8HJE2TVA0zRZgJEjMQkHzDgsPYTgkGAKBzz+JtAToDCM2oDFLFPJ1HldCwL1QAAxScyxQfgkyVagiXuJUKWpeoYHAp5HnsDgJwgdocjIXN8wAMnQlFMOcWshCcMQmFYIiYC4UjBhYCj32baj1No8IFjlBYdh4IjqHtFBpxASgKHgDEiXoCpdCJSlqVpahTxYcjznMqjaBsvD7MclYXKgHJ50C8DgsEu4OjIPiUEsdzPLgDEvGgzkwAtBw7RYNdjNoX5UGTKA224fK8HgCNDAi8YossDF5UrZSck9CzotsuKnMS5LUogqD-EyzocqgPKPNawrDGK1B2VK8qwEqhChWqpiXTnJ4zK6q5aCtSlHnuR4cNkyR+DnM8hlOgFzs0GtJF2fYFlFcVWElfoMVM1BerlAkchiuzIN4caUSSpAUrA6aBNmrKFqWgqipKrltsqo9qu+F7OreyYB1auVh22PYODbZjbgeKckDIUaYbYBL4dw-MpuCnI2EIa65uyiAFigIkwa+H4RjBEEQXqMpqdROUDm4XAeJQIlkxYEAuDiG44CoWsJAeGtWJwSR2GgB7WzQuI4UMpABVQJmTFN4gMHSMUYQBh3+lsHYlVK4iRjtyUAH0YFrFAYCOGB+HpI8AuR4KE6FdB0Aht8zsmMGce5Xl+Xed9aGnHnIMea9KBfPNjknPiB0zDqkxwHAjhdNudbhH2uEYnBnRYuY6p9V45gWJYYBWCRQ4dp5WZ2BSlILKs3dQ1gUScR0++Y466rgB9nQAKQAdRceWy7pZ6L0r-Svr2VBj9Ppmhu68-UdzjaYPz+CWD2oVTzI2ql5qCNQgNwB+t8kC02TM9YYqA3AAHkeCnwVmKOm08uAK0tlAdB3AGzp3nOgHQOx0BEEThgKABgQAkPQA-DOqACbzkTugSM1DMAtXgGHSMtB0BrnTqgTe-djqwP5mhdhcB2oGFZOzTyLA7gPXtlwQalFzrk0jsOG698T6S0AagGWctojrBboGOOXN5GSmJFUBSOA5RRgWAbSgRtJC4HMO3CkRi44SEsIQXYhwADUiYOB3GQkgHIJtazu3TnwMiFp3HUBGM0e4YdcBBjjunKxNiRj4PQDgiOUdYCx3iKQ-a6dgD0npDwHA9p-B2ikuIO2R4ykCO3u6EYMwLAG3gIGCQrUkCBlrnMcA9xUAK0qWKLgzAUDPV3g8OAfSY4uhFgHJAvjBlyMrtXRIOBKB4TcSkh0Og0BkC2Ts5JxjHhOnqtQG81c5QwJGIiMsyCWCjLVhMgIRM6p6LPuM+GwBTB6yOds7msTLnXOTLcgYOirqzPmG3dZ4LdlnIkOyQOTQ8BoHhTXU5JikxrzCKEfMFz2QgBuXc1ADynkvJ+ZMj50tZbfPVgEf5FcrlVwRdix47QlTbBhpOYlpLDoDxOqC28aBaxHH4Ai6IdxxKPGiI8OkaAOWCiFGSilwy4g2zXgopAZRkxHC1nI0J1ZwmZM9v9HV-R5QjFVDgixxoSm0oACwgm6A2V2pqPZQm9pai0ydy4h27kgXJ8MY5xwgKnAUScgrl0jWkrOpNijoE2rBAuLASHYBmK0doQpaC8NEE0o6LT7zVkPifM+-qL6Qqvqym+itNEuCUZFc6lhX7i0MPKPOcE+Q-yPP-KWlyQFgPLYrKBDpIWwPVSgrVOC9XUANawI1SAwn8DNd6iUvtbDa11nE1AqoH4OvQIWoVsDVGU2dM3VurjO52wdto34XyDEctMXa6o6TbFIHsY4lgzjmJt2VVYbxSzUD+NWcE41bs13AP6DEvZ8SWh3CSbE+NRyMkewITkyOoaCkQBIQTEpgqd6Bq1WYme+kwAyIeODS5LAOjUByEBhYOgRX6TVY8jVVLGX3rpfokZVTXm-JRLcoTQA) Highlights: @@ -232,6 +234,7 @@ This section expands on the [generic design](#high-level-design) to address diff This is the same use case elaborated in the high level design [above](#high-level-design). However, we have separated the IdP/RP components of the server that applies to certain enterprise and consumer use cases in the below diagram. ![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) +[Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DOBDAtjNLoCVEAaaAYzXHFzWgAcBXAI3BBOgBkB7M8aAaUgCe0ABKRwNSACcAUNLR1gHAHZ0MDKdACM0mmkmgSIXUuDQARHjECQSgObREe4ALPQc0AOo6nLI2hPmCIiu7rDe+r7GpmYAQpIcAO4oUiG4MeEGfgFmnNx8giJiEpKpDhmR-tEAgsDAkCjAaKDKAMpSAG4skKVVskocddAc7RoexFUAXNAtILZK0DYAdMvSHgC0AHwbMVMtjfqos-M20AAUAMwADABMAJTQADpKT20ka20oKCDKawDikEopE1IPwBFMngQAKqScDEWAAEUQ0NhpAAFuQoHZIABefpKEiQYiQAAewEkaEc5IwKGWiyeL0gbw+Xx+onEUgQbBADXBSgA2mzighNMRBRz4NcALqiopSADCaBIqMgABUQFhZDFNtspiQ6JJJADgGLJAhoNjHkoAKLtch0YG0DjMEhCABmHEkZyCxAFstN8BFhXZ-uuhFpktu0i1W0QU0QhrWtgB0AA1gV-PBLU06g0zlCYXDEcjiEqMQCk7jlASiaTycBKZgactI9JENrY9B-oC6zBQbI21tJp3IKYYjZ4DZ7HtgVgAk8zvQmCxQeNYLwS+iKOWcXiCZGqu2ppZgPr5gxx5PUI06rPTE8AN7QXeE6DAVGqBg0SQ2YCnRfO0FbhrMk0DlcA0HVJtFmgABfVttR2fIBAQYgIRHU9oHPJQJzsK8ZyNS1H2fYg3w-L8fz-RgAMEIDoBJECwIg6laVgqMEKPSAsDUDQ325VMCj491PQIM4M2gDA0AEdRaCaVFI2jDZYCmTg0EzL45jWE4GSZeoWSUNZQRQKZQRQy0x2wy8GnwuclCIqsX1fd81HIkxKKXEhAOA8lGMgli4NgbUlOgW1mHgB11KUJp9RgJ5lEcmAsJw+wrJvAixOIy0Gg9GBSOc78TFkAKtkQmY5gWeYCUNDBlAENitiC0r5ngZRIEK7UPCmKpEFgU4qgUVFXw4NMlFwBIwAG3LP3y4BiBM+AW36QZhlGcYplgJQwBAB14RiFo5WgWlVnY6BrkuS5oAAeV4S1XneXTvn0yxbG5EDmiUXldDfYgCDlTdMSTEihoBAB+WbBFM+jyQbak6o2DtLAARzoepTEa6AACkPBVM59RADcyyxQHhtB-jkPgEmACoKchik9EbWkqcjAcdXwdDJHmTHscaqLDVhjqHAulpsYAemSPVDWST4HtF-ZgElvSzk5omARQSN1i2fmADVyBAMLBiVy1TgSYXxKaJVHLI6byviwbhtVo7is6-q5Q4IaQFa6RFpgZbPTGaAh0sV0JYGna9sOhT+d+K0RbF6L5elw0g-qAbTnj5QETV47foJgHoCpmnoagqnYfhyAkZR6YjgxrGzjTpQEWIfPa1pqki4ppnjuPDDOcruYedaiOpijmPGTj+7lGFxPg8VrHM41qZtdCh0e6N4X-xYUmhnmV0QCgOeWb6t8Xbd1qgA) Highlights: @@ -250,6 +253,7 @@ For easy mapping with the existing DBSC proposal, please note: ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) +[Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DGBDc4DO03QA4CuARuCCtADID2640A0pAJ7QASk4+kATgFB80hYNQB2hALbFe0AIx98aHqBQhFo4NABEAJU7MQogObRES4My24cAdQXnyatBu0JEVtDlj3lj9Zq0AIR5qAHcsXg8cQJ8VJxctGjpGFnZObh4o01i-ZwCAQWBgSCxgNFAxAGVeADdySCz8gVFqYuhqGpkbABpofIAuaEqQI1FoQwA6Kb4bAFoAPnnAwcqy5WgsEbHDaAAKAGYABgAmAEo+QIX52EGaNHgNrdmd3YAzakww6GAACxgjs4CWBXZZDSAoWbVLCbMSzADikFEvHKkCYzEGAB1RDpEABVHjgXqwAAieIJvRQPwwUGMkAAvC1RChIL1IAAPYA8NBmLkSLBTCZYrHVCFQmGiWYcLi8BCUEClTGiADaUoyCFkvVVMvgxwAupr0rwAMJoSmQAAqIAkkAuIMGKEIPB4iOAWp4CGgdOgWIAojUMIQUQQPuRWO8eHs3L0VYb3fANWlpXHjt0BbrzpdFohBohnbMjIjoABrVLOB5Y8rFUp7HH4wlwUl13pYynUxEFhliZmsjlcnloPkC858RBXbPQBFIrltNECUeLAYTyCaQKGeCGEyrFHWlxY3ZEUjkNG9fKwBgUqmYdv0xnM875MeDPTAR1jYhrjcbMrFHeaLEAb2gW8WW+H5JGIfAeEMYB9xIMgUDRU4e05NAjXANArX5KZoAAXxHO0UmYBBm2xZdX2gd9RHXYwv23F1vVEQDgN6X5wMg6DYMPBCWCQ6B2RQtCMMHbC8MzJYn0ga0pBkX55WLVI5PDaAcT2MtoAkNBmGkAhyh+DMrhuMFRRKcVZjRLBBjRYiGNXKjP1KOjd0YoCuxA1ipHYjROPgxDkK5QTMIFXC+GBRZDP9Mh4CDTZRnKR0YDEUCYEo6iTAcn96KxAAyFymRA0pqGdUC2KgjQgQI4ZRnGMZmWdCQxGYW0wpWLZoHgMQbRCgj8mEH5vmoEtRBwXZQjAPr3Ig0rgF4rErPgJr5hsQYet+frBuG0bVomzzppIubmlaBLOgjHo+kGWBRDAEAg2JQJKiNaABRmCq1mAMUQESvdWyvWlOzyliBsRAB+Xo5pB6AACoIf4vslAHLCJih-SswkgBHQgSk0SqxgAKRsc0GN2R0QAvNtfuYrE1uB3oSyI+BwahmHuTh4TEYh8553E5SyJ4XH8aGLY4udBaltMAB5SoCYAegiB1nQiaEPtEGXXoV8U9jx80AfW845kWUWADUMBAKK2k1kiRql9TykpYqPKmhidl+GARB157FlBFafiNagBpATqWjaDouhPCTXnlvrbvup6xNFuEfWl2X4rVpWpedcOSj63YU7EEldYIo1LxpAtekZ3tmd5BGoYW8c9HRzGBaqzW9hz0QSVL6Hy-7Vmkfwj2JJfXnoGb7GhZtWPBnjxPwWTkzU-TiONfx-P9cGI3IqDZu91CKWD3g+TWES14QCgFeua9n2-ZtIA) #### IDP Calls Private Local Key Helper @@ -263,6 +267,7 @@ In DBSC(E), the use of private local key helper for specific IDPs enables the be ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) +[Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DGBDc4DO03QA4BOIAbmsDADID2640A0pAJ7QASk4+khAUL2gCuwagDtBAWwBGPaAEZe+NIVAoQS0cGgAiAEqdmIUQHNoiZcGbbcOAOqKLINRq3aEia2hywHKp+rRNHQAhQmoAdyweTxxg31UAoO0aOkYWdk5uQhizflFqCmhqEllbABozAC44JGhwEAAzSAA6Vt5ggFoAPi7YaoBBUVZCSABHQUgsYF5Ybq7ggaHoEax8MSiAHVEAZUgUDt2sLBAxDo4uHgRKECnqgG1zrIQ5CsfL+AAmAF1XzJ4AYTQKAAFpAACogCSQdpzBbQQEgmBvQgIaANaiEOAAEUQAFVdJQ0RiMhdCAjQRCoXkCjBiqUKohqtsQMZRNAjK1mrxbLCmcALNBjqz2WyABQAZgADB8AJRbXb7Q7HU76Yw3YCEcgnUTVJTAYEVXSIf7AjBQEyQMqc6DyvYHSbK0QdADikFEPHIkCYzGqRtxhHAFVgOP9gegkAAHhq0OZNRIsDCenCTXsANZEzHoRHwElPHPozHBvEB-gYLTkyA55GooiTN1aUUATkbzWbAFJUF5JjL+NA+9BOknqihBIQRppqzmALzQACiZHAgk9BGo9RQrAL0FF7gqDz+KPgL1z7w+nK+Pd4-YHc0ZZhGHWMbugqfSgRz5AoUy3foDQZDv-DKNNVjNB405C8r0QG9qldd1NUKb1e37cBqGofBoAAMWJSAgWBaB4EgEgnGhK9IOg1ARmXKQjHgIxTCmT0oSCbZRXwQQpDXb0Kn6WAGB7K83XgJC+ygodoH0YBRx1NJmAQCotmUTVWGoBpoGo0RaJMQV+QoJjgBwO5ghoujth0yA9LkaAAG9I2jf5wDQSEsE5ZoAF95NEIyNJMsy9I+azbM1QF6jA1pXK+S9+0HeZfXM8yZExfUbmfdJks3I0tzfaAJDQZgZAIchgQgqK5j6aAaDQHMhSdIwt3RTAImgfUYClWUti2XEokIfphGBDhKp4OQrPyUQUEgVytixQjiJ6-V+oIwhhrEMaJtEDqutmvqcIWoaRpWybprGzb5p4JbRvG6BOXanY7SVbUOi8zTjFgUR0Wqb05LMdjOJYDzFNyopVPUp7tMY+sDMenywc0SybKAtB7Mc0Kwo8yGTFM6HgH8uG7IwJzOXC4SinwLQ9pgZKGKgSLSLgXloFaprqBqZBwjAPDRhwJQ40gChMSOagAH0yand1wiF5bIFtRUHXu2CPQob1fTxAk-2VygKkCmNlFAhMab7aKyoqqqWRqtazc6nhju2wbhsgMWydWqaiKO3qTsIXa7fF87VvWy3XetwgPlt+2Jcdw7ICtgbA+Dr2Vsu1proVe0jnutHnte6h3pYT7EG+pwuJtUR-uUoHjK0hjdPB6BDLL4wMcrmGAvhxH8YJ1Ha-ruLNGxzXgtbtyIoEjT+E4KJoAAOSZrNQSrfcaxWet+Gp68ekN6hKsFE2Olq0V6pQ8ImtBenpTlc2Nv9qPdtDg7nYji+drO-az79uaA6Dh2b5m++eHf0P4+aQuUtk6OjOPuLENwUB0kIMwcekBKyViVvidW2I1Ya3hiBeMRN8iFCgXACocJJ5qVriKdEBAF6aAqFIYQh8YAjDGBML8pocByzHOQAuWAmbuHZEcBh0BQSknZDmeoUwiazDEgzEQzNoCs31NADmBVua80FBw2OkARaezJonW6MtTgsM9IrcSqCUFILQdGDBWAgF3VOJOa4txq6TiPJOb4vxSQVkpCREqYkKzHgPBmYxBI-HIjcZCaEy9opwhHGOesk5oAznnBgJchQ1hrg3MSbcSBdwOPPGE8iiB7yPjZC+VgWUPyTAbH6FW-jkGa3MeBImokui3j0QhFgRMUJoUwthXC+Fw7LzIj0W8KBKKFGBnRUGDctAsTYhxfOv1oA8T4svQS9S6YSSklnWS8A-qsJLkQ7y5dfJVxrvsuuhzG44yCg5fubl24nM7n5JuuMQrOTCoPTxMVxJxWkLIJKOAincL8RlUUWUcp5RgHqIqRMDbVCNpvVk28za+26t-d2McP6iCdl-V+l80XXzZBbZF2KFrvw0Xi6AmKXZEp-ri72-9AE3WlinU4acXpvRkjnPOKAC4KR2YDPZIMK5d30tXNO9z6yw17lc5GNzC6irOVjR5QU8bI0JiPYevA0KTO2AAeRIRiHKoAxAAuwYKQQDQGj+EXleMRHzmTClqmNEYEgxDMByavJkJt8JiGhMsmYdNNoYhAAALy1EayBBEKgfSEtSHBJRMTlAHB6865LgjbH+IKHRbImFqTgWyIwYAQB4yDZWXA4BKLwFSZiI0lCwiRFkO6SsOBJEFPljAAAUrYMERQ2QjFoiMFAWgpBAlTImRpsVxhlOgHatkHau2sUKoaY0ppMBukfKY4C2t4w9gaXCNZhAZ2dqnSbcgo5oTYNpHG6ACa4SzoBWgfA3ANIlqkKwZqala1dRzQWWhPMpJjLfSsNYogx4NDCBIFBalh2MxoYY0dtgBi9UDSGw1bJw2WnZVs6As7uSlWqKKSBr0QAEU0IW+gKB6j1mWPQspMoqMEXMrgRDxBkPalQNQAifqejwa3ARi1xHQAYFQBRoIgH1iQFoyMSS+7BECxEC+UQOGuO6mUGPIjsnqDydwBpaAC4iNUVrhUA1IJpFsxg7e0D1BwNvtrERagggEw8jEsEOz2nNr-FQqmEAoTz1FEvQm28+hQOTDwliVN-xORwZgrOLtAB6KIkS6xMtEDFkYQWsB4VFFEJLwYeyOY+SaM0q70MACpis1M3VgUro6AvUa-NOrDh7MuZuDIugrK6LQVFK+VuMlXivbtWb+6Tt7p0npGJF6AzpovQDi3sU9WXHQpcgGljLs7ctzG4wANTxvAZct7RThBi9MtcKVlJsgtVANbYk3Mea87wIAA) ### Cleanup of the binding keys and their artifacts From ccb268411f7e3069c863245499e1f396b2a7198d Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 6 Sep 2024 12:21:41 -0700 Subject: [PATCH 36/47] Add line separators --- DBSCE/Overview.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 77bb267..1fa3b8c 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -118,6 +118,7 @@ The device registration client can be owned and supported by: DBSC(E) aims to support most of these scenarios. DBSC(E) does not define the device registration protocol, but is only concerned that the device registration is executed in a "clean room" and the management of the generated keys to prove device binding. ![DeviceRegistration](./DeviceRegistration.svg) + [Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIBFIG4gMYwE6QOYgM7DQIagD2AdgFDkECuwZ1AtgEaRrQCM5ADgWqMiB6lg0AETwkqaBmx5CJUtGTgQkYaOgEccbr36CCwsQEFgwSHiIgy0HK0mQNW6Mcqli56MQSs4AGhcALmgABTRvXGtSEFJMaAA6RPJYAFoAPjTjYIAlLFxzNgATRBQYAAoJUoBpSABPAOMASSroADNiNiqAcQbmto7oABUQgFlelva2AGViVuAAd15IAEpyY3S02GCAJgAGXegAeSrKIA) ### Local Key Helper @@ -200,6 +201,7 @@ Since we want to integrate DBSC(E) with the original design and make it as widel DBSC(E) (in contrast with DBSC): ![DBSC(E) Highlevel Design](<./DBSC(E).svg>) + [Link to editable diagram](https://sequencediagram.org/index.html#initialData=FABwhgTgLglgxjcA7KACARAHjgewDY4QBcAxAEZ4CuApgHwCCUU1AzlGLDkqgMrUQA3eNXSowLVC1CRYCZGiy4CxclToAZHHDB4A0tQCeACWp4Q-VAAoAStRB4wcVqgAqABQCyASlHjUUaWh4RDAUDAAhCBwAdxZ+XwkyQNkQsPQ+QX4AHSRsfEJSChpaazcAegBJABE3BNRo4GAwSiguSgBbMgsARmAyAFpaaKJUPOVCtVpUSjiIVBgkGFgOZ0wypUIplhgAcyR+hdQAMwJo0Y2VIrp57igAC2pUMijYizWLqeBowbIRsYLVMUAMwABgATDk+HB+nwWNsuP0AOLUJD8Fb6AwjHKlACqEDwABpUNU3HjCag4HcdHgUTtqABeJBcJxE6gADygEDAbkgYHaLAAdEKcpDqNDYfD9iYzPwKgATdQwNhYpAAbWl5gg8u6RI1srlYKJQoAurrTJqAMKOB4uGDtajAJnMVA4AQWX7-S6TZ4xWY3AQ4ADWzgI2jwqGDBlQDxlcxyrVQIAg1H6dNRXOdkYkT3E1DlLu4VXCPAtlgAol5o9QwHL+CwRbkLhNinBKBBkyg9Vq5fSctQBDpKCtE-h4FGjoRUDlLBk3RAAN4kslE3H4gC+RPV5v1OtQXflYKFAuNXj6gygI2TAEcaGwKcnh5HwDA4438l7ipZZnOyYuasvUFXPANwpKk8BpJA6VZDkuR5Ll+QAfi8HJE2TVA0zRZgJEjMQkHzDgsPYTgkGAKBzz+JtAToDCM2oDFLFPJ1HldCwL1QAAxScyxQfgkyVagiXuJUKWpeoYHAp5HnsDgJwgdocjIXN8wAMnQlFMOcWshCcMQmFYIiYC4UjBhYCj32baj1No8IFjlBYdh4IjqHtFBpxASgKHgDEiXoCpdCJSlqVpahTxYcjznMqjaBsvD7MclYXKgHJ50C8DgsEu4OjIPiUEsdzPLgDEvGgzkwAtBw7RYNdjNoX5UGTKA224fK8HgCNDAi8YossDF5UrZSck9CzotsuKnMS5LUogqD-EyzocqgPKPNawrDGK1B2VK8qwEqhChWqpiXTnJ4zK6q5aCtSlHnuR4cNkyR+DnM8hlOgFzs0GtJF2fYFlFcVWElfoMVM1BerlAkchiuzIN4caUSSpAUrA6aBNmrKFqWgqipKrltsqo9qu+F7OreyYB1auVh22PYODbZjbgeKckDIUaYbYBL4dw-MpuCnI2EIa65uyiAFigIkwa+H4RjBEEQXqMpqdROUDm4XAeJQIlkxYEAuDiG44CoWsJAeGtWJwSR2GgB7WzQuI4UMpABVQJmTFN4gMHSMUYQBh3+lsHYlVK4iRjtyUAH0YFrFAYCOGB+HpI8AuR4KE6FdB0Aht8zsmMGce5Xl+Xed9aGnHnIMea9KBfPNjknPiB0zDqkxwHAjhdNudbhH2uEYnBnRYuY6p9V45gWJYYBWCRQ4dp5WZ2BSlILKs3dQ1gUScR0++Y466rgB9nQAKQAdRceWy7pZ6L0r-Svr2VBj9Ppmhu68-UdzjaYPz+CWD2oVTzI2ql5qCNQgNwB+t8kC02TM9YYqA3AAHkeCnwVmKOm08uAK0tlAdB3AGzp3nOgHQOx0BEEThgKABgQAkPQA-DOqACbzkTugSM1DMAtXgGHSMtB0BrnTqgTe-djqwP5mhdhcB2oGFZOzTyLA7gPXtlwQalFzrk0jsOG698T6S0AagGWctojrBboGOOXN5GSmJFUBSOA5RRgWAbSgRtJC4HMO3CkRi44SEsIQXYhwADUiYOB3GQkgHIJtazu3TnwMiFp3HUBGM0e4YdcBBjjunKxNiRj4PQDgiOUdYCx3iKQ-a6dgD0npDwHA9p-B2ikuIO2R4ykCO3u6EYMwLAG3gIGCQrUkCBlrnMcA9xUAK0qWKLgzAUDPV3g8OAfSY4uhFgHJAvjBlyMrtXRIOBKB4TcSkh0Og0BkC2Ts5JxjHhOnqtQG81c5QwJGIiMsyCWCjLVhMgIRM6p6LPuM+GwBTB6yOds7msTLnXOTLcgYOirqzPmG3dZ4LdlnIkOyQOTQ8BoHhTXU5JikxrzCKEfMFz2QgBuXc1ADynkvJ+ZMj50tZbfPVgEf5FcrlVwRdix47QlTbBhpOYlpLDoDxOqC28aBaxHH4Ai6IdxxKPGiI8OkaAOWCiFGSilwy4g2zXgopAZRkxHC1nI0J1ZwmZM9v9HV-R5QjFVDgixxoSm0oACwgm6A2V2pqPZQm9pai0ydy4h27kgXJ8MY5xwgKnAUScgrl0jWkrOpNijoE2rBAuLASHYBmK0doQpaC8NEE0o6LT7zVkPifM+-qL6Qqvqym+itNEuCUZFc6lhX7i0MPKPOcE+Q-yPP-KWlyQFgPLYrKBDpIWwPVSgrVOC9XUANawI1SAwn8DNd6iUvtbDa11nE1AqoH4OvQIWoVsDVGU2dM3VurjO52wdto34XyDEctMXa6o6TbFIHsY4lgzjmJt2VVYbxSzUD+NWcE41bs13AP6DEvZ8SWh3CSbE+NRyMkewITkyOoaCkQBIQTEpgqd6Bq1WYme+kwAyIeODS5LAOjUByEBhYOgRX6TVY8jVVLGX3rpfokZVTXm-JRLcoTQA) Highlights: @@ -234,6 +236,7 @@ This section expands on the [generic design](#high-level-design) to address diff This is the same use case elaborated in the high level design [above](#high-level-design). However, we have separated the IdP/RP components of the server that applies to certain enterprise and consumer use cases in the below diagram. ![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) + [Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DOBDAtjNLoCVEAaaAYzXHFzWgAcBXAI3BBOgBkB7M8aAaUgCe0ABKRwNSACcAUNLR1gHAHZ0MDKdACM0mmkmgSIXUuDQARHjECQSgObREe4ALPQc0AOo6nLI2hPmCIiu7rDe+r7GpmYAQpIcAO4oUiG4MeEGfgFmnNx8giJiEpKpDhmR-tEAgsDAkCjAaKDKAMpSAG4skKVVskocddAc7RoexFUAXNAtILZK0DYAdMvSHgC0AHwbMVMtjfqos-M20AAUAMwADABMAJTQADpKT20ka20oKCDKawDikEopE1IPwBFMngQAKqScDEWAAEUQ0NhpAAFuQoHZIABefpKEiQYiQAAewEkaEc5IwKGWiyeL0gbw+Xx+onEUgQbBADXBSgA2mzighNMRBRz4NcALqiopSADCaBIqMgABUQFhZDFNtspiQ6JJJADgGLJAhoNjHkoAKLtch0YG0DjMEhCABmHEkZyCxAFstN8BFhXZ-uuhFpktu0i1W0QU0QhrWtgB0AA1gV-PBLU06g0zlCYXDEcjiEqMQCk7jlASiaTycBKZgactI9JENrY9B-oC6zBQbI21tJp3IKYYjZ4DZ7HtgVgAk8zvQmCxQeNYLwS+iKOWcXiCZGqu2ppZgPr5gxx5PUI06rPTE8AN7QXeE6DAVGqBg0SQ2YCnRfO0FbhrMk0DlcA0HVJtFmgABfVttR2fIBAQYgIRHU9oHPJQJzsK8ZyNS1H2fYg3w-L8fz-RgAMEIDoBJECwIg6laVgqMEKPSAsDUDQ325VMCj491PQIM4M2gDA0AEdRaCaVFI2jDZYCmTg0EzL45jWE4GSZeoWSUNZQRQKZQRQy0x2wy8GnwuclCIqsX1fd81HIkxKKXEhAOA8lGMgli4NgbUlOgW1mHgB11KUJp9RgJ5lEcmAsJw+wrJvAixOIy0Gg9GBSOc78TFkAKtkQmY5gWeYCUNDBlAENitiC0r5ngZRIEK7UPCmKpEFgU4qgUVFXw4NMlFwBIwAG3LP3y4BiBM+AW36QZhlGcYplgJQwBAB14RiFo5WgWlVnY6BrkuS5oAAeV4S1XneXTvn0yxbG5EDmiUXldDfYgCDlTdMSTEihoBAB+WbBFM+jyQbak6o2DtLAARzoepTEa6AACkPBVM59RADcyyxQHhtB-jkPgEmACoKchik9EbWkqcjAcdXwdDJHmTHscaqLDVhjqHAulpsYAemSPVDWST4HtF-ZgElvSzk5omARQSN1i2fmADVyBAMLBiVy1TgSYXxKaJVHLI6byviwbhtVo7is6-q5Q4IaQFa6RFpgZbPTGaAh0sV0JYGna9sOhT+d+K0RbF6L5elw0g-qAbTnj5QETV47foJgHoCpmnoagqnYfhyAkZR6YjgxrGzjTpQEWIfPa1pqki4ppnjuPDDOcruYedaiOpijmPGTj+7lGFxPg8VrHM41qZtdCh0e6N4X-xYUmhnmV0QCgOeWb6t8Xbd1qgA) Highlights: @@ -253,6 +256,7 @@ For easy mapping with the existing DBSC proposal, please note: ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) + [Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DGBDc4DO03QA4CuARuCCtADID2640A0pAJ7QASk4+kATgFB80hYNQB2hALbFe0AIx98aHqBQhFo4NABEAJU7MQogObRES4My24cAdQXnyatBu0JEVtDlj3lj9Zq0AIR5qAHcsXg8cQJ8VJxctGjpGFnZObh4o01i-ZwCAQWBgSCxgNFAxAGVeADdySCz8gVFqYuhqGpkbABpofIAuaEqQI1FoQwA6Kb4bAFoAPnnAwcqy5WgsEbHDaAAKAGYABgAmAEo+QIX52EGaNHgNrdmd3YAzakww6GAACxgjs4CWBXZZDSAoWbVLCbMSzADikFEvHKkCYzEGAB1RDpEABVHjgXqwAAieIJvRQPwwUGMkAAvC1RChIL1IAAPYA8NBmLkSLBTCZYrHVCFQmGiWYcLi8BCUEClTGiADaUoyCFkvVVMvgxwAupr0rwAMJoSmQAAqIAkkAuIMGKEIPB4iOAWp4CGgdOgWIAojUMIQUQQPuRWO8eHs3L0VYb3fANWlpXHjt0BbrzpdFohBohnbMjIjoABrVLOB5Y8rFUp7HH4wlwUl13pYynUxEFhliZmsjlcnloPkC858RBXbPQBFIrltNECUeLAYTyCaQKGeCGEyrFHWlxY3ZEUjkNG9fKwBgUqmYdv0xnM875MeDPTAR1jYhrjcbMrFHeaLEAb2gW8WW+H5JGIfAeEMYB9xIMgUDRU4e05NAjXANArX5KZoAAXxHO0UmYBBm2xZdX2gd9RHXYwv23F1vVEQDgN6X5wMg6DYMPBCWCQ6B2RQtCMMHbC8MzJYn0ga0pBkX55WLVI5PDaAcT2MtoAkNBmGkAhyh+DMrhuMFRRKcVZjRLBBjRYiGNXKjP1KOjd0YoCuxA1ipHYjROPgxDkK5QTMIFXC+GBRZDP9Mh4CDTZRnKR0YDEUCYEo6iTAcn96KxAAyFymRA0pqGdUC2KgjQgQI4ZRnGMZmWdCQxGYW0wpWLZoHgMQbRCgj8mEH5vmoEtRBwXZQjAPr3Ig0rgF4rErPgJr5hsQYet+frBuG0bVomzzppIubmlaBLOgjHo+kGWBRDAEAg2JQJKiNaABRmCq1mAMUQESvdWyvWlOzyliBsRAB+Xo5pB6AACoIf4vslAHLCJih-SswkgBHQgSk0SqxgAKRsc0GN2R0QAvNtfuYrE1uB3oSyI+BwahmHuTh4TEYh8553E5SyJ4XH8aGLY4udBaltMAB5SoCYAegiB1nQiaEPtEGXXoV8U9jx80AfW845kWUWADUMBAKK2k1kiRql9TykpYqPKmhidl+GARB157FlBFafiNagBpATqWjaDouhPCTXnlvrbvup6xNFuEfWl2X4rVpWpedcOSj63YU7EEldYIo1LxpAtekZ3tmd5BGoYW8c9HRzGBaqzW9hz0QSVL6Hy-7Vmkfwj2JJfXnoGb7GhZtWPBnjxPwWTkzU-TiONfx-P9cGI3IqDZu91CKWD3g+TWES14QCgFeua9n2-ZtIA) #### IDP Calls Private Local Key Helper @@ -267,6 +271,7 @@ In DBSC(E), the use of private local key helper for specific IDPs enables the be ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) + [Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DGBDc4DO03QA4BOIAbmsDADID2640A0pAJ7QASk4+khAUL2gCuwagDtBAWwBGPaAEZe+NIVAoQS0cGgAiAEqdmIUQHNoiZcGbbcOAOqKLINRq3aEia2hywHKp+rRNHQAhQmoAdyweTxxg31UAoO0aOkYWdk5uQhizflFqCmhqEllbABozAC44JGhwEAAzSAA6Vt5ggFoAPi7YaoBBUVZCSABHQUgsYF5Ybq7ggaHoEax8MSiAHVEAZUgUDt2sLBAxDo4uHgRKECnqgG1zrIQ5CsfL+AAmAF1XzJ4AYTQKAAFpAACogCSQdpzBbQQEgmBvQgIaANaiEOAAEUQAFVdJQ0RiMhdCAjQRCoXkCjBiqUKohqtsQMZRNAjK1mrxbLCmcALNBjqz2WyABQAZgADB8AJRbXb7Q7HU76Yw3YCEcgnUTVJTAYEVXSIf7AjBQEyQMqc6DyvYHSbK0QdADikFEPHIkCYzGqRtxhHAFVgOP9gegkAAHhq0OZNRIsDCenCTXsANZEzHoRHwElPHPozHBvEB-gYLTkyA55GooiTN1aUUATkbzWbAFJUF5JjL+NA+9BOknqihBIQRppqzmALzQACiZHAgk9BGo9RQrAL0FF7gqDz+KPgL1z7w+nK+Pd4-YHc0ZZhGHWMbugqfSgRz5AoUy3foDQZDv-DKNNVjNB405C8r0QG9qldd1NUKb1e37cBqGofBoAAMWJSAgWBaB4EgEgnGhK9IOg1ARmXKQjHgIxTCmT0oSCbZRXwQQpDXb0Kn6WAGB7K83XgJC+ygodoH0YBRx1NJmAQCotmUTVWGoBpoGo0RaJMQV+QoJjgBwO5ghoujth0yA9LkaAAG9I2jf5wDQSEsE5ZoAF95NEIyNJMsy9I+azbM1QF6jA1pXK+S9+0HeZfXM8yZExfUbmfdJks3I0tzfaAJDQZgZAIchgQgqK5j6aAaDQHMhSdIwt3RTAImgfUYClWUti2XEokIfphGBDhKp4OQrPyUQUEgVytixQjiJ6-V+oIwhhrEMaJtEDqutmvqcIWoaRpWybprGzb5p4JbRvG6BOXanY7SVbUOi8zTjFgUR0Wqb05LMdjOJYDzFNyopVPUp7tMY+sDMenywc0SybKAtB7Mc0Kwo8yGTFM6HgH8uG7IwJzOXC4SinwLQ9pgZKGKgSLSLgXloFaprqBqZBwjAPDRhwJQ40gChMSOagAH0yand1wiF5bIFtRUHXu2CPQob1fTxAk-2VygKkCmNlFAhMab7aKyoqqqWRqtazc6nhju2wbhsgMWydWqaiKO3qTsIXa7fF87VvWy3XetwgPlt+2Jcdw7ICtgbA+Dr2Vsu1proVe0jnutHnte6h3pYT7EG+pwuJtUR-uUoHjK0hjdPB6BDLL4wMcrmGAvhxH8YJ1Ha-ruLNGxzXgtbtyIoEjT+E4KJoAAOSZrNQSrfcaxWet+Gp68ekN6hKsFE2Olq0V6pQ8ImtBenpTlc2Nv9qPdtDg7nYji+drO-az79uaA6Dh2b5m++eHf0P4+aQuUtk6OjOPuLENwUB0kIMwcekBKyViVvidW2I1Ya3hiBeMRN8iFCgXACocJJ5qVriKdEBAF6aAqFIYQh8YAjDGBML8pocByzHOQAuWAmbuHZEcBh0BQSknZDmeoUwiazDEgzEQzNoCs31NADmBVua80FBw2OkARaezJonW6MtTgsM9IrcSqCUFILQdGDBWAgF3VOJOa4txq6TiPJOb4vxSQVkpCREqYkKzHgPBmYxBI-HIjcZCaEy9opwhHGOesk5oAznnBgJchQ1hrg3MSbcSBdwOPPGE8iiB7yPjZC+VgWUPyTAbH6FW-jkGa3MeBImokui3j0QhFgRMUJoUwthXC+Fw7LzIj0W8KBKKFGBnRUGDctAsTYhxfOv1oA8T4svQS9S6YSSklnWS8A-qsJLkQ7y5dfJVxrvsuuhzG44yCg5fubl24nM7n5JuuMQrOTCoPTxMVxJxWkLIJKOAincL8RlUUWUcp5RgHqIqRMDbVCNpvVk28za+26t-d2McP6iCdl-V+l80XXzZBbZF2KFrvw0Xi6AmKXZEp-ri72-9AE3WlinU4acXpvRkjnPOKAC4KR2YDPZIMK5d30tXNO9z6yw17lc5GNzC6irOVjR5QU8bI0JiPYevA0KTO2AAeRIRiHKoAxAAuwYKQQDQGj+EXleMRHzmTClqmNEYEgxDMByavJkJt8JiGhMsmYdNNoYhAAALy1EayBBEKgfSEtSHBJRMTlAHB6865LgjbH+IKHRbImFqTgWyIwYAQB4yDZWXA4BKLwFSZiI0lCwiRFkO6SsOBJEFPljAAAUrYMERQ2QjFoiMFAWgpBAlTImRpsVxhlOgHatkHau2sUKoaY0ppMBukfKY4C2t4w9gaXCNZhAZ2dqnSbcgo5oTYNpHG6ACa4SzoBWgfA3ANIlqkKwZqala1dRzQWWhPMpJjLfSsNYogx4NDCBIFBalh2MxoYY0dtgBi9UDSGw1bJw2WnZVs6As7uSlWqKKSBr0QAEU0IW+gKB6j1mWPQspMoqMEXMrgRDxBkPalQNQAifqejwa3ARi1xHQAYFQBRoIgH1iQFoyMSS+7BECxEC+UQOGuO6mUGPIjsnqDydwBpaAC4iNUVrhUA1IJpFsxg7e0D1BwNvtrERagggEw8jEsEOz2nNr-FQqmEAoTz1FEvQm28+hQOTDwliVN-xORwZgrOLtAB6KIkS6xMtEDFkYQWsB4VFFEJLwYeyOY+SaM0q70MACpis1M3VgUro6AvUa-NOrDh7MuZuDIugrK6LQVFK+VuMlXivbtWb+6Tt7p0npGJF6AzpovQDi3sU9WXHQpcgGljLs7ctzG4wANTxvAZct7RThBi9MtcKVlJsgtVANbYk3Mea87wIAA) ### Cleanup of the binding keys and their artifacts From bf2ca85f0bc4fee119e071bc822b0c2d01c1e38b Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Fri, 6 Sep 2024 12:49:18 -0700 Subject: [PATCH 37/47] Adding TOC under the right section --- DBSCE/Overview.md | 61 ++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 1fa3b8c..af91b0d 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -1,35 +1,3 @@ - - - -- [Device Bound Session Credentials for Enterprise - explainer](#device-bound-session-credentials-for-enterprise---explainer) - - [Authors](#authors) - - [Contributors](#contributors) - - [Participate (TBD links)](#participate-tbd-links) - - [Overview](#overview) - - [Why DBSC(E)?](#why-dbsce) - - [How does it integrate with DBSC?](#how-does-it-integrate-with-dbsc) - - [Terminology](#terminology) - - [Browser](#browser) - - [Relying Party (RP)](#relying-party-rp) - - [Identity Provider (IdP)](#identity-provider-idp) - - [Device Registration Client](#device-registration-client) - - [Device Registration](#device-registration) - - [Local Key Helper](#local-key-helper) - - [Platform Requirements](#platform-requirements) - - [Attestation Service](#attestation-service) - - [Key Generation Specifics](#key-generation-specifics) - - [Binding Key](#binding-key) - - [Attestation Key](#attestation-key) - - [Binding Statement](#binding-statement) - - [High-Level Design](#high-level-design) - - [DBSC(E) use cases](#dbsce-use-cases) - - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) - - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) - - [IDP Calls Private Local Key Helper](#idp-calls-private-local-key-helper) - - [Cleanup of the binding keys and their artifacts](#cleanup-of-the-binding-keys-and-their-artifacts) - - - # Device Bound Session Credentials for Enterprise - explainer This is the repository for Device Bound Session Credentials for Enterprise. You're welcome to @@ -59,6 +27,35 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' - [Issue tracker]() - [Discussion forum] +## Table of Contents + + + + - [Overview](#overview) + - [Why DBSC(E)?](#why-dbsce) + - [How does it integrate with DBSC?](#how-does-it-integrate-with-dbsc) + - [Terminology](#terminology) + - [Browser](#browser) + - [Relying Party (RP)](#relying-party-rp) + - [Identity Provider (IdP)](#identity-provider-idp) + - [Device Registration Client](#device-registration-client) + - [Local Key Helper](#local-key-helper) + - [Platform Requirements](#platform-requirements) + - [Attestation Service](#attestation-service) + - [Key Generation Specifics](#key-generation-specifics) + - [Attestation Key](#attestation-key) + - [Binding Key](#binding-key) + - [Binding Statement](#binding-statement) + - [High-Level Design](#high-level-design) + - [DBSC(E) use cases](#dbsce-use-cases) + - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) + - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) + - [IDP Calls Private Local Key Helper](#idp-calls-private-local-key-helper) + - [Cleanup of the binding keys and their artifacts](#cleanup-of-the-binding-keys-and-their-artifacts) + + + + ## Overview Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to the existing [DBSC](https://github.com/wicg/dbsc) proposal. It refines the key generation mechanism resulting in additional security for enterprise use cases. It aims to provide a mechanism for enterprise customers to be able to deploy enhanced/customised device binding for any browser session, hence protecting against session hijacking and cookie theft. From c7c23dc22242d6f62a5f9f0297fa6a2e713f3244 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 12 Sep 2024 12:38:34 -0700 Subject: [PATCH 38/47] Update nonce and private local key helper specifics --- DBSCE/LocalKeyHelper-Mac.md | 9 +++++---- DBSCE/Overview.md | 18 ++++++++++-------- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/DBSCE/LocalKeyHelper-Mac.md b/DBSCE/LocalKeyHelper-Mac.md index 23c448c..8f0d2bb 100644 --- a/DBSCE/LocalKeyHelper-Mac.md +++ b/DBSCE/LocalKeyHelper-Mac.md @@ -5,9 +5,7 @@ On macOS, a Local Key Helper is a protocol (`LocalKeyHelper.h`), and its implementation (`LocalKeyHelperImpl.h`/`LocalKeyHelperImpl.m`) is yet to be determined. -Each _Local key helper_ vendor will implement and ship as an XPC service on macOS. It will be signed with app sandbox entitlement for security requirement. - -To start the Local Key Helper XPC service, the service plist (property list) needs to be defined and registered in the launchAgent. This will ensure the service starts up when a idP sends a service connections. +Each _Local key helper_ vendor will implement and ship as an XPC service on macOS. It will be signed with app sandbox entitlement for security requirement. Each vendor will also manage their own lifecycle of the XPC service depending on their specific and other functionality provided by the service. Each XPC service needs to be defined and registered with launchd as a launch agent. Vendors can decided whether to start XPC service on machine startup or on demand. Here is an example of the Local Key Helper XPC service plist: @@ -31,6 +29,9 @@ Here is an example of the Local Key Helper XPC service plist: ``` +Please refer to Apple documentation for building and configuring XPC services. + + When the browser (e.g. Chrome) communicates with this service, it needs to establish a service connection first. Here is an example of starting a new connection with the Local Key Helper: @@ -50,7 +51,7 @@ The browser (e.g. Chrome) can then call the methods defined in the LocalKeyHelpe - The input and output parameters of the XPC service should follow the `NSSecureCoding` protocol. - Un-sandboxed applications can communicate directly to the XPC service. -#### Define Available Local Key Helpers +#### Browser discovery process To inform the browser about the Local Key Helper to use, the manifest file is created within the browser's root folder during the LocalKeyHelper's installation (e.g. `/Library/Google/Chrome/LocalKeyHelpers`). This folder contains the following 2 types of files: **1st type: files that define the Local Key Helpers** diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index af91b0d..bcdac0f 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -55,7 +55,6 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' - ## Overview Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to the existing [DBSC](https://github.com/wicg/dbsc) proposal. It refines the key generation mechanism resulting in additional security for enterprise use cases. It aims to provide a mechanism for enterprise customers to be able to deploy enhanced/customised device binding for any browser session, hence protecting against session hijacking and cookie theft. @@ -210,17 +209,17 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _short lived_. If _binding statement_ is not shortlived, it is possible for the attacker to generate the _binding statement_ and the _binding key_ from a device controlled by the attacker and use them to bind the victim's cookies to the malicious _binding key_. The enforcement of a shortlived binding statement is achieved through `nonce`. - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of posession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). - - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate `nonce` to ensure the _binding statement_ is issued recently. + - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate `nonce` to ensure the _binding statement_ is issued recently. - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. - - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser must prefer the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. + - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser must prefer the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. There is also an optional `HelperCacheTime` which can cache a preferred `HelperId` for the IDP in the browser for a given time. -1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce` sent by the IdP, the thumbprint of the public key, and any extra claims that the IdP wants to send. +1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce`(challenge) sent by the IdP, the thumbprint of the publicKey (pub(BindingKey) TDD: refer to standard notation for pub key), and any extra claims that the IdP wants to send. - Format of the Binding Statement: We expect the [_binding statement_](#binding-statement) will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the _binding statement_ is prescribed to include `nonce` and the thumbprint of the public key. The _binding statement_ is expected to be shortlived as covered in the previous section. More details on _binding statement_ can be found [here](#binding-statement). - The [_attestation service_](#attestation-service) is also separate from the IDP in this diagram. - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the _binding statement_. It is intentionally left undefined, and can be customized. -1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP [validates](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the public key. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the thumbprint of the public key). The `KeyId` is expected to be returned to the RP/IdP, and the IdP will use the `KeyId` to identify the key to be used for the session. +1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP [validates](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the publicKey. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the publicKey or a thumbprint of the publicKey. 1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with two caveats: The _local key helper_ is called for JWT generation and the additional params introduced for DBSC(E) customization can be optionally added. @@ -262,9 +261,12 @@ As referred in [Local Key Helper](#local-key-helper) section, it is possible for In DBSC(E), the use of private local key helper for specific IDPs enables the below optimizations: -- Since the IDP can trust the private local key helper, the `HelperId` discovery can be optimized by caching. An IDP can specify its preferred ordered list of `HelperId`s in any response, and can request the browser to cache its preference for a specific duration(`HelperCacheTime`). Also, such requests need not be initiated by the RP that implements DBSC(E), the IDP can specify its `HelperIdList` in any communication(request/response) within the browser context. -- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of presence of the device by its own proprietery mechanism (usually authentication) for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache [TDD: Add more specifics here] those binding statements for further performance optimization. -- RP can combine the request for a DBSC(E) session as a part of IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the sign-in flow to generate (with local key helper, which is private to IdP) and append the new JWT proof to the response, before navigating to RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. [TDD: Follow up the conditions of redirection with google, is the URL enough or do we need the KeyId?] +- An IDP can specify its preferred ordered list of `HelperId`s in any response, and can request the browser to cache its preference for a specific duration (`HelperCacheTime`). The IDP which is capable of DBSC(E) can specify its `HelperIdList` in any communication(request/response) within the browser context. +- The caching of `HelperId` is more beneficial for private local key helper for two reasons: + - Since the IDP is associated mostly with the same local key helper, it us unlikely to change often. + - `long lived` binding statements are possible with private key local helper (more below), eliminating the need for an additional redirect to fetch the IDP nonce for the binding statement. +- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of presence of the device by its own proprietery mechanism for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache [TDD: Add more specifics here] those binding statements for further performance optimization. +- RP can combine the request for a DBSC(E) startsession as a part of the IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the response for the sign-in flow and append the new JWT proof (which is generated by the local key helper) on navigation to the RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. [TDD: Follow up the conditions of redirection with google, is the URL enough or do we need the KeyId?] ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) From 8aeda9fc45745a6981694a816eecd890c54e73e2 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 12 Sep 2024 12:44:33 -0700 Subject: [PATCH 39/47] Update mac local key helper --- DBSCE/LocalKeyHelper-Mac.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/DBSCE/LocalKeyHelper-Mac.md b/DBSCE/LocalKeyHelper-Mac.md index 8f0d2bb..a4dc14e 100644 --- a/DBSCE/LocalKeyHelper-Mac.md +++ b/DBSCE/LocalKeyHelper-Mac.md @@ -31,7 +31,6 @@ Here is an example of the Local Key Helper XPC service plist: Please refer to Apple documentation for building and configuring XPC services. - When the browser (e.g. Chrome) communicates with this service, it needs to establish a service connection first. Here is an example of starting a new connection with the Local Key Helper: @@ -51,7 +50,7 @@ The browser (e.g. Chrome) can then call the methods defined in the LocalKeyHelpe - The input and output parameters of the XPC service should follow the `NSSecureCoding` protocol. - Un-sandboxed applications can communicate directly to the XPC service. -#### Browser discovery process +#### Deployment of a 3rd party local key helper To inform the browser about the Local Key Helper to use, the manifest file is created within the browser's root folder during the LocalKeyHelper's installation (e.g. `/Library/Google/Chrome/LocalKeyHelpers`). This folder contains the following 2 types of files: **1st type: files that define the Local Key Helpers** From 94874fff4ea8dd9da5464907ffc86cabc4059f08 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 12 Sep 2024 18:58:29 -0700 Subject: [PATCH 40/47] Update language for publicKey and thumbprint, mac updates --- DBSCE/LocalKeyHelper-Mac.md | 6 +++--- DBSCE/Overview.md | 28 +++++++++++++--------------- 2 files changed, 16 insertions(+), 18 deletions(-) diff --git a/DBSCE/LocalKeyHelper-Mac.md b/DBSCE/LocalKeyHelper-Mac.md index a4dc14e..61fc7ad 100644 --- a/DBSCE/LocalKeyHelper-Mac.md +++ b/DBSCE/LocalKeyHelper-Mac.md @@ -5,7 +5,7 @@ On macOS, a Local Key Helper is a protocol (`LocalKeyHelper.h`), and its implementation (`LocalKeyHelperImpl.h`/`LocalKeyHelperImpl.m`) is yet to be determined. -Each _Local key helper_ vendor will implement and ship as an XPC service on macOS. It will be signed with app sandbox entitlement for security requirement. Each vendor will also manage their own lifecycle of the XPC service depending on their specific and other functionality provided by the service. Each XPC service needs to be defined and registered with launchd as a launch agent. Vendors can decided whether to start XPC service on machine startup or on demand. +Each _Local key helper_ vendor will implement and ship as an XPC service on macOS. Each vendor will also manage their own lifecycle of the XPC service depending on their specific and other functionality provided by the service. Each XPC service needs to be defined and registered with launchd as a launch agent. Vendors can decided whether to start XPC service on machine startup or on demand. Here is an example of the Local Key Helper XPC service plist: @@ -48,7 +48,7 @@ The browser (e.g. Chrome) can then call the methods defined in the LocalKeyHelpe - It is important to define the LocalKeyHelper protocol exactly the same way in both the browser and the XPC service provider. This allows for easy extension of the protocol in the future (e.g. using a dictionary as an input parameter instead of a strict object type). - The input and output parameters of the XPC service should follow the `NSSecureCoding` protocol. -- Un-sandboxed applications can communicate directly to the XPC service. +- Non-sandboxed applications can communicate directly to the XPC service. #### Deployment of a 3rd party local key helper To inform the browser about the Local Key Helper to use, the manifest file is created within the browser's root folder during the LocalKeyHelper's installation (e.g. `/Library/Google/Chrome/LocalKeyHelpers`). This folder contains the following 2 types of files: @@ -93,4 +93,4 @@ com.contoso.LocalKeyHelper.idP.json } ``` -The MDM service can do post script to update the URLs in this file without touching the Local Key Helpers file. +The MDM service can run an on-device script to update the URLs in this file without changing the Local Key Helper definition file. diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index bcdac0f..3cfaeae 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -63,7 +63,7 @@ Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to While the original DBSC proposal enables browsers to bind session cookies to a device providing protection from network based attacks, it still remains vulnerable to "on device" malware. Temporary malware on the device can inject its own binding keys when the DBSC session is established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a new signin operation, and potentially hijack all subsequent sessions. -DBSC(E) aims to mitigate this risk by introducing the concept of `one-time protected` [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) is able to provide this risk mitigation if the device registration is a `protected` operation, which means there is no malware on the device (a state referred to as ["clean room"](#device-registration-client)) e.g. an organization registering a device before giving a device to an employee. As device registration is expected to be a `one-time` operation, the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. +DBSC(E) aims to mitigate this risk by introducing the concept of `one-time protected` [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) is able to provide this risk mitigation if the device registration is a `protected` operation, meaning it is performed in a ["clean room"](#device-registration-client)) enviroment e.g. an organization registering a device before giving a device to an employee. As device registration is expected to be a `one-time` operation, the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. If device registration is executed in a clean room and precedes any sign in sessions malware would not be able to bind session cookies to malicious binding keys during a sign in operation that implements DBSC(E). @@ -121,7 +121,7 @@ DBSC(E) aims to support most of these scenarios. DBSC(E) does not define the dev DBSC(E) introduces the concept of `Local Key Helper`. -**Local Key Helper** is an integral part of the the `Device Registration Client`, and is a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IDP/OS) or can be installed by a provider in compliance with the protocol expanded below. DBSC(E) defines browser interaction with _Local key helpers_ for each platform. Those details are outlined in [KeyGeneration.md](./KeyGeneration.md). +**Local Key Helper** is an integral part of the the `Device Registration Client`, and is a software interface responsible for the DBSC Key management. *Local key helper* can be public or private and is expected to be either shipped as a part of a given enterprise framework (with the IDP/OS) or can be installed by a provider in compliance with the protocol expanded below. DBSC(E) defines browser interaction with _Local key helpers_ for each platform [below](#platform-requirements). There are two types of local key helpers: _private_ and _public_ @@ -161,7 +161,7 @@ An _attestation key_ is generated during the device registration process and has 1. It signs only the private/other keys that reside in the same secure enclave as the attestation key. 2. It cannot sign any external payload, or if it signs, it cannot generate an output that can be interpreted as an attestation statement. -In addition, the _attestation key_ can be uploaded only once to the backend at the moment of device registration, in the clean room, and is seldom changed unless the device loses it (could be due to key rotation or similar operations). +In addition, the _attestation key_ can be uploaded only once to the backend at the moment of device registration, in the clean room, and is seldom changed unless the device loses it. The _attestation key_, hence, can be used to attest that the [binding key](#binding-key) belongs to the same device as the _attestation key_, by signing the public part of the _binding key_ (with the _attestation key_) and generating an _attestation statement_. Depending on the specific implementation, this _attestation statement_ itself can be a _binding statement_, or it can be sent to an [attestation service](#attestation-service) to produce the final _binding statement_. @@ -175,7 +175,7 @@ This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC pr ##### Binding Statement -Additonal to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. +Additional to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. The validation of the _binding statement_ authenticates the device by using device ID to find the corresponding _attestation key_. The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. @@ -206,20 +206,19 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of posession) and to prevent the clock-skew between the IdP and the Local Key Helper. + - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of possession) and to prevent the clock-skew between the IdP and the Local Key Helper. - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _short lived_. If _binding statement_ is not shortlived, it is possible for the attacker to generate the _binding statement_ and the _binding key_ from a device controlled by the attacker and use them to bind the victim's cookies to the malicious _binding key_. The enforcement of a shortlived binding statement is achieved through `nonce`. - - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of posession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). + - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of possession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate `nonce` to ensure the _binding statement_ is issued recently. - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser must prefer the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. There is also an optional `HelperCacheTime` which can cache a preferred `HelperId` for the IDP in the browser for a given time. -1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain the `nonce`(challenge) sent by the IdP, the thumbprint of the publicKey (pub(BindingKey) TDD: refer to standard notation for pub key), and any extra claims that the IdP wants to send. +1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain `nonce`(challenge) sent by the IdP, the thumbprint(a cryptographic hash digest) of the `publicKey`(public part of the [binding key](#binding-key)), and any extra claims that the IdP wants to send. - - Format of the Binding Statement: We expect the [_binding statement_](#binding-statement) will be a `string`, as we want to keep the format open to allow for platform-specific optimizations. However, the validation of the _binding statement_ is prescribed to include `nonce` and the thumbprint of the public key. The _binding statement_ is expected to be shortlived as covered in the previous section. More details on _binding statement_ can be found [here](#binding-statement). - The [_attestation service_](#attestation-service) is also separate from the IDP in this diagram. - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the _binding statement_. It is intentionally left undefined, and can be customized. -1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP [validates](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the publicKey. Once the validation succeeds, the IdP will proceed with the sign-in ceremony (optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the publicKey or a thumbprint of the publicKey. +1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP [validates](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the publicKey. Once the validation succeeds, the IdP will proceed with the sign-in ceremony. It can optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the publicKey or a thumbprint of the publicKey. 1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with two caveats: The _local key helper_ is called for JWT generation and the additional params introduced for DBSC(E) customization can be optionally added. @@ -237,9 +236,9 @@ This is the same use case elaborated in the high level design [above](#high-leve Highlights: -- Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of auth tokens and issue cookies based on those tokens. In such case, the IdP can generate the auth tokens and embed the thumbprint of the public key in the token. +- Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of auth tokens and issue cookies based on those tokens. In such case, the IdP can generate the auth tokens and embed the thumbprint of the publicKey in the token. - The tokens can be delivered to the RP directly through an API instead of a header based response. -- The tokens also contain the thumbbrint of the public key, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. The RP will also embed the thumbprint in the cookie for subsequent session validation. +- The tokens also contain the thumbprint of the publicKey, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. The RP will also embed the thumbprint in the cookie for subsequent session validation. #### IDP Calls Public Local Key Helper @@ -247,9 +246,8 @@ In many use cases, it is also a valid to have separate servers as [RP](#relying- For easy mapping with the existing DBSC proposal, please note: -- Steps 1-16 specify the key generation process for a public local key helper. -- Steps 17-29 are [DBSC](https://github.com/wicg/dbsc), added for completeness. - +- Steps 1-16 specify the key generation process for a public local key helper. Please note the `nonce` properties for this use case are elaborated in the previous [section](#high-level-design). +- Steps 17-29 are [DBSC](https://github.com/wicg/dbsc) with additional parameters introduced with DBSC(E). ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) @@ -265,7 +263,7 @@ In DBSC(E), the use of private local key helper for specific IDPs enables the be - The caching of `HelperId` is more beneficial for private local key helper for two reasons: - Since the IDP is associated mostly with the same local key helper, it us unlikely to change often. - `long lived` binding statements are possible with private key local helper (more below), eliminating the need for an additional redirect to fetch the IDP nonce for the binding statement. -- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of presence of the device by its own proprietery mechanism for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache [TDD: Add more specifics here] those binding statements for further performance optimization. +- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of possession of the device by its own proprietary mechanism for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache [TDD: Add more specifics here] those binding statements for further performance optimization. - RP can combine the request for a DBSC(E) startsession as a part of the IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the response for the sign-in flow and append the new JWT proof (which is generated by the local key helper) on navigation to the RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. [TDD: Follow up the conditions of redirection with google, is the URL enough or do we need the KeyId?] From 79d1e7468c0d6b285a72ddc7b2a941a183a70214 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 16 Sep 2024 05:36:33 -0700 Subject: [PATCH 41/47] Update text on use cases, remove txt files --- DBSCE/DBSC(E).svg | 2 +- DBSCE/DBSC(E).txt | 53 ----------- DBSCE/DeviceRegistration.txt | 10 -- DBSCE/IDPCallsPrivateLocalKeyHelper.txt | 92 ------------------- DBSCE/IDPCallsPublicLocalKeyHelper.txt | 48 ---------- .../IDPSameAsRP-CallsPublicLocalKeyHelper.txt | 45 --------- DBSCE/Overview.md | 27 +++--- 7 files changed, 15 insertions(+), 262 deletions(-) delete mode 100644 DBSCE/DBSC(E).txt delete mode 100644 DBSCE/DeviceRegistration.txt delete mode 100644 DBSCE/IDPCallsPrivateLocalKeyHelper.txt delete mode 100644 DBSCE/IDPCallsPublicLocalKeyHelper.txt delete mode 100644 DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.txt diff --git a/DBSCE/DBSC(E).svg b/DBSCE/DBSC(E).svg index 4598da6..ebe37e0 100644 --- a/DBSCE/DBSC(E).svg +++ b/DBSCE/DBSC(E).svg @@ -1 +1 @@ -%0Aparticipant%20%22%3Ccolor%3A%23blue%3EAttestation%20Service%22%20as%20s%0Aparticipant%20%22%3Ccolor%3A%23blue%3ELocalKeyHelper%20(Replaces%20TPM)%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%5Cn%3Ccolor%3A%23blue%3ERP%2FIDP%22%20as%20w%0A%0Aautonumber%201%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3E%20user%20initiates%20%3C%2Fcolor%3E%20sign-in%20flow%20%3Ccolor%3A%23blue%3E%20in%20the%20browser%20%3C%2Fcolor%3E%20%0Aw-%3Eb%3A%20%3Ccolor%3A%23blue%3E302%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%2C%20..%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%3Ccolor%3A%23blue%3Ebrowser%20invokes%20local%20key%20helper%20%5Cnto%20pre-generate%20keys%20%20based%20on%20DBSC(E)%20headers%5Cn%5Cn%3Ccolor%3A%23blue%3EcurrentHelperId%3D%5Cnevaluate%20policy%20for%20%5Cn(Server%7BIDPUrl%2C%20RPUrl%7D%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%7BIDPUrl%2C%20RPUrl%7D%2C%20challenge%2C%20extraParams%3F)%5Cn%20pre%20generates%20key%20and%20attestation%0At-%3Et%3A%20%3Ccolor%3A%23blue%3EgenerateKey()%0Anote%20over%20t%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Es%3A%20%3Ccolor%3A%23blue%3EgenerateBindingStatement%5Cn(publicKey%2C%20AIK%2C%20challenge)%0As-%3Et%3A%20%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%7D%0At-%3Eb%3A%20return%20public%20key%20%3Ccolor%3A%23blue%3E(KeyId)%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20%3Ccolor%3A%23blue%3ECache%20the%20key%20for%20server%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3ELoad%20sign-in%5CnSec-Session-Keys%3A%20KeyId%2C%5CnBinding%20Statement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims...%7D%0Aw-%3Ew%3A%20%3Ccolor%3A%23blue%3Evalidate%20signature%20on%20the%20%5Cnbinding%20statement%20and%20challenge%5Cnstore%20thumbprint%2C%20KeyId%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%2C%5Cn%3Ccolor%3A%23blue%3EKeyId%2C%20extraParams%3C%2Fcolor%3E%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2C%20KeyId%2C%20extraParams%3F...)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%5Cn%3Ccolor%3A%23blue%3Evalidate%20the%20JWT%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn%3Ccolor%3A%23blue%3E%22extraParams%22%3A%3Ccustom..%3E%7D%22%22%20%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%5Cn%3Ccolor%3A%23blue%3E(challenge%2C%20KeyId%2C%20extraParams%3F...)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendAttestation ServiceLocalKeyHelper (Replaces TPM)BrowserServerRP/IDP user initiates  sign-in flow  in the browser  1 3022 Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2, ..], HelperCacheTimebrowser invokes local key helper to pre-generate keys  based on DBSC(E) headerscurrentHelperId=evaluate policy for (Server{IDPUrl, RPUrl}, [HelperId1, HelperId2...])request create keypair 3 (serverUrl{IDPUrl, RPUrl}, challenge, extraParams?) pre generates key and attestationgenerateKey()4 For Enterprise, this call will be platformbased & generates device attestationgenerateBindingStatement5 (publicKey, AIK, challenge)BindingStatement6 {challenge, thumbprint(publicKey), extraClaims}return public key (KeyId) &7 BindingStatement{challenge, thumbprint(publicKey), extraClaims?..}Cache the key for serverLoad sign-in8 Sec-Session-Keys: KeyId,Binding Statement{challenge, thumbprint(publicKey), extraClaims...}validate signature on the 9 binding statement and challengestore thumbprint, KeyId200 w/signed-in content, response includes header to start secure session.  10 Header: Sec-Session-Registration: session_identifier=..., challenge=...,KeyId, extraParams(challenge required for private key proof of possession)browser initiates session bindingbased on header presencecreate JWT w/challengerequest sign JWT  11 (challenge, KeyId, extraParams?...)return JWT signature12 POST /securesession/startsession 13 {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish sessionvalidate the JWT200 w/cookie and session ID14 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookie15 GET /somecontent16 200 w/content17 check if required cookies exist18 GET /somecontent19 200 w/content20 request deferred while we get cookies...GET /securesession/refresh 21 header: Sec-Session-Id: [session ID]40122 Header: Sec-Session-Challenge: session_identifier=..., challenge=..."extraParams":<custom..>} create JWT w/challengerequest sign JWT23 (challenge, KeyId, extraParams?...)return JWT signature24 GET /securesession/refresh 25 header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session ID26 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent27 200 w/some content28 alt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file +%0Aparticipant%20%22%3Ccolor%3A%23blue%3EAttestation%20Service%22%20as%20s%0Aparticipant%20%22%3Ccolor%3A%23blue%3ELocalKeyHelper%20(Replaces%20TPM)%22%20as%20t%0Aparticipant%20%22Browser%22%20as%20b%0Aparticipant%20%22Server%5Cn%3Ccolor%3A%23blue%3ERP%2FIDP%22%20as%20w%0A%0Aautonumber%201%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3E%20user%20initiates%20%3C%2Fcolor%3E%20sign-in%20flow%20%3Ccolor%3A%23blue%3E%20in%20the%20browser%20%3C%2Fcolor%3E%20%0Aw-%3Eb%3A%20%3Ccolor%3A%23blue%3E302%5CnSec-Session-GenerateKey%3A%20%5CnRPUrl%2C%20IDPUrl%2C%20challenge%3Dnonce%2C%20extraParams...%5Cn%5CnSec-Session-HelperIdList%3A%20%5Cn%5BHelperId1%2C%20HelperId2%2C%20..%5D%2C%20HelperCacheTime%0Anote%20over%20b%3A%3Ccolor%3A%23blue%3Ebrowser%20invokes%20local%20key%20helper%20%5Cnto%20pre-generate%20keys%20%20based%20on%20DBSC(E)%20headers%5Cn%5Cn%3Ccolor%3A%23blue%3EcurrentHelperId%3D%5Cnevaluate%20policy%20for%20%5Cn(Server%7BIDPUrl%2C%20RPUrl%7D%2C%20%5BHelperId1%2C%20HelperId2...%5D)%0Ab-%3Et%3A%20request%20create%20keypair%20%5Cn%3Ccolor%3A%23blue%3E(serverUrl%7BIDPUrl%2C%20RPUrl%7D%2C%20challenge%2C%20extraParams%3F)%5Cn%20pre%20generates%20key%20and%20attestation%0At-%3Et%3A%20%3Ccolor%3A%23blue%3EgenerateKey()%0Anote%20over%20t%3A%20For%20Enterprise%2C%20this%20call%20will%20be%20platform%5Cnbased%20%26%20generates%20device%20attestation%0At-%3Es%3A%20%3Ccolor%3A%23blue%3EgenerateBindingStatement%5Cn(publicKey%2C%20AIK%2C%20challenge)%0As-%3Et%3A%20%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%7D%0At-%3Eb%3A%20return%20public%20key%20%3Ccolor%3A%23blue%3E(KeyId)%20%26%5Cn%3Ccolor%3A%23blue%3EBindingStatement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims%3F..%7D%0Anote%20over%20b%3A%20%3Ccolor%3A%23blue%3ECache%20the%20key%20for%20server%0Ab-%3Ew%3A%20%3Ccolor%3A%23blue%3ELoad%20sign-in%5CnSec-Session-Keys%3A%20KeyId%2C%5CnBinding%20Statement%5Cn%7Bchallenge%2C%20thumbprint(publicKey)%2C%20extraClaims...%7D%0Aw-%3Ew%3A%20%3Ccolor%3A%23blue%3Evalidate%20signature%20on%20the%20%5Cnbinding%20statement%20and%20challenge%5Cnstore%20thumbprint%2C%20KeyId%0Aw-%3Eb%3A%20200%20w%2Fsigned-in%20content%2C%20response%20includes%20header%20to%20start%20secure%20session.%20%20%5CnHeader%3A%20%22%22Sec-Session-Registration%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%2C%5Cn%3Ccolor%3A%23blue%3EKeyId%2C%20extraParams%3C%2Fcolor%3E%5Cn(challenge%20required%20for%20private%20key%20proof%20of%20possession)%0Anote%20over%20b%3A%20browser%20initiates%20session%20binding%5Cnbased%20on%20header%20presence%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%20%20%5Cn%3Ccolor%3A%23blue%3E(challenge%2C%20KeyId%2C%20extraParams%3F...)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20POST%20%2Fsecuresession%2Fstartsession%20%5Cn%5Cn%22%22%7B%22alg%22%3A...%2C%20%22typ%22%3A%22JWT%22%2C%20...%7D%7B...%2C%22key%22%3A%22%3Cpublic_key%3E%22%7D%22%22%20%0Anote%20over%20w%3A%20store%20public%20key%2C%20establish%20session%5Cn%3Ccolor%3A%23blue%3Evalidate%20the%20JWT%5Cn%3Ccolor%3A%23blue%3Evalidate%20that%20stored%20thumbprint%20is%5Cnmatched%20to%20the%20public%20key%20in%20the%20request.%0Aw-%3Eb%3A%20200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0A%3D%3DSome%20time%20passes...%3D%3D%0Anote%20over%20b%3A%20user%20clicks%20link%20for%20path%20%2Fsomecontent%0Ab-%3Eb%3A%20check%20if%20origin%2Bpath%20requires%20bound%20cookie%0Aalt%20bound%20cookie%20not%20required%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20bound%20cookie%20required%0Ab-%3Eb%3A%20check%20if%20required%20cookies%20exist%0Aalt%20required%20cookie%20present%20and%20not%20expired%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fcontent%0Aelse%20required%20cookie%20missing%20or%20expired%0Anote%20over%20b%3A%20request%20deferred%20while%20we%20get%20cookies...%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Id%3A%20%5Bsession%20ID%5D%22%22%0Aw-%3Eb%3A401%5Cn%5CnHeader%3A%20%22%22Sec-Session-Challenge%3A%20session_identifier%3D...%2C%20challenge%3D...%22%22%5Cn%3Ccolor%3A%23blue%3E%22extraParams%22%3A%3Ccustom..%3E%7D%22%22%20%0Anote%20over%20b%3A%20create%20JWT%20w%2Fchallenge%0Ab-%3Et%3Arequest%20sign%20JWT%5Cn%3Ccolor%3A%23blue%3E(challenge%2C%20KeyId%2C%20extraParams%3F...)%0At-%3Eb%3A%20return%20JWT%20signature%0Ab-%3Ew%3A%20GET%20%2Fsecuresession%2Frefresh%20%5Cnheader%3A%20%22%22Sec-Session-Response%3A%20%5BJWT%5D%22%22%0Anote%20over%20w%3A%20validate%20proof%20of%20possesion%0Aw-%3Eb%3A200%20w%2Fcookie%20and%20session%20ID%5Cnbody%20includes%20scope%20of%20cookies%20(origin%20%2B%20path)%5Cn%5Cnheader%3A%20%22%22Set-Cookie%3A%20auth_cookie%22%22%5Cnbody%3A%20%22%22%7B%22session_identifier%22%3A...%7D%22%22%0Anote%20over%20b%3A%20secure%20session%20established%2C%20resume%5Cnoriginal%20request%0Ab-%3Ew%3A%20GET%20%2Fsomecontent%0Aw-%3Eb%3A%20200%20w%2Fsome%20content%0Aend%0AendAttestation ServiceLocalKeyHelper (Replaces TPM)BrowserServerRP/IDP user initiates  sign-in flow  in the browser  1 3022 Sec-Session-GenerateKey: RPUrl, IDPUrl, challenge=nonce, extraParams...Sec-Session-HelperIdList: [HelperId1, HelperId2, ..], HelperCacheTimebrowser invokes local key helper to pre-generate keys  based on DBSC(E) headerscurrentHelperId=evaluate policy for (Server{IDPUrl, RPUrl}, [HelperId1, HelperId2...])request create keypair 3 (serverUrl{IDPUrl, RPUrl}, challenge, extraParams?) pre generates key and attestationgenerateKey()4 For Enterprise, this call will be platformbased & generates device attestationgenerateBindingStatement5 (publicKey, AIK, challenge)BindingStatement6 {challenge, thumbprint(publicKey), extraClaims}return public key (KeyId) &7 BindingStatement{challenge, thumbprint(publicKey), extraClaims?..}Cache the key for serverLoad sign-in8 Sec-Session-Keys: KeyId,Binding Statement{challenge, thumbprint(publicKey), extraClaims...}validate signature on the 9 binding statement and challengestore thumbprint, KeyId200 w/signed-in content, response includes header to start secure session.  10 Header: Sec-Session-Registration: session_identifier=..., challenge=...,KeyId, extraParams(challenge required for private key proof of possession)browser initiates session bindingbased on header presencecreate JWT w/challengerequest sign JWT  11 (challenge, KeyId, extraParams?...)return JWT signature12 POST /securesession/startsession 13 {"alg":..., "typ":"JWT", ...}{...,"key":"<public_key>"} store public key, establish sessionvalidate the JWTvalidate that stored thumbprint ismatched to the public key in the request.200 w/cookie and session ID14 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}Some time passes...user clicks link for path /somecontentcheck if origin+path requires bound cookie15 GET /somecontent16 200 w/content17 check if required cookies exist18 GET /somecontent19 200 w/content20 request deferred while we get cookies...GET /securesession/refresh 21 header: Sec-Session-Id: [session ID]40122 Header: Sec-Session-Challenge: session_identifier=..., challenge=..."extraParams":<custom..>} create JWT w/challengerequest sign JWT23 (challenge, KeyId, extraParams?...)return JWT signature24 GET /securesession/refresh 25 header: Sec-Session-Response: [JWT]validate proof of possesion200 w/cookie and session ID26 body includes scope of cookies (origin + path)header: Set-Cookie: auth_cookiebody: {"session_identifier":...}secure session established, resumeoriginal requestGET /somecontent27 200 w/some content28 alt[bound cookie not required][bound cookie required]alt[required cookie present and not expired][required cookie missing or expired] \ No newline at end of file diff --git a/DBSCE/DBSC(E).txt b/DBSCE/DBSC(E).txt deleted file mode 100644 index 5c27b3e..0000000 --- a/DBSCE/DBSC(E).txt +++ /dev/null @@ -1,53 +0,0 @@ - -participant "Attestation Service" as s -participant "LocalKeyHelper (Replaces TPM)" as t -participant "Browser" as b -participant "Server\nRP/IDP" as w - -autonumber 1 -b->w: user initiates sign-in flow in the browser -w->b: 302\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2, ..], HelperCacheTime -note over b:browser invokes local key helper \nto pre-generate keys based on DBSC(E) headers\n\ncurrentHelperId=\nevaluate policy for \n(Server{IDPUrl, RPUrl}, [HelperId1, HelperId2...]) -b->t: request create keypair \n(serverUrl{IDPUrl, RPUrl}, challenge, extraParams?)\n pre generates key and attestation -t->t: generateKey() -note over t: For Enterprise, this call will be platform\nbased & generates device attestation -t->s: generateBindingStatement\n(publicKey, AIK, challenge) -s->t: BindingStatement\n{challenge, thumbprint(publicKey), extraClaims} -t->b: return public key (KeyId) &\nBindingStatement\n{challenge, thumbprint(publicKey), extraClaims?..} -note over b: Cache the key for server -b->w: Load sign-in\nSec-Session-Keys: KeyId,\nBinding Statement\n{challenge, thumbprint(publicKey), extraClaims...} -w->w: validate signature on the \nbinding statement and challenge\nstore thumbprint, KeyId -w->b: 200 w/signed-in content, response includes header to start secure session. \nHeader: ""Sec-Session-Registration: session_identifier=..., challenge=..."",\nKeyId, extraParams\n(challenge required for private key proof of possession) -note over b: browser initiates session binding\nbased on header presence -note over b: create JWT w/challenge -b->t:request sign JWT \n(challenge, KeyId, extraParams?...) -t->b: return JWT signature -b->w: POST /securesession/startsession \n\n""{"alg":..., "typ":"JWT", ...}{...,"key":""}"" -note over w: store public key, establish session\nvalidate the JWT -w->b: 200 w/cookie and session ID\nbody includes scope of cookies (origin + path)\n\nheader: ""Set-Cookie: auth_cookie""\nbody: ""{"session_identifier":...}"" -==Some time passes...== -note over b: user clicks link for path /somecontent -b->b: check if origin+path requires bound cookie -alt bound cookie not required -b->w: GET /somecontent -w->b: 200 w/content -else bound cookie required -b->b: check if required cookies exist -alt required cookie present and not expired -b->w: GET /somecontent -w->b: 200 w/content -else required cookie missing or expired -note over b: request deferred while we get cookies... -b->w: GET /securesession/refresh \nheader: ""Sec-Session-Id: [session ID]"" -w->b:401\n\nHeader: ""Sec-Session-Challenge: session_identifier=..., challenge=...""\n"extraParams":}"" -note over b: create JWT w/challenge -b->t:request sign JWT\n(challenge, KeyId, extraParams?...) -t->b: return JWT signature -b->w: GET /securesession/refresh \nheader: ""Sec-Session-Response: [JWT]"" -note over w: validate proof of possesion -w->b:200 w/cookie and session ID\nbody includes scope of cookies (origin + path)\n\nheader: ""Set-Cookie: auth_cookie""\nbody: ""{"session_identifier":...}"" -note over b: secure session established, resume\noriginal request -b->w: GET /somecontent -w->b: 200 w/some content -end -end \ No newline at end of file diff --git a/DBSCE/DeviceRegistration.txt b/DBSCE/DeviceRegistration.txt deleted file mode 100644 index c95015f..0000000 --- a/DBSCE/DeviceRegistration.txt +++ /dev/null @@ -1,10 +0,0 @@ -title Device registration - -autonumber 1 -participant "Device registration client" as D -participant "Attestation service" as A - -note over D, A: Provisioning ... -D->>A: Register device (DeviceKey, AIK for KG, AIK for TPM, AIK for Software) -A->>D: 200 OK - diff --git a/DBSCE/IDPCallsPrivateLocalKeyHelper.txt b/DBSCE/IDPCallsPrivateLocalKeyHelper.txt deleted file mode 100644 index 7fdbad9..0000000 --- a/DBSCE/IDPCallsPrivateLocalKeyHelper.txt +++ /dev/null @@ -1,92 +0,0 @@ -title IdP calls a private Local Key Helper - -autonumber 1 -participant "Relying Party" as W -participant "IdP" as I -participant "Browser" as B -participant "Local Key Helper" as P - -note over W, P: IdP life... -B->>I: Any request -I->>B: Any response\nSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTime -B->>B: Cache HelperId for IDPURL for HelperCacheTime - -note over W, P: Sign in... -W->>B: Start sign in (302)\nSec-Session-Registration: path, RPChallenge,... \nSec-Session-GenerateKey: RPUrl, IDPUrl, extraParams -B->>B: Check for cached HelperId for IDPUrl - -alt Cached HelperId present (99.99% cases) - - B->>B: currentHelperId = Evaluate policy for (IdP, [HelperId1, HelperId2...]) - - B->>P: Pre-gen key and attest (RPUrl, IDPUrl, extraParams...) - - P->>P: Generate Key - - loop For each device - P->>P: create binding statement S(publicKey, AIK) - end - - P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] - B->>B: Remember this key is for RP (and maybe path) - - B->>I: Load sign-in (follow the 302)\n\nUserAuthHeader1{nonce}\nDeviceAuthHeader{nonce}\n\nUserAuthHeader1{nonce}\nDeviceAuthHeader{nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] - - opt nonce is stale - I->>B: 302 to IdP with qs parameter sso_nonce=new_nonce\nSec-Session-GenerateKey: RPURL, IDPURL, extraParams - B->>I: Load sign-in\n\nUserAuthHeader1{new_nonce}\nDeviceAuthHeader1{new_nonce}\n\nUserAuthHeader2{new_nonce}\nDeviceAuthHeader2{new_nonce} ...\n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] - end - -else No cached HelperId present - - - B->>I: Load sign-in (follow the 302)\n\nUserAuthHeader1{nonce}\nDeviceAuthHeader1{nonce}\n\nUserAuthHeader2{nonce}\nDeviceAuthHeader2{nonce} ... \n\nSec-Session-HelperDiscoveryNeeded: RPURL, IDPURL, extraParams - - note over I, B: No binding info present, but the reequest has GenerratKey, so IdP issues helper id list - - I->>B: 302 to IdP with qs parameter sso_nonce=new_nonce\n\nSec-Session-GenerateKey: RPURL, IDPURL, extraParams\nSec-Session-HelperIdList: [HelperId1, HelperId2], HelperCacheTime - B->>B: Cache HelperId for IDPURL for HelperCacheTime - - B->>B: currentHelperId = Evaluate policy for (IdP, [HelperId1]) - B->>P: Pre-gen key and attest (RPURL, IDPURL, extraParams...) - - P->>P: Generate Key - - loop For each device - P->>P: create binding statement S(publicKey, AIK) - end - - P->>B: Return: KeyId, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] - B->>B: Remember this key is for RP (and maybe path) - - B->>I: Load sign-in\n\nUserAuthHeader1{new_nonce}\nDeviceAuthHeader1{new_nonce}\n UserAuthHeader2{new_nonce}\n DeviceAuthHeader2{new_nonce} ... \n\nSec-Session-BindingInfo: KeyId, PublicKey, \narray of binding statements [BindingStatement1 {extraClaims....}, \nBindingStatement2 {extraCalims...}] - - -end - -opt SSO information is not sufficient - I->>B: Sign in ceremony - B->>I: Sign done -end - -I->>B: Authorization code, KeyId - - -note over W, B: Since DBSC session has been initialized already for RP, browser needs to generate JWT on redirect back -B->>P: Request Sign JWT (path, RPChallenge, extraParams) -P->>B: Return JWT Signature -note over W, B: JWT is appended by the browser before returning the response from IDP back to the RP -B->>W: Authorization code, KeyId, JWT -W->>I: (confidential client request) redeem authorization code -I->>W: (confidential client response) return id_token -W->>W: parse id_token and validate binding, match with the JWT from the previous -W->>B: Bound AuthCookie - -note over W, P: Refresh DBSC... -B->>W: GET /securesession/refresh (sessionID) -W->>B: Challenge, **extraParams** -B->>P: Request Sign JWT (sessionID, RPChallenge, **extraParams**) -P->>B: Return JWT Signature -B->>W: GET /securesession/refresh (JWT) -W->>W: Validate JWT (w/public key on file) -W->>B: AuthCookie diff --git a/DBSCE/IDPCallsPublicLocalKeyHelper.txt b/DBSCE/IDPCallsPublicLocalKeyHelper.txt deleted file mode 100644 index 6581265..0000000 --- a/DBSCE/IDPCallsPublicLocalKeyHelper.txt +++ /dev/null @@ -1,48 +0,0 @@ -title IdP calls a public Local Key Helper - -autonumber 1 -participant "Relying Party" as W -participant "IdP" as I -participant "Browser" as B -participant "Local Key Helper" as P -participant "AttestationService" as A - -note over W, A: Sign in... -W->>B: Start sign in (302) -B->>I: Load sign-in (follow the 302) - -I->>B: Sec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2], HelperCacheTime -B->>B: currentHelperId = \nEvaluate policy for (IdP, [HelperId1, HelperId2,...]) -B->>P: Pre-gen key and \nattest (RPUrl, IDPUrl, \nchallenge=nonce, extraParams...) - -P->>P: Generate Key - -P->>A: Get Binding Statement \n(publicKey, AIK, challenge=nonce) -A->>P: Return binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } -P->>B: KeyId, \nReturn binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } -B->>B: Remember this key is for RP (and maybe path) -B->>I: Sec-Session-Keys: KeyId, \nBinding statement \n{ nonce, thumbprint(publicKey), extraClaims... } -I->>I: validate signature on the binding statement \n& nonce, store thumbprint - -I->>B: Sign in ceremony -B->>I: Sign done - -I->>B: Auth tokens (with thumbprint), \nKeyId -B->>W: Auth tokens (with thumbprint), \nKeyId - -note over W, A: Initiate DBSC ... -W->>B: StartSession \n(challenge=nonce, token?, KeyId?, **extraParams...**) -B->>P: Request Sign JWT \n(uri, challenge=nonce,\n token?, keyId?, **extraParams...**) -P->>B: Return JWT Signature -B->>W: POST /securesession/startsession (JWT, tokens) -W->>W: Validate JWT, \n(w/ match thumbprint \nin the tokens) -W->>B: AuthCookie - -note over W, A: Refresh DBSC... -B->>W: GET /securesession/refresh (sessionID) -W->>B: Challenge, **extraParams...** -B->>P: Request Sign JWT (sessionID, **extraParams...**) -P->>B: Return JWT Signature -B->>W: GET /securesession/refresh (JWT) -W->>W: Validate JWT \n(w/public key on file) -W->>B: AuthCookie diff --git a/DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.txt b/DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.txt deleted file mode 100644 index 229824f..0000000 --- a/DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.txt +++ /dev/null @@ -1,45 +0,0 @@ -title IdP same as RP, calls a public Local Key Helper - -autonumber 1 -participant "Relying Party" as W -participant "IdP" as I -participant "Browser" as B -participant "Local Key Helper" as P -participant "AttestationService" as A - -note over W, A: Sign in... -W->>B: Start sign in (302) \n\nSec-Session-GenerateKey: \nRPUrl, IDPUrl, challenge=nonce, extraParams...\n\nSec-Session-HelperIdList: \n[HelperId1, HelperId2], HelperCacheTime - -B->>B: currentHelperId = \nEvaluate policy for (IdP, [HelperId1, HelperId2,...]) -B->>P: Pre-gen key and \nattest (RPUrl, IDPUrl, challenge=nonce, extratParams...) - -P->>P: Generate Key - -P->>A: Get Binding Statement \n (publicKey, AIK, challenge=nonce) -A->>P: Return binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } -P->>B: KeyId, \nReturn binding statement \n{ nonce, thumbprint(publicKey), extraClaims... } -B->>B: Remember this key is for RP (and maybe path) -B->>I: Load sign-in \nSec-Session-Keys: KeyId, \nBinding statement \n{ nonce, thumbprint(publicKey), extraClaims... } -I->>I: validate signature \non the binding statement and nonce, \nstore thumbprint - -I->>B: Sign in ceremony -B->>I: Sign done - -I->>W: API(Auth tokens with thumbprint, KeyId) - -note over W, A: Initiate DBSC ... -W->>B: 200 OK \nSec-Session-Registration: \npath, RPChallenge, token?, KeyId, extraParams -B->>P: Request Sign JWT (uri, challenge, token?, keyId?, **extraParams...**) -P->>B: Return JWT Signature -B->>W: POST /securesession/startsession (JWT, tokens) -W->>W: Validate JWT, \n(w/ match thumbprint in the tokens) -W->>B: AuthCookie - -note over W, A: Refresh DBSC... -B->>W: GET /securesession/refresh (sessionID) -W->>B: Challenge, **extraParams...** -B->>P: Request Sign JWT (sessionID, **extraParams...**) -P->>B: Return JWT Signature -B->>W: GET /securesession/refresh (JWT) -W->>W: Validate JWT (w/public key on file) -W->>B: AuthCookie diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 3cfaeae..fd3f71a 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -65,7 +65,7 @@ While the original DBSC proposal enables browsers to bind session cookies to a d DBSC(E) aims to mitigate this risk by introducing the concept of `one-time protected` [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) is able to provide this risk mitigation if the device registration is a `protected` operation, meaning it is performed in a ["clean room"](#device-registration-client)) enviroment e.g. an organization registering a device before giving a device to an employee. As device registration is expected to be a `one-time` operation, the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. -If device registration is executed in a clean room and precedes any sign in sessions malware would not be able to bind session cookies to malicious binding keys during a sign in operation that implements DBSC(E). +If device registration is executed in a clean room and precedes any sign in sessions, malware would not be able to bind session cookies to malicious binding keys during a sign in operation that implements DBSC(E). Note: While DBSC(E) hardens security against temporary malware attacks, if the malware is persistent on the device, the malware can still exfiltrate data. @@ -109,7 +109,7 @@ The device registration client can be owned and supported by: - Operating system - the device gets registered when the OS is installed. - Browser - the device gets registered when the browser is installed. - Device management software (MDM provider) - the device gets registered when the MDM is enrolled. -- Third-party software vendor - the device gets registered according to the vendor rules. +- Third-party software vendor - the device gets registered according to the vendor rules. DBSC(E) aims to support most of these scenarios. DBSC(E) does not define the device registration protocol, but is only concerned that the device registration is executed in a "clean room" and the management of the generated keys to prove device binding. @@ -146,7 +146,7 @@ Note: Above are platform specifications for Local Key Helpers that can be used f ### Attestation Service -Attestation service is responsible for providing the attestation statement for the binding key. The attestation service can be owned by the IdP or a third party. DBSC(E) relies on the attestation service to enable the IDP to validate the binding statement and ensure that the binding key and the device key belong to the same device. An attestation service can be part of the IdP, or a separate service. +Attestation service is responsible for providing the attestation statement for the binding key. DBSC(E) relies on the attestation service to enable the IDP to validate the binding statement and ensure that the binding key and the device key belong to the same device. An attestation service can be part of the IdP, or a separate service. This document does not define the implementation details of the Attestation Service. It defines the artifacts which are generated during the [Device Registration](#device-registration-client) and are necessary to validate the binding statement. @@ -175,14 +175,14 @@ This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC pr ##### Binding Statement -Additional to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. - -The validation of the _binding statement_ authenticates the device by using device ID to find the corresponding _attestation key_. The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. +Additional to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. The validation of the _binding statement_ authenticates the device by using device ID to find the corresponding _attestation key_. The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. Binding statements can be long-lived or short-lived. - If an IdP performs fresh device authentication outside of DBSC(E) integration at the time of _binding key_ validation, then the _binding statement_ can be long lived, as the IdP ensures the device identity through other mechanisms. - IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements. Otherwise, the attacker will be able to bind the victim's cookies to malicious keys from a different machine. A short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement, minimizing the attack window. +Since there could be multiple devices supported by a [device registration client](#device-registration-client) and since it is possible for a device to be unknown when the local key helper is invoked during authentication, multiple binding keys can be issued for a single binding key. This is especially true for [private local key helpers](#idp-calls-private-local-key-helper). + ## High-Level Design DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an enterprise policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. @@ -198,7 +198,7 @@ DBSC(E) (in contrast with DBSC): ![DBSC(E) Highlevel Design](<./DBSC(E).svg>) -[Link to editable diagram](https://sequencediagram.org/index.html#initialData=FABwhgTgLglgxjcA7KACARAHjgewDY4QBcAxAEZ4CuApgHwCCUU1AzlGLDkqgMrUQA3eNXSowLVC1CRYCZGiy4CxclToAZHHDB4A0tQCeACWp4Q-VAAoAStRB4wcVqgAqABQCyASlHjUUaWh4RDAUDAAhCBwAdxZ+XwkyQNkQsPQ+QX4AHSRsfEJSChpaazcAegBJABE3BNRo4GAwSiguSgBbMgsARmAyAFpaaKJUPOVCtVpUSjiIVBgkGFgOZ0wypUIplhgAcyR+hdQAMwJo0Y2VIrp57igAC2pUMijYizWLqeBowbIRsYLVMUAMwABgATDk+HB+nwWNsuP0AOLUJD8Fb6AwjHKlACqEDwABpUNU3HjCag4HcdHgUTtqABeJBcJxE6gADygEDAbkgYHaLAAdEKcpDqNDYfD9iYzPwKgATdQwNhYpAAbWl5gg8u6RI1srlYKJQoAurrTJqAMKOB4uGDtajAJnMVA4AQWX7-S6TZ4xWY3AQ4ADWzgI2jwqGDBlQDxlcxyrVQIAg1H6dNRXOdkYkT3E1DlLu4VXCPAtlgAol5o9QwHL+CwRbkLhNinBKBBkyg9Vq5fSctQBDpKCtE-h4FGjoRUDlLBk3RAAN4kslE3H4gC+RPV5v1OtQXflYKFAuNXj6gygI2TAEcaGwKcnh5HwDA4438l7ipZZnOyYuasvUFXPANwpKk8BpJA6VZDkuR5Ll+QAfi8HJE2TVA0zRZgJEjMQkHzDgsPYTgkGAKBzz+JtAToDCM2oDFLFPJ1HldCwL1QAAxScyxQfgkyVagiXuJUKWpeoYHAp5HnsDgJwgdocjIXN8wAMnQlFMOcWshCcMQmFYIiYC4UjBhYCj32baj1No8IFjlBYdh4IjqHtFBpxASgKHgDEiXoCpdCJSlqVpahTxYcjznMqjaBsvD7MclYXKgHJ50C8DgsEu4OjIPiUEsdzPLgDEvGgzkwAtBw7RYNdjNoX5UGTKA224fK8HgCNDAi8YossDF5UrZSck9CzotsuKnMS5LUogqD-EyzocqgPKPNawrDGK1B2VK8qwEqhChWqpiXTnJ4zK6q5aCtSlHnuR4cNkyR+DnM8hlOgFzs0GtJF2fYFlFcVWElfoMVM1BerlAkchiuzIN4caUSSpAUrA6aBNmrKFqWgqipKrltsqo9qu+F7OreyYB1auVh22PYODbZjbgeKckDIUaYbYBL4dw-MpuCnI2EIa65uyiAFigIkwa+H4RjBEEQXqMpqdROUDm4XAeJQIlkxYEAuDiG44CoWsJAeGtWJwSR2GgB7WzQuI4UMpABVQJmTFN4gMHSMUYQBh3+lsHYlVK4iRjtyUAH0YFrFAYCOGB+HpI8AuR4KE6FdB0Aht8zsmMGce5Xl+Xed9aGnHnIMea9KBfPNjknPiB0zDqkxwHAjhdNudbhH2uEYnBnRYuY6p9V45gWJYYBWCRQ4dp5WZ2BSlILKs3dQ1gUScR0++Y466rgB9nQAKQAdRceWy7pZ6L0r-Svr2VBj9Ppmhu68-UdzjaYPz+CWD2oVTzI2ql5qCNQgNwB+t8kC02TM9YYqA3AAHkeCnwVmKOm08uAK0tlAdB3AGzp3nOgHQOx0BEEThgKABgQAkPQA-DOqACbzkTugSM1DMAtXgGHSMtB0BrnTqgTe-djqwP5mhdhcB2oGFZOzTyLA7gPXtlwQalFzrk0jsOG698T6S0AagGWctojrBboGOOXN5GSmJFUBSOA5RRgWAbSgRtJC4HMO3CkRi44SEsIQXYhwADUiYOB3GQkgHIJtazu3TnwMiFp3HUBGM0e4YdcBBjjunKxNiRj4PQDgiOUdYCx3iKQ-a6dgD0npDwHA9p-B2ikuIO2R4ykCO3u6EYMwLAG3gIGCQrUkCBlrnMcA9xUAK0qWKLgzAUDPV3g8OAfSY4uhFgHJAvjBlyMrtXRIOBKB4TcSkh0Og0BkC2Ts5JxjHhOnqtQG81c5QwJGIiMsyCWCjLVhMgIRM6p6LPuM+GwBTB6yOds7msTLnXOTLcgYOirqzPmG3dZ4LdlnIkOyQOTQ8BoHhTXU5JikxrzCKEfMFz2QgBuXc1ADynkvJ+ZMj50tZbfPVgEf5FcrlVwRdix47QlTbBhpOYlpLDoDxOqC28aBaxHH4Ai6IdxxKPGiI8OkaAOWCiFGSilwy4g2zXgopAZRkxHC1nI0J1ZwmZM9v9HV-R5QjFVDgixxoSm0oACwgm6A2V2pqPZQm9pai0ydy4h27kgXJ8MY5xwgKnAUScgrl0jWkrOpNijoE2rBAuLASHYBmK0doQpaC8NEE0o6LT7zVkPifM+-qL6Qqvqym+itNEuCUZFc6lhX7i0MPKPOcE+Q-yPP-KWlyQFgPLYrKBDpIWwPVSgrVOC9XUANawI1SAwn8DNd6iUvtbDa11nE1AqoH4OvQIWoVsDVGU2dM3VurjO52wdto34XyDEctMXa6o6TbFIHsY4lgzjmJt2VVYbxSzUD+NWcE41bs13AP6DEvZ8SWh3CSbE+NRyMkewITkyOoaCkQBIQTEpgqd6Bq1WYme+kwAyIeODS5LAOjUByEBhYOgRX6TVY8jVVLGX3rpfokZVTXm-JRLcoTQA) +[Link to editable diagram](https://sequencediagram.org/index.html#initialData=FABwhgTgLglgxjcA7KACARAHjgewDY4QBcAxAEZ4CuApgHwCCUU1AzlGLDkqgMrUQA3eNXSowLVC1CRYCZGiy4CxclToAZHHDB4A0tQCeACWp4Q-VAAoAStRB4wcVqgAqABQCyASlHjUUaWh4RDAUDAAhCBwAdxZ+XwkyQNkQsPQ+QX4AHSRsfEJSChpaazcAegBJABE3BNRo4GAwSiguSgBbMgsARmAyAFpaaKJUPOVCtVpUSjiIVBgkGFgOZ0wypUIplhgAcyR+hdQAMwJo0Y2VIrp57igAC2pUMijYizWLqeBowbIRsYLVMUAMwABgATDk+HB+nwWNsuP0AOLUJD8Fb6AwjHKlACqEDwABpUNU3HjCag4HcdHgUTtqABeJBcJxE6gADygEDAbkgYHaLAAdEKcpDqNDYfD9iYzPwKgATdQwNhYpAAbWl5gg8u6RI1srlYKJQoAurrTJqAMKOB4uGDtajAJnMVA4AQWX7-S6TZ4xWY3AQ4ADWzgI2jwqGDBlQDxlcxyrVQIAg1H6dNRXOdkYkT3E1DlLu4VXCPAtlgAol5o9QwHL+CwRbkLhNinBKBBkyg9Vq5fSctQBDpKCtE-h4FGjoRUDlLBk3RAAN4kslE3H4gC+RPV5v1OtQXflYKFAuNXj6gygI2TAEcaGwKcnh5HwDA4438l7ipZZnOyYuasvUFXPANwpKk8BpJA6VZDkuR5Ll+QAfi8HJE2TVA0zRZgJEjMQkHzDgsPYTgkGAKBzz+JtAToDCM2oDFLFPJ1HldCwL1QAAxScyxQfgkyVagiXuJUKWpeoYHAp5HnsDgJwgdocjIXN8wAMnQlFMOcWshCcMQmFYIiYC4UjBhYCj32baj1No8IFjlBYdh4IjqHtFBpxASgKHgDEiXoCpdCJSlqVpahTxYcjznMqjaBsvD7MclYXKgHJ50C8DgsEu4OjIPiUEsdzPLgDEvGgzkwAtBw7RYNdjNoX5UGTKA224fK8HgCNDAi8YossDF5UrZSck9CzotsuKnMS5LUogqD-EyzocqgPKPNawrDGK1B2VK8qwEqhChWqpiXTnJ4zK6q5aCtSlHnuR4cNkyR+DnM8hlOgFzs0GtJF2fYFlFcVWElfoMVM1BerlAkchiuzIN4caUSSpAUrA6aBNmrKFqWgqipKrltsqo9qu+F7OreyYB1auVh22PYODbZjbgeKckDIUaYbYBL4dw-MpuCnI2EIa65uyiAFigIkwa+H4RjBEEQXqMpqdROUDm4XAeJQIlkxYEAuDiG44CoWsJAeGtWJwSR2GgB7WzQuI4UMpABVQJmTFN4gMHSMUYQBh3+lsHYlVK4iRjtyUAH0YFrFAYCOGB+HpI8AuR4KE6FdB0Aht8zsmMGce5Xl+Xed9aGnHnIMea9KBfPNjknPiB0zDqkxwHAjhdNudbhH2uEYnBnRYuY6p9V45gWJYYBWCRQ4dp5WZ2BSlILKs3dQ1gUScR0++Y466rgB9nQAKQAdRceWy7pZ6L0r-Svr2VBj9Ppmhu68-UdzjaYPz+CWD2oVTzI2ql5qCNQgNwB+t8kC02TM9YYqA3AAHkeCnwVmKOm08uAK0tlAdB3AGzp3nOgHQOx0BEEThgKABgQAkPQA-DOqACbzkTugSM1DMAtXgGHSMtB0BrnTqgTe-djqwP5mhdhcB2oGFZOzTyLA7gPXtlwQalFzrk0jsOG698T5KMiionQajnT3A4BbAW+Z7joxFmEJUOR2gcCuqY82GixESJuLNCu1Abz6QFJLQBqAZZy2iOsFugY45c3kZKYkVQFI4DlFGBYBtKBG0kLgcw7cKRBLjhISwhBdiHAANSJg4HcZCSAcgm1rO7dOfAyIWnSdQEYzR7hh1wEGOO6cokxJGPg9AOCI5R1gLHeIpD9rp2APSekPAcD2n8HaKS4g7ZHjGQI7e7oRgzAsAbeAgYJCtSQIGWucxwD3FQArSZYouDMBQM9XeDw4B7Jji6EWAckC5MOXIyu1dEg4EoHhNJLSHQ6DQGQL5PzmnBMeE6eq7iq7JjlDAkYiIyzIJYKctWFyAhEzqn4s+5z4bAFMHrIF3zua1MhTeausKBg+Kurc+Ybd3kwt+WCiQ7JA5NDwGgelNdQUhKTGvMIoR8wQvZCAclcLUAIqRSinFlyMXS1lti9WAR8VuLJQy7ljx2hKm2DDScwrRWHQHidUlt40C1iOPwBl0Q7jiUeNER4dI0DqsFEKMVErjlxBtmvBRSAyjJiOFrORpTqzlM6Z7f63r+jyhGKqHBETjQjNlQAFhBN0BsrsQ0eyhN7CNFpk7lxDt3JAvT4YxzjhAVOAok5BXLhWtpWdSbFHQJtWCBcWAkOwDMVo7QhS0F4aIJZR0Vn3mrIfE+Z880X0pVfKFN9FaaJcNo7On5X7i0MPKPOcE+Q-yPP-KWkKQFgLHYrKBDpKWwLdSgz1ODfXUH9awQNSAyn8FDVmiUvtbDa11nU1AqoH7xvQAOw1sDVGU2dM3VuqTO52wdt434WKAnqtCbG6o7TYlIHiYklgyTmJtydVYbJTzUD5NecUoNbsX3AP6DUv59SWh3CabUutQKOkewIT0yOJaBkQBIQTEZBqd4Fs9WEme+kwAyIeODSFLAOjUByARhYOhjX6VdYi91UrFWwblf4k5UzUW4pRLCgzQA) Highlights: @@ -207,7 +207,7 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **Pre-Session initiation with special headers (steps 1-2):** When a user starts a sign-in process, or initiates a session, the webpage initiating the session sends special headers `Sec-Session-GenerateKey` and `Sec-Session-HelperIdList` to the browser in response, to indicate that the session is expected to be DBSC(E) compliant. - The `Sec-Session-GenerateKey` header contains the URL of the server(RP), the URL of the IdP (authentication service in most cases - which is optional for consumer use cases), a `nonce` and any extra parameters that the IdP wants to send to the Local Key Helper. `nonce` is essential to prevent replay of cached binding key/binding statements from a different device (proof of possession) and to prevent the clock-skew between the IdP and the Local Key Helper. - - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _short lived_. If _binding statement_ is not shortlived, it is possible for the attacker to generate the _binding statement_ and the _binding key_ from a device controlled by the attacker and use them to bind the victim's cookies to the malicious _binding key_. The enforcement of a shortlived binding statement is achieved through `nonce`. + - For all _public local key helpers_, e.g., Contoso's IDP calling Fabrikam's Local key helper, `nonce` must be _short lived_. If _binding statement_ is not shortlived, it is possible for the attacker to generate the _binding statement_ and the _binding key_ from a device controlled by the attacker and use them to bind the victim's cookies to the malicious _binding key_. The enforcement of a shortlived binding statement is achieved through `nonce`. - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of possession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate `nonce` to ensure the _binding statement_ is issued recently. - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. @@ -218,7 +218,7 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC - The [_attestation service_](#attestation-service) is also separate from the IDP in this diagram. - The `extra claims` is a provision added for specific IdPs or Local Key Helper vendors to add any additional information to the _binding statement_. It is intentionally left undefined, and can be customized. -1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP [validates](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the publicKey. Once the validation succeeds, the IdP will proceed with the sign-in ceremony. It can optionally generate auth tokens if the RP and IdP are separate, illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the publicKey or a thumbprint of the publicKey. +1. **Sign In/Session Initiation (steps 8-9):** The _binding statement_, with the `KeyId` is expected to be returned to the IdP with a new header, `Sec-Session-Keys`. The IdP [validates](#binding-statement) the signature on the _binding statement_, `nonce` and stores the thumbprint of the publicKey. Once the validation succeeds, the IdP will proceed with the sign-in ceremony. It can optionally generate auth tokens as illustrated [below](#idp-is-rp-and-calls-public-local-key-helper), that embed the publicKey or a thumbprint of the publicKey. 1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with two caveats: The _local key helper_ is called for JWT generation and the additional params introduced for DBSC(E) customization can be optionally added. @@ -228,7 +228,7 @@ This section expands on the [generic design](#high-level-design) to address diff #### IDP is RP and Calls Public Local Key Helper -This is the same use case elaborated in the high level design [above](#high-level-design). However, we have separated the IdP/RP components of the server that applies to certain enterprise and consumer use cases in the below diagram. +This is the similar use case elaborated in the high level design [above](#high-level-design). This use case covers where an IDP/RP calls a [_public Local Key Helper_](#local-key-helper). The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). ![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) @@ -236,17 +236,18 @@ This is the same use case elaborated in the high level design [above](#high-leve Highlights: +- The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). - Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of auth tokens and issue cookies based on those tokens. In such case, the IdP can generate the auth tokens and embed the thumbprint of the publicKey in the token. -- The tokens can be delivered to the RP directly through an API instead of a header based response. +- The tokens can be delivered to the RP directly through an API instead of a header based response since they are the same server in this use case. - The tokens also contain the thumbprint of the publicKey, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. The RP will also embed the thumbprint in the cookie for subsequent session validation. #### IDP Calls Public Local Key Helper -In many use cases, it is also a valid to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where the IdP calls a _public Local Key Helper_ and is a separate service from the RP below. +In many use cases, it is also a valid to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where the IdP calls a [_public Local Key Helper_](#local-key-helper) and is a separate service from the RP below. For easy mapping with the existing DBSC proposal, please note: -- Steps 1-16 specify the key generation process for a public local key helper. Please note the `nonce` properties for this use case are elaborated in the previous [section](#high-level-design). +- Steps 1-16 specify the key generation process for a public local key helper. The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). - Steps 17-29 are [DBSC](https://github.com/wicg/dbsc) with additional parameters introduced with DBSC(E). ![IDPCallsPublicLocalKeyHelper](./IDPCallsPublicLocalKeyHelper.svg) From 0af8c4323f72b24b732311bbb3b64376f657b717 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 16 Sep 2024 05:43:24 -0700 Subject: [PATCH 42/47] Update local key helper android --- DBSCE/LocalKeyHelper-Android.md | 120 +++++++++++++++++++++----------- 1 file changed, 78 insertions(+), 42 deletions(-) diff --git a/DBSCE/LocalKeyHelper-Android.md b/DBSCE/LocalKeyHelper-Android.md index 36cbd26..d523025 100644 --- a/DBSCE/LocalKeyHelper-Android.md +++ b/DBSCE/LocalKeyHelper-Android.md @@ -6,41 +6,96 @@ On android platform a Local Key Helper is a protocol interface (`ILocalKeyHelper Local KeyHelpers on the Android platform are implemented using [content providers](https://developer.android.com/guide/topics/providers/content-providers). These content providers allow browser applications, such as Chrome, to interact with them by querying and accessing specific APIs defined by the Local KeyHelpers. -#### Content Provider Authority -Each Local KeyHelper defines a content provider with a authority such as `com.contoso.localkeyhelper`. Different APIs are implemented as separate paths on this content provider. +#### Registering LocalkeyHelpers with Browser Interaction +To register the localkeyhelpers with a browser (e.g. Chrome), the browser application exports a content provider with the authority `$browserPackageName.localkeyhelpersregistration` in it's manifest file. -#### Browser Interaction with Local KeyHelpers -To interact with Local KeyHelpers, browser applications must define a `` inside the `` tag in their manifest file with the same authority `com.contoso.localkeyhelper`. This allows the browser to query the Local KeyHelpers. +```xml + + +``` + +##### Implementing localkeyhelpersregistration provider in Browser +Browser application implements `localkeyhelpersregistration` content provider and provides path `/register` for the local key helpers to register themselves. +When the LocalKeyHelper queries the browser's content provider, it register itself with the browser. +Example implementation. +``` java +public class LocalKeyHelperConsumerProvider extends ContentProvider { + public static final String AUTHORITY = "com.custombrowser.localkeyhelpersregistration"; + private static final UriMatcher uriMatcher = new UriMatcher(UriMatcher.NO_MATCH); + + static { + uriMatcher.addURI("AUTHORITY", "/register", 1); + } + + @Override + public boolean onCreate() { + return true; + } -##### Example Manifest Entry + @Nullable + @Override + public Cursor query(@NonNull Uri uri, @Nullable String[] projection, @Nullable String selection, @Nullable String[] selectionArgs, @Nullable String sortOrder) { + switch (uriMatcher.match(uri)) { + case 1 : + return new MatrixCursor(new String[0]) { + @Override + public Bundle getExtras() { + Bundle bundle = new Bundle(); + bundle.putBoolean("registered", true); + return bundle; + } + }; + default: + throw new IllegalArgumentException("Unknown URI: " + uri); + } + } + ... + +} +``` +##### Calling Browser Content Provider to register a local key helper. +LocalKeyhelpers make the browser content provider visible to them by adding queries tag with browser content provider authority to their manifest file. ```xml - + -``` -To get the installed applications that provide a content provider with authority "com.contoso.localkeyhelper" and select a specific package "com.contoso.localkeyhelper.entra" to query the content provider, you can use the following Java code: +``` +LocalKeyHelper call the browser's content provider to register itself with the browser. ```java -PackageManager packageManager = getPackageManager(); -List installedPackages = packageManager.getInstalledPackages(PackageManager.GET_PROVIDERS); - -for (PackageInfo packageInfo : installedPackages) { - ProviderInfo[] providers = packageInfo.providers; - if (providers != null) { - for (ProviderInfo provider : providers) { - if ("com.contoso.localkeyhelper".equals(provider.authority)) { - // select specific package to query - } +Uri uri = Uri.parse("content://com.custombrowser.localkeyhelpersregistration/register"); +Cursor cursor = getContentResolver().query(uri, null, null, null, null); +if (cursor != null) { + try { + val resultBundle = cursor.extras + if (resultBundle != null) { + val registered = resultBundle.getBoolean("registered") + Log.i("TAG", "Registered: $registered") + } else { + Log.i("TAG", "Failed to register.") } + } finally { + cursor.close(); } } -``` +``` +#### Calling Local KeyHelpers from Browser +Once a localkeyhelper is registered with the Browser application, the browser can query the Local KeyHelper's content providers without defining the query tag. +To implement the localkeyhelper protocol interface LocalKeyHelper defines a content provider with the authority `$packagename.**localkeyhelper**`. Different APIs are implemented as separate paths on this content provider. -#### Implementing the ContentProvider in Local KeyHelper -Each Local KeyHelper must implement a ContentProvider to handle the interactions. Below is an example of how to implement a ContentProvider in a Local KeyHelper. +##### Sample Manifest Entry for Local KeyHelper Content Provider +```xml + +``` -##### Example ContentProvider Implementation +##### Implementing the ContentProvider in Local KeyHelper +Each Local KeyHelper must implement a ContentProvider to handle the interactions. Below is an example of how to implement a ContentProvider in a Local KeyHelper. ```java public class LocalKeyHelperProvider extends ContentProvider { @@ -48,7 +103,7 @@ public class LocalKeyHelperProvider extends ContentProvider { private static final UriMatcher uriMatcher = new UriMatcher(UriMatcher.NO_MATCH); static { - uriMatcher.addURI(AUTHORITY, "keyhelper1/api1", 1); + uriMatcher.addURI(AUTHORITY, "sample_api_path", 1); // Add more paths as needed } @@ -67,23 +122,4 @@ public class LocalKeyHelperProvider extends ContentProvider { } } } -``` - -#### Browser Interaction with the ContentProvider -Browser applications can interact with the Local KeyHelper's ContentProvider by querying it. Below is an example of how a browser application can query the ContentProvider. - -##### Example Code to Query the ContentProvider - -```java -Uri uri = Uri.parse("content://com.contoso.localkeyhelper/keyhelper1/api1"); -Cursor cursor = getContentResolver().query(uri, null, null, null, null); -if (cursor != null) { - try { - if (cursor.moveToFirst()) { - // Read the data from the cursor - } - } finally { - cursor.close(); - } -} ``` \ No newline at end of file From 9616a67fadd45321b7e68e394a8388f3ce2ebeca Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Mon, 16 Sep 2024 09:28:14 -0700 Subject: [PATCH 43/47] removed follow up texts - will track offline --- DBSCE/Overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index fd3f71a..750c283 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -264,8 +264,8 @@ In DBSC(E), the use of private local key helper for specific IDPs enables the be - The caching of `HelperId` is more beneficial for private local key helper for two reasons: - Since the IDP is associated mostly with the same local key helper, it us unlikely to change often. - `long lived` binding statements are possible with private key local helper (more below), eliminating the need for an additional redirect to fetch the IDP nonce for the binding statement. -- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of possession of the device by its own proprietary mechanism for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache [TDD: Add more specifics here] those binding statements for further performance optimization. -- RP can combine the request for a DBSC(E) startsession as a part of the IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the response for the sign-in flow and append the new JWT proof (which is generated by the local key helper) on navigation to the RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. [TDD: Follow up the conditions of redirection with google, is the URL enough or do we need the KeyId?] +- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of possession of the device by its own proprietary mechanism for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache those binding statements for further performance optimization. +- RP can combine the request for a DBSC(E) startsession as a part of the IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the response for the sign-in flow and append the new JWT proof (which is generated by the local key helper) on navigation to the RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) From 04a65c28ccf5ffd37346d1476908b829b0ed8bd1 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Wed, 18 Sep 2024 15:25:25 -0700 Subject: [PATCH 44/47] Add missing image, address few comments. --- DBSCE/Overview.md | 26 ++++++++++++++++---------- DBSCE/images/keyhelper-reg.png | Bin 0 -> 30995 bytes 2 files changed, 16 insertions(+), 10 deletions(-) create mode 100644 DBSCE/images/keyhelper-reg.png diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 750c283..3df649b 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -6,15 +6,15 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' ## Authors - [Sameera Gajjarapu](sameera.gajjarapu@microsoft.com), Microsoft -- [Aleksander Tokarev](alextok@microsoft.com), Microsoft +- [Aleksandr Tokarev](alextok@microsoft.com), Microsoft ## Contributors - [Olga Dalton](), Microsoft - [Kristian Monsen](), Google - [Phil Leblanc](), Google -- [Sebastian](), Google - [Arnar Birgisson](), Google +- [Sebastian](), Google - [Pamela Dingle](), Microsoft - [Paul Garner](), Microsoft - [Erik Anderson](), Microsoft @@ -61,7 +61,7 @@ Device Bound Session Credentials for Enterprise - DBSC(E), is an enhancement to ## Why DBSC(E)? -While the original DBSC proposal enables browsers to bind session cookies to a device providing protection from network based attacks, it still remains vulnerable to "on device" malware. Temporary malware on the device can inject its own binding keys when the DBSC session is established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a new signin operation, and potentially hijack all subsequent sessions. +While the original DBSC proposal enables browsers to bind session cookies to a device providing protection from network based attacks, it still remains vulnerable to "on device" malware. Temporary malware on the device can inject its own binding keys when the DBSC session is being established during any signin operaton. If a DBSC session is already established when the malware gains access to the system, the malware can force a new signin operation, and potentially hijack all subsequent sessions. DBSC(E) aims to mitigate this risk by introducing the concept of `one-time protected` [device registration](#device-registration) operation and binds all the future sessions to binding keys that can be cryptographically proven to be on the same device. DBSC(E) is able to provide this risk mitigation if the device registration is a `protected` operation, meaning it is performed in a ["clean room"](#device-registration-client)) enviroment e.g. an organization registering a device before giving a device to an employee. As device registration is expected to be a `one-time` operation, the user will not be required to perform this operation again, reducing opportunities for malware to compromise a user session. @@ -146,7 +146,7 @@ Note: Above are platform specifications for Local Key Helpers that can be used f ### Attestation Service -Attestation service is responsible for providing the attestation statement for the binding key. DBSC(E) relies on the attestation service to enable the IDP to validate the binding statement and ensure that the binding key and the device key belong to the same device. An attestation service can be part of the IdP, or a separate service. +Attestation service is responsible for providing the attestation statement for the binding key. DBSC(E) relies on the attestation service to enable the IDP to validate the binding statement and ensure that the binding key and the attestation key belong to the same device. An attestation service can be part of the IdP, or a separate service. This document does not define the implementation details of the Attestation Service. It defines the artifacts which are generated during the [Device Registration](#device-registration-client) and are necessary to validate the binding statement. @@ -163,7 +163,7 @@ An _attestation key_ is generated during the device registration process and has In addition, the _attestation key_ can be uploaded only once to the backend at the moment of device registration, in the clean room, and is seldom changed unless the device loses it. -The _attestation key_, hence, can be used to attest that the [binding key](#binding-key) belongs to the same device as the _attestation key_, by signing the public part of the _binding key_ (with the _attestation key_) and generating an _attestation statement_. Depending on the specific implementation, this _attestation statement_ itself can be a _binding statement_, or it can be sent to an [attestation service](#attestation-service) to produce the final _binding statement_. +The _attestation key_, hence, can be used to attest that the [binding key](#binding-key) belongs to the same device as the _attestation key_ by signing the public part of the _binding key_ (with the _attestation key_) if it finds a corresponding private key in the same secure enclave, and generating an _attestation statement_. Depending on the specific implementation, this _attestation statement_ itself can be a _binding statement_, or it can be sent to an [attestation service](#attestation-service) to produce the final _binding statement_. Note: _Attestation Key_ is also referred as _AIK_ in the document in some of the flow diagrams below. @@ -175,7 +175,12 @@ This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC pr ##### Binding Statement -Additional to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the device key. Details on how this statement is issued are out of scope for this document. However, the validation of the binding statement is a key building block of the DBSC(E) protocol. The validation of the _binding statement_ authenticates the device by using device ID to find the corresponding _attestation key_. The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. +Additional to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the attestation key. Details on how this statement is issued and its format is specific to each local key helper. + +- For a _public local key helper_, the _binding statement_ is usually signed by an asymmetric key from the attestation service, and should not include any device identifying information, like device id etc. The validation of the _binding statement_ is a simple signature validation of public service. +- For a _private local key helper_, The _binding statement_ is usually signed by the _attestation key_. The validation of the _binding statement_ authenticates the device to find the deviceId, and by using deviceId to find the corresponding _attestation key_. + +The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. Binding statements can be long-lived or short-lived. - If an IdP performs fresh device authentication outside of DBSC(E) integration at the time of _binding key_ validation, then the _binding statement_ can be long lived, as the IdP ensures the device identity through other mechanisms. @@ -196,6 +201,8 @@ Since we want to integrate DBSC(E) with the original design and make it as widel DBSC(E) (in contrast with DBSC): +Note: In this case, IDP is same as RP, calls a Public Local Key Helper. + ![DBSC(E) Highlevel Design](<./DBSC(E).svg>) [Link to editable diagram](https://sequencediagram.org/index.html#initialData=FABwhgTgLglgxjcA7KACARAHjgewDY4QBcAxAEZ4CuApgHwCCUU1AzlGLDkqgMrUQA3eNXSowLVC1CRYCZGiy4CxclToAZHHDB4A0tQCeACWp4Q-VAAoAStRB4wcVqgAqABQCyASlHjUUaWh4RDAUDAAhCBwAdxZ+XwkyQNkQsPQ+QX4AHSRsfEJSChpaazcAegBJABE3BNRo4GAwSiguSgBbMgsARmAyAFpaaKJUPOVCtVpUSjiIVBgkGFgOZ0wypUIplhgAcyR+hdQAMwJo0Y2VIrp57igAC2pUMijYizWLqeBowbIRsYLVMUAMwABgATDk+HB+nwWNsuP0AOLUJD8Fb6AwjHKlACqEDwABpUNU3HjCag4HcdHgUTtqABeJBcJxE6gADygEDAbkgYHaLAAdEKcpDqNDYfD9iYzPwKgATdQwNhYpAAbWl5gg8u6RI1srlYKJQoAurrTJqAMKOB4uGDtajAJnMVA4AQWX7-S6TZ4xWY3AQ4ADWzgI2jwqGDBlQDxlcxyrVQIAg1H6dNRXOdkYkT3E1DlLu4VXCPAtlgAol5o9QwHL+CwRbkLhNinBKBBkyg9Vq5fSctQBDpKCtE-h4FGjoRUDlLBk3RAAN4kslE3H4gC+RPV5v1OtQXflYKFAuNXj6gygI2TAEcaGwKcnh5HwDA4438l7ipZZnOyYuasvUFXPANwpKk8BpJA6VZDkuR5Ll+QAfi8HJE2TVA0zRZgJEjMQkHzDgsPYTgkGAKBzz+JtAToDCM2oDFLFPJ1HldCwL1QAAxScyxQfgkyVagiXuJUKWpeoYHAp5HnsDgJwgdocjIXN8wAMnQlFMOcWshCcMQmFYIiYC4UjBhYCj32baj1No8IFjlBYdh4IjqHtFBpxASgKHgDEiXoCpdCJSlqVpahTxYcjznMqjaBsvD7MclYXKgHJ50C8DgsEu4OjIPiUEsdzPLgDEvGgzkwAtBw7RYNdjNoX5UGTKA224fK8HgCNDAi8YossDF5UrZSck9CzotsuKnMS5LUogqD-EyzocqgPKPNawrDGK1B2VK8qwEqhChWqpiXTnJ4zK6q5aCtSlHnuR4cNkyR+DnM8hlOgFzs0GtJF2fYFlFcVWElfoMVM1BerlAkchiuzIN4caUSSpAUrA6aBNmrKFqWgqipKrltsqo9qu+F7OreyYB1auVh22PYODbZjbgeKckDIUaYbYBL4dw-MpuCnI2EIa65uyiAFigIkwa+H4RjBEEQXqMpqdROUDm4XAeJQIlkxYEAuDiG44CoWsJAeGtWJwSR2GgB7WzQuI4UMpABVQJmTFN4gMHSMUYQBh3+lsHYlVK4iRjtyUAH0YFrFAYCOGB+HpI8AuR4KE6FdB0Aht8zsmMGce5Xl+Xed9aGnHnIMea9KBfPNjknPiB0zDqkxwHAjhdNudbhH2uEYnBnRYuY6p9V45gWJYYBWCRQ4dp5WZ2BSlILKs3dQ1gUScR0++Y466rgB9nQAKQAdRceWy7pZ6L0r-Svr2VBj9Ppmhu68-UdzjaYPz+CWD2oVTzI2ql5qCNQgNwB+t8kC02TM9YYqA3AAHkeCnwVmKOm08uAK0tlAdB3AGzp3nOgHQOx0BEEThgKABgQAkPQA-DOqACbzkTugSM1DMAtXgGHSMtB0BrnTqgTe-djqwP5mhdhcB2oGFZOzTyLA7gPXtlwQalFzrk0jsOG698T5KMiionQajnT3A4BbAW+Z7joxFmEJUOR2gcCuqY82GixESJuLNCu1Abz6QFJLQBqAZZy2iOsFugY45c3kZKYkVQFI4DlFGBYBtKBG0kLgcw7cKRBLjhISwhBdiHAANSJg4HcZCSAcgm1rO7dOfAyIWnSdQEYzR7hh1wEGOO6cokxJGPg9AOCI5R1gLHeIpD9rp2APSekPAcD2n8HaKS4g7ZHjGQI7e7oRgzAsAbeAgYJCtSQIGWucxwD3FQArSZYouDMBQM9XeDw4B7Jji6EWAckC5MOXIyu1dEg4EoHhNJLSHQ6DQGQL5PzmnBMeE6eq7iq7JjlDAkYiIyzIJYKctWFyAhEzqn4s+5z4bAFMHrIF3zua1MhTeausKBg+Kurc+Ybd3kwt+WCiQ7JA5NDwGgelNdQUhKTGvMIoR8wQvZCAclcLUAIqRSinFlyMXS1lti9WAR8VuLJQy7ljx2hKm2DDScwrRWHQHidUlt40C1iOPwBl0Q7jiUeNER4dI0DqsFEKMVErjlxBtmvBRSAyjJiOFrORpTqzlM6Z7f63r+jyhGKqHBETjQjNlQAFhBN0BsrsQ0eyhN7CNFpk7lxDt3JAvT4YxzjhAVOAok5BXLhWtpWdSbFHQJtWCBcWAkOwDMVo7QhS0F4aIJZR0Vn3mrIfE+Z880X0pVfKFN9FaaJcNo7On5X7i0MPKPOcE+Q-yPP-KWkKQFgLHYrKBDpKWwLdSgz1ODfXUH9awQNSAyn8FDVmiUvtbDa11nU1AqoH7xvQAOw1sDVGU2dM3VuqTO52wdt434WKAnqtCbG6o7TYlIHiYklgyTmJtydVYbJTzUD5NecUoNbsX3AP6DUv59SWh3CabUutQKOkewIT0yOJaBkQBIQTEZBqd4Fs9WEme+kwAyIeODSFLAOjUByARhYOhjX6VdYi91UrFWwblf4k5UzUW4pRLCgzQA) @@ -262,10 +269,10 @@ In DBSC(E), the use of private local key helper for specific IDPs enables the be - An IDP can specify its preferred ordered list of `HelperId`s in any response, and can request the browser to cache its preference for a specific duration (`HelperCacheTime`). The IDP which is capable of DBSC(E) can specify its `HelperIdList` in any communication(request/response) within the browser context. - The caching of `HelperId` is more beneficial for private local key helper for two reasons: - - Since the IDP is associated mostly with the same local key helper, it us unlikely to change often. + - Since the IDP is associated mostly with the same local key helper, it is unlikely to change often. - `long lived` binding statements are possible with private key local helper (more below), eliminating the need for an additional redirect to fetch the IDP nonce for the binding statement. -- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of possession of the device by its own proprietary mechanism for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache those binding statements for further performance optimization. -- RP can combine the request for a DBSC(E) startsession as a part of the IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the response for the sign-in flow and append the new JWT proof (which is generated by the local key helper) on navigation to the RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session. +- The IDP and the private local key helper can also leverage `long lived` binding statements. If the IdP can establish the proof of possession of the device by its own proprietary mechanism for a given request, then it can accept binding statements without requiring fresh `nonce` challenge for those. Once the device authentication is complete, the IDP can use the long lived binding statements for binding proof. Browser can cache those binding statements for further performance optimization with an optional signal from the local key helper. +- RP can combine the request for a DBSC(E) startsession as a part of the IDP redirection during sign-in. If the key generation and sign in are successful, the browser must intercept the response for the sign-in flow and append the new JWT proof (which is generated by the local key helper) on navigation to the RP. This allows the RP to avoid an additional round trip to initiate the DBSC(E) session, based on the URL (and optionally KeyId). ![IDPCallsPrivateLocalKeyHelper](./IDPCallsPrivateLocalKeyHelper.svg) @@ -280,4 +287,3 @@ The cleanup can occur: - When cookies are expired. - On demand, when the user decides to clear browser cookies. -- Automatically, when a key hasn't been used for a long time (N days) to keep the OS healthy. diff --git a/DBSCE/images/keyhelper-reg.png b/DBSCE/images/keyhelper-reg.png new file mode 100644 index 0000000000000000000000000000000000000000..e15e8003ef0ec0286f00d0a8cff730c0f9ff7f94 GIT binary patch literal 30995 zcmbTd2UJsQw>BELiUrV(bP!QN5NSdJkuEBofYLjdKtc;eiWC7Akxhw8C!zOF3?+0> zAVDCZ_bMR0NiPw&!M(rleCNOCj(g9|7z|h;dDr_svp;jLkf&NI^p`m<0{{SeHPt6N z0Khq00N{++MH=cmH-XW))L&=ZbW|PziaV|^QZLRS6d{TL0PZ90ujl8f*Oy#Wjoko% zD@~_AXIh+dtpNb9T(u{PdR`W*N4}rT^~cvyo{bV`Hq;M-v$Awd?&{CW85mQ%d#0}K z!eT0VbS#*q2W&ngyyryR*&9E^_D=lRJd{~H(qlH zI)Bp4Os92wr@0n~U?=!r%IGj$IeY#08oId7KN$0p%N+*okBAU1IO#zZVL0=iWR8}; z<8f{V6PUZ}TWA9Rs-C;zho^jdVWr{FhS%MFPgj~a|MUANzdBF)KA8JX)1F+4vuUfu zIz5-n%TF*2z9;#z&oz|uYOVwU676}f`fiGqM~~U3I7*Nd3&Hu9cD0R*8($Gm#Eu){=p;E5C3Pe&sJDPmNW_S;irpSL_<@!M)H#1ym?c3 z>CfEx`OY6ZCnnL>t?x>ZkllU~y0g%5Q$p|~LGuTTHCNiun6x6UD*eguTX_R;cN-_2 ztz&4yy_vj)+t<_5$3(y3?(WjEdc;Dx8>vg*dIt^li?t0lk+dbbw??ypPGGs&ZD-YL zp4oI&5{7CfcAR#$xAk@sPWIN9SQ;{(<+0(aB)XmbDK%q>tL)I#;fk6U*> zI#cYLJn5Me1oQ8icC{?=nRo}Di7^~|%C4=%I(?CO)?X@Ce}z>T^NJvE`}<%hWn3rQ zOp&XEttPx}=ty-gyj3&IV;RghxZ6+naiyNCdNaSu`z*g?1%ovWiV)HtbeSGw(6-D( z;`At+9Do$6sZ)29l9WNidvd@sNVpaHmXJuX76FDYugo1 zs*JxM$R}CB0=h*5c|Kvg$qZ)g8e#?;64Mvna(dve_zt;ckJveb`@$5LfC*6}Y#!%wk1m;s9wEA6hO--n2w0t2=Q< zh*o$SSFv;P36@shPe$K0mKlXIO(Zz_4-77?9G9ll)OI{*9SO3BcQLh)rfvL4iLFZz zw6Pu-d{SuO?6GU6CS>U^ez!jUV+FDTy7h1-tFl#`MTvDh*DVGOj6!x*TK)y2YKaiW zj3BRf3g&o5JbSMy?$}l+)NhyV>dvblJluIej!^qMf!SW%rVA`K#K&;;cQo(VMW*W5 znc-eT<>h2LG^tR414KARlUDAR^7@K6M3uEC_mUU_kgJhmM}9`hzLY-Yz}I(x^r=lV-xJR4kv|=F;5F(gD0vlhBa~AJ_RM_>C2g8yMcv{1qINp!cC@2DIyQ8c1Z_wK55G#50gkK22}}LLxb(f}IE6$BP^Dv;7huS^p*v>Q^L0 z!NdepW%myDu|E}u<E;Q3+?6nhRv2d_Gml zq*tM6@hGZ=RvY3v`C!l5X&_pL6Db%FgvsDaZxDL(C2Q+BJ^Eo)o8mAPR!%LXx zIdpBK^-$cFaq&EF6r*C8QHf7cbR2@T?ZR5(#R&-8vY}t%XNlHZts^!_*ikiPgYe1> zcRZ6f6mMJ01U9BB_ifHo%dgzfTVcI>sxZ7swV{3wuP`qMj%3CC`G_lHsG)mJe`P)( zM?i9Y?deLXI(tles@;@4{!fv7s^Q#sk!4m4nBYI2xeu+kz}3$b4OQC8GJ%b#8+!EH z6;*8Ltg!N9ya@6a%kzzDe9ql8sB!6H!WnPYuY#ta)-YzX8q!7xDG0_*YC)MN-7?5(=3Fh(DUh_=s7Be?8Bh2@^mAiK3u5igo=UCfDtq2h4RO)88D$x5mJjH z4i`$53D@ntc86Lf3gIt43*1#z6w|Uoawtm5JJin$NrhHd2{*5JF|Ac^1<|kfY{fhK zEwocyEYwdjUKRCGvDf~@sK$UfELd7+gFyKfO5iAf&ZOe*I>F1RqB?kBn@&_jMpI@b zsQBqTVZ;svXHfOwRG$3QxLn91z=FsZ*fpcN<4d7OB+R`~Iqe+5-Rq20dA$qK8B2Ag z#ZiOH=oJD{i7RhEy}ksE+WcyG#)<+j1=L!DV9vJ9Wa%iaB=)T~t@$=i!93ZDDeG{?AS%uJz zXDavVy+m`2es$kvVJz3!;cM{{tiH>whG10|V_gETqnG!@FUGyk`DqN7E#%V2mLb5ZIss&=n90`hyK;yQ1EZiQ2(_wqvf-Jse zp#-Iww9340CneT-p1UjvUcz+hmHw}|i-9z=%#_a(2cdrZ*HKV08717o?RQVXg1e=k z8JQB6^>kON_zZBJEHimTM3-jS*jtyjd%Ln3&xGcfp1yiESq&9ap~3@VA&|pE^xWS} zJi)Ok5f0M?(sLKZO`dn9VxZjkr!vfx*W+4*xldGUx%H0t7?&cIls#1Ym~fby4owjz z>Lxw!stlTn)?e{%yUW6<&kSZHYU9LUp*yQ01o{sl2JUGVPYW%nFz23SmM|dd#)Iza zuQajP$3badd)|`_4$*Vex|l|dw391O9K`1tKXB<5UJVu49fr#GZ)I>F-F0Fsd+c;( z$RkvantVbtp1ATn|HZ^viiV0+tGGtN?g`q{q;@>()3gg-qWZ}dR-Pp-g1mJa)v+`k zTi=ze2pQD4nD*h>%H+b2ySu=GQ}8*|aGe}8Y027tOS*qhQ~lG|>(&g!#x&vh+TWJ| z0AJt_I*xx`#LM2NRu6x__}Ksb{%f`D^MUY(G08V}&SA=3j5sWEjpa(MXLn7LuUE2$8WoF^CV}Xxa4F-d#SePN=U>7Xq{OBf}#?!(yMiHc?tL zldu7Tn#6sWcLP6V=bv+Z1JVTY35k}ek-{Bo$VQNGzOY5BL}OZ3E5K`~3`< z5iR08JFqGo6Op2jf@HK)$gYy`M>&rD+G0&^`iwxAclAGb;f76d%Mx!_(3Q;g6aFyu zm;cpF*kFsu;|zpIw8}gKeq-=#xhHb+#%X;;eLYR>V+SoZN|$^qs=<%8v9ZWHTkfa`M7aHLjEhW=Ge=E{4 z`*FDZh(T>yBsr*e(=1brLJR1--N}fV?+j-f#M_f9Jv};~y{GAnPtcgS*jD2C zVpt}kDh_PR5pXqgSPLeh$RX=yG~sdsGM8Md#RmF&{rkA^2E{0|kMmMD$V9AgX0K8} z#zFI891oCnv(xap=<%-*c5%Um@;n{(WtRIHUx6mOnj$iMwy?d@d-?HdKf+3?49Ovh zU!Psi*e4OH=O)j#I&^3HTZh8nO!LeMDp8U=@fv^M3b1PRtKtEB>+OolqD-O1KdL#} z^Qz;o;Mbe4UeYqTV|-JsWevhuK(BNe;6jZIaSK*=grfa z=67N9Cx-V94f)O43x8jozTd^0hd9`r_1Pe>?)=*7Qi9A*dFU6J* zT)iQT{QvQ-a|QG5md7uq`-bTM!3v-$E5}W(HpTwSFGM6SV;gP+{$l_Dt80q~>nBGI zu&#f9<#ubz@QvYAb^}Z2k3K%NJ`}T7JsYa~2&FhP2(If}jt2(K5+sj3@{B+Qv=%)4 zf;V!vb1T@~Q>Q7-wxFvYcj$?^VM+HlDK=aADNPq)^FKRBze~NR_>2$j;HGEbAk51Q z@1R-Fq&h5W&cKm7d{&SBB8=%<-CB?&WHRc|wNT!h>+&pmv)A(|r%K9sqvAcMGsc1G zIE*V-QzIFCf*m?!fgyyU9tLyCMQbW=VrusL@scTU1yOMtkSMywL1rvxc-Vu-#7;LD z_1sNl7x%&!Vo;retiNkj>5R{=!m+T-Nn#>eV%~T=$vf58(U#uMQj8kc2wJA6FVRW zM>A)=3TyRdkT41+*0YzpFKd`0POSQ1f8&g{S&?pb&HAh{ZCTZtFMreA%QO}zr(5`h z7Ns>~7AJplIr(r{f{OpcJ+TtS85YsHwWa{4?uE9)^n#%fqVV+$+P%4<=}M>7iTegd z$<9$=OO9=Aiv|}(XTB$;Qef}w=8G4XbsqB|E|zWj8z)SJ-t*Y975C(_8=Y7vHA=Gl z7VJUa;sHwf7w#RyW1;JAI6ptq!k)5t#do>Fj&`wW-)r1C%4rkRL5!bqImWe^$FMoW zao>rBBhB#O75p^IHhxIkY188d(8r!nOL;(2Set~JkUtpZiw}9aJSajlm*v*+5enhcAk@;IEs%FdcIlP>D}m2Pw0LsX>qh1QL9pQbH=JGx{;Vv+%|(n{X7nDOl^Im zc$Ny;IQb$Cq=#nL~LsVQ=cNm$X6>m;61iqI&O53LSsBySmrf( z5y)U-2UaeTnt!iGAHGd-(>V4PGQC4NcHA2?Nw>u_tp%@luXu0F7wp)*b3lY0FpNs1 zb`QZqhOebvdR8;>qB96%anFq}BSN4j)c7AP(o$@yEBEf6U^KH8XNX+gUSCsB{nB6E zrBFgBkp|+FHvBphB22Ew8+n91Fa-?XmdY(vvL3+W;|rZl4Gqm-!uNK|C7t@WzmfSH zRPh886N83tMcn*6LVJULxbwal$5#?`d+M3bW+^7VUsw7mR8(t8*rlfrkN7q+GU!4Q z@)t9Ra#czEtw>X{_OqzcL=FPooH1eKy{l|dEkAur>)nB1zrewg>Ycl_l9<|JHB&=Y zcvt1&HvXw0fslaQXiT|4g{aVFotVVs7}th)YrWd&&_v8bCa6=GMtEIIC7Fvf{gtzh zN{Zy{6a?ME8tomMpvJ@MCq6+l@Y8A&DY^c9To>P8MGWva0Y(?bAV9z)-g<7l~>!=T}V%mlx5?6_OHcqjYbTVWYb&3MW-n zq$^<(a$e>=((M3rtlvrHJOuT=>)p>m+VQ>h6?uAQUEo+et3gX*LCZ(yXOls_;}nMQ zqh?u%_TgdGAUi8VZxcat-d=3gn8(fM)$`5T0jGh+n*}*)Cv9UEd$r7l_>!Qi%0Uv| z?O+hGHuJGSyl$6cm*h8wvO|gpH4CtTst$}2Z#Lb@O(?f|6K3g4G@%QqOHE%aE+WL2 zr^XYkk@jxXf4S+LH23G&`s^I}nPKlF)pkeL`rC0koS0k_Ez+>$-y5l$v&hL8n4#!n z%`Lgznq7a5%@up;Ki)Hoc4}%Pk`?|!6s*3Sw{J@R~ksns2>p6dLF=f)S;>Z`v&)|$?H zbm2v`JdyAA$V*fg(V{Uk&ob0s9bSea<1D7U?2PMLbyiX=EBQ?kLX7E)%XUo3w=$-D zr&tovi@<5h?6-1UJ;b6RyKiI;e_nrv6)M5`ve}!}a`dV3bq7X&g`infanpmZ6#c!r z=b6~j@}hu&+h2Wkz*=1jw-R;LS9jb!(0H$ zPKt|%^Z1Lyzs4T8;8)tKg-ONW*MI>uKC^tN?u;gKQ|jRuNtyl@L_7*JfXJgnxo7;l0+dV zo-S*#&g5xPd&@V{r|m>^=#2p3_{VS88Oh-|X`ta-uVE<(C#?fF_}HHM*Uzn-pvOx! zKbgp3PFeZo3O7E$+&s4AccSeibor{VwuA!0LG~PJB}i$DNRZiK(tiPmNUzVV`L-`* z&l52djYd@U0Z91xANHoicBY2(&9lT+1tCf)Q1b%U%O0(-E^}8$-Q3xTDjA!W9w7b| z9%p^{WLk;hJJ#4U7bUL?0rw>THJ88IQM;>xKR*{zqw5&n!ZzyR z-z$egE`8F=1;=?a_VrIK!E5F_%ZqH3GTC|S+XzWXVaq0l^b8d@clh2BaxDxg=aR04 zA{)h4CpXoTe$IwGoA%ABtPk0kc8)S~N{c6KdK^?89DYB10!_3YmcFIPS%WGoAZjf= z0=9G)`iXgt*G;uWBEG3Zk=G@)a7n^*r3eQD!&h}tjx3YK&lD^pt;ELC7oq6c)QT&Fr&3Ff7lv<#)zU7?NXn-}|nf1rkaib49NpEkzwW1vYoiA8}Z) zjt1>-cBQJ35?ACfS?Bcw`G5{3aDOehyB<9{ldn=6i|8yFpy>Yy#y~ z92=7KEgE!jE``cRK;`^S+rHwjz7f823=>#h&(F5G_m(G@uA@E|fq7pb>fi0~phnwj zVO#e;bT3Gi>=Slz@d5|yC|L=&yqLYrg9qI{%j*^`XTVw#_!#}ep24b-fgQ5V*K=5h z&CcN^b6@AiALPVW<`KW1e>EQc)_D<(-DL;iBn1{NpTEHR#YRl$q7ugR>FEZg#|O%K z>fTS}whj&!GxDTaWoDj3u1NNXDAY@+&Br_1*pJlzS+gde)x8yjjP#C?wADF#NBQ{k z_f*Rl>o~Ry3ELO5c>R{?kq2p)7|cwSLsAgeT6VNa!BDecn?R$vPL{nosHHih3Tf>A z+s*f4oFsufjf&fMh93*>d>lvg#qpzsd$aAp7{)zqW@GHKiRNQ`! zH7wW^SD1umH4ZR*`7D+ps$W9fHrrvh(74?3MiVNEjo&}fSG2^{tT5Gi$K!YKe|-i1 zqhXq<{g+Ev&WPpUr6os(VVCD4EAl8^bJ@9RCYG|!;P7Mxx zIN`=SsSCGww+a)Jo7yA3PEaW~mtJ3T6hNJPaP>3YBh zJEB`Z*DpSjU)2qd7-wC+Tse>BVo5AV9fg0E23y4Hz>dcLkd`nYJ^6MRH0bo9G^c9t zZshqW2k!Rhyytw7k{#kCKg{rIS@|*5@W{i$D`cTO0`0QHAi3g!4YGu?T@~e9@i3fS z2Hul78i*hL-0RAoHATDo$H(N4~%z7 z)YxvE=Dv*YX7Pw@#CH1IC5K{K6}%s4bFZ7eO86D9P5bQUo$9 zU`3wC!l~2m`Q~83uVu>>gxlw)w^52IPbbU-oLt*9qh6VB32RNoM^xLxH9e8!;sJrR zBQjphd||0kSPPF5NYEu);i~(Fa#1nkgT;mxepK$V#MUv9mX*&m40PR5=JE*t%#hz> z#yhn)$SgUe&vq;_l`W^4-fO;a$1b*hLXlzRP)C2&)yDqI6)p}3@^xBQziYx~S(f}a zl5>9!z7guZCA`NK>IP{GgCT~Xk_y3xk~>>;qr5Zx*x>&2Gt#rDbmfh(@IU!q2`9e5 z>M95Bwa;Nvbk&7`^0#VTdoF5>n!({5TXRmPedISoSSI8?+fiv8}#>iT~m ztfNwq8%oZH$<6aR85?F{b73~+Lqo$2dNp94G}Ruk-8_{4eK6LgZ`#ECr>2&7Q?n*h zLR^fsE61;Jmvz(CPv1W$nX1mw#X-%H4(j%1r$%5 zrCVG$A^m1*C7M01OIQAIGKfpCl=ej4GG_Dj3B(D%FVJX5*66IF9p7;5YIH`ap%O9+ zUlz|9kfXaYbHPGFrq(9TUdI{_oJX~y@nxR9g5?zVD+fjbK`*#V55wv453(){XTx%a zh1EW@9CETWDbyJHbh&hOOkkHvZG!13^Xl~qjR-fajmTrFCn2>tGt%N|P+qDo<(8Qu z@Gf4r%?qm?C3_X{FKE}ufTKTnGR_C`i5;!{IcXuYWuxJf#Mwfi9WjJ~LC>HbIeL>R z`?tRO3-DcC-8pn;6C+cAtPkG;j>E}h|*;HT`p_dWjgwMG|EkxI7dcjp}5 zLbaU5pnI%Mb-8AwcF#Q^h9Mu2i)k|50ZZaL7dnhwahLQ2AC3cBYi0+k~b^v7#%K8X6wA@D^ew{Qns zrxFUO%ed7iQv;b*MTkyK0Y_65QV}O?uqytvnvlAI)%O_vKK3o8END(WXi+#$^IfkqtQhzF-9P__FR`NXCE9BXkEx%=ED=~O z`>5nee)a17-jmUPI2C1V{%LjCbrA@I(x9@Szj?+lLyO+q-75Tq)B_^8ehS+rHhgpj zkbOBVPe+-Ch92O~((=S1+Al$3#KoxuPAcc~Gn3;#kN@~$ zEjCMs(dv9HRloOAx_U|2$Btkp-Qz6%IGEDe7om`dol)^TGynjSv~BaFBTfs|@r$(k zYw!110eoQsh%R?&l@l+Ej(Djtg~u1-$bD(Eh~=()TK8$AYTGk_1@}j~S>be4fEJXE zzPtq2HURD$Yf1%X_X2G{6yApsL63tE5li1oO1C?05Hd*_XEiLbtlYkVy_`EA?>P6+ zYD}!S7bgd7o7LU_smL{6KBOWbo~o|>(If1O$AdkyFB^JXV1_AVL? zkkV#j#oS`AV8lwdJ)}QxU*}o~D6p{b3o6@->sj+nT#NM_yM;W#mF*bV?ZcDUs#{eA zpfnJ2H2d1JzP59U@_hFX7yuCd9&xLAsR_sHOo@?z0hBeOvy zc2{A+!p0E4e#UO^54#p*&n~z6XgxoD=gVrfkxgN{Z)As`9Nbx|-DUzXyj2(A%fiL~ zSv0L*Na&iiYK;PeqRl&yp*=yn^`o8}?UBYeSF3eLyo14Te_muw|619$0o@ zV&{@vwy4gXsp=L8Prc?CkWZHxR1eAO;dDe@9^Gg2i?R21UYMZU%c~g4nKt2kPAa4W zRL6Ab3GiejDsH`-gQR5Jxfw2b6(_}X8ccRw+Q6{`_@dz4sVTK{?n%;e6gvIh!W!`6 zki)NS%w>?}O}V_~4p~Ufx%JhCV`!koRNeX4u2yaApePR-6dEXu2I<4*M4U;#`Z$4; zad?c_7MEQ+N^3IueQ_KOHdfO74)Rxi*;JUkYDDd=Uav6Sp^oCmy?3~I3a}i~XW@N6 zQ1K>%p&xa_F9F6iPet);A{AXUF>yoR;Koa&pV+CsUo7%_?XNSK>>t76B+WOlrW+PP zj|nSxX%am4E2s2&w8gZ$Zx3x`DkVY{0Iz+h3IarzS@-Y~Nu60-6*5OpMvl+gEemUH zIS@&3XA)gUjHEwgy{bW1VR3z(JvXjdItZ0(Vzs0*?-sqM7s^a?Tt_savi z$nUb%+1X)Ywuc5HeJjI$BRa@1s-+~Ip@F;vN(T~gJMv^HSn}b=8@jMC8mc8K!%yLf zQG^ZA?j%h9;uEu52?{HjK}^I8Bm#lf>_D(;AU-K?8if|j+_C(We3V$W2JEqvUkqfj zgNF0M)!{>Q1z4~H`0``ETa}#zIy>>JfCcGOV+$8!2R-Ho-FL2r@6lK79=xdWYwU+4 z%t3xEdFFl@LrV(hCDd$I;#tvMCR@Y2jJ*dU;06^KV&1 zD@G*&VeG(G&+L^%^s=5DBHNy1W&wl`_-mSMJ*R3jBdoauQL?HPf{QHY47wHd=ftRo zqo6MCD!?6h>H~;I^cY5Z?BkNnnR+q^vTUAv%k6n`e9mHTcE2Y2M}2xs2m|A;#0N}VU9XJh1 z4x&rs$M)aZbDX=LaLKBW27>yGET!WpaRA)3p$d~LfChy`h{NFfM34jDXh(D+aEsZl zDXwQ#b6LdgFuH7arU&y;wLpPa4%l)*poheUD`a1<-80a$i&vacFKK$0F&cAukAT#2 zbp7MO;%{$2bm|&fm4&1r*u~H8%*tyJ@h?RRIY4g~dsgJ*TCEz25A~_7pUY#va@S0HS_}Ffn-=6pxs-&?rIN#_Zq=72ffjTVYXb z!lf!H)V|M!(G&o{B$K-RM1HpoS@Nof0+t5&m^hM{KRjFoY^5f#(E@#6--%JpdQIEV z20b}pZ7jwr+V|eDN7%uwqf+%HKa%!{178{sa48X=J{!itx!USZUt zOR!2{G)?4tM|Ewz_7{!^kP!9G3@MN50?MGEM;7}Fd0@8BU6&U(f5v8x+eLT+TsEoq z$FxdQ9nN=ao>Q6KMNoSq?vgeN4+pPY*gem{c!4jaWL*^S#R&a^>P7*YbpI7iv*aK0 zni#l`A@Dyw{qN)d zk4b>lhxMbR55+!V7ACHk58DYHT~o(Ej~`d(m-i!*>X`u#=NU2gY^q zPpHYF+mX7sO^4wTB*lx7yV8!)(v>ShM{dKzTJsBEdIpyXEfe3jm5*Sp3EPd4V40+X zd2TsFQMy-8RbC43J`1JG)j87j&$ig1r{rfFDNK4+YS;1XIAqZS5<$P+Ked6_h5Gz@ z-N`H9j8#ee3mQlc%orFPYf2;;OWP7jJ%fv1dfePoPl|lJcbI!7EY)k)U8_w;T!YJw zT6zXdv!)U}pbLD|q`<1|0ky@{-#eNU;TQdi8n3$l{C_|pS73Od8h4C;a<~k& zI|*FV_q3th_~a@2$#aYkd6HJP>f7`4RZc>t@MPrsv057J#jpRu0Kvj&zb z{qa@poIr&gB55zH2u^yXGV&s$7o3&0ob|OJ3u36o*|225Z@H})`U4g9i-o^{Hav1n zN*qOp>9bxek``k}jf^7iAlK`6zqbJrnf`rqW^w4-W!02uXo8C-KkZWc zGMNjoAo<%7bhCjt!A{$TML24&gSVq@Zz4?XckRM2EY}_@;ZDQen z?Zo%nM;9r=W>ICcB_}!fU+X7V_W}>RdM4;N+S70SUGiwb`N*kgx|PQ#f1!cw!&1Ol zu_#AGTL-#ItKSWtPbAGsz~HMbnG)Q)ilHDe+sNu^ss}W(v+63VCFFT$hoeE(Jpgyn zQ@5c^9V!ezE8;H{20v|08X7F^hnyiN$U}OC7`q$>-rh1?+AlB$$%h41{A^wB=v$1jk;W8! z_R3j~{(f{4Cj+kBQ@D8i!$W#&TQ}cBlu})^NA70Nv6<90v>(=JaUYu|=YC{ek6K)= z-s%{Z7S?eRv()ez*y{5Dj_s9|Q&`8Vj&1Hdmi0)2R|bFwPAu2VEV&G|&9UrM7H#xZ zN8tyGhp=C3U9lPj7Aenq{Ak(IzyHYBSADQk_HmBE{8$E7R4(1{vSM%q4afDY59ZV}lv(D)mFy}W1YByD z)Anm3wvBYA>S*whQa#U#pXPLL{<9uGHsz5Vno=oHEM+pV{be|#|el( z{B6%R)KS)Ov7`rUEc`(wg=6?+%n}{P-j;*s`Xi*;*vE7==w2@fS&Rmg{j*JL7V~A- z4ka80qFq*|W#9LMWt=7eU-XD{7}|2HDARW%3Tw?z@_6S$gx#_9%a5+P!SQQXmXd3C zP3UXwk8bm>&f6(n1J^a|g$!<+;Bcq_6Q%Z2&n`aY`?i>#-1R7*O*M+#yhz1Fjz&j( z&T$4j-m7qB+8ZNNFzBaU7l~oNRPJSm20Ip$!mrmfC<{g!8IShSi8ak*n3Z_Gm7||I zL`~#ugoeSINFOvjWH}6|rOIB~uB4K{*>;OeRnAO}E>~!h;sgsn} z!?qmoUh61M=4{{`bUcau$(l#9+g!iN4Gym2l^%`a0sYdkhGCRSujeJ>$MlO4l$ z(T!Qf2B~9-;ZLFsC#^8)xs)SLgvz1$5~avFE2ZJMo#AEOy-F>gJ4eSw9P58sw6@87 zinH>H+n4$=OtT;m^PQDF+BW6)6C; z`OvUyzkMiST3P9-6i6&V_^>){3=1g1nxE5jY=;_D)9e6S|Jvr1cpk1Q+unr+M?O0T z&<%U5IJ4%Et;rJzr?wRLL1a?~>)!Bp?4qn9w#m<G!+Eo}>)g#%tX6(A&86}YP z)P{Yi8Lih8AJW9jb+bJ7mTs7#@MZcN?a5VeC5f%C;f%}9#BWi9Sx5|`@=(f;Lz6BNz&RfoG_uf6ZdN132?uR{iS}MP90G!f z$tNR04P7g=rCt-Y-{>&azROXVJDjW*kr=-IuO;{*P7n$fWMsB?*l*M1*zXr-ksjnh z)XLap_fOUjBu21{dH9))lA>`d?0a=?Lp7G8`Fveb)yF-)Wdfi-xklGcuxftr5xsTp z1}%j7D7HzyJ?mKwJ?;FDwk^lrqZ5x0EHujDJ2mc8K1G&ZcAMp{4H~`vP4F*5eTO`Y zwT6B(j^?8Q-;PXw3a_73nAP%dt#l>2vxACWxVP~5_|FQhTK@7}JvovY8+^G`rL^8t zue3fe5!~53p|swe96VVtel=-*TYlAN;b`RG`}vVARqPdK)42?4A}as8q_d^N&~t*9 z$_FhVdZbwI)qcZ2bhAB?a7dlv3{V$ut*lD2#Yy(+8!xsM-WPK$5kBL#v%e8j+_}9Z z8R)1Hjnu%%lMxIZeq)@1gncnxc-B3|T6;^*m%ELTqd9<7V2E{>9x9rK1|r6peMe{@ zZ|R7@$K~)jf6{(5X|Bl1p|`SBf6sy%B*;j)%aGWJCE<7Me2bnH0aeQ)WVwDnOQUhd z!9`LSi)|pq;#*z8d0oPs%j6wahcufGI#WLKBV_(=2pdR^0t8`Ca%m_!upCUD4ysOR zkDQ0h%SXaO*+49vxlYcY(r~zt6cW$|c;ML!ns3pe4KAE9_03K#=X2nWJfMe>?4H6&2ptn3>7# zLMMX6n#2C_QBAVPdap|XF%0=KpF?uO3r9jfZ_hN&rT0)yeLgHYn1AxgW{S;wX0`#d zAr4g-oS!Vzj#Z3`%{kUAT8o)FnL{NSDsKRNp#MQYDkHiazoCIBP4v&he%M;md;yk) zjsvJPcYaumhaD7j$UkT28R-W@3^Gw{nlW@GEHrbReyZx%WmR*QjKth4 z2io?y!9FA?x^+LIKXi<5Hj*M}&II&}E|nl3^^g*Dvza?e#BQ5rTgj@D<7fkLUxlGf ztdjSwNY+({8(%cV9t9GMwG9a=0x?;?_8f7Kiuii0is`7gD_ z5%D0jDO3KuygTmE1$_@@;{o&|r8Zx?cXMNZ+$9aEMD^|b_uJrMaDVp>Uofo!d zGB}osL#pfR^4)i6bk+_|5^!rB|7tAWx|>akzC^;X93G7tBX|))en>T8Up@h9+kbR> zQoJ<#Ppt0E|DuJJZMqzXQVlKTvW4T0oI?(-wS~t+z3n@$Yv^^Py4u9rM71YxsEeE3 zrh$0cy7V~3vOGb>{jBfycu$6TrqKbiB^7DNE@D79HSE)m5LFLT(yR2N_#~X*lj9F+ zXw;`Ima9vxuKjVAShpU_1zaxfY8L3@pHs)n3FkU&d!j>L_+Zzzvo-K_0;2=bY*Jf? zM~zi1SiIBAuvgC0bmP6DiZB8^(ujr3NKc1(y9j+BVw1sS*xdhOUFRH8eW&X?Zy-F# z6hx66_7f>3gsMzTGeKurC+jRko$JBiY_99IcVrn`=AwbNf57p_P>4V@i5t(pv@ z>F#s=?SAhe0~J=;m27dz-ag1z&ii_uF_)m^T;itD}1)Y|N|2>(ARyxYnU zPKTphkuh1Z_opo8QG;2H3#Y!Azt`k~bW_{6)H4ero2H3EoO9_xffIM_tgD;bRGxP| zXk687-C3zod5}V*-W{qqW4T?lX96c}9|~*PP#a*Y0859IlLGa;;=U4V3kGWId&E>K zkgu6)iE@z}CJzGnq}pv}+dbH6`!~BR@AiC2HE#HxjtPkrY^Z$d?>C}=fEu}uRk}(n ze*HoiygzJGt~2IH>$G(?De91Dj94nG9{l0p zBQzSxM9#$_H8%V;@{g8)_TsuZhj9rjqS95~Tt41k2nh@yUv|~4*)4yV&LpSa3j7yM z5l-cyu+cpW9jQ2qUHKLwlCl_~P-nh?7zWlI*Ty#&F7B{{raT2EoqU99vL9RxCQQ+B zycWqI-TLZ;jCORuET4=-iM>_a`cYT?vfZIxgcR=$)gxXBk7dC>I8T80@S;W5{POy9 zXxjfWO-z2Jqdk&#pqBZ?JtSEd#xB0dlHEn8&ieCUW9)TaRV2{uk1c}g$WY4piWh@? zh_0bJ0xfGzL^$T1@~l#0LsvA%?bhAAH_Mo6}%F(xW>4Ian5Tr8K&YBKQxzP_G z;ICz^W9&V-#SydV(S4^)w5Xw|Of;KJ-Wwe+Pgcr`*fvGulOomQ1awEVU^`=Sh9q;S zN*uV<%*!E8oz<;QJmq3wAR02(e@9U6=a;h~q(bl67()|-iBz%4jD5qz?EWhYMNW{* zs&sKy3A*lKy7tYyu5fbym~p8+-_yz+yW)a`xux6LnmeDSRz6uRw^+LVu^=8wgEAG@ z2bvhnb>_Gp4*vW!`9u4~sKIMhb1wMzz7&tGALTiQS98eJI`BG+tW)NDmDsO3akpSJ zZHqbkgZ1(Scf2*Cgf;9E-Upv^E-#F8G}V&);2{Sb_R*shKm^K>T4$>ch6f@Y9rR+X zehE1px!KTY+JE~o!wk9V5Ow2w!ifmyA{Km}SNX4i3G8UfPc2^~nhvz*746>5EP3C# zJTtiFFGtKp4;o1P@O1KEg2We){FLUf_?)<0*qy9Z?wiyiI-)W6abM#;H zU6?F=u(LYTrvQ85uPGTbhQGTfE$>;mE6rz`tW_jB$+C@ebGQahVv4$Mzof z=L!&)zazD*yUIdld;@Ya3MSIy3=*?>j*{~|4Jp^djT z+f{bj1V!iD#BDsX(-ouGM5rUjSs6gxSJ~R#Lcg1nZ0Ao`%?OYcMUbwqrKAP6!p6ElpppnaS#G7e zk&YPk-JI$(0FGzhqSbz!97Z`)=^B2pTzjlAPhd9vb>rv6aJ%9DcBWALL#y{AQubVir0}+d<>_836oU(P;;ZL59?8@1B)%QYr zVx83Xfngi&W-O_uq^sb-Sr`pA>ul*c*SD;?!`oTOIV*xM@}Y zAa32TXM&O?7kj7l;fP00+13?mOHOsfv!M57o!A!AZh^*btGwsCtX*%6yy_cXU-&ym zbmMMLBDxo9?rdpk)y71JF$?#EuK~VzF<|Z~4acUR?0-DT1zJ90|L5U})gU?y%YDW< zq_c0rTxW`Y=%8)Y!-!1@qx`zdJKT@dLCp|_hLd%*G|v({+{fDOq6Ae zZd^`Omq0`Q`9*=m{osne*qh@}@7=)w1GBH4_0!wvg4&b-#T1JVy|{99HF zbl+0#BDylsK!lc?8*yj@=uBejK(m*Gqd7AbM?3U3h$QBoLs8XEe=U zZgh=rBvpXp37~6{%2+)62dtzs?4XRBAUg~OsO;GhZbRZ7MVGk2i*P2C9;Fyr#oEgN8-) z7Z`r5y^CAbgp=qdyn}OMo|JTACt@(ob48Z+< z>a;=nKTnHDpQWmKb2rz=g@c&VvVe`za_ZCVE|!yd^DK256qY(uUv7DAU)DMm-y8l| zPX+h-UP{?=+MdIFAggUBPn~ov68%wJYG@cFR|T{KSly$VkkUWGcc-!LdJQx3tNV(- zQ-T0ghyM5d{xkOQpBwonDE;T5c&&d@X&`D}>pw+JB^X}(ANWR=$()_rpO{=+$gfz) zV$NAqZCIq^T2s(fId-Z4z&*TZdIk_qZBjD@{T}HDbg@%SG41-%jJFhQ&gF!T%S=)? zI5wr|ae+uz2y8L^62OZ0|9*?Wxo?+&a800lZb0@G5gCmWGf#Z46m^1O$7cfveo*)9 z#AuVR?(+|_*8I|eN@qXqS?<1W^Dw_?Wv1goPv;atF&e$aMSV-3vjFo)|L11@f6YaN z+#k!CNWP&@^NTtTdKgKa-FfZA``^(LP(vSUD;$*_Z|5i+)XXIg?U^pFw`Vm7M;uoh zjhv)zCkl@4y)N^8Q#K=MN4c7XoQ!%uFEh@IJctGTn3M2AebnJ4C$^%2QdFI(j`;6V zg#RJtHdkD;)|0Pa@Jfww_eg!jx1p@1#F|C5W-Z!tVhV-kRvUHlI4lOk>xJpZZzAgr zI1>4h)jbykK3R9_^>wAR(qZ0!+KG6D9fNU9S+UNd$E^JOPGT!wy+1tV@PPq%4B;2% z%2oA%Ja++LLv6tRr^=}7;2Zu|qYP(&kMifq&G%thIi7svhj;F4_EgtCXN(sQX^pg* zY@R;nw>(W_EK@9kpz@FL|7j_K$ypk4k&3{t|C{-Q%Viiv-5r%i$|G~$frod1ju?X2 zTZ$Rght0?t0iM47Pc-8}fpga6R53@zt-ogvl6}{tEKRIhI%~yrA0Xi0#Nke#Xpl0x z1Wur#>T<(PIf|6sI3ly*6%|bJ5uok=)!df{LcM?QPwA3U?v*f>l&$PBBWoy^42GCU zmc%fOCCO4*uew^SAwHZvtcB$-C*6hFc=q?$3Zgup zK{J*?`yM}{o*bW{hR(s1MN!?u_#SQ!2w5{OaJb3a$YcSHo;(cHJAjf?8u7lQRuLKm zQrdD;vwlmX>H8va`$MO${@R)!pSBv*pSN1=cWZe`_c&q1oI)7sr7XX{MkyaTPMLY{ zRkEBslhBuL&Rl7s$XlW6bzrn(z^T!j6$JVdyfZ;ypaIcbcXPBNA`0diK(R+QL&TrC z;pb2#%n1DXQA3(t`vstbbN4SR@|e%DRTd9Ic}8Uul519N$DZ@HkU#J%`iO#lo2P-+ zZ(wqt11bDJ5;6npjjrA^^eaAz16AjN2`E|4a;5st9>>oyo$2xJ@dlV0h6Ix9`aD#q zhsy8&iInl7+Geu|vZ#uyGpIs1Mr736{=9+0LQ5>y;|BH3Yd{jxomkGDU3g3EkJj`v z7n}4u?b#AF>7`1kRHeAY6|deR;@`n)W)dz&;JvjuFVApR)SVKJz;Z`v<$DI{-m=L) zBf?{Sople;#{63Y-)7K6`vdh>$#aic+4(jKp7m80Ft2wp^TyFl+tK6%VvAyh)C@nm zJ6E?K*pP&@WUka^veu26RQTDYgX+?eHC0AE=5-I3B66^8JA^s;I_snz4bm{;XfBAi zXW`X`&I~I>{?7hDs09ZjCnFd?#`Ka;X07!`Dc*gzoS-Cao+smyxgidwblX@or z=;#~*cU)LdJ=Ux`k(%Z96RCL@rlAfN!RA+(LHlUek}nwsv2BST8VWA>CbtzMd~bCw zItehLjo%pmaMVs|)FN;foC{b13{hK9?%~3z`4iB`)HXgy8uR=)DGT=M9gd8N?2}G z#qac5#=H?zqjRsp^z!cnBZtm)X82csDB@PJ}>ZUz|aF&C@GW`8Ny zkmAg%Elsv*?)RfReNURq=mWK9k=4Zq&^UU~g?O6V{84_l9dy)V^L=~)=(cjQFMJ6= zL#1y*LxIVbuR34(senk;EtbO8KQjLb*RY#R*u8H@cv~C6kXy^PBYzZP6pB|Ic}(2> zb-A_K;UEw{kRxq4SExs0F}t*#7IEr7yH8B0P0Lj4Nw-TfkJPrLzim3yW7q4@4V+p* z4o0m}962P$14W`n$K5WB$}6<38&y^;?LxnkOzT~c>lL4Tq()goqQ`TI@0%5*+# zB0w(k$y52M1r_jsJWu*@BKPIr#i%yLmyYL^7u$D;SP*~rsg9WMlbkFN!~8_dQ%p;^ zauqpriikH&s2UH!IBToPYR2V9(GSDo@@7w10d7aaspH2pMd*x-jv{U@w~voII0Zi# zB|frnw&11Tqk8Kvi_G7z`+FH%czgV4t}FaxN^Kq;LP*N|X_*E+ys96_MLhvRsz9Ys z8!uVbMOaP^=-tl{^i2q9#G~_h;E*ddG?oP+@A{=*vA_0{8j3~Y{g`9LSo3lm=fN| zPVZL?!Ui5e2-K_8)ogdVs0&<(DqhogkOK9P`23L(5rwO!(zZ<9E!K5S??cd?I`{-( zdD|gT;!Vl4ZcL~7(5x_evOZ0QH{8fi(-RfS%)&2YV4@=M=t7|YE;v8?%=GGYg}sdQ zBiuloZ`i_t2mWpTBz^M^X>9eN+t)$o@rHH+_`#^3ji@rftpg_Pgji_qr5`Oi{`s>y zKLL{Zr_}HBdxXR4D7>HzaNh9HQ}2MX`!CkEdHoo{a-Z<$pKofnBEybr08CkxebY0< zz#w+de?zx?sH`TvG<1HcEvicj_a%W9di-#qD+As>lOjF<$bl{P>D1zAwX1>{{e`<7rg7>)cAp@K}I9^VmpU zt+E#XhSrpLAiq!fEHQ*BgGkD*n(~(WE&8v1g1_DcPvC!IV>@en#wJJgZ65b?<>g3L z@a{{n4g?m1gIWWowle^q4U`kGSyEY@B>^3oYj56Rw^-kZu6d6Abi}Ejh@su7lPdS{ zK6;#q@7yAb-io>QfF)AUIp@rAmVP`Z zF3&0V;v-3!n@`KIT`Vl2;dlq7n534(!;lQlFWrNXf3yzvJ5;p_4xr0p=*}yj&OYRNrPr%gY}7fl9mBF@lUt_fh7pm_A_l; z0bmfOgB?!vYKdX{HpMO2jUHavWqD3Kx;DZGE{xy(nr*DEF{z=p-~(r|!?BpBJ}X_I zvM`!}0s#GMCUk-8ttT5W(3&m_7ZFa*P{1jaVIcD>lLNb>$_vb4DTDw=KJZ%ee1i}_ z*AFFNLNzAp< zxA|A#vZ)A^~XrRKq z|5+J<0@~ri?kUDUs+OlnlZ5{Bgu4Y^ zqJ$-d?^6DV&#r=}5c&P{?cL-UXR?*Ko?dMT(91@P{K5@(OL2@de<#4G?@fTEfEIMb zNi{+7)|M2YdCc7%!w4}jztG8arrop>s3B}LOngqsK*?aFMHsJ2VtJUvB^Kn+FmPlg z`0_ce`xno#r7r@e+ag&M{je5SwUE=t!s4|VVo}WEL3K{+He)s&=lk}xC(40R#mz9p zO1mW}_E*|Pg=uuFK+!`@7*bEXl*dXF7bL(HbyEyEM2~L6LkugVTmy>Nb`y*4M|S#X zEHxhXxyv_s)b3U1j*SWh`15)WqrkV6DEI(NMry?b+hN5RoWwzp+s|8~%4WIS3I$j} z`6cbYL(B_rKg~!GFl>(U*E($^xAW0Ca~En41V|y22E9qiUoA_Z*#Utu_A>1riwG`R z*ZjfelGm-OX{Rv*w_-RobsdxOuMsNH2wJ zccw_>2U)_c<@RoXPFng|?DC5CSZ}z*#UE$;q3q>22VV5XxJvU}|DbdBj<@qm>fNdY zK)~Jfn#x!kvGT<|(x?{V2?#2>N|zxzF@V|L**n0mUbb)JqIi1lV9SzHf}} zo$UCtHaI{7Ut$@MGF+59&AB-zNMo)6lbq&?EH%P$+SvtM1507nZNZwI(E(QoTe3>x z=&Ig#$$>5m)Q*ebP9=`)t~OoAi#%3s&|EI@JQeyqthBqK_r-U~e^x_J9xi!$wa4w> zd#0V#J*<`M^f2UbcTJ>qkoDVuoN#3_nQZua@#DE`oVcT5W=+pMlI_g0MIlusxxKcn zGN&^o8(WKBmh_gnr1)?*c%+(4yik3_fiH!NwwJCM^4H~&7UMHSTl02H8RfaTmnd7P^0{z~^&Nvq-_8#%kjSS@L1MZs70-9R zPW8!#vlIzgu!qF82as**C0ROU%3IE>AyUXq=6btzFwb&a-2DrPrZFr?pB%V}1;njz z`e}(*6?$rMT6-cV@e2!A7WK{K^%ue=XKNh+oW_NF0<08vX>%4qoGnI9{W@k~wvMhGgBM~? z&IpO;L+m2tLMVmrr~dAn0s@joBSyRz_!cyMDZ3=gpxZZb?{%2Kj*^(fJmlj?57Q6BQ*sd> zYNRyEJfPzULM`Ca)}Rc&$rG{k$yM?*=l80jT$2&2C=b|#=sMUFkn>;xo6)5;d_qGo zW`K*7gK<s}-lFq14J#z3 z*f&*#2U^--XqC?cdL-8!;eEx87?C`u5(&uV95II&tlYe>V?z`Jd1_J2RVYMXKSDK< zRZqK7Uf_`^Z9JR5_pxa0-wx_krAcnTC}`k3{XlZpXz%({8EUhj z(QxJ+Gw3igP3V6`*{<=L>|x51d2RfyZAE*%~dU;N(OGS$POX+aX8kqrY9wSVxRfT>&$-;ZjF zMU9*Wyh>&s(QBm>j_Iy|>N!3)h;+W>nX*>!2JUIu5SP%>F%y=U%}%eJky6gKd_;Yt zGT#5N8osk}qU_Xhe-Szu|EZjOeVkr4l#3L@ypVZC2MKc9@SlIKJ!tM1tQ8B%Trop9ju{oDp|?40va@IFWTpJ zr#&ro)oZ*d?o!hrM>FLM7x^B@w!|Fysff=u^i6Z{Kvm!42|H^y*2WsgmXJtF z^W$7!J0>n&>#7isOTV}mgt$kuAxOFZF5YI=>x5HErPr$LeOa4>hcq;`l9i-Pt$ZdF zUg7Tj3AQ~-uTlDz-g?bufn+)zLE3i)Q>d!`_U`pN;n+hRz^vpVArwlW>j;c1d-sxj z2h-h$N)r~hV`8NXJT#PbeddGiUjfGZUb~dAa_+sDhB*IWspK57m;kz??zH>k|7V;e z&WxmlMVvrf{{s7#MpMPff10KNeEOtQA}Uot@k%t5`EN`2XNlmwR1)NCP0;@rRGq&0 zNAc2W_W(!jhfhNAi{Gkw_k;}fy?}%)xXRv^1-wBnJPZc`r`#sZ#7#I_#?`LWrYSz{ z2C7NSCt<8EGP=ne`t<;^)HuqDUBP;)iE5>P6qBeawXgC^X(~cws-JEqAke zDmx>c(5fzcm#b*dB>nZ9x&zObj$yr$DS@KKlQU^$aV9(H(6ar4(ZxA;pd4KeSPBr%P2Lt1`?{tp zsp7Hn=WFL!^Mg+1jRiIH5b$x`l?jUJpqdRzz&e)w^42&|HB&y6~_9 zy)jpC(UvE(`sJV*4wJdBOezl;6|J=;p_6{OsuqcAiI;C~1|z@80!4gmd^`3iKPR;G za${k`;7#NX@*T{+XJ}Tk<#2~FUTa<^?MY9~r;&MwUKw>5_@xAtUY!8r=8V0)?wcQ{ z-*fLEO{C}?IvI(}lt=zM&;wILjNc0d=-XEPikHI-NDm%MUb)(E;z?<6EWK&E*m-C5 zsH{;WG|o%zycjC-SSc{!ty;gL^)^uG6FM7qf=-YYcLgyyYj_TmO3%6HL44m{)iV%~ zIrvmu=~@b(s3ewY(Kj+Q?fIae*_ z6?pfXo8W?K%Y_qM=~>$%ONt$3mW4_cOE|rwywJ9gp<_qTPz4f7LsTA9>(#U&ba!KZl&2sqBiM zYtXg!gzHnZill0&ql@qRhAVG2k?^&G=}JoBD5l5ifcyO3tpbx((9Ojy(s=*T#*_GYV&FlKfjXW+r^Tgw}=2 zVNn{dZG&dML(;yy&8+8%!{yzpSRqmp+Qy6tdwR=iaX!~KkAJruRlMMf4zpWPtHYu`3(E;9jO^tbp52RN;rO9mEsvh zS^;#6E-uIo*R&9e$Yb8;OxCZBb~RF$W_u)`)GyPhK$|#$p_?6V_s)o8xeCT#`9xlJ z4otOYm5fD@3W(#(&zd5m>%gOZqF&8`D6P~La*W>0&5$4)Fw}Aaw;;21LuyHPt=4ND z^PO-gldHg-Ey&(Mh$oJAX$dwZ z#f2f67j^l=Y=jUOvkhuoIBP}v%Ez<(rLp3=7|VV0&Tp%PMrgHWI83N~-53q^b$7Yg zjcJMnS4lNv8}JZ8z&Wc0wKg?~&pIr*_ubYE{(W$s zH~)e|+wEIB&MwPjiQ=_GLIu_sB*Qj9Y6IRCR)|6e=(L*#1_`VovcCiAd4YbWk1(!Dy$cSfnCbz4-`j zyhWEWVs;O9{LhWu$~LUH=C@$KUdU{}K1gs_f7d@yRfT93_l%hr_aw|Kdne9Ic!td@ zt(>3q9q~?IK$F$pky{uf+gjAuALOnt@|Fgy8Aq*Tj`d)mc6?he#6m0L?Q?3OvT1p?hbm4JGrdPEwY&(F@0QuV^by-NmmP zQ#`Yw-bK1hy>EbD2L7)P|48)kZ;_iNNU9XmFr{Lo!MXmds$a{`LSohF&Mdi>xWgMbU!jh6+)2OZvGtbYs^z-`{#|t%h31*3 zj-QX(W^r+cd!>)hiRz=&OyLZ2_Lv(SNXEFp*#q31wfJe1<-{Dd8o3l6!tJ^HY{fG{ zmg6eo6Zgdt+lSh=;4gi_y)VI0R2ZX zz+_1ve%@)DHpec87QfX9pn9 zM=-@=3|!LG4I)$fD!|wFet0#&9W3OMV^PAF()H+2raZzq5$2{<#d$0rfZ`8$_nDvkv% zBtAE0Y#wTZdL&;=wS_T7Trhyw?|JA!GAkckk~L61jTr(4O%SrqA%oqR57W`;oS)*- z`nBv**4M`|H9$3Z{0pQaGGB_*ha7I+z6%(>IJqx}hkj2m?eEeLeueNGK;^e1_-swy zjANZ$UgU*nxTkatvbH2gz0xR>lbMiz>guR*;0n|C8b0=+-QYo5K{dd@g z8JihSS?Q!QkUN<;^ezu+o5&6xdeY&`-(iE?-yHsm8(ZsfWq*JA5MS-<9j)PtytdHS zb$jV_budYOjW=~Z9M~f6?)g>zs}7Sy0hET1#x79tmdZSgVB7Yi#aXq8+z3Tr-j&7{ zGQAg=#wgU?xo@4+1!@!7vg*Bw)OokGe?=>$d+@EUZ&QD)pJ#d&u0qwQVd}cS=AFE7 G{r>@uMS3j& literal 0 HcmV?d00001 From 93f094817f64063afc9083df2ea05ca6e2e05dd1 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Wed, 18 Sep 2024 18:31:10 -0700 Subject: [PATCH 45/47] Move the IDP==RP section to appendix for clarity. --- DBSCE/Overview.md | 89 ++++++++++++++++++++++++----------------------- 1 file changed, 46 insertions(+), 43 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 3df649b..9e6fa0f 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -24,34 +24,35 @@ This is the repository for Device Bound Session Credentials for Enterprise. You' ## Participate (TBD links) -- [Issue tracker]() +- [Issue tracker](https://github.com/WICG/dbsc/issues) - [Discussion forum] ## Table of Contents - - [Overview](#overview) - - [Why DBSC(E)?](#why-dbsce) - - [How does it integrate with DBSC?](#how-does-it-integrate-with-dbsc) - - [Terminology](#terminology) - - [Browser](#browser) - - [Relying Party (RP)](#relying-party-rp) - - [Identity Provider (IdP)](#identity-provider-idp) - - [Device Registration Client](#device-registration-client) - - [Local Key Helper](#local-key-helper) - - [Platform Requirements](#platform-requirements) - - [Attestation Service](#attestation-service) - - [Key Generation Specifics](#key-generation-specifics) - - [Attestation Key](#attestation-key) - - [Binding Key](#binding-key) - - [Binding Statement](#binding-statement) - - [High-Level Design](#high-level-design) - - [DBSC(E) use cases](#dbsce-use-cases) - - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) - - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) - - [IDP Calls Private Local Key Helper](#idp-calls-private-local-key-helper) - - [Cleanup of the binding keys and their artifacts](#cleanup-of-the-binding-keys-and-their-artifacts) +- [Overview](#overview) +- [Why DBSC(E)?](#why-dbsce) +- [How does it integrate with DBSC?](#how-does-it-integrate-with-dbsc) +- [Terminology](#terminology) + - [Browser](#browser) + - [Relying Party (RP)](#relying-party-rp) + - [Identity Provider (IdP)](#identity-provider-idp) + - [Device Registration Client](#device-registration-client) + - [Local Key Helper](#local-key-helper) + - [Platform Requirements](#platform-requirements) + - [Attestation Service](#attestation-service) + - [Key Generation Specifics](#key-generation-specifics) + - [Attestation Key](#attestation-key) + - [Binding Key](#binding-key) + - [Binding Statement](#binding-statement) +- [High-Level Design](#high-level-design) + - [DBSC(E) additional use cases](#dbsce-additional-use-cases) + - [IDP Calls Public Local Key Helper](#idp-calls-public-local-key-helper) + - [IDP Calls Private Local Key Helper](#idp-calls-private-local-key-helper) + - [Cleanup of the binding keys and their artifacts](#cleanup-of-the-binding-keys-and-their-artifacts) + - [Appendix](#appendix) + - [IDP is RP and Calls Public Local Key Helper](#idp-is-rp-and-calls-public-local-key-helper) @@ -176,9 +177,8 @@ This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC pr ##### Binding Statement Additional to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the attestation key. Details on how this statement is issued and its format is specific to each local key helper. - -- For a _public local key helper_, the _binding statement_ is usually signed by an asymmetric key from the attestation service, and should not include any device identifying information, like device id etc. The validation of the _binding statement_ is a simple signature validation of public service. -- For a _private local key helper_, The _binding statement_ is usually signed by the _attestation key_. The validation of the _binding statement_ authenticates the device to find the deviceId, and by using deviceId to find the corresponding _attestation key_. +- For a _public local key helper_, the _binding statement_ must be signed by an asymmetric key from the _attestation service_, and should not include any device identifying information, like device id etc. The validation of the _binding statement_ is a simple signature validation by the _attestation service_. +- For a _private local key helper_, The _binding statement_ must be signed by the _attestation key_. During the validation of the _binding statement_, the IDP authenticates the device to find the deviceId, and uses the deviceId to find the corresponding _attestation key_ which helps with the validation. Device authentication with the IDP is out of scope of this protocol. The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. @@ -190,7 +190,7 @@ Since there could be multiple devices supported by a [device registration client ## High-Level Design -DBSC(E), if enabled for a given enteprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an enterprise policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. +DBSC(E), if enabled for a given enterprise, specifies the generation of the cryptographic artifacts (keys and binding info) before a sign in session is established. By enabling the browser to invoke specific APIs based on an enterprise policy, it allows enterprises to add to the existing key generation. It also allows them to place stricter restrictions on specific sessions, hence providing the flexibility to secure a session appropriately. The high-level design is divided into two parts: @@ -218,7 +218,7 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC - The allowance for long lived _binding statement_ is possible with _private local key helpers_ where the IDP can use other means to establish fresh proof of possession of the device. This is covered in detail in [later sections](#idp-calls-private-local-key-helper). - `nonce` also helps prevent the clock skew between servers where IDP and Attestation servers are from different vendors. Since the `nonce` sent by the IDP is embedded in the _binding statement_, the IDP will be able to validate `nonce` to ensure the _binding statement_ is issued recently. - `nonce` is generated by the IdP/RP as a part of the request, is a random number that MUST be unique, MUST be time sensitive and MUST be verifiable by the issuer. - - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser must prefer the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. There is also an optional `HelperCacheTime` which can cache a preferred `HelperId` for the IDP in the browser for a given time. + - The `Sec-Session-HelperIdList` header contains an _ordered list_ of helper IDs that the browser can use to generate the key. The browser must prefer the first available and enabled `HelperId` from the list. The browser will then call the Local Key Helper with the `HelperId` to generate the key. There is also an optional `HelperCacheTime` which can cache a `HelperIdList` for the IDP in the browser for a given time. 1. **Key and Binding Statement Generation (steps 3-7):** The Local Key Helper generates the key and the binding statement. AIK refers to the `Attestation Key` described [above](#attestation-key). The binding statement is expected to contain `nonce`(challenge) sent by the IdP, the thumbprint(a cryptographic hash digest) of the `publicKey`(public part of the [binding key](#binding-key)), and any extra claims that the IdP wants to send. @@ -229,25 +229,10 @@ Note: All references to RP, IDP are equivalent to `server` in the original [DBSC 1. **SignIn Succeeds with binding (steps 10-14)**: At this point, all DBSC(E) specific steps are completed. The server returns signed in content with a special header response to the browser: `Sec-Session-Registration` indicated the session is expected to be DBSC compliant. All steps further are as per the original DBSC proposal with two caveats: The _local key helper_ is called for JWT generation and the additional params introduced for DBSC(E) customization can be optionally added. -### DBSC(E) use cases +### DBSC(E) additional use cases This section expands on the [generic design](#high-level-design) to address different enterprise use cases: -#### IDP is RP and Calls Public Local Key Helper - -This is the similar use case elaborated in the high level design [above](#high-level-design). This use case covers where an IDP/RP calls a [_public Local Key Helper_](#local-key-helper). The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). - -![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) - -[Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DOBDAtjNLoCVEAaaAYzXHFzWgAcBXAI3BBOgBkB7M8aAaUgCe0ABKRwNSACcAUNLR1gHAHZ0MDKdACM0mmkmgSIXUuDQARHjECQSgObREe4ALPQc0AOo6nLI2hPmCIiu7rDe+r7GpmYAQpIcAO4oUiG4MeEGfgFmnNx8giJiEpKpDhmR-tEAgsDAkCjAaKDKAMpSAG4skKVVskocddAc7RoexFUAXNAtILZK0DYAdMvSHgC0AHwbMVMtjfqos-M20AAUAMwADABMAJTQADpKT20ka20oKCDKawDikEopE1IPwBFMngQAKqScDEWAAEUQ0NhpAAFuQoHZIABefpKEiQYiQAAewEkaEc5IwKGWiyeL0gbw+Xx+onEUgQbBADXBSgA2mzighNMRBRz4NcALqiopSADCaBIqMgABUQFhZDFNtspiQ6JJJADgGLJAhoNjHkoAKLtch0YG0DjMEhCABmHEkZyCxAFstN8BFhXZ-uuhFpktu0i1W0QU0QhrWtgB0AA1gV-PBLU06g0zlCYXDEcjiEqMQCk7jlASiaTycBKZgactI9JENrY9B-oC6zBQbI21tJp3IKYYjZ4DZ7HtgVgAk8zvQmCxQeNYLwS+iKOWcXiCZGqu2ppZgPr5gxx5PUI06rPTE8AN7QXeE6DAVGqBg0SQ2YCnRfO0FbhrMk0DlcA0HVJtFmgABfVttR2fIBAQYgIRHU9oHPJQJzsK8ZyNS1H2fYg3w-L8fz-RgAMEIDoBJECwIg6laVgqMEKPSAsDUDQ325VMCj491PQIM4M2gDA0AEdRaCaVFI2jDZYCmTg0EzL45jWE4GSZeoWSUNZQRQKZQRQy0x2wy8GnwuclCIqsX1fd81HIkxKKXEhAOA8lGMgli4NgbUlOgW1mHgB11KUJp9RgJ5lEcmAsJw+wrJvAixOIy0Gg9GBSOc78TFkAKtkQmY5gWeYCUNDBlAENitiC0r5ngZRIEK7UPCmKpEFgU4qgUVFXw4NMlFwBIwAG3LP3y4BiBM+AW36QZhlGcYplgJQwBAB14RiFo5WgWlVnY6BrkuS5oAAeV4S1XneXTvn0yxbG5EDmiUXldDfYgCDlTdMSTEihoBAB+WbBFM+jyQbak6o2DtLAARzoepTEa6AACkPBVM59RADcyyxQHhtB-jkPgEmACoKchik9EbWkqcjAcdXwdDJHmTHscaqLDVhjqHAulpsYAemSPVDWST4HtF-ZgElvSzk5omARQSN1i2fmADVyBAMLBiVy1TgSYXxKaJVHLI6byviwbhtVo7is6-q5Q4IaQFa6RFpgZbPTGaAh0sV0JYGna9sOhT+d+K0RbF6L5elw0g-qAbTnj5QETV47foJgHoCpmnoagqnYfhyAkZR6YjgxrGzjTpQEWIfPa1pqki4ppnjuPDDOcruYedaiOpijmPGTj+7lGFxPg8VrHM41qZtdCh0e6N4X-xYUmhnmV0QCgOeWb6t8Xbd1qgA) - -Highlights: - -- The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). -- Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of auth tokens and issue cookies based on those tokens. In such case, the IdP can generate the auth tokens and embed the thumbprint of the publicKey in the token. -- The tokens can be delivered to the RP directly through an API instead of a header based response since they are the same server in this use case. -- The tokens also contain the thumbprint of the publicKey, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. The RP will also embed the thumbprint in the cookie for subsequent session validation. - #### IDP Calls Public Local Key Helper In many use cases, it is also a valid to have separate servers as [RP](#relying-party-rp) and [IdP](#identity-provider-idp). We address the use case where the IdP calls a [_public Local Key Helper_](#local-key-helper) and is a separate service from the RP below. @@ -261,6 +246,12 @@ For easy mapping with the existing DBSC proposal, please note: [Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DGBDc4DO03QA4CuARuCCtADID2640A0pAJ7QASk4+kATgFB80hYNQB2hALbFe0AIx98aHqBQhFo4NABEAJU7MQogObRES4My24cAdQXnyatBu0JEVtDlj3lj9Zq0AIR5qAHcsXg8cQJ8VJxctGjpGFnZObh4o01i-ZwCAQWBgSCxgNFAxAGVeADdySCz8gVFqYuhqGpkbABpofIAuaEqQI1FoQwA6Kb4bAFoAPnnAwcqy5WgsEbHDaAAKAGYABgAmAEo+QIX52EGaNHgNrdmd3YAzakww6GAACxgjs4CWBXZZDSAoWbVLCbMSzADikFEvHKkCYzEGAB1RDpEABVHjgXqwAAieIJvRQPwwUGMkAAvC1RChIL1IAAPYA8NBmLkSLBTCZYrHVCFQmGiWYcLi8BCUEClTGiADaUoyCFkvVVMvgxwAupr0rwAMJoSmQAAqIAkkAuIMGKEIPB4iOAWp4CGgdOgWIAojUMIQUQQPuRWO8eHs3L0VYb3fANWlpXHjt0BbrzpdFohBohnbMjIjoABrVLOB5Y8rFUp7HH4wlwUl13pYynUxEFhliZmsjlcnloPkC858RBXbPQBFIrltNECUeLAYTyCaQKGeCGEyrFHWlxY3ZEUjkNG9fKwBgUqmYdv0xnM875MeDPTAR1jYhrjcbMrFHeaLEAb2gW8WW+H5JGIfAeEMYB9xIMgUDRU4e05NAjXANArX5KZoAAXxHO0UmYBBm2xZdX2gd9RHXYwv23F1vVEQDgN6X5wMg6DYMPBCWCQ6B2RQtCMMHbC8MzJYn0ga0pBkX55WLVI5PDaAcT2MtoAkNBmGkAhyh+DMrhuMFRRKcVZjRLBBjRYiGNXKjP1KOjd0YoCuxA1ipHYjROPgxDkK5QTMIFXC+GBRZDP9Mh4CDTZRnKR0YDEUCYEo6iTAcn96KxAAyFymRA0pqGdUC2KgjQgQI4ZRnGMZmWdCQxGYW0wpWLZoHgMQbRCgj8mEH5vmoEtRBwXZQjAPr3Ig0rgF4rErPgJr5hsQYet+frBuG0bVomzzppIubmlaBLOgjHo+kGWBRDAEAg2JQJKiNaABRmCq1mAMUQESvdWyvWlOzyliBsRAB+Xo5pB6AACoIf4vslAHLCJih-SswkgBHQgSk0SqxgAKRsc0GN2R0QAvNtfuYrE1uB3oSyI+BwahmHuTh4TEYh8553E5SyJ4XH8aGLY4udBaltMAB5SoCYAegiB1nQiaEPtEGXXoV8U9jx80AfW845kWUWADUMBAKK2k1kiRql9TykpYqPKmhidl+GARB157FlBFafiNagBpATqWjaDouhPCTXnlvrbvup6xNFuEfWl2X4rVpWpedcOSj63YU7EEldYIo1LxpAtekZ3tmd5BGoYW8c9HRzGBaqzW9hz0QSVL6Hy-7Vmkfwj2JJfXnoGb7GhZtWPBnjxPwWTkzU-TiONfx-P9cGI3IqDZu91CKWD3g+TWES14QCgFeua9n2-ZtIA) +Highlights: + +- The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). +- Auth tokens are not mentioned in the DBSC(E) high level design to simplify the over all scenario. However, most signin/access operations will often make use of auth tokens and issue cookies based on those tokens. In such case, the IdP can generate the auth tokens and embed the thumbprint of the publicKey in the token. +- The tokens also contain the thumbprint of the publicKey, and the RP must validate the thumbprint from the token against the thumbprint from the JWT. The RP will also embed the thumbprint in the cookie for subsequent session validation. + #### IDP Calls Private Local Key Helper As referred in [Local Key Helper](#local-key-helper) section, it is possible for an IdP to implement a private local key helper and establish a private protocol to communicate. Any such private local key helper can only be used by the specific IDP that owns its implementation. @@ -287,3 +278,15 @@ The cleanup can occur: - When cookies are expired. - On demand, when the user decides to clear browser cookies. + +### Appendix + +#### IDP is RP and Calls Public Local Key Helper + +This is the similar use case elaborated in the high level design [above](#high-level-design). This use case covers where an IDP/RP calls a [_public Local Key Helper_](#local-key-helper). The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). + +![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) + +[Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DOBDAtjNLoCVEAaaAYzXHFzWgAcBXAI3BBOgBkB7M8aAaUgCe0ABKRwNSACcAUNLR1gHAHZ0MDKdACM0mmkmgSIXUuDQARHjECQSgObREe4ALPQc0AOo6nLI2hPmCIiu7rDe+r7GpmYAQpIcAO4oUiG4MeEGfgFmnNx8giJiEpKpDhmR-tEAgsDAkCjAaKDKAMpSAG4skKVVskocddAc7RoexFUAXNAtILZK0DYAdMvSHgC0AHwbMVMtjfqos-M20AAUAMwADABMAJTQADpKT20ka20oKCDKawDikEopE1IPwBFMngQAKqScDEWAAEUQ0NhpAAFuQoHZIABefpKEiQYiQAAewEkaEc5IwKGWiyeL0gbw+Xx+onEUgQbBADXBSgA2mzighNMRBRz4NcALqiopSADCaBIqMgABUQFhZDFNtspiQ6JJJADgGLJAhoNjHkoAKLtch0YG0DjMEhCABmHEkZyCxAFstN8BFhXZ-uuhFpktu0i1W0QU0QhrWtgB0AA1gV-PBLU06g0zlCYXDEcjiEqMQCk7jlASiaTycBKZgactI9JENrY9B-oC6zBQbI21tJp3IKYYjZ4DZ7HtgVgAk8zvQmCxQeNYLwS+iKOWcXiCZGqu2ppZgPr5gxx5PUI06rPTE8AN7QXeE6DAVGqBg0SQ2YCnRfO0FbhrMk0DlcA0HVJtFmgABfVttR2fIBAQYgIRHU9oHPJQJzsK8ZyNS1H2fYg3w-L8fz-RgAMEIDoBJECwIg6laVgqMEKPSAsDUDQ325VMCj491PQIM4M2gDA0AEdRaCaVFI2jDZYCmTg0EzL45jWE4GSZeoWSUNZQRQKZQRQy0x2wy8GnwuclCIqsX1fd81HIkxKKXEhAOA8lGMgli4NgbUlOgW1mHgB11KUJp9RgJ5lEcmAsJw+wrJvAixOIy0Gg9GBSOc78TFkAKtkQmY5gWeYCUNDBlAENitiC0r5ngZRIEK7UPCmKpEFgU4qgUVFXw4NMlFwBIwAG3LP3y4BiBM+AW36QZhlGcYplgJQwBAB14RiFo5WgWlVnY6BrkuS5oAAeV4S1XneXTvn0yxbG5EDmiUXldDfYgCDlTdMSTEihoBAB+WbBFM+jyQbak6o2DtLAARzoepTEa6AACkPBVM59RADcyyxQHhtB-jkPgEmACoKchik9EbWkqcjAcdXwdDJHmTHscaqLDVhjqHAulpsYAemSPVDWST4HtF-ZgElvSzk5omARQSN1i2fmADVyBAMLBiVy1TgSYXxKaJVHLI6byviwbhtVo7is6-q5Q4IaQFa6RFpgZbPTGaAh0sV0JYGna9sOhT+d+K0RbF6L5elw0g-qAbTnj5QETV47foJgHoCpmnoagqnYfhyAkZR6YjgxrGzjTpQEWIfPa1pqki4ppnjuPDDOcruYedaiOpijmPGTj+7lGFxPg8VrHM41qZtdCh0e6N4X-xYUmhnmV0QCgOeWb6t8Xbd1qgA) + + From 062b0d084f666bb4822b070b9c68ae6def4f0fbd Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Wed, 18 Sep 2024 19:18:04 -0700 Subject: [PATCH 46/47] Remove SVG in Appendix to avoid clutter --- DBSCE/Overview.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 9e6fa0f..858298c 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -285,8 +285,6 @@ The cleanup can occur: This is the similar use case elaborated in the high level design [above](#high-level-design). This use case covers where an IDP/RP calls a [_public Local Key Helper_](#local-key-helper). The binding statement is expected to be short lived as elaborated in the [high level design](#high-level-design). -![IDPSameAsRP-CallsPublicLocalKeyHelper](./IDPSameAsRP-CallsPublicLocalKeyHelper.svg) - [Link to editable diagram](https://sequencediagram.org/index.html#initialData=C4S2BsFMAIEkBMAK0DOBDAtjNLoCVEAaaAYzXHFzWgAcBXAI3BBOgBkB7M8aAaUgCe0ABKRwNSACcAUNLR1gHAHZ0MDKdACM0mmkmgSIXUuDQARHjECQSgObREe4ALPQc0AOo6nLI2hPmCIiu7rDe+r7GpmYAQpIcAO4oUiG4MeEGfgFmnNx8giJiEpKpDhmR-tEAgsDAkCjAaKDKAMpSAG4skKVVskocddAc7RoexFUAXNAtILZK0DYAdMvSHgC0AHwbMVMtjfqos-M20AAUAMwADABMAJTQADpKT20ka20oKCDKawDikEopE1IPwBFMngQAKqScDEWAAEUQ0NhpAAFuQoHZIABefpKEiQYiQAAewEkaEc5IwKGWiyeL0gbw+Xx+onEUgQbBADXBSgA2mzighNMRBRz4NcALqiopSADCaBIqMgABUQFhZDFNtspiQ6JJJADgGLJAhoNjHkoAKLtch0YG0DjMEhCABmHEkZyCxAFstN8BFhXZ-uuhFpktu0i1W0QU0QhrWtgB0AA1gV-PBLU06g0zlCYXDEcjiEqMQCk7jlASiaTycBKZgactI9JENrY9B-oC6zBQbI21tJp3IKYYjZ4DZ7HtgVgAk8zvQmCxQeNYLwS+iKOWcXiCZGqu2ppZgPr5gxx5PUI06rPTE8AN7QXeE6DAVGqBg0SQ2YCnRfO0FbhrMk0DlcA0HVJtFmgABfVttR2fIBAQYgIRHU9oHPJQJzsK8ZyNS1H2fYg3w-L8fz-RgAMEIDoBJECwIg6laVgqMEKPSAsDUDQ325VMCj491PQIM4M2gDA0AEdRaCaVFI2jDZYCmTg0EzL45jWE4GSZeoWSUNZQRQKZQRQy0x2wy8GnwuclCIqsX1fd81HIkxKKXEhAOA8lGMgli4NgbUlOgW1mHgB11KUJp9RgJ5lEcmAsJw+wrJvAixOIy0Gg9GBSOc78TFkAKtkQmY5gWeYCUNDBlAENitiC0r5ngZRIEK7UPCmKpEFgU4qgUVFXw4NMlFwBIwAG3LP3y4BiBM+AW36QZhlGcYplgJQwBAB14RiFo5WgWlVnY6BrkuS5oAAeV4S1XneXTvn0yxbG5EDmiUXldDfYgCDlTdMSTEihoBAB+WbBFM+jyQbak6o2DtLAARzoepTEa6AACkPBVM59RADcyyxQHhtB-jkPgEmACoKchik9EbWkqcjAcdXwdDJHmTHscaqLDVhjqHAulpsYAemSPVDWST4HtF-ZgElvSzk5omARQSN1i2fmADVyBAMLBiVy1TgSYXxKaJVHLI6byviwbhtVo7is6-q5Q4IaQFa6RFpgZbPTGaAh0sV0JYGna9sOhT+d+K0RbF6L5elw0g-qAbTnj5QETV47foJgHoCpmnoagqnYfhyAkZR6YjgxrGzjTpQEWIfPa1pqki4ppnjuPDDOcruYedaiOpijmPGTj+7lGFxPg8VrHM41qZtdCh0e6N4X-xYUmhnmV0QCgOeWb6t8Xbd1qgA) From 18c44e535d80d16d74d297ee79d15d7fb7859966 Mon Sep 17 00:00:00 2001 From: Sameera Gajjarapu Date: Thu, 19 Sep 2024 15:09:51 -0700 Subject: [PATCH 47/47] Fix a typo, clarify text --- DBSCE/Overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DBSCE/Overview.md b/DBSCE/Overview.md index 858298c..3596f21 100644 --- a/DBSCE/Overview.md +++ b/DBSCE/Overview.md @@ -177,7 +177,7 @@ This _binding key_ for DBSC(E) is similar to the artifact defined in the DBSC pr ##### Binding Statement Additional to the _binding key_, the local key helper also generates a _binding statement_, a statement that asserts the binding key was generated on the same device as the attestation key. Details on how this statement is issued and its format is specific to each local key helper. -- For a _public local key helper_, the _binding statement_ must be signed by an asymmetric key from the _attestation service_, and should not include any device identifying information, like device id etc. The validation of the _binding statement_ is a simple signature validation by the _attestation service_. +- For a _public local key helper_, the _binding statement_ must be signed by an asymmetric key from the _attestation service_, and should not include any device identifying information, like device id etc. The validation of the _binding statement_ is a simple signature validation that ensures that it is signed by the same key from the _attestation service_. - For a _private local key helper_, The _binding statement_ must be signed by the _attestation key_. During the validation of the _binding statement_, the IDP authenticates the device to find the deviceId, and uses the deviceId to find the corresponding _attestation key_ which helps with the validation. Device authentication with the IDP is out of scope of this protocol. The validation component verifies the _binding statement_, and it can understand that such a statement cannot be generated unless the private key resides in the same secure enclave when signed by the _attestation key_. Hence, a valid _binding statement_ means that both the _attestation key_ and the _binding key_ belong to the same device. @@ -186,7 +186,7 @@ Binding statements can be long-lived or short-lived. - If an IdP performs fresh device authentication outside of DBSC(E) integration at the time of _binding key_ validation, then the _binding statement_ can be long lived, as the IdP ensures the device identity through other mechanisms. - IdPs that do not perform proof of possession of the device, the ones that use public local key helpers, must use short-lived binding statements. Otherwise, the attacker will be able to bind the victim's cookies to malicious keys from a different machine. A short-lived binding statement must have an embedded nonce sent by the IdP to validate that it is a fresh binding statement, minimizing the attack window. -Since there could be multiple devices supported by a [device registration client](#device-registration-client) and since it is possible for a device to be unknown when the local key helper is invoked during authentication, multiple binding keys can be issued for a single binding key. This is especially true for [private local key helpers](#idp-calls-private-local-key-helper). +Since there could be multiple devices supported by a [device registration client](#device-registration-client) and since it is possible for a device to be unknown when the local key helper is invoked during authentication, multiple binding statements can be issued for a single binding key. This is especially true for [private local key helpers](#idp-calls-private-local-key-helper). ## High-Level Design