Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 1 | /* |
| 2 | * |
Craig Tiller | 6169d5f | 2016-03-31 07:46:18 -0700 | [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> |
Deepak Lukose | dba4c5f | 2016-03-25 12:54:25 -0700 | [diff] [blame] | 38 | #include <grpc/grpc_security_constants.h> |
Nicolas "Pixel" Noble | 1ed15e2 | 2015-06-09 02:24:35 +0200 | [diff] [blame] | 39 | #include <grpc/status.h> |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 40 | |
nnoble | 0c475f0 | 2014-12-05 15:37:39 -0800 | [diff] [blame] | 41 | #ifdef __cplusplus |
| 42 | extern "C" { |
| 43 | #endif |
| 44 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 45 | /** --- Authentication Context. --- */ |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 46 | |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 47 | typedef struct grpc_auth_context grpc_auth_context; |
| 48 | |
| 49 | typedef struct grpc_auth_property_iterator { |
| 50 | const grpc_auth_context *ctx; |
| 51 | size_t index; |
| 52 | const char *name; |
| 53 | } grpc_auth_property_iterator; |
| 54 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 55 | /** value, if not NULL, is guaranteed to be NULL terminated. */ |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 56 | typedef struct grpc_auth_property { |
| 57 | char *name; |
| 58 | char *value; |
| 59 | size_t value_length; |
| 60 | } grpc_auth_property; |
| 61 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 62 | /** Returns NULL when the iterator is at the end. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 63 | GRPCAPI const grpc_auth_property *grpc_auth_property_iterator_next( |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 64 | grpc_auth_property_iterator *it); |
| 65 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 66 | /** Iterates over the auth context. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 67 | GRPCAPI grpc_auth_property_iterator |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 68 | grpc_auth_context_property_iterator(const grpc_auth_context *ctx); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 69 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 70 | /** Gets the peer identity. Returns an empty iterator (first _next will return |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 71 | NULL) if the peer is not authenticated. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 72 | GRPCAPI grpc_auth_property_iterator |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 73 | grpc_auth_context_peer_identity(const grpc_auth_context *ctx); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 74 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 75 | /** Finds a property in the context. May return an empty iterator (first _next |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 76 | will return NULL) if no property with this name was found in the context. */ |
Craig Tiller | f40df23 | 2016-03-25 13:38:14 -0700 | [diff] [blame] | 77 | GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name( |
| 78 | const grpc_auth_context *ctx, const char *name); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 79 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 80 | /** Gets the name of the property that indicates the peer identity. Will return |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 81 | NULL if the peer is not authenticated. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 82 | GRPCAPI const char *grpc_auth_context_peer_identity_property_name( |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 83 | const grpc_auth_context *ctx); |
| 84 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 85 | /** Returns 1 if the peer is authenticated, 0 otherwise. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 86 | GRPCAPI int grpc_auth_context_peer_is_authenticated( |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 87 | const grpc_auth_context *ctx); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 88 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 89 | /** Gets the auth context from the call. Caller needs to call |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 90 | grpc_auth_context_release on the returned context. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 91 | GRPCAPI grpc_auth_context *grpc_call_auth_context(grpc_call *call); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 92 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 93 | /** Releases the auth context returned from grpc_call_auth_context. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 94 | GRPCAPI void grpc_auth_context_release(grpc_auth_context *context); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 95 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 96 | /** -- |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 97 | The following auth context methods should only be called by a server metadata |
| 98 | processor to set properties extracted from auth metadata. |
| 99 | -- */ |
| 100 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 101 | /** Add a property. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 102 | GRPCAPI void grpc_auth_context_add_property(grpc_auth_context *ctx, |
| 103 | const char *name, const char *value, |
| 104 | size_t value_length); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 105 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 106 | /** Add a C string property. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 107 | GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context *ctx, |
| 108 | const char *name, |
| 109 | const char *value); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 110 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 111 | /** Sets the property name. Returns 1 if successful or 0 in case of failure |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 112 | (which means that no property with this name exists). */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 113 | GRPCAPI int grpc_auth_context_set_peer_identity_property_name( |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 114 | grpc_auth_context *ctx, const char *name); |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 115 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 116 | /** --- grpc_channel_credentials object. --- |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 117 | |
Julien Boeuf | acd835f | 2015-10-09 15:20:57 -0700 | [diff] [blame] | 118 | A channel credentials object represents a way to authenticate a client on a |
| 119 | channel. */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 120 | |
Julien Boeuf | acd835f | 2015-10-09 15:20:57 -0700 | [diff] [blame] | 121 | typedef struct grpc_channel_credentials grpc_channel_credentials; |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 122 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 123 | /** Releases a channel credentials object. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 124 | The creator of the credentials object is responsible for its release. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 125 | GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials *creds); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 126 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 127 | /** Creates default credentials to connect to a google gRPC service. |
Julien Boeuf | c66f2a8 | 2015-02-23 13:00:36 -0800 | [diff] [blame] | 128 | WARNING: Do NOT use this credentials to connect to a non-google service as |
| 129 | this could result in an oauth2 token leak. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 130 | GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 131 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 132 | /** Callback for getting the SSL roots override from the application. |
Julien Boeuf | aaebf7a | 2016-01-28 17:04:42 -0800 | [diff] [blame] | 133 | In case of success, *pem_roots_certs must be set to a NULL terminated string |
| 134 | containing the list of PEM encoded root certificates. The ownership is passed |
| 135 | to the core and freed (laster by the core) with gpr_free. |
| 136 | If this function fails and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is |
| 137 | set to a valid path, it will override the roots specified this func */ |
| 138 | typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)( |
| 139 | char **pem_root_certs); |
| 140 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 141 | /** Setup a callback to override the default TLS/SSL roots. |
Julien Boeuf | 373debd | 2016-01-27 15:41:12 -0800 | [diff] [blame] | 142 | This function is not thread-safe and must be called at initialization time |
| 143 | before any ssl credentials are created to have the desired side effect. |
Julien Boeuf | aaebf7a | 2016-01-28 17:04:42 -0800 | [diff] [blame] | 144 | If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the |
| 145 | callback will not be called. */ |
Nicolas "Pixel" Noble | 6397660 | 2016-02-17 23:43:55 +0100 | [diff] [blame] | 146 | GRPCAPI void grpc_set_ssl_roots_override_callback( |
| 147 | grpc_ssl_roots_override_callback cb); |
Julien Boeuf | 373debd | 2016-01-27 15:41:12 -0800 | [diff] [blame] | 148 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 149 | /** Object that holds a private key / certificate chain pair in PEM format. */ |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 150 | typedef struct { |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 151 | /** private_key is the NULL-terminated string containing the PEM encoding of |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 152 | the client's private key. */ |
| 153 | const char *private_key; |
| 154 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 155 | /** cert_chain is the NULL-terminated string containing the PEM encoding of |
Julien Boeuf | 68ad53e | 2015-01-20 22:37:03 -0800 | [diff] [blame] | 156 | the client's certificate chain. */ |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 157 | const char *cert_chain; |
| 158 | } grpc_ssl_pem_key_cert_pair; |
| 159 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 160 | /** Creates an SSL credentials object. |
Julien Boeuf | b71ef65 | 2017-04-12 21:44:49 -0700 | [diff] [blame] | 161 | - pem_root_certs is the NULL-terminated string containing the PEM encoding |
Julien Boeuf | 3e00179 | 2015-02-20 15:02:36 -0800 | [diff] [blame] | 162 | of the server root certificates. If this parameter is NULL, the |
| 163 | implementation will first try to dereference the file pointed by the |
| 164 | GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails, |
Julien Boeuf | a50da47 | 2016-01-27 16:23:41 -0800 | [diff] [blame] | 165 | try to get the roots set by grpc_override_ssl_default_roots. Eventually, |
| 166 | if all these fail, it will try to get the roots from a well-known place on |
| 167 | disk (in the grpc install directory). |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 168 | - pem_key_cert_pair is a pointer on the object containing client's private |
| 169 | key and certificate chain. This parameter can be NULL if the client does |
Julien Boeuf | 5029b30 | 2015-07-21 23:02:16 -0700 | [diff] [blame] | 170 | not have such a key/cert pair. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 171 | GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create( |
Julien Boeuf | 8b78c28 | 2015-08-14 13:39:19 -0700 | [diff] [blame] | 172 | const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair, |
| 173 | void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 174 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 175 | /** --- grpc_call_credentials object. |
Julien Boeuf | acd835f | 2015-10-09 15:20:57 -0700 | [diff] [blame] | 176 | |
| 177 | A call credentials object represents a way to authenticate on a particular |
| 178 | call. These credentials can be composed with a channel credentials object |
| 179 | so that they are sent with every call on this channel. */ |
| 180 | |
| 181 | typedef struct grpc_call_credentials grpc_call_credentials; |
| 182 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 183 | /** Releases a call credentials object. |
Julien Boeuf | 441176d | 2015-10-09 21:14:07 -0700 | [diff] [blame] | 184 | The creator of the credentials object is responsible for its release. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 185 | GRPCAPI void grpc_call_credentials_release(grpc_call_credentials *creds); |
Julien Boeuf | 441176d | 2015-10-09 21:14:07 -0700 | [diff] [blame] | 186 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 187 | /** Creates a composite channel credentials object. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 188 | GRPCAPI grpc_channel_credentials *grpc_composite_channel_credentials_create( |
Julien Boeuf | acd835f | 2015-10-09 15:20:57 -0700 | [diff] [blame] | 189 | grpc_channel_credentials *channel_creds, grpc_call_credentials *call_creds, |
| 190 | void *reserved); |
| 191 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 192 | /** Creates a composite call credentials object. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 193 | GRPCAPI grpc_call_credentials *grpc_composite_call_credentials_create( |
Julien Boeuf | acd835f | 2015-10-09 15:20:57 -0700 | [diff] [blame] | 194 | grpc_call_credentials *creds1, grpc_call_credentials *creds2, |
| 195 | void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 196 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 197 | /** Creates a compute engine credentials object for connecting to Google. |
Julien Boeuf | c66f2a8 | 2015-02-23 13:00:36 -0800 | [diff] [blame] | 198 | WARNING: Do NOT use this credentials to connect to a non-google service as |
| 199 | this could result in an oauth2 token leak. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 200 | GRPCAPI grpc_call_credentials *grpc_google_compute_engine_credentials_create( |
Julien Boeuf | acd835f | 2015-10-09 15:20:57 -0700 | [diff] [blame] | 201 | void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 202 | |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 203 | GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(); |
jboeuf | befd265 | 2014-12-12 15:39:47 -0800 | [diff] [blame] | 204 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 205 | /** Creates a JWT credentials object. May return NULL if the input is invalid. |
Julien Boeuf | f47a5cb | 2015-02-18 12:24:08 -0800 | [diff] [blame] | 206 | - json_key is the JSON key string containing the client's private key. |
| 207 | - token_lifetime is the lifetime of each Json Web Token (JWT) created with |
| 208 | this credentials. It should not exceed grpc_max_auth_token_lifetime or |
| 209 | will be cropped to this value. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 210 | GRPCAPI grpc_call_credentials * |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 211 | grpc_service_account_jwt_access_credentials_create(const char *json_key, |
| 212 | gpr_timespec token_lifetime, |
| 213 | void *reserved); |
Julien Boeuf | f47a5cb | 2015-02-18 12:24:08 -0800 | [diff] [blame] | 214 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 215 | /** Creates an Oauth2 Refresh Token credentials object for connecting to Google. |
Julien Boeuf | 510a920 | 2015-08-25 21:51:07 -0700 | [diff] [blame] | 216 | May return NULL if the input is invalid. |
Julien Boeuf | 9835cf0 | 2015-03-09 16:56:44 -0700 | [diff] [blame] | 217 | WARNING: Do NOT use this credentials to connect to a non-google service as |
| 218 | this could result in an oauth2 token leak. |
| 219 | - json_refresh_token is the JSON string containing the refresh token itself |
| 220 | along with a client_id and client_secret. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 221 | GRPCAPI grpc_call_credentials *grpc_google_refresh_token_credentials_create( |
Julien Boeuf | 8b78c28 | 2015-08-14 13:39:19 -0700 | [diff] [blame] | 222 | const char *json_refresh_token, void *reserved); |
Julien Boeuf | 9835cf0 | 2015-03-09 16:56:44 -0700 | [diff] [blame] | 223 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 224 | /** Creates an Oauth2 Access Token credentials with an access token that was |
Julien Boeuf | 2805be1 | 2015-07-01 02:47:18 -0700 | [diff] [blame] | 225 | aquired by an out of band mechanism. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 226 | GRPCAPI grpc_call_credentials *grpc_access_token_credentials_create( |
Julien Boeuf | acd835f | 2015-10-09 15:20:57 -0700 | [diff] [blame] | 227 | const char *access_token, void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 228 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 229 | /** Creates an IAM credentials object for connecting to Google. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 230 | GRPCAPI grpc_call_credentials *grpc_google_iam_credentials_create( |
Julien Boeuf | 510a920 | 2015-08-25 21:51:07 -0700 | [diff] [blame] | 231 | const char *authorization_token, const char *authority_selector, |
| 232 | void *reserved); |
nnoble | 0c475f0 | 2014-12-05 15:37:39 -0800 | [diff] [blame] | 233 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 234 | /** Callback function to be called by the metadata credentials plugin |
Julien Boeuf | 97f80fa | 2015-09-15 16:17:31 -0700 | [diff] [blame] | 235 | implementation when the metadata is ready. |
| 236 | - user_data is the opaque pointer that was passed in the get_metadata method |
| 237 | of the grpc_metadata_credentials_plugin (see below). |
| 238 | - creds_md is an array of credentials metadata produced by the plugin. It |
| 239 | may be set to NULL in case of an error. |
| 240 | - num_creds_md is the number of items in the creds_md array. |
| 241 | - status must be GRPC_STATUS_OK in case of success or another specific error |
| 242 | code otherwise. |
| 243 | - error_details contains details about the error if any. In case of success |
| 244 | it should be NULL and will be otherwise ignored. */ |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 245 | typedef void (*grpc_credentials_plugin_metadata_cb)( |
| 246 | void *user_data, const grpc_metadata *creds_md, size_t num_creds_md, |
| 247 | grpc_status_code status, const char *error_details); |
| 248 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 249 | /** Context that can be used by metadata credentials plugin in order to create |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 250 | auth related metadata. */ |
| 251 | typedef struct { |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 252 | /** The fully qualifed service url. */ |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 253 | const char *service_url; |
| 254 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 255 | /** The method name of the RPC being called (not fully qualified). |
Julien Boeuf | eb029c9 | 2015-11-25 13:47:56 -0800 | [diff] [blame] | 256 | The fully qualified method name can be built from the service_url: |
| 257 | full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */ |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 258 | const char *method_name; |
| 259 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 260 | /** The auth_context of the channel which gives the server's identity. */ |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 261 | const grpc_auth_context *channel_auth_context; |
| 262 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 263 | /** Reserved for future use. */ |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 264 | void *reserved; |
| 265 | } grpc_auth_metadata_context; |
| 266 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 267 | /** grpc_metadata_credentials plugin is an API user provided structure used to |
Julien Boeuf | 97f80fa | 2015-09-15 16:17:31 -0700 | [diff] [blame] | 268 | create grpc_credentials objects that can be set on a channel (composed) or |
| 269 | a call. See grpc_credentials_metadata_create_from_plugin below. |
| 270 | The grpc client stack will call the get_metadata method of the plugin for |
| 271 | every call in scope for the credentials created from it. */ |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 272 | typedef struct { |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 273 | /** The implementation of this method has to be non-blocking. |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 274 | - context is the information that can be used by the plugin to create auth |
| 275 | metadata. |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 276 | - cb is the callback that needs to be called when the metadata is ready. |
| 277 | - user_data needs to be passed as the first parameter of the callback. */ |
Julien Boeuf | ea44bba | 2015-11-18 15:56:01 -0800 | [diff] [blame] | 278 | void (*get_metadata)(void *state, grpc_auth_metadata_context context, |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 279 | grpc_credentials_plugin_metadata_cb cb, void *user_data); |
| 280 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 281 | /** Destroys the plugin state. */ |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 282 | void (*destroy)(void *state); |
| 283 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 284 | /** State that will be set as the first parameter of the methods above. */ |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 285 | void *state; |
Julien Boeuf | caf9935 | 2015-11-19 22:00:30 -0800 | [diff] [blame] | 286 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 287 | /** Type of credentials that this plugin is implementing. */ |
Julien Boeuf | caf9935 | 2015-11-19 22:00:30 -0800 | [diff] [blame] | 288 | const char *type; |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 289 | } grpc_metadata_credentials_plugin; |
| 290 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 291 | /** Creates a credentials object from a plugin. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 292 | GRPCAPI grpc_call_credentials *grpc_metadata_credentials_create_from_plugin( |
Julien Boeuf | 8b5bb27 | 2015-08-31 13:25:21 -0700 | [diff] [blame] | 293 | grpc_metadata_credentials_plugin plugin, void *reserved); |
| 294 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 295 | /** --- Secure channel creation. --- */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 296 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 297 | /** Creates a secure channel using the passed-in credentials. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 298 | GRPCAPI grpc_channel *grpc_secure_channel_create( |
Craig Tiller | d6546c9 | 2016-01-29 07:59:35 -0800 | [diff] [blame] | 299 | grpc_channel_credentials *creds, const char *target, |
| 300 | const grpc_channel_args *args, void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 301 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 302 | /** --- grpc_server_credentials object. --- |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 303 | |
| 304 | A server credentials object represents a way to authenticate a server. */ |
| 305 | |
| 306 | typedef struct grpc_server_credentials grpc_server_credentials; |
| 307 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 308 | /** Releases a server_credentials object. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 309 | The creator of the server_credentials object is responsible for its release. |
| 310 | */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 311 | GRPCAPI void grpc_server_credentials_release(grpc_server_credentials *creds); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 312 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 313 | /** Deprecated in favor of grpc_ssl_server_credentials_create_ex. |
Deepak Lukose | dba4c5f | 2016-03-25 12:54:25 -0700 | [diff] [blame] | 314 | Creates an SSL server_credentials object. |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 315 | - pem_roots_cert is the NULL-terminated string containing the PEM encoding of |
| 316 | the client root certificates. This parameter may be NULL if the server does |
| 317 | not want the client to be authenticated with SSL. |
| 318 | - pem_key_cert_pairs is an array private key / certificate chains of the |
| 319 | server. This parameter cannot be NULL. |
| 320 | - num_key_cert_pairs indicates the number of items in the private_key_files |
Julien Boeuf | 5029b30 | 2015-07-21 23:02:16 -0700 | [diff] [blame] | 321 | and cert_chain_files parameters. It should be at least 1. |
| 322 | - force_client_auth, if set to non-zero will force the client to authenticate |
| 323 | with an SSL cert. Note that this option is ignored if pem_root_certs is |
| 324 | NULL. */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 325 | GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create( |
Julien Boeuf | 8fbcc43 | 2015-01-15 16:44:13 -0800 | [diff] [blame] | 326 | const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, |
Julien Boeuf | 8b78c28 | 2015-08-14 13:39:19 -0700 | [diff] [blame] | 327 | size_t num_key_cert_pairs, int force_client_auth, void *reserved); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 328 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 329 | /** Same as grpc_ssl_server_credentials_create method except uses |
Deepak Lukose | dba4c5f | 2016-03-25 12:54:25 -0700 | [diff] [blame] | 330 | grpc_ssl_client_certificate_request_type enum to support more ways to |
| 331 | authenticate client cerificates.*/ |
| 332 | GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex( |
| 333 | const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, |
| 334 | size_t num_key_cert_pairs, |
| 335 | grpc_ssl_client_certificate_request_type client_certificate_request, |
| 336 | void *reserved); |
| 337 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 338 | /** --- Server-side secure ports. --- */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 339 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 340 | /** Add a HTTP2 over an encrypted link over tcp listener. |
Craig Tiller | d251ab9 | 2015-02-17 17:22:14 -0800 | [diff] [blame] | 341 | Returns bound port number on success, 0 on failure. |
| 342 | REQUIRES: server not started */ |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 343 | GRPCAPI int grpc_server_add_secure_http2_port(grpc_server *server, |
| 344 | const char *addr, |
| 345 | grpc_server_credentials *creds); |
Craig Tiller | d251ab9 | 2015-02-17 17:22:14 -0800 | [diff] [blame] | 346 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 347 | /** --- Call specific credentials. --- */ |
Julien Boeuf | 9f218dd | 2015-04-23 10:24:02 -0700 | [diff] [blame] | 348 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 349 | /** Sets a credentials to a call. Can only be called on the client side before |
Julien Boeuf | 9f218dd | 2015-04-23 10:24:02 -0700 | [diff] [blame] | 350 | grpc_call_start_batch. */ |
Craig Tiller | f40df23 | 2016-03-25 13:38:14 -0700 | [diff] [blame] | 351 | GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call *call, |
| 352 | grpc_call_credentials *creds); |
Julien Boeuf | 9f218dd | 2015-04-23 10:24:02 -0700 | [diff] [blame] | 353 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 354 | /** --- Auth Metadata Processing --- */ |
Julien Boeuf | ea456fc | 2015-07-07 15:23:30 -0700 | [diff] [blame] | 355 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 356 | /** Callback function that is called when the metadata processing is done. |
Julien Boeuf | ee3dbb0 | 2015-08-19 22:17:03 -0700 | [diff] [blame] | 357 | - Consumed metadata will be removed from the set of metadata available on the |
| 358 | call. consumed_md may be NULL if no metadata has been consumed. |
| 359 | - Response metadata will be set on the response. response_md may be NULL. |
| 360 | - status is GRPC_STATUS_OK for success or a specific status for an error. |
| 361 | Common error status for auth metadata processing is either |
| 362 | GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or |
| 363 | GRPC_STATUS PERMISSION_DENIED in case of an authorization failure. |
| 364 | - error_details gives details about the error. May be NULL. */ |
Julien Boeuf | ea456fc | 2015-07-07 15:23:30 -0700 | [diff] [blame] | 365 | typedef void (*grpc_process_auth_metadata_done_cb)( |
| 366 | void *user_data, const grpc_metadata *consumed_md, size_t num_consumed_md, |
Julien Boeuf | ee3dbb0 | 2015-08-19 22:17:03 -0700 | [diff] [blame] | 367 | const grpc_metadata *response_md, size_t num_response_md, |
| 368 | grpc_status_code status, const char *error_details); |
Julien Boeuf | ea456fc | 2015-07-07 15:23:30 -0700 | [diff] [blame] | 369 | |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 370 | /** Pluggable server-side metadata processor object. */ |
Julien Boeuf | a87d6c2 | 2015-07-17 15:51:46 -0700 | [diff] [blame] | 371 | typedef struct { |
Alexander Polcyn | d809a15 | 2017-05-03 14:49:41 -0700 | [diff] [blame] | 372 | /** The context object is read/write: it contains the properties of the |
Julien Boeuf | 77a7b87 | 2015-08-05 20:11:02 -0700 | [diff] [blame] | 373 | channel peer and it is the job of the process function to augment it with |
Julien Boeuf | bf25bb0 | 2015-08-14 12:36:11 -0700 | [diff] [blame] | 374 | properties derived from the passed-in metadata. |
| 375 | The lifetime of these objects is guaranteed until cb is invoked. */ |
Julien Boeuf | 77a7b87 | 2015-08-05 20:11:02 -0700 | [diff] [blame] | 376 | void (*process)(void *state, grpc_auth_context *context, |
Julien Boeuf | bf25bb0 | 2015-08-14 12:36:11 -0700 | [diff] [blame] | 377 | const grpc_metadata *md, size_t num_md, |
Julien Boeuf | 77a7b87 | 2015-08-05 20:11:02 -0700 | [diff] [blame] | 378 | grpc_process_auth_metadata_done_cb cb, void *user_data); |
Julien Boeuf | 0c711ad | 2015-08-28 14:10:58 -0700 | [diff] [blame] | 379 | void (*destroy)(void *state); |
Julien Boeuf | a87d6c2 | 2015-07-17 15:51:46 -0700 | [diff] [blame] | 380 | void *state; |
| 381 | } grpc_auth_metadata_processor; |
Julien Boeuf | ea456fc | 2015-07-07 15:23:30 -0700 | [diff] [blame] | 382 | |
Nicolas "Pixel" Noble | cd41a0b | 2016-02-08 22:53:14 +0100 | [diff] [blame] | 383 | GRPCAPI void grpc_server_credentials_set_auth_metadata_processor( |
Julien Boeuf | 6bdc9b4 | 2015-07-19 21:56:02 -0700 | [diff] [blame] | 384 | grpc_server_credentials *creds, grpc_auth_metadata_processor processor); |
Julien Boeuf | ea456fc | 2015-07-07 15:23:30 -0700 | [diff] [blame] | 385 | |
nnoble | 0c475f0 | 2014-12-05 15:37:39 -0800 | [diff] [blame] | 386 | #ifdef __cplusplus |
| 387 | } |
| 388 | #endif |
| 389 | |
Craig Tiller | 9a57633 | 2015-06-17 10:21:49 -0700 | [diff] [blame] | 390 | #endif /* GRPC_GRPC_SECURITY_H */ |