GRPC Core 0.10.0.0

- Main Page
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
jwt_verifier.h
Go to the documentation of this file.
1 /*
2 *
3 * Copyright 2015, Google Inc.
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
8 * met:
9 *
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimser.
12 * * Redistributions in binary form must reproduce the above
13 * copyright notice, this list of conditions and the following disclaimser
14 * in the documentation and/or other materials provided with the
15 * distribution.
16 * * Neither the name of Google Inc. nor the names of its
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
33
34 #ifndef GRPC_INTERNAL_CORE_SECURITY_JWT_VERIFIER_H
35 #define GRPC_INTERNAL_CORE_SECURITY_JWT_VERIFIER_H
36
37 #include "src/core/iomgr/pollset.h"
38 #include "src/core/json/json.h"
39
40 #include <grpc/support/slice.h>
41 #include <grpc/support/time.h>
42
43 /* --- Constants. --- */
44
45 #define GRPC_OPENID_CONFIG_URL_SUFFIX "/.well-known/openid-configuration"
46 #define GRPC_GOOGLE_SERVICE_ACCOUNTS_EMAIL_DOMAIN \
47 "developer.gserviceaccount.com"
48 #define GRPC_GOOGLE_SERVICE_ACCOUNTS_KEY_URL_PREFIX \
49 "www.googleapis.com/robot/v1/metadata/x509"
50
51 /* --- grpc_jwt_verifier_status. --- */
52
53 typedef enum {
54 GRPC_JWT_VERIFIER_OK = 0,
55 GRPC_JWT_VERIFIER_BAD_SIGNATURE,
56 GRPC_JWT_VERIFIER_BAD_FORMAT,
57 GRPC_JWT_VERIFIER_BAD_AUDIENCE,
58 GRPC_JWT_VERIFIER_KEY_RETRIEVAL_ERROR,
59 GRPC_JWT_VERIFIER_TIME_CONSTRAINT_FAILURE,
60 GRPC_JWT_VERIFIER_GENERIC_ERROR
61 } grpc_jwt_verifier_status;
62
63 const char *grpc_jwt_verifier_status_to_string(grpc_jwt_verifier_status status);
64
65 /* --- grpc_jwt_claims. --- */
66
67 typedef struct grpc_jwt_claims grpc_jwt_claims;
68
69 void grpc_jwt_claims_destroy(grpc_jwt_claims *claims);
70
71 /* Returns the whole JSON tree of the claims. */
72 const grpc_json *grpc_jwt_claims_json(const grpc_jwt_claims *claims);
73
74 /* Access to registered claims in https://tools.ietf.org/html/rfc7519#page-9 */
75 const char *grpc_jwt_claims_subject(const grpc_jwt_claims *claims);
76 const char *grpc_jwt_claims_issuer(const grpc_jwt_claims *claims);
77 const char *grpc_jwt_claims_id(const grpc_jwt_claims *claims);
78 const char *grpc_jwt_claims_audience(const grpc_jwt_claims *claims);
79 gpr_timespec grpc_jwt_claims_issued_at(const grpc_jwt_claims *claims);
80 gpr_timespec grpc_jwt_claims_expires_at(const grpc_jwt_claims *claims);
81 gpr_timespec grpc_jwt_claims_not_before(const grpc_jwt_claims *claims);
82
83 /* --- grpc_jwt_verifier. --- */
84
85 typedef struct grpc_jwt_verifier grpc_jwt_verifier;
86
87 typedef struct {
88 /* The email domain is the part after the @ sign. */
89 const char *email_domain;
90
91 /* The key url prefix will be used to get the public key from the issuer:
92 https://<key_url_prefix>/<issuer_email>
93 Therefore the key_url_prefix must NOT contain https://. */
94 const char *key_url_prefix;
95 } grpc_jwt_verifier_email_domain_key_url_mapping;
96
97 /* Globals to control the verifier. Not thread-safe. */
98 extern gpr_timespec grpc_jwt_verifier_clock_skew;
99 extern gpr_timespec grpc_jwt_verifier_max_delay;
100
101 /* The verifier can be created with some custom mappings to help with key
102 discovery in the case where the issuer is an email address.
103 mappings can be NULL in which case num_mappings MUST be 0.
104 A verifier object has one built-in mapping (unless overridden):
105 GRPC_GOOGLE_SERVICE_ACCOUNTS_EMAIL_DOMAIN ->
106 GRPC_GOOGLE_SERVICE_ACCOUNTS_KEY_URL_PREFIX.*/
107 grpc_jwt_verifier *grpc_jwt_verifier_create(
108 const grpc_jwt_verifier_email_domain_key_url_mapping *mappings,
109 size_t num_mappings);
110
111 /*The verifier must not be destroyed if there are still outstanding callbacks.*/
112 void grpc_jwt_verifier_destroy(grpc_jwt_verifier *verifier);
113
114 /* User provided callback that will be called when the verification of the JWT
115 is done (maybe in another thread).
116 It is the responsibility of the callee to call grpc_jwt_claims_destroy on
117 the claims. */
118 typedef void (*grpc_jwt_verification_done_cb)(void *user_data,
119 grpc_jwt_verifier_status status,
120 grpc_jwt_claims *claims);
121
122 /* Verifies for the JWT for the given expected audience. */
123 void grpc_jwt_verifier_verify(grpc_jwt_verifier *verifier,
124 grpc_pollset *pollset, const char *jwt,
125 const char *audience,
126 grpc_jwt_verification_done_cb cb,
127 void *user_data);
128
129 /* --- TESTING ONLY exposed functions. --- */
130
131 grpc_jwt_claims *grpc_jwt_claims_from_json(grpc_json *json, gpr_slice buffer);
132 grpc_jwt_verifier_status grpc_jwt_claims_check(const grpc_jwt_claims *claims,
133 const char *audience);
134
135 #endif /* GRPC_INTERNAL_CORE_SECURITY_JWT_VERIFIER_H */
136
grpc_jwt_claims_subject
const char * grpc_jwt_claims_subject(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:203
grpc_jwt_verifier_verify
void grpc_jwt_verifier_verify(grpc_jwt_verifier *verifier, grpc_pollset *pollset, const char *jwt, const char *audience, grpc_jwt_verification_done_cb cb, void *user_data)
Definition: jwt_verifier.c:754
time.h
grpc_jwt_verification_done_cb
void(* grpc_jwt_verification_done_cb)(void *user_data, grpc_jwt_verifier_status status, grpc_jwt_claims *claims)
Definition: jwt_verifier.h:118
pollset.h
grpc_jwt_verifier_status_to_string
const char * grpc_jwt_verifier_status_to_string(grpc_jwt_verifier_status status)
Definition: jwt_verifier.c:49
grpc_jwt_verifier_status
grpc_jwt_verifier_status
Definition: jwt_verifier.h:53
grpc_jwt_claims_audience
const char * grpc_jwt_claims_audience(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:218
grpc_jwt_verifier
Definition: jwt_verifier.c:375
GRPC_JWT_VERIFIER_OK
Definition: jwt_verifier.h:54
grpc_jwt_claims_issued_at
gpr_timespec grpc_jwt_claims_issued_at(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:223
GRPC_JWT_VERIFIER_KEY_RETRIEVAL_ERROR
Definition: jwt_verifier.h:58
grpc_jwt_verifier_destroy
void grpc_jwt_verifier_destroy(grpc_jwt_verifier *verifier)
Definition: jwt_verifier.c:823
grpc_pollset
Definition: pollset_posix.h:48
grpc_jwt_claims_check
grpc_jwt_verifier_status grpc_jwt_claims_check(const grpc_jwt_claims *claims, const char *audience)
Definition: jwt_verifier.c:284
GRPC_JWT_VERIFIER_BAD_SIGNATURE
Definition: jwt_verifier.h:55
json.h
grpc_jwt_claims_from_json
grpc_jwt_claims * grpc_jwt_claims_from_json(grpc_json *json, gpr_slice buffer)
Definition: jwt_verifier.c:239
grpc_jwt_claims_id
const char * grpc_jwt_claims_id(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:213
GRPC_JWT_VERIFIER_GENERIC_ERROR
Definition: jwt_verifier.h:60
grpc_jwt_claims
Definition: jwt_verifier.c:178
GRPC_JWT_VERIFIER_TIME_CONSTRAINT_FAILURE
Definition: jwt_verifier.h:59
grpc_jwt_claims_destroy
void grpc_jwt_claims_destroy(grpc_jwt_claims *claims)
Definition: jwt_verifier.c:192
grpc_jwt_verifier_clock_skew
gpr_timespec grpc_jwt_verifier_clock_skew
Definition: jwt_verifier.c:365
grpc_json
Definition: json.h:44
GRPC_JWT_VERIFIER_BAD_FORMAT
Definition: jwt_verifier.h:56
grpc_jwt_verifier_email_domain_key_url_mapping::email_domain
const char * email_domain
Definition: jwt_verifier.h:89
slice.h
grpc_jwt_claims_not_before
gpr_timespec grpc_jwt_claims_not_before(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:233
GRPC_JWT_VERIFIER_BAD_AUDIENCE
Definition: jwt_verifier.h:57
gpr_timespec
Definition: time.h:60
grpc_jwt_claims_json
const grpc_json * grpc_jwt_claims_json(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:198
grpc_jwt_claims_issuer
const char * grpc_jwt_claims_issuer(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:208
grpc_jwt_verifier_email_domain_key_url_mapping
Definition: jwt_verifier.h:87
grpc_jwt_verifier_email_domain_key_url_mapping::key_url_prefix
const char * key_url_prefix
Definition: jwt_verifier.h:94
gpr_slice
Definition: slice.h:79
grpc_jwt_verifier_create
grpc_jwt_verifier * grpc_jwt_verifier_create(const grpc_jwt_verifier_email_domain_key_url_mapping *mappings, size_t num_mappings)
Definition: jwt_verifier.c:800
grpc_jwt_verifier_max_delay
gpr_timespec grpc_jwt_verifier_max_delay
Definition: jwt_verifier.c:368
grpc_jwt_claims_expires_at
gpr_timespec grpc_jwt_claims_expires_at(const grpc_jwt_claims *claims)
Definition: jwt_verifier.c:228