GateKeeper Authentication

Summary :

A GateKeeper authentication involves 3 differents parties :

  • A web application WA.
  • A end user U in control of a web browser UB capable of running the GateKeeper extension.
  • An authentication portail AP capable to authenticate end user.

The protocol involves the following steps :

  1. User visits WA which returns an authentication request.
  2. UB detects the authentication request and register some data pertaining to the connection.
  3. The UB GUI pop up to allow end user entering his credentials.
  4. UB determines which authentication provider AP to use from the end user identifier uid.
  5. UB and AP enters in mutual authentication using the SRP protocol.
  6. If mutual authentication is successful, the AP returns to UB a special message sometimes called a Token.
  7. UB extract the Token and forward it to WA for final authentication.

Step 2 : Authentication request parsing and connection scan

  • UB records the url from where the authentication request is coming : arurl
  • UB reads the value of X-GateKeeper-Authentication header and calculates : tvurl
  • If the connection was opened on https, UB stores the certificate digest : hcert

Step 4 :

  • UB extracts ct (credentials type) from provided uid.
  • UB calculates ap-url the base url where authentication shall happen.
  • UB makes sure that the calculated ap-url is trusted by WA. If not terminate with error.

See GateKeeper identifier for details.

Step 5 : provisionnal SRP implementation

preconditions :

  • We assume that the end user credentials have been entered into UB.
  • The authentication portail AP was successfully resolved from uid.
  • AP was found to be trusted by WA.

Data :

  • A prime N.
  • A generator g.
  • Server side account are (uid,s,v) where :
    • s is a salt
    • v a password verifier

See here for references.

Protocol :

1. UB :

  • Generates 32 bytes random a and calculates A = g**a (mod N) (checks that A != 0 mod N, generates other a if so...)
  • Sends (uid,A) to AP

2. AP :

  • Checks that A != 0 mod N , If not terminates with error (HTTP -> 403 UB gui turns red ...)
  • Retrieves s , v
  • Generates 32 bytes random b and calculates b = kv + g**b (mod N) (checks that B != 0 mod N, generates other b if so ...)
  • Generates 16 bytes sid, stores (uid,A,b,B,s,v) indexed by sid
  • Responds with sid,s,B

3. UB :

  • Checks that B != 0 mod N , If not terminates with error ( UB gui turns red ...)
  • Calculates x = H(salt|H(uid|:|password))
  • Calculates u = H(A|B)
  • Calculates S = (B - kg**x)**(a + ux) (mod N)
  • Calculates K = H(S)
  • Calculates M1 = H(H(N) xor H(g)|H(uid)|s|A|B|K)
  • Calculates macKey = H(1|K)
  • Packs (sid,M1,arurl,tvurl,hcert) as request body.to AP
  • Add X-GKmac as request header X-GKmac = hmac(macKey,requestBody)
  • Post request to AP

4. AP :

  • Retrieves (uid,A,B,b,s,v) with key sid
  • Calculates u = H(A|B)
  • Calculate S = (Av**u)**b mod N
  • Calculates K = H(S)
  • Validates received M1, if not ok terminates with error (HTTP -> 403 UB gui turns red ...)
  • Calculates M2 = H(A|M1|K)
  • Calculates K_uae = H(2|K), K_uas=H(3|K)
  • Write the authentication token (TOK) using (uid,K_uas,arurl,tvurl,hcert). See here for details.
  • Encrypt TOK using K_wae and a second time using K_uae | encode binary string using base 64 : {{TOK}}
  • Responds with M2, {{TOK}}

5. UB :

  • Validates M2, if not ok UB turns red and authentication terminates with error.
  • Calculates K_uae,K_uas as above and K_uasm = H(1|K_uas)
  • Decode {{TOK}} (b64 --> binary) and decrypt using K_uae | encode binary string using base 64 : {TOK}
  • Let auth_portail_url be the base url of the authentication portail.
  • Generate 20 bytes random chal | encode hexadecimal : r_chal
  • Packs (auth_portail_url,{TOK},r_chal) as request body.to WA
  • Add X-GKmac as request header X-GKmac = hmac(K_uasm,requestBody)
  • Post token validation request to tvurl.

6. WA :

  • Retrieves K_wae that corresponds to auth_portail_url.
  • Decode {TOK} (b64 --> binary) and decrypt using K_wae : TOK
  • Proceeds with TOK validation. See here for details.
  • If TOK is not valid : responds with HTTP 403.
  • Extract K_uas from TOK. Calculates K_uasm.
  • Validates request header X-GKmac using K_uasm.
  • If not OK : responds with HTTP 403.
  • If OK : Calculates ACK = H(OK|K_uas|r_chal)
  • If OK : Generates session id and set session cookie
  • Responds with HTTP 200 with content ACK

7. UB :

  • Validates ACK : If OK , UB turn green, else red...

See also :

here and here