

`security` Enterprise Plugin¶

Version	Language
1.0.0	Go

This plugin implementation provides the following enterprise features to geth JSON RPC server:

Providing TLS configuration to HTTP and WS transports
Enabling geth JSON RPC (HTTP/WS) server to be an OAuth2-compliant resource server

Configuration¶

{
    "tls": object(TLSConfiguration),
    "tokenValidation": object(TokenValidationConfiguration)
}

Fields	Description
`tls`	(Optional) If provided, serve the TLS configuration. See TLSConfiguration for more details
`tokenValidation`	(Required) Configuration to verify access token and extract granted authorities from the token. See TokenValidationConfiguration for more details

`TLSConfiguration`¶

{
    "auto": bool,
    "certFile": EnvironmentAwaredValue,
    "keyFile": EnvironmentAwaredValue,
    "advanced": object(TLSAdvancedConfiguration)
}

Fields	Description
`auto`	If true, generate a self-signed TLS certificate. Then save the generated certificate and private key in PEM format in `certFile` and `keyFile` respectively If false, use values from `certFile` and `keyFile`
`certFile`	Location to a file storing certificate in PEM format. Default is `cert.pem`
`keyFile`	Location to a file storing private key in PEM format. Default is `key.pem`
`advanced`	Additional TLS configuration

`TLSAdvancedConfiguration`¶

{
    "cipherSuites": array,
}

Fields	Description
`cipherSuites`	List of cipher suites to be enforced. Default to `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA` `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA` Go here to view all supported cipher suites

`TokenValidationConfiguration`¶

{
    "issuers": array,
    "cache": object(CacheConfiguration),
    "introspect": object(IntrospectionConfiguration),
    "jws": object(JWSConfiguration),
    "jwt": object(JWTConfiguration),
}

Fields	Description
`issuers`	Array of strings specifying approved entities who issue tokens
`cache`	Configuration of a token cache
`introspect`	Configuration of how to connect to introspection API
`jws`	Configuration of how to obtain JSON Web Keyset in order to validate JSON Web Signature
`jwt`	Configuration of how to handle JSON Web Token

`CacheConfiguration`¶

An LRU cache which also checks for expiration before returning the value. Below is the default configuration if not specified

{
    "limit": 80,
    "expirationInSeconds": 3600
}

Fields	Description
`limit`	Max number of items in the cache
`expirationInSeconds`	Expiry time for a cache item

`IntrospectionConfiguration`¶

{
    "endpoint": string,
    "authentication": object(AuthenticationConfiguration),
    "tlsConnection": object(TLSConnectionConfiguration)
}

Fields	Description
`endpoint`	Introspection API endpoint
`authentication`	Configuration of how to authenticate when invoking `endpoint`
`tlsConnection`	Configuration of TLS when connecting to `endpoint`

`AuthenticationConfiguration`¶

{
    "method": string,
    "credentials": map(string->EnvironmentAwaredValue)
}

Fields	Description
`method`	Defines authentication mechanism. Supported values are `client_secret_basic`: basic authentication `client_secret_form`: form authentication `private_key`: mutual TLS authentication
`credentials`	Defines key value pair used for the given authentication mechanism above. See below for the supported keys

Method	Keys
`client_secret_basic`	`clientId`, `clientSecret`
`client_secret_form`	`clientId`, `clientSecret`
`private_key`	`certFile`, `keyFile`

`TLSConnectionConfiguration`¶

{
    "insecureSkipVerify": bool,
    "certFile": EnvironmentAwaredValue,
    "caFile": EnvironmentAwaredValue
}

Fields	Description
`insecureSkipVerify`	If true, do not verify server TLS certificate
`certFile`	Location to a file storing server certificate in PEM format. Default is `server.crt`
`caFile`	Location to a file storing server CA certificate in PEM format. Default is `server.ca.cert`

`JWSConfiguration`¶

{
    "endpoint": string,
    "tlsConnection": object(TLSConnectionConfiguration)
}

Fields	Description
`endpoint`	API endpoint to obtain JSON Web Keyset
`tlsConnection`	Configuration of TLS when connecting to `endpoint`

`JWTConfiguration`¶

{
    "authorizationField": string,
    "preferIntrospection": bool
}

Fields	Description
`authorizationField`	Claim field name that is used to extract scopes for authorization. Default to `scope`
`preferIntrospection`	If true, introspection (if defined) result is used

`EnvironmentAwaredValue`¶

A regular string which allows value being read from an environment variable by specifying an URI with env scheme. For example: env://MY_VAR will return value from MY_VAR environment variable.

Supported Cipher Suites¶

TLS_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

OAuth2 Authz Server Integration¶

Examples on how to integrate Quorum Security Plugin with an OAuth2 Authorization Server are here.

OAuth2 Scopes¶

Scope is a mechanism to limit a client’s access to protected resources in Quorum Client RPC server. A client can request one ore more scopes from a token endpoint of an OAuth2 Provider. The access token issued to the client will be limited to the scopes granted.

The scope syntax is as follow:

    scope := "rpc://"rpc-string

    rpc-string := service-name delimiter method-name

    service-name := string

    delimiter := "." or "_"

    method-name := string

Examples¶

Protecting APIs

Scope	Description
`rpc://web3.clientVersion`	Allow access to `web3_clientVersion` API
`rpc://eth_*` or `rpc://eth_`	Allow access to all APIs under `eth` namespace
`rpc://*_version` or `rpc://_version`	Allow access to `version` method of all namespaces. E.g.: `net_version`, `ssh_version`

Change Log¶

v1.0.0¶

Initial release

security Enterprise Plugin¶

Configuration¶

TLSConfiguration¶

TLSAdvancedConfiguration¶

TokenValidationConfiguration¶

CacheConfiguration¶

IntrospectionConfiguration¶

AuthenticationConfiguration¶

TLSConnectionConfiguration¶

JWSConfiguration¶

JWTConfiguration¶

EnvironmentAwaredValue¶