legacy-libs/grpc/deps/grpc/src/core/lib/security/credentials/jwt/jwt_verifier.h

   1 /*
   2  *
   3  * Copyright 2015 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPC_CORE_LIB_SECURITY_CREDENTIALS_JWT_JWT_VERIFIER_H
  20 #define GRPC_CORE_LIB_SECURITY_CREDENTIALS_JWT_JWT_VERIFIER_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include "src/core/lib/iomgr/pollset.h"
  25 #include "src/core/lib/json/json.h"
  26
  27 #include <grpc/slice.h>
  28 #include <grpc/support/time.h>
  29
  30 /* --- Constants. --- */
  31
  32 #define GRPC_OPENID_CONFIG_URL_SUFFIX "/.well-known/openid-configuration"
  33 #define GRPC_GOOGLE_SERVICE_ACCOUNTS_EMAIL_DOMAIN "gserviceaccount.com"
  34 #define GRPC_GOOGLE_SERVICE_ACCOUNTS_KEY_URL_PREFIX \
  35   "www.googleapis.com/robot/v1/metadata/x509"
  36
  37 /* --- grpc_jwt_verifier_status. --- */
  38
  39 typedef enum {
  40   GRPC_JWT_VERIFIER_OK = 0,
  41   GRPC_JWT_VERIFIER_BAD_SIGNATURE,
  42   GRPC_JWT_VERIFIER_BAD_FORMAT,
  43   GRPC_JWT_VERIFIER_BAD_AUDIENCE,
  44   GRPC_JWT_VERIFIER_KEY_RETRIEVAL_ERROR,
  45   GRPC_JWT_VERIFIER_TIME_CONSTRAINT_FAILURE,
  46   GRPC_JWT_VERIFIER_BAD_SUBJECT,
  47   GRPC_JWT_VERIFIER_GENERIC_ERROR
  48 } grpc_jwt_verifier_status;
  49
  50 const char* grpc_jwt_verifier_status_to_string(grpc_jwt_verifier_status status);
  51
  52 /* --- grpc_jwt_claims. --- */
  53
  54 typedef struct grpc_jwt_claims grpc_jwt_claims;
  55
  56 void grpc_jwt_claims_destroy(grpc_jwt_claims* claims);
  57
  58 /* Returns the whole JSON tree of the claims. */
  59 const grpc_json* grpc_jwt_claims_json(const grpc_jwt_claims* claims);
  60
  61 /* Access to registered claims in https://tools.ietf.org/html/rfc7519#page-9 */
  62 const char* grpc_jwt_claims_subject(const grpc_jwt_claims* claims);
  63 const char* grpc_jwt_claims_issuer(const grpc_jwt_claims* claims);
  64 const char* grpc_jwt_claims_id(const grpc_jwt_claims* claims);
  65 const char* grpc_jwt_claims_audience(const grpc_jwt_claims* claims);
  66 gpr_timespec grpc_jwt_claims_issued_at(const grpc_jwt_claims* claims);
  67 gpr_timespec grpc_jwt_claims_expires_at(const grpc_jwt_claims* claims);
  68 gpr_timespec grpc_jwt_claims_not_before(const grpc_jwt_claims* claims);
  69
  70 /* --- grpc_jwt_verifier. --- */
  71
  72 typedef struct grpc_jwt_verifier grpc_jwt_verifier;
  73
  74 typedef struct {
  75   /* The email domain is the part after the @ sign. */
  76   const char* email_domain;
  77
  78   /* The key url prefix will be used to get the public key from the issuer:
  79      https://<key_url_prefix>/<issuer_email>
  80      Therefore the key_url_prefix must NOT contain https://. */
  81   const char* key_url_prefix;
  82 } grpc_jwt_verifier_email_domain_key_url_mapping;
  83
  84 /* Globals to control the verifier. Not thread-safe. */
  85 extern gpr_timespec grpc_jwt_verifier_clock_skew;
  86 extern grpc_millis grpc_jwt_verifier_max_delay;
  87
  88 /* The verifier can be created with some custom mappings to help with key
  89    discovery in the case where the issuer is an email address.
  90    mappings can be NULL in which case num_mappings MUST be 0.
  91    A verifier object has one built-in mapping (unless overridden):
  92    GRPC_GOOGLE_SERVICE_ACCOUNTS_EMAIL_DOMAIN ->
  93    GRPC_GOOGLE_SERVICE_ACCOUNTS_KEY_URL_PREFIX.*/
  94 grpc_jwt_verifier* grpc_jwt_verifier_create(
  95     const grpc_jwt_verifier_email_domain_key_url_mapping* mappings,
  96     size_t num_mappings);
  97
  98 /*The verifier must not be destroyed if there are still outstanding callbacks.*/
  99 void grpc_jwt_verifier_destroy(grpc_jwt_verifier* verifier);
 100
 101 /* User provided callback that will be called when the verification of the JWT
 102    is done (maybe in another thread).
 103    It is the responsibility of the callee to call grpc_jwt_claims_destroy on
 104    the claims. */
 105 typedef void (*grpc_jwt_verification_done_cb)(void* user_data,
 106                                               grpc_jwt_verifier_status status,
 107                                               grpc_jwt_claims* claims);
 108
 109 /* Verifies for the JWT for the given expected audience. */
 110 void grpc_jwt_verifier_verify(grpc_jwt_verifier* verifier,
 111                               grpc_pollset* pollset, const char* jwt,
 112                               const char* audience,
 113                               grpc_jwt_verification_done_cb cb,
 114                               void* user_data);
 115
 116 /* --- TESTING ONLY exposed functions. --- */
 117
 118 grpc_jwt_claims* grpc_jwt_claims_from_json(grpc_json* json,
 119                                            const grpc_slice& buffer);
 120 grpc_jwt_verifier_status grpc_jwt_claims_check(const grpc_jwt_claims* claims,
 121                                                const char* audience);
 122 const char* grpc_jwt_issuer_email_domain(const char* issuer);
 123
 124 #endif /* GRPC_CORE_LIB_SECURITY_CREDENTIALS_JWT_JWT_VERIFIER_H */