Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 1 | /* |
| 2 | * |
Craig Tiller | 0605995 | 2015-02-18 08:34:56 -0800 | [diff] [blame] | 3 | * Copyright 2015, Google Inc. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 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 disclaimer. |
| 12 | * * Redistributions in binary form must reproduce the above |
| 13 | * copyright notice, this list of conditions and the following disclaimer |
| 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 | |
Nicolas "Pixel" Noble | 1ff52d5 | 2015-03-01 05:24:36 +0100 | [diff] [blame] | 34 | #ifndef GRPC_GRPC_SECURITY_H |
| 35 | #define GRPC_GRPC_SECURITY_H |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 36 | |
Nicolas "Pixel" Noble | 1ed15e2 | 2015-06-09 02:24:35 +0200 | [diff] [blame] | 37 | #include <grpc/grpc.h> |
| 38 | #include <grpc/status.h> |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 39 | |
nnoble | 0c475f0 | 2014-12-05 15:37:39 -0800 | [diff] [blame] | 40 | #ifdef __cplusplus |
| 41 | extern "C" { |
| 42 | #endif |
| 43 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 44 | /* --- grpc_credentials object. --- |
| 45 | |
| 46 | A credentials object represents a way to authenticate a client. */ |
| 47 | |
| 48 | typedef struct grpc_credentials grpc_credentials; |
| 49 | |
| 50 | /* Releases a credentials object. |
| 51 | The creator of the credentials object is responsible for its release. */ |
| 52 | void grpc_credentials_release(grpc_credentials *creds); |
| 53 | |
Julien Boeuf | b037bb6 | 2015-07-08 14:58:14 -0700 | [diff] [blame] | 54 | /* Environment variable that points to the google default application |
| 55 | credentials json key or refresh token. Used in the |
| 56 | grpc_google_default_credentials_create function. */ |
| 57 | #define GRPC_GOOGLE_CREDENTIALS_ENV_VAR "GOOGLE_APPLICATION_CREDENTIALS" |
| 58 | |
Julien Boeuf | c66f2a8 | 2015-02-23 13:00:36 -0800 | [diff] [blame] | 59 | /* Creates default credentials to connect to a google gRPC service. |
| 60 | WARNING: Do NOT use this credentials to connect to a non-google service as |
| 61 | this could result in an oauth2 token leak. */ |
| 62 | grpc_credentials *grpc_google_default_credentials_create(void); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 63 | |
Julien Boeuf | 026a417 | 2015-02-02 18:36:37 -0800 | [diff] [blame] | 64 | /* Environment variable that points to the default SSL roots file. This file |
| 65 | must be a PEM encoded file with all the roots such as the one that can be |
| 66 | downloaded from https://pki.google.com/roots.pem. */ |
| 67 | #define GRPC_DEFAULT_SSL_ROOTS_FILE_PATH_ENV_VAR \ |
| 68 | "GRPC_DEFAULT_SSL_ROOTS_FILE_PATH" |
| 69 | |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 70 | /* Object that holds a private key / certificate chain pair in PEM format. */ |
| 71 | typedef struct { |
| 72 | /* private_key is the NULL-terminated string containing the PEM encoding of |
| 73 | the client's private key. */ |
| 74 | const char *private_key; |
| 75 | |
Julien Boeuf | 68ad53e | 2015-01-20 22:37:03 -0800 | [diff] [blame] | 76 | /* cert_chain is the NULL-terminated string containing the PEM encoding of |
| 77 | the client's certificate chain. */ |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 78 | const char *cert_chain; |
| 79 | } grpc_ssl_pem_key_cert_pair; |
| 80 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 81 | /* Creates an SSL credentials object. |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 82 | - pem_roots_cert is the NULL-terminated string containing the PEM encoding |
Julien Boeuf | 3e00179 | 2015-02-20 15:02:36 -0800 | [diff] [blame] | 83 | of the server root certificates. If this parameter is NULL, the |
| 84 | implementation will first try to dereference the file pointed by the |
| 85 | GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails, |
| 86 | get the roots from a well-known place on disk (in the grpc install |
| 87 | directory). |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 88 | - pem_key_cert_pair is a pointer on the object containing client's private |
| 89 | key and certificate chain. This parameter can be NULL if the client does |
| 90 | not have such a key/cert pair. */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 91 | grpc_credentials *grpc_ssl_credentials_create( |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 92 | const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 93 | |
| 94 | /* Creates a composite credentials object. */ |
| 95 | grpc_credentials *grpc_composite_credentials_create(grpc_credentials *creds1, |
| 96 | grpc_credentials *creds2); |
| 97 | |
Julien Boeuf | c66f2a8 | 2015-02-23 13:00:36 -0800 | [diff] [blame] | 98 | /* Creates a compute engine credentials object. |
| 99 | WARNING: Do NOT use this credentials to connect to a non-google service as |
| 100 | this could result in an oauth2 token leak. */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 101 | grpc_credentials *grpc_compute_engine_credentials_create(void); |
| 102 | |
jboeuf | ab4f914 | 2014-12-16 16:32:39 -0800 | [diff] [blame] | 103 | extern const gpr_timespec grpc_max_auth_token_lifetime; |
jboeuf | befd265 | 2014-12-12 15:39:47 -0800 | [diff] [blame] | 104 | |
| 105 | /* Creates a service account credentials object. May return NULL if the input is |
jboeuf | ab4f914 | 2014-12-16 16:32:39 -0800 | [diff] [blame] | 106 | invalid. |
Julien Boeuf | c66f2a8 | 2015-02-23 13:00:36 -0800 | [diff] [blame] | 107 | WARNING: Do NOT use this credentials to connect to a non-google service as |
| 108 | this could result in an oauth2 token leak. |
jboeuf | ab4f914 | 2014-12-16 16:32:39 -0800 | [diff] [blame] | 109 | - json_key is the JSON key string containing the client's private key. |
| 110 | - scope is a space-delimited list of the requested permissions. |
| 111 | - token_lifetime is the lifetime of each token acquired through this service |
| 112 | account credentials. It should not exceed grpc_max_auth_token_lifetime |
| 113 | or will be cropped to this value. */ |
| 114 | grpc_credentials *grpc_service_account_credentials_create( |
| 115 | const char *json_key, const char *scope, gpr_timespec token_lifetime); |
jboeuf | befd265 | 2014-12-12 15:39:47 -0800 | [diff] [blame] | 116 | |
Julien Boeuf | f47a5cb | 2015-02-18 12:24:08 -0800 | [diff] [blame] | 117 | /* Creates a JWT credentials object. May return NULL if the input is invalid. |
| 118 | - json_key is the JSON key string containing the client's private key. |
| 119 | - token_lifetime is the lifetime of each Json Web Token (JWT) created with |
| 120 | this credentials. It should not exceed grpc_max_auth_token_lifetime or |
| 121 | will be cropped to this value. */ |
| 122 | grpc_credentials *grpc_jwt_credentials_create(const char *json_key, |
| 123 | gpr_timespec token_lifetime); |
| 124 | |
Eric Dobson | a6124ec | 2015-06-08 11:17:42 -0700 | [diff] [blame] | 125 | /* Creates an Oauth2 Refresh Token credentials object. May return NULL if the |
Julien Boeuf | 9835cf0 | 2015-03-09 16:56:44 -0700 | [diff] [blame] | 126 | input is invalid. |
| 127 | WARNING: Do NOT use this credentials to connect to a non-google service as |
| 128 | this could result in an oauth2 token leak. |
| 129 | - json_refresh_token is the JSON string containing the refresh token itself |
| 130 | along with a client_id and client_secret. */ |
| 131 | grpc_credentials *grpc_refresh_token_credentials_create( |
| 132 | const char *json_refresh_token); |
| 133 | |
Julien Boeuf | 2805be1 | 2015-07-01 02:47:18 -0700 | [diff] [blame] | 134 | /* Creates an Oauth2 Access Token credentials with an access token that was |
| 135 | aquired by an out of band mechanism. */ |
| 136 | grpc_credentials *grpc_access_token_credentials_create( |
| 137 | const char *access_token); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 138 | |
nnoble | 0c475f0 | 2014-12-05 15:37:39 -0800 | [diff] [blame] | 139 | /* Creates an IAM credentials object. */ |
| 140 | grpc_credentials *grpc_iam_credentials_create(const char *authorization_token, |
| 141 | const char *authority_selector); |
| 142 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 143 | /* --- Secure channel creation. --- */ |
| 144 | |
| 145 | /* The caller of the secure_channel_create functions may override the target |
| 146 | name used for SSL host name checking using this channel argument which is of |
| 147 | type GRPC_ARG_STRING. This *should* be used for testing only. |
| 148 | If this argument is not specified, the name used for SSL host name checking |
| 149 | will be the target parameter (assuming that the secure channel is an SSL |
| 150 | channel). If this parameter is specified and the underlying is not an SSL |
| 151 | channel, it will just be ignored. */ |
| 152 | #define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override" |
| 153 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 154 | /* Creates a secure channel using the passed-in credentials. */ |
| 155 | grpc_channel *grpc_secure_channel_create(grpc_credentials *creds, |
| 156 | const char *target, |
| 157 | const grpc_channel_args *args); |
| 158 | |
| 159 | /* --- grpc_server_credentials object. --- |
| 160 | |
| 161 | A server credentials object represents a way to authenticate a server. */ |
| 162 | |
| 163 | typedef struct grpc_server_credentials grpc_server_credentials; |
| 164 | |
| 165 | /* Releases a server_credentials object. |
| 166 | The creator of the server_credentials object is responsible for its release. |
| 167 | */ |
| 168 | void grpc_server_credentials_release(grpc_server_credentials *creds); |
| 169 | |
| 170 | /* Creates an SSL server_credentials object. |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 171 | - pem_roots_cert is the NULL-terminated string containing the PEM encoding of |
| 172 | the client root certificates. This parameter may be NULL if the server does |
| 173 | not want the client to be authenticated with SSL. |
| 174 | - pem_key_cert_pairs is an array private key / certificate chains of the |
| 175 | server. This parameter cannot be NULL. |
| 176 | - num_key_cert_pairs indicates the number of items in the private_key_files |
| 177 | and cert_chain_files parameters. It should be at least 1. */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 178 | grpc_server_credentials *grpc_ssl_server_credentials_create( |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 179 | const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, |
| 180 | size_t num_key_cert_pairs); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 181 | |
Jan Tattermusch | b0829eb | 2015-03-03 09:30:55 -0800 | [diff] [blame] | 182 | /* --- Server-side secure ports. --- */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 183 | |
Craig Tiller | d251ab9 | 2015-02-17 17:22:14 -0800 | [diff] [blame] | 184 | /* Add a HTTP2 over an encrypted link over tcp listener. |
Craig Tiller | d251ab9 | 2015-02-17 17:22:14 -0800 | [diff] [blame] | 185 | Returns bound port number on success, 0 on failure. |
| 186 | REQUIRES: server not started */ |
Craig Tiller | 759026c | 2015-02-22 23:09:45 -0800 | [diff] [blame] | 187 | int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr, |
| 188 | grpc_server_credentials *creds); |
Craig Tiller | d251ab9 | 2015-02-17 17:22:14 -0800 | [diff] [blame] | 189 | |
Julien Boeuf | 9f218dd | 2015-04-23 10:24:02 -0700 | [diff] [blame] | 190 | /* --- Call specific credentials. --- */ |
| 191 | |
| 192 | /* Sets a credentials to a call. Can only be called on the client side before |
| 193 | grpc_call_start_batch. */ |
| 194 | grpc_call_error grpc_call_set_credentials(grpc_call *call, |
| 195 | grpc_credentials *creds); |
| 196 | |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 197 | /* --- Authentication Context. --- */ |
| 198 | |
| 199 | /* TODO(jboeuf): Define some well-known property names. */ |
| 200 | |
Craig Tiller | 9a57633 | 2015-06-17 10:21:49 -0700 | [diff] [blame] | 201 | #define GRPC_TRANSPORT_SECURITY_TYPE_PROPERTY_NAME "transport_security_type" |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 202 | #define GRPC_SSL_TRANSPORT_SECURITY_TYPE "ssl" |
| 203 | |
| 204 | #define GRPC_X509_CN_PROPERTY_NAME "x509_common_name" |
| 205 | #define GRPC_X509_SAN_PROPERTY_NAME "x509_subject_alternative_name" |
| 206 | |
| 207 | typedef struct grpc_auth_context grpc_auth_context; |
Julien Boeuf | 83b0297 | 2015-05-20 22:50:34 -0700 | [diff] [blame] | 208 | |
| 209 | typedef struct grpc_auth_property_iterator { |
| 210 | const grpc_auth_context *ctx; |
| 211 | size_t index; |
| 212 | const char *name; |
| 213 | } grpc_auth_property_iterator; |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 214 | |
| 215 | /* value, if not NULL, is guaranteed to be NULL terminated. */ |
| 216 | typedef struct grpc_auth_property { |
| 217 | char *name; |
| 218 | char *value; |
| 219 | size_t value_length; |
| 220 | } grpc_auth_property; |
| 221 | |
| 222 | /* Returns NULL when the iterator is at the end. */ |
| 223 | const grpc_auth_property *grpc_auth_property_iterator_next( |
| 224 | grpc_auth_property_iterator *it); |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 225 | |
Julien Boeuf | 83b0297 | 2015-05-20 22:50:34 -0700 | [diff] [blame] | 226 | /* Iterates over the auth context. */ |
| 227 | grpc_auth_property_iterator grpc_auth_context_property_iterator( |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 228 | const grpc_auth_context *ctx); |
| 229 | |
Julien Boeuf | 83b0297 | 2015-05-20 22:50:34 -0700 | [diff] [blame] | 230 | /* Gets the peer identity. Returns an empty iterator (first _next will return |
| 231 | NULL) if the peer is not authenticated. */ |
| 232 | grpc_auth_property_iterator grpc_auth_context_peer_identity( |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 233 | const grpc_auth_context *ctx); |
| 234 | |
Julien Boeuf | 83b0297 | 2015-05-20 22:50:34 -0700 | [diff] [blame] | 235 | /* Finds a property in the context. May return an empty iterator (first _next |
| 236 | will return NULL) if no property with this name was found in the context. */ |
| 237 | grpc_auth_property_iterator grpc_auth_context_find_properties_by_name( |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 238 | const grpc_auth_context *ctx, const char *name); |
| 239 | |
| 240 | /* Gets the name of the property that indicates the peer identity. Will return |
| 241 | NULL if the peer is not authenticated. */ |
| 242 | const char *grpc_auth_context_peer_identity_property_name( |
| 243 | const grpc_auth_context *ctx); |
| 244 | |
Julien Boeuf | 83b0297 | 2015-05-20 22:50:34 -0700 | [diff] [blame] | 245 | /* Returns 1 if the peer is authenticated, 0 otherwise. */ |
| 246 | int grpc_auth_context_peer_is_authenticated(const grpc_auth_context *ctx); |
| 247 | |
yang-g | f9e8e59 | 2015-07-09 12:32:15 -0700 | [diff] [blame] | 248 | /* Gets the auth context from the call. Caller needs to call |
| 249 | grpc_auth_context_release on the returned context. */ |
| 250 | grpc_auth_context *grpc_call_auth_context(grpc_call *call); |
| 251 | |
| 252 | /* Releases the auth context returned from grpc_call_auth_context. */ |
| 253 | void grpc_auth_context_release(grpc_auth_context *context); |
Julien Boeuf | 84d964a | 2015-04-29 11:31:06 -0700 | [diff] [blame] | 254 | |
nnoble | 0c475f0 | 2014-12-05 15:37:39 -0800 | [diff] [blame] | 255 | #ifdef __cplusplus |
| 256 | } |
| 257 | #endif |
| 258 | |
Craig Tiller | 9a57633 | 2015-06-17 10:21:49 -0700 | [diff] [blame] | 259 | #endif /* GRPC_GRPC_SECURITY_H */ |