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_SRC_CORE_LIB_SECURITY_CREDENTIALS_JWT_JWT_VERIFIER_H 20 #define GRPC_SRC_CORE_LIB_SECURITY_CREDENTIALS_JWT_JWT_VERIFIER_H 21 22 #include <grpc/support/port_platform.h> 23 #include <grpc/support/time.h> 24 #include <stddef.h> 25 26 #include "src/core/lib/iomgr/iomgr_fwd.h" 27 #include "src/core/util/json/json.h" 28 #include "src/core/util/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_core::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 struct grpc_jwt_verifier_email_domain_key_url_mapping { 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 }; 83 // Globals to control the verifier. Not thread-safe. 84 extern gpr_timespec grpc_jwt_verifier_clock_skew; 85 extern grpc_core::Duration grpc_jwt_verifier_max_delay; 86 87 // The verifier can be created with some custom mappings to help with key 88 // discovery in the case where the issuer is an email address. 89 // mappings can be NULL in which case num_mappings MUST be 0. 90 // A verifier object has one built-in mapping (unless overridden): 91 // GRPC_GOOGLE_SERVICE_ACCOUNTS_EMAIL_DOMAIN -> 92 // GRPC_GOOGLE_SERVICE_ACCOUNTS_KEY_URL_PREFIX. 93 grpc_jwt_verifier* grpc_jwt_verifier_create( 94 const grpc_jwt_verifier_email_domain_key_url_mapping* mappings, 95 size_t num_mappings); 96 97 // The verifier must not be destroyed if there are still outstanding callbacks. 98 void grpc_jwt_verifier_destroy(grpc_jwt_verifier* verifier); 99 100 // User provided callback that will be called when the verification of the JWT 101 // is done (maybe in another thread). 102 // It is the responsibility of the callee to call grpc_jwt_claims_destroy on 103 // the claims. 104 typedef void (*grpc_jwt_verification_done_cb)(void* user_data, 105 grpc_jwt_verifier_status status, 106 grpc_jwt_claims* claims); 107 108 // Verifies for the JWT for the given expected audience. 109 void grpc_jwt_verifier_verify(grpc_jwt_verifier* verifier, 110 grpc_pollset* pollset, const char* jwt, 111 const char* audience, 112 grpc_jwt_verification_done_cb cb, 113 void* user_data); 114 115 // --- TESTING ONLY exposed functions. --- 116 117 grpc_jwt_claims* grpc_jwt_claims_from_json(grpc_core::Json json); 118 grpc_jwt_verifier_status grpc_jwt_claims_check(const grpc_jwt_claims* claims, 119 const char* audience); 120 const char* grpc_jwt_issuer_email_domain(const char* issuer); 121 122 #endif // GRPC_SRC_CORE_LIB_SECURITY_CREDENTIALS_JWT_JWT_VERIFIER_H 123