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 24 #include <stddef.h> 25 26 #include <grpc/support/time.h> 27 28 #include "src/core/lib/gprpp/time.h" 29 #include "src/core/lib/iomgr/iomgr_fwd.h" 30 #include "src/core/lib/json/json.h" 31 32 // --- Constants. --- 33 34 #define GRPC_OPENID_CONFIG_URL_SUFFIX "/.well-known/openid-configuration" 35 #define GRPC_GOOGLE_SERVICE_ACCOUNTS_EMAIL_DOMAIN "gserviceaccount.com" 36 #define GRPC_GOOGLE_SERVICE_ACCOUNTS_KEY_URL_PREFIX \ 37 "www.googleapis.com/robot/v1/metadata/x509" 38 39 // --- grpc_jwt_verifier_status. --- 40 41 typedef enum { 42 GRPC_JWT_VERIFIER_OK = 0, 43 GRPC_JWT_VERIFIER_BAD_SIGNATURE, 44 GRPC_JWT_VERIFIER_BAD_FORMAT, 45 GRPC_JWT_VERIFIER_BAD_AUDIENCE, 46 GRPC_JWT_VERIFIER_KEY_RETRIEVAL_ERROR, 47 GRPC_JWT_VERIFIER_TIME_CONSTRAINT_FAILURE, 48 GRPC_JWT_VERIFIER_BAD_SUBJECT, 49 GRPC_JWT_VERIFIER_GENERIC_ERROR 50 } grpc_jwt_verifier_status; 51 52 const char* grpc_jwt_verifier_status_to_string(grpc_jwt_verifier_status status); 53 54 // --- grpc_jwt_claims. --- 55 56 typedef struct grpc_jwt_claims grpc_jwt_claims; 57 58 void grpc_jwt_claims_destroy(grpc_jwt_claims* claims); 59 60 // Returns the whole JSON tree of the claims. 61 const grpc_core::Json* grpc_jwt_claims_json(const grpc_jwt_claims* claims); 62 63 // Access to registered claims in https://tools.ietf.org/html/rfc7519#page-9 64 const char* grpc_jwt_claims_subject(const grpc_jwt_claims* claims); 65 const char* grpc_jwt_claims_issuer(const grpc_jwt_claims* claims); 66 const char* grpc_jwt_claims_id(const grpc_jwt_claims* claims); 67 const char* grpc_jwt_claims_audience(const grpc_jwt_claims* claims); 68 gpr_timespec grpc_jwt_claims_issued_at(const grpc_jwt_claims* claims); 69 gpr_timespec grpc_jwt_claims_expires_at(const grpc_jwt_claims* claims); 70 gpr_timespec grpc_jwt_claims_not_before(const grpc_jwt_claims* claims); 71 72 // --- grpc_jwt_verifier. --- 73 74 typedef struct grpc_jwt_verifier grpc_jwt_verifier; 75 76 struct grpc_jwt_verifier_email_domain_key_url_mapping { 77 // The email domain is the part after the @ sign. 78 const char* email_domain; 79 80 // The key url prefix will be used to get the public key from the issuer: 81 // https://<key_url_prefix>/<issuer_email> 82 // Therefore the key_url_prefix must NOT contain https://. 83 const char* key_url_prefix; 84 }; 85 // Globals to control the verifier. Not thread-safe. 86 extern gpr_timespec grpc_jwt_verifier_clock_skew; 87 extern grpc_core::Duration grpc_jwt_verifier_max_delay; 88 89 // The verifier can be created with some custom mappings to help with key 90 // discovery in the case where the issuer is an email address. 91 // mappings can be NULL in which case num_mappings MUST be 0. 92 // A verifier object has one built-in mapping (unless overridden): 93 // GRPC_GOOGLE_SERVICE_ACCOUNTS_EMAIL_DOMAIN -> 94 // GRPC_GOOGLE_SERVICE_ACCOUNTS_KEY_URL_PREFIX. 95 grpc_jwt_verifier* grpc_jwt_verifier_create( 96 const grpc_jwt_verifier_email_domain_key_url_mapping* mappings, 97 size_t num_mappings); 98 99 // The verifier must not be destroyed if there are still outstanding callbacks. 100 void grpc_jwt_verifier_destroy(grpc_jwt_verifier* verifier); 101 102 // User provided callback that will be called when the verification of the JWT 103 // is done (maybe in another thread). 104 // It is the responsibility of the callee to call grpc_jwt_claims_destroy on 105 // the claims. 106 typedef void (*grpc_jwt_verification_done_cb)(void* user_data, 107 grpc_jwt_verifier_status status, 108 grpc_jwt_claims* claims); 109 110 // Verifies for the JWT for the given expected audience. 111 void grpc_jwt_verifier_verify(grpc_jwt_verifier* verifier, 112 grpc_pollset* pollset, const char* jwt, 113 const char* audience, 114 grpc_jwt_verification_done_cb cb, 115 void* user_data); 116 117 // --- TESTING ONLY exposed functions. --- 118 119 grpc_jwt_claims* grpc_jwt_claims_from_json(grpc_core::Json json); 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_SRC_CORE_LIB_SECURITY_CREDENTIALS_JWT_JWT_VERIFIER_H 125