Subversion Repositories oidplus

Rev

Rev 1282 | Rev 1298 | Go to most recent revision | Show entire file | Regard whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 1282 Rev 1283
Line 9... Line 9...
9 
This value is chosen randomly by the configuration file generator (setup).
 9 
This value is chosen randomly by the configuration file generator (setup).
10 
 
 10 
 
11 
Derivation of secrets and auth keys
 11 
Derivation of secrets and auth keys
12 
-----------------------------------
 12 
-----------------------------------
13 
 
 13 
 
14 
Important: The usage of `OIDplus::baseConfig()->getValue("SERVER_SECRET")`
 14 
The usage of `OIDplus::baseConfig()->getValue("SERVER_SECRET")`
15 
is deprecated due to security considerations.
 15 
is deprecated due to security considerations.
16 
 
 16 
 
17 
Instead, please always use `OIDplus::authUtils()->makeSecret()`
 17 
Instead, please always use `OIDplus::authUtils()->makeSecret()`
18 
with a unique `$data` argument (prefer a GUID)
 18 
with a unique `$data` argument (prefer a GUID)
19 
if you need a secret that is derived from the server secret.
 19 
if you need a secret that is derived from the server secret.
20 
 
 20 
 
21 
If you want to generate an authentication key (e.g. to send via an email),
 21 
If you want to generate an authentication key (e.g. to send via an email),
22 
use `OIDplus::authUtils()->makeAuthKey()`
 22 
use `OIDplus::authUtils()->makeAuthKey()`
23 
with a unique `$data` argument (prefer a GUID)
 23 
with a unique `$data` argument (prefer a GUID)
24 
in combination with `OIDplus::authUtils()->validateAuthKey()`.
 24 
in combination with `OIDplus::authUtils()->validateAuthKey()`.
25 
This auth key is NOT temporary by default so you need to make sure
 25 
An auth key is usually temporary; therefore `makeAuthKey` encodes a timestamp
26 
that you encode a timestamp in it.
 - 
 
27 
 
 - 
 
28 
Implementation
 - 
 
29 
--------------
 - 
 
30 
 
 - 
 
31 
`makeAuthKey(data) = makeSecret(data) = sha3_512_hmac(data, "OIDplus:" + SERVER_SECRET)`
 - 
 
32 
 
 - 
 
33 
Currently, the implementation of `makeAuthKey` and `makeSecret`
 - 
 
34 
is the same, but you should only use `makeAuthKey`
 - 
 
35 
if you combine it with `validateAuthKey`, otherwise, you
 26 
which can be checked by `validateAuthKey` by providing
36 
should use `makeSecret`. This makes the code easier to understand.
 27 
a validity period in seconds.
37 
 
 28 
 
38 
Where are makeAuthKey and makeSecret being used?
 29 
Where are makeAuthKey and makeSecret being used?
39 
------------------------------------------------
 30 
------------------------------------------------
40 
 
 31 
 
41 
System / Core:
 32 
System / Core:
42 
- Auth content Store (OIDplusAuthContentStoreJWT.class.php):
 33 
- Auth content Store (OIDplusAuthContentStoreJWT.class.php):
43 
  Key to sign JWT tokens (used for Automated AJAX requests, REST API and logins with "Remember me") using PBKDF2+HMAC
 34 
  Key to sign JWT tokens (used for Automated AJAX requests, REST API and logins with "Remember me")
44 
  * If a private/public key pair exists: Sign the JWT using that private key.
 35 
  * If a private/public key pair exists: Sign the JWT using that private key.
45 
  * Otherwise sign it with:
 36 
  * Otherwise sign it using PBKDF2+HMAC:
46 
    `JWT = HS512(hash_pbkdf2("sha512", OIDplus::authUtils()->makeSecret("0be35e52-f4ef-11ed-b67e-3c4a92df8582"), "", 10000, 64/*256bit*/, false))`
 37 
    `JWT = HS512(hash_pbkdf2("sha512", OIDplus::authUtils()->makeSecret(["0be35e52-f4ef-11ed-b67e-3c4a92df8582"]), "", 10000, 64/*256bit*/, false))`
47 
- Session Handler (OIDplusSessionHandler.class.php):
 38 
- Session Handler (OIDplusSessionHandler.class.php):
48 
  Encryption of session contents (regular logins)
 39 
  Encryption of session contents (regular logins)
49 
  * if OpenSSL is installed:        sha512-pbkdf2 + AES-256-CBC + sha3-512-hmac
 40 
  * if OpenSSL is installed:        sha512-pbkdf2 + AES-256-CBC + sha3-512-hmac
50 
  * if OpenSSL is not installed:    sha3-512-hmac
 41 
  * if OpenSSL is not installed:    sha3-512-hmac
51 
  * In both cases, the key is `OIDplus::authUtils()->makeSecret("b118abc8-f4ec-11ed-86ca-3c4a92df8582")`.
 42 
  * In both cases, the key is `OIDplus::authUtils()->makeSecret(["b118abc8-f4ec-11ed-86ca-3c4a92df8582"])`.
52 
 
 43 
 
53 
Temporary auth keys (sent via email etc.):
 44 
Temporary auth keys (sent via email etc.):
54 
* used at plugin forgot RA password (public/091):
 45 
* used at plugin forgot RA password (public/091):
55 
  `makeAuthKey("93a16dbe-f4fb-11ed-b67e-3c4a92df8582:" + email + "/" + timestamp)`
 46 
  `makeAuthKey(["93a16dbe-f4fb-11ed-b67e-3c4a92df8582", email])`
56 
* used at plugin ViaThinkSoft FreeOID activation (public/200):
 47 
* used at plugin ViaThinkSoft FreeOID activation (public/200):
57 
  `makeAuthKey("40c87e20-f4fb-11ed-86ca-3c4a92df8582:" + email + "/" + timestamp)`
 48 
  `makeAuthKey(["40c87e20-f4fb-11ed-86ca-3c4a92df8582", email])`
58 
* used at plugin invite RA (ra/092):
 49 
* used at plugin invite RA (ra/092):
59 
  `makeAuthKey("ed840c3e-f4fa-11ed-b67e-3c4a92df8582:" + email + "/" + timestamp)`
 50 
  `makeAuthKey(["ed840c3e-f4fa-11ed-b67e-3c4a92df8582", email])`
60 
* used at plugin change RA email (ra/102):
 51 
* used at plugin change RA email (ra/102):
61 
  `makeAuthKey("5ef24124-f4fb-11ed-b67e-3c4a92df8582:" + old_email + "/" + new_email + "/" + timestamp)`
 52 
  `makeAuthKey(["5ef24124-f4fb-11ed-b67e-3c4a92df8582", old_email, new_email])`
62 
 
 53 
 
63 
Plugin OID-IP (public/100):
 54 
Plugin OID-IP (public/100):
64 
- Authentication token for hidden OIDs = `smallhash(OIDplus::authUtils()->makeSecret("d8f44c7c-f4e9-11ed-86ca-3c4a92df8582:" + id))`
 55 
- Authentication token for hidden OIDs = `smallhash(OIDplus::authUtils()->makeSecret(["d8f44c7c-f4e9-11ed-86ca-3c4a92df8582", id]))`
65 
 
 56 
 
66 
Plugin VNag version check (admin/901):
 57 
Plugin VNag version check (admin/901):
67 
- Webreader password = `OIDplus::authUtils()->makeSecret("65d9f488-f4eb-11ed-b67e-3c4a92df8582")`
 58 
- Webreader password = `OIDplus::authUtils()->makeSecret(["65d9f488-f4eb-11ed-b67e-3c4a92df8582"])`
68 
 
 59 
 
69 
Plugin RDAP (frdl):
 60 
Plugin RDAP (frdl):
70 
- `OIDplus::authUtils()->makeSecret("cee75760-f4f8-11ed-b67e-3c4a92df8582")` is used to generate a cache filename
 61 
- `OIDplus::authUtils()->makeSecret(["cee75760-f4f8-11ed-b67e-3c4a92df8582"])` is used to generate a cache filename
71 
 
 62 
 
72 
Plugin VTS Client Challenge Captcha:
 63 
Plugin VTS Client Challenge Captcha:
73 
- Challenge integrity : `OIDplus::authUtils()->makeAuthKey("797bfc34-f4fa-11ed-86ca-3c4a92df8582:" + challenge)`
 64 
- Challenge integrity : `OIDplus::authUtils()->makeAuthKey(["797bfc34-f4fa-11ed-86ca-3c4a92df8582", challenge])`
74 
- Cache filename : `"vts_client_challenge_" + OIDplus::authUtils()->makeSecret("461f4a9e-f4fa-11ed-86ca-3c4a92df8582:" + ipTarget + "/" + random) + ".tmp"`
 65 
- Cache filename : `"vts_client_challenge_" + OIDplus::authUtils()->makeSecret(["461f4a9e-f4fa-11ed-86ca-3c4a92df8582", ipTarget, random]) + ".tmp"`
75 
 
 66 
 
76 
GUID Registry
 67 
GUID Registry
77 
-------------
 68 
-------------
78 
 
 69 
 
79 
The "real GUIDs" are documented at the [ViaThinkSoft OIDplus Registration Authority](https://oidplus.viathinksoft.com/oidplus/?goto=guid%3Aoidplus%2FauthRealms).
70 
The "realm GUIDs" are documented at the [ViaThinkSoft OIDplus Registration Authority](https://oidplus.viathinksoft.com/oidplus/?goto=guid%3Aoidplus%2FauthRealms).