Skip to content

Commit ede2488

Browse files
sameeragsameerag
authored
Merge pull request #67 from sameerag/dbsc-e
Dbsc(e)
2 parents beb7c6d + bcbb500 commit ede2488

11 files changed

+580
-1
lines changed

‎DBSCE/DBSC(E).svg

+1
Loading

‎DBSCE/DeviceRegistration.svg

+1
Loading

‎DBSCE/IDPCallsPrivateLocalKeyHelper.svg

+1
Loading

‎DBSCE/IDPCallsPublicLocalKeyHelper.svg

+1
Loading

‎DBSCE/IDPSameAsRP-CallsPublicLocalKeyHelper.svg

+1
Loading

‎DBSCE/LocalKeyHelper-Android.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
<span style="color:red">!!! DRAFT - Please note this page is still in draft as we work on platform specific details
2+
</span>
3+
4+
### Local Key Helper on Android
5+
On android platform a Local Key Helper is a protocol interface (`ILocalKeyHelper.java`), and its implementation (`LocalKeyHelperImpl.java`) is yet to be determined.
6+
7+
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.
8+
9+
#### Registering LocalkeyHelpers with Browser Interaction
10+
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.
11+
12+
```xml
13+
<provider
14+
android:authorities="com.custombrowser.localkeyhelpersregistration"
15+
android:name="LocalKeyHelpersRegistrationProvider"
16+
android:exported="true" >
17+
</provider>
18+
```
19+
20+
##### Implementing localkeyhelpersregistration provider in Browser
21+
Browser application implements `localkeyhelpersregistration` content provider and provides path `/register` for the local key helpers to register themselves.
22+
When the LocalKeyHelper queries the browser's content provider, it register itself with the browser.
23+
Example implementation.
24+
``` java
25+
public class LocalKeyHelperConsumerProvider extends ContentProvider {
26+
public static final String AUTHORITY = "com.custombrowser.localkeyhelpersregistration";
27+
private static final UriMatcher uriMatcher = new UriMatcher(UriMatcher.NO_MATCH);
28+
29+
static {
30+
uriMatcher.addURI("AUTHORITY", "/register", 1);
31+
}
32+
33+
@Override
34+
public boolean onCreate() {
35+
return true;
36+
}
37+
38+
@Nullable
39+
@Override
40+
public Cursor query(@NonNull Uri uri, @Nullable String[] projection, @Nullable String selection, @Nullable String[] selectionArgs, @Nullable String sortOrder) {
41+
switch (uriMatcher.match(uri)) {
42+
case 1 :
43+
return new MatrixCursor(new String[0]) {
44+
@Override
45+
public Bundle getExtras() {
46+
Bundle bundle = new Bundle();
47+
bundle.putBoolean("registered", true);
48+
return bundle;
49+
}
50+
};
51+
default:
52+
throw new IllegalArgumentException("Unknown URI: " + uri);
53+
}
54+
}
55+
...
56+
57+
}
58+
```
59+
##### Calling Browser Content Provider to register a local key helper.
60+
LocalKeyhelpers make the browser content provider visible to them by adding queries tag with browser content provider authority to their manifest file.
61+
```xml
62+
<queries>
63+
<provider android:authorities="com.custombrowser.localkeyhelpersregistration" />
64+
</queries>
65+
```
66+
67+
LocalKeyHelper call the browser's content provider to register itself with the browser.
68+
```java
69+
Uri uri = Uri.parse("content://com.custombrowser.localkeyhelpersregistration/register");
70+
Cursor cursor = getContentResolver().query(uri, null, null, null, null);
71+
if (cursor != null) {
72+
try {
73+
val resultBundle = cursor.extras
74+
if (resultBundle != null) {
75+
val registered = resultBundle.getBoolean("registered")
76+
Log.i("TAG", "Registered: $registered")
77+
} else {
78+
Log.i("TAG", "Failed to register.")
79+
}
80+
} finally {
81+
cursor.close();
82+
}
83+
}
84+
```
85+
86+
#### Calling Local KeyHelpers from Browser
87+
Once a localkeyhelper is registered with the Browser application, the browser can query the Local KeyHelper's content providers without defining the query tag.
88+
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.
89+
90+
##### Sample Manifest Entry for Local KeyHelper Content Provider
91+
```xml
92+
<provider
93+
android:authorities="com.contoso.localkeyhelper"
94+
android:name="ContosoLocalKeyHelperProvider" />
95+
```
96+
97+
##### Implementing the ContentProvider in Local KeyHelper
98+
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.
99+
100+
```java
101+
public class LocalKeyHelperProvider extends ContentProvider {
102+
public static final String AUTHORITY = "com.contoso.localkeyhelper";
103+
private static final UriMatcher uriMatcher = new UriMatcher(UriMatcher.NO_MATCH);
104+
105+
static {
106+
uriMatcher.addURI(AUTHORITY, "sample_api_path", 1);
107+
// Add more paths as needed
108+
}
109+
110+
@Override
111+
public boolean onCreate() {
112+
return true;
113+
}
114+
115+
@Nullable
116+
@Override
117+
public Cursor query(@NonNull Uri uri, @Nullable String[] projection, @Nullable String selection, @Nullable String[] selectionArgs, @Nullable String sortOrder) {
118+
switch (uriMatcher.match(uri)) {
119+
// call the Implementation specific api based on the path
120+
default:
121+
throw new IllegalArgumentException("Unknown URI: " + uri);
122+
}
123+
}
124+
}
125+
```

‎DBSCE/LocalKeyHelper-Mac.md

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<span style="color:red">!!! DRAFT - Please note this page is still in draft as we work on platform specific details
2+
</span>
3+
4+
### Local key helper on Mac
5+
6+
On macOS, a Local Key Helper is a protocol (`LocalKeyHelper.h`), and its implementation (`LocalKeyHelperImpl.h`/`LocalKeyHelperImpl.m`) is yet to be determined.
7+
8+
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.
9+
10+
Here is an example of the Local Key Helper XPC service plist:
11+
12+
```xml
13+
<?xml version="1.0" encoding="UTF-8"?>
14+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
15+
<plist version="1.0">
16+
<dict>
17+
<key>Label</key>
18+
<string>com.contoso.LocalKeyHelper</string>
19+
<key>Program</key>
20+
<string>/pathToXcpService/LocalKepHelper.xpc/Contents/MacOS/LocalKepHelper</string>
21+
<key>KeepAlive</key>
22+
<true/>
23+
<key>MachServices</key>
24+
<dict>
25+
<key>com.contoso.LocalKeyHelper</key>
26+
<true/>
27+
</dict>
28+
</dict>
29+
</plist>
30+
```
31+
32+
Please refer to Apple documentation for building and configuring XPC services.
33+
34+
When the browser (e.g. Chrome) communicates with this service, it needs to establish a service connection first.
35+
Here is an example of starting a new connection with the Local Key Helper:
36+
37+
```objective-c
38+
// Start a new connection by providing the Local Key Helper defined in the plist
39+
NSXPCConnection* localKeyhelper = [[NSXPCConnection alloc] initWithMachServiceName:@"com.contoso.LocalKeyHelper"];
40+
41+
// Make the connection conform to the defined Local Key Helper protocol
42+
[localKeyhelper setRemoteObjectInterface:[NSXPCInterface interfaceWithProtocol:@protocol(LocalKeyHelper)]];
43+
```
44+
45+
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.
46+
47+
**Note:**
48+
49+
- 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).
50+
- The input and output parameters of the XPC service should follow the `NSSecureCoding` protocol.
51+
- Non-sandboxed applications can communicate directly to the XPC service.
52+
53+
#### Deployment of a 3rd party local key helper
54+
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:
55+
56+
**1st type: files that define the Local Key Helpers**
57+
58+
i.e.
59+
````
60+
com.provider1.LocalKeyHelper.json (if helper was installed)
61+
com.provider2.LocalKeyHelper.json (if helper was installed)
62+
com.provider3.LocalKeyHelper.json (if helper was installed)
63+
````
64+
For example:
65+
````
66+
com.contoso.LocalKeyHelper.json
67+
````
68+
69+
Within the file:
70+
71+
```json
72+
{
73+
"provider": "contoso",
74+
"xpc": // Local key helper type
75+
{
76+
"service": "com.contoso.LocalKeyHelper", // Service name/API activation id
77+
"version": "0.0.1", // Helper service version
78+
"Idp_resource":"com.contoso.LocalKeyHelper.idP.json" // File path to IdP URL allow-list
79+
}
80+
}
81+
```
82+
83+
**2nd type: files that defines the allow-list for IdP URLs:**
84+
85+
For example:
86+
````
87+
com.contoso.LocalKeyHelper.idP.json
88+
````
89+
90+
```json
91+
{
92+
"urls": ["*.contoso1.com", "login.contoso1.net", "login.contoso2.com"],
93+
}
94+
```
95+
96+
The MDM service can run an on-device script to update the URLs in this file without changing the Local Key Helper definition file.

‎DBSCE/LocalKeyHelper-Windows.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
### Local key helper on Windows
2+
3+
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)
4+
5+
#### Deployment of a 3rd party local key helper.
6+
7+
Local key helpers will be deployed using registry.
8+
9+
The base registry key is:
10+
11+
```
12+
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\<Company>\<Browser>\LocalKeyHelperList]
13+
```
14+
15+
i.e.
16+
17+
```
18+
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\LocalKeyHelperList]
19+
20+
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\LocalKeyHelperList]
21+
```
22+
23+
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.
24+
25+
```
26+
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\<Company>\<Browser>\LocalKeyHelperList\<LocalKeyHelperId>]
27+
@="<Scheme>:<API activation ID>"
28+
```
29+
30+
Here is example:
31+
32+
```
33+
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\LocalKeyHelperList\login.contoso.com]
34+
@="progid:App.Component.1.0"
35+
36+
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\LocalKeyHelperList\login.fabrikam.com]
37+
@="clsid:3AD05D77-6885-4BAF-A727-D30690A2A28A"
38+
```
39+
40+
Currently the supported schemes are:
41+
42+
1. clsid: \<GUID\> - CLSID of a COM class that implements the Local Key Helper.
43+
2. progid:\<ProgId string\> - [a programic identifier](https://learn.microsoft.com/en-us/windows/win32/com/-progid--key) of the local key helper.
44+
45+
This scheme can be extended by other schemes in future.
46+
The local key helper registry key can have extra values, which we can use for in future.
47+
48+
Here is a visual example how Local key helper is organized:
49+
50+
![Local key helper registry key](./images/keyhelper-reg.png)
51+
52+
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.
53+
54+
#### Well-known local key helpers on Windows
55+
56+
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.
57+

0 commit comments

Comments
 (0)