AppCheck API Proposal - Draft

app_check/samples/sample_code.cc

@@ -0,0 +1,68 @@
+#include "firebase/app.h"
+#include "firebase/app_check/firebase_app_check.h"
+
+// Create a custom AppCheck provider.
+
+class YourCustomAppCheckProvider
+ : public ::firebase::app_check::AppCheckProvider {
+ public:
+ Future<::firebase::app_check::AppCheckToken> GetToken() override;
+}
+
+Future<::firebase::app_check::AppCheckToken>
+YourCustomAppCheckProvider::GetToken() {
+ // Logic to exchange proof of authenticity for an App Check token and
+ // expiration time.
+ // ...
+
+ // Refresh the token early to handle clock skew.
+ long exp_millis = expiration_from_server * 1000 - 60000;
+
+ // Create and return AppCheckToken struct.
+ ::firebase::app_check::AppCheckToken app_check_token(token_from_server,
+ exp_millis);
+ return app_check_token;
+}
+
+// Create a factory for a custom provider.
+
+class YourCustomAppCheckProviderFactory
+ : public ::firebase::app_check::AppCheckProviderFactory {
+ public:
+ static DebugAppCheckProviderFactory GetInstance();
+
+ ::firebase::app_check::AppCheckProvider* CreateProvider(
+ const ::firebase::App& app) override;
+
+}
+
+::firebase::app_check::AppCheckProvider*
+YourCustomAppCheckProviderFactory::CreateProvider(const ::firebase::App& app) {
+ // Create and return an AppCheckProvider object.
+ return new YourCustomAppCheckProvider(app);
+}
+
+// Initialize App Check (with a given provider factory)
+
+// Note: SetAppCheckProviderFactory must be called before App::Create()
+// to be compatible with iOS
+
+::firebase::app_check::AppCheck.SetAppCheckProviderFactory(
+ YourCustomAppCheckProviderFactory.GetInstance());
+::firebase::App* app = ::firebase::App::Create();
+::firebase::app_check::AppCheck* app_check =
+ ::firebase::app_check::AppCheck.getInstance();
+
+// Add a listener for token changes.
+
+class MyAppCheckListener : public ::firebase::app_check::AppCheckListener {
+ public:
+ void OnAppCheckTokenChanged(
+ const ::firebase::app_check::AppCheckToken& token) override {
+ // Use the token to authorize requests to non-firebase backends.
+ // ...
+ }
+};
+
+MyAppCheckListener app_check_listener;
+app_check->addAppCheckListener(&state_change_listener);

app_check/src/attest/app_attest_provider_factory.h

@@ -0,0 +1,28 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Implementation of an {@link AppCheckProviderFactory} that builds {@link
+ * AppAttestCheckProvider}s. This is the default implementation.
+ */
+class AppAttestCheckProviderFactory : public AppCheckProviderFactory {
+ public:
+ /**
+ * Gets an instance of this class for installation into a {@link
+ * com.google.firebase.appcheck.AppCheck} instance.
+ */
+ static AppAttestCheckProviderFactory GetInstance();
+
+ AppCheckProvider* CreateProvider(const App& app) override;
+}

app_check/src/include/firebase/app_check.h

@@ -0,0 +1,28 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace firebase {
+namespace app_check {
+
+#ifndef FIREBASE_APP_CHECK_SRC_INCLUDE_FIREBASE_APP_CHECK_H_
+#define FIREBASE_APP_CHECK_SRC_INCLUDE_FIREBASE_APP_CHECK_H_
+
+#include "firebase/app_check/app_check_provider.h"
+#include "firebase/app_check/app_check_provider_factory.h"
+#include "firebase/app_check/firebase_app_check.h"
+
+#endif // FIREBASE_APP_CHECK_SRC_INCLUDE_FIREBASE_APP_CHECK_H_
+
+} // namespace app_check
+} // namespace firebase

app_check/src/include/firebase/app_check/app_check_provider.h

@@ -0,0 +1,37 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace firebase {
+namespace app_check {
+
+/**
+ * Interface for a provider that generates {@link AppCheckToken}s. This provider
+ * can be called at any time by any Firebase library that depends (optionally or
+ * otherwise) on {@link AppCheckToken}s. This provider is responsible for
+ * determining if it can create a new token at the time of the call and
+ * returning that new token if it can.
+ */
+class AppCheckProvider {
+ public:
+ virtual ~AppCheckProvider();
+ /**
+ * Returns a {@link Future} which resolves to a valid {@link AppCheckToken} or
+ * an {@link Exception} in the case that an unexpected failure occurred while
+ * getting the token.
+ */
+ virtual Future<AppCheckToken> GetToken() = 0;
+}
+
+} // namespace app_check
+} // namespace firebase

app_check/src/include/firebase/app_check/app_check_provider_factory.h

@@ -0,0 +1,30 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace firebase {
+namespace app_check {
+
+/** Interface for a factory that generates {@link AppCheckProvider}s. */
+class AppCheckProviderFactory {
+ public:
+ virtual ~AppCheckProviderFactory();
+ /**
+ * Gets the {@link AppCheckProvider} associated with the given {@link
+ * FirebaseApp} instance, or creates one if none already exists.
+ */
+ virtual AppCheckProvider* CreateProvider(const App& app) = 0;
+}
+
+} // namespace app_check
+} // namespace firebase

app_check/src/include/firebase/app_check/debug_app_check_provider_factory.h

@@ -0,0 +1,37 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace firebase {
+namespace app_check {
+
+/**
+ * Implementation of an {@link AppCheckProviderFactory} that builds {@link
+ * DebugAppCheckProvider}s.
+ */
+class DebugAppCheckProviderFactory : public AppCheckProviderFactory {
+ public:
+ /**
+ * Gets an instance of this class for installation into a {@link
+ * com.google.firebase.appcheck.AppCheck} instance. If no debug secret is
+ * found in {@link android.content.SharedPreferences}, a new debug secret will
+ * be generated and printed to the logcat. The debug secret should then be
+ * added to the allow list in the Firebase Console.
+ */
+ static DebugAppCheckProviderFactory GetInstance();
+
+ AppCheckProvider* CreateProvider(const App& app) override;
+}
+
+} // namespace app_check
+} // namespace firebase

app_check/src/include/firebase/app_check/firebase_app_check.h

@@ -0,0 +1,107 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace firebase {
+namespace app_check {
+
+/// Struct to hold tokens emitted by the Firebase App Check service which are
+/// minted upon a successful application verification. These tokens are the
+/// federated output of a verification flow, the structure of which is
+/// independent of the mechanism by which the application was verified.
+struct AppCheckToken {
+ /// A Firebase App Check token.
+ std::string token;
+
+ /// A Firebase App Check token expiration date in the device local time.
+ int64_t expire_time_millis;
+}
+
+class AppCheckListener {
+ virtual ~AppCheckListener();
+ /**
+ * This method gets invoked on the UI thread on changes to the token state.
+ * Does not trigger on token expiry.
+ */
+ virtual void OnAppCheckTokenChanged(const AppCheckToken& token) = 0;
+}
+
+class AppCheck {
+ public:
+ /**
+ * Gets the instance of {@code AppCheck} associated with the given {@link
+ * FirebaseApp} instance.
+ */
+ static AppCheck* GetInstance(::firebase::App* app);
+
+ /**
+ * Installs the given {@link AppCheckProviderFactory}, overwriting any that
+ * were previously associated with this {@code AppCheck} instance. Any {@link
+ * AppCheckTokenListener}s attached to this {@code AppCheck} instance will be
+ * transferred from existing factories to the newly installed one.
+ *
+ * <p>Automatic token refreshing will only occur if the global {@code
+ * isDataCollectionDefaultEnabled} flag is set to true. To allow automatic
+ * token refreshing for Firebase App Check without changing the {@code
+ * isDataCollectionDefaultEnabled} flag for other Firebase SDKs, use {@link
+ * #setAppCheckProviderFactory(AppCheckProviderFactory, bool)} instead or call
+ * {@link #setTokenAutoRefreshEnabled(bool)} after installing the {@code
+ * factory}.
+ *
+ * This method should be called before initializing the Firebase App.
+ */
+ static void SetAppCheckProviderFactory(
+ const AppCheckProviderFactory& factory) = 0;
+
+ /**
+ * Installs the given {@link AppCheckProviderFactory}, overwriting any that
+ * were previously associated with this {@code AppCheck} instance. Any {@link
+ * AppCheckTokenListener}s attached to this {@code AppCheck} instance will be
+ * transferred from existing factories to the newly installed one.
+ *
+ * <p>Automatic token refreshing will only occur if the {@code
+ * isTokenAutoRefreshEnabled} field is set to true. To use the global {@code
+ * isDataCollectionDefaultEnabled} flag for determining automatic token
+ * refreshing, call {@link
+ * #setAppCheckProviderFactory(AppCheckProviderFactory)} instead.
+ *
+ * This method should be called before initializing the Firebase App.
+ */
+ static void SetAppCheckProviderFactory(
+ AppCheckProviderFactory* factory, bool is_token_auto_refresh_enabled) = 0;
+
+ /** Sets the {@code isTokenAutoRefreshEnabled} flag. */
+ static void SetTokenAutoRefreshEnabled(bool is_token_auto_refresh_enabled) =
+ 0;
+
+ /**
+ * Requests a Firebase App Check token. This method should be used ONLY if you
+ * need to authorize requests to a non-Firebase backend. Requests to Firebase
+ * backends are authorized automatically if configured.
+ */
+ Future<AppCheckToken> GetAppCheckToken(bool force_refresh) = 0;
+
+ /**
+ * Registers an {@link AppCheckListener} to changes in the token state. This
+ * method should be used ONLY if you need to authorize requests to a
+ * non-Firebase backend. Requests to Firebase backends are authorized
+ * automatically if configured.
+ */
+ void AddAppCheckListener(AppCheckListener* listener) = 0;
+
+ /** Unregisters an {@link AppCheckListener} to changes in the token state. */
+ void RemoveAppCheckListener(AppCheckListener* listener) = 0;
+}
+
+} // namespace app_check
+} // namespace firebase

app_check/src/playintegrity/play_integrity_app_check_provider_factory.h

@@ -0,0 +1,28 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Implementation of an {@link AppCheckProviderFactory} that builds {@link
+ * PlayIntegrityAppCheckProvider}s. This is the default implementation.
+ */
+class PlayIntegrityAppCheckProviderFactory : public AppCheckProviderFactory {
+ public:
+ /**
+ * Gets an instance of this class for installation into a {@link
+ * com.google.firebase.appcheck.AppCheck} instance.
+ */
+ static PlayIntegrityAppCheckProviderFactory GetInstance();
+
+ AppCheckProvider* CreateProvider(const App& app) override;
+}