ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-03-14 00:06:45 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

REFACTOR - Removing Network Services code and docs

Browse Source
This commit is contained in:
Katelyn Baker 2018-05-31 13:48:56 +01:00
parent 63d357f62b
commit f56f07b34a
10 changed files with 6 additions and 515 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/source/certificate-revocation.rst
View File

@ -51,7 +51,7 @@ Submission of the certificate revocation requests expects the following fields t
:SUPERSEDED: This reason indicates that the certificate has been superseded.
:CESSATION_OF_OPERATION: This reason indicates that the certificate is no longer needed.
:PRIVILEGE_WITHDRAWN: This reason indicates that the privileges granted to the subject of the certificate have been withdrawn.
:reporter: Issuer of this certificate revocation request.
@ -61,11 +61,3 @@ Note: At least one of the three: certificateSerialNumber, csrRequestId or legalN
Because of the proprietary serialization mechanism, it is assumed that those endpoints are used by dedicated tools that support this kind of data encoding.
Internal protocol
-----------------
There is an internal communication protocol between the revocation service and the HSM signing service for producing the signed CRLs.
This does not use HTTP to avoid exposing any web vulnerabilities to the signing process.

5
docs/source/crr-submission-tool.rst
View File

@ -1,5 +0,0 @@
Certificate Revocation Request Submission Tool
==============================================
The purpose of the Certificate Revocation Request (CRR) Submission Tool is to facilitate the process of creating a CRR.
The tool is designed with the support line in mind, and assumes it is for internal (i.e. within the doorman service managing company) usage.

12
docs/source/database-migration.rst
View File

@ -182,8 +182,6 @@ Currently it has these features:
using this tool, the CorDapp can be "lifted" (`--create-migration-sql-for-cordapp`).
The reason this is needed is because those CorDapps don't handle this enterprise level concern.
See below for details.
5. The tool is intended to be used to run database migrations on "Doorman" instances. There is no difference from running over a normal node.
It has the following command line options:
@ -192,11 +190,11 @@ It has the following command line options:
==================================== =======================================================================
Option Description
==================================== =======================================================================
--help Print help message.
--mode Either 'NODE' or 'DOORMAN'. By default 'NODE'.
--base-directory(*) The node or doorman directory.
--config-file The name of the config file. By default 'node.conf' for a simple node and 'network-management.conf' for a doorman.
--doorman-jar-path The path to the doorman fat jar.
--help Print help message
--mode Either 'NODE' or 'DOORMAN'. By default 'NODE'
--base-directory(*) The node directory
--config-file The name of the config file, by default 'node.conf'
--doorman-jar-path For internal use only
--create-migration-sql-for-cordapp Create migration files for a CorDapp. You can specify the fully qualified name of the `MappedSchema` class. If not specified it will generate the migration for all schemas that don't have migrations. The output directory is the base-directory, where a `migration` folder is created.
--dry-run Output the database migration to the specified output file. The output directory is the base-directory. You can specify a file name or 'CONSOLE' if you want to send the output to the console.
--execute-migration This option will run the db migration on the configured database. This is the only command that will actually write to the database.

28
docs/source/hsm-cert-generator.rst
View File

@ -1,28 +0,0 @@
HSM Certificate Generation Tool
===============================
The purpose of the HSM Certificate Generation Tool is to provide means for corda certificate hierarchy generation on an HSM infrastructure.
The tool is intended to be executed automatically, therefore no human interaction is required. All necessary data is fed
to the tool from the provided configuration file.
In the configuration file, the tool expects 2 main parts to be configured:
* HSM device location
* HSM user(s) credentials, that will be used to gain access to the HSM device and to its functionality related to key/certificate generation.
As such, it is assumed that the relevant privileged users are already set-up on the HSM prior to the script execution.
The tool supports multi-user authentication, so it works with more strict policies, where there is a need for distributed privileges.
* Certificate configuration.
The tool is designed to generate a single certificate in one execution. The type of the generated certificate is driven by the certificateType parameter.
Currently in Corda there is a 2-level certificate hierarchy composed of a root certificate and 2 intermediate certificates (one for CSR and one for network map/parameters signing).
Most attributes for those certificates are taken from the configuration file provided to the tool during the execution time. Some of them (e.g. aliases), however,
are fixed in the code due to compatibility aspects.
In addition to the certificate hierarchy creation on the HSM side, the tool stores the created root CA certificate in a trust store, which is intended for distribution across the nodes.
IMPORTANT NOTE:
===============
Caution is required when the tool is used, especially in case where certificate attributes needs to be altered.
Incorrect usage of the tool may result in existing certificates being overriden and possible network corruption.

12
docs/source/running-crr-submission-tool.rst
View File

@ -1,12 +0,0 @@
Running the Certificate Revocation Request Submission Tool
==========================================================
The purpose of this tool is to facilitate the certificate revocation request submission process.
See :doc:`crr-submission-tool` for more details.
See the Readme under ``network-management`` for detailed building instructions.
Command line argument
----------------------
At startup, the Certificate Revocation Request Submission Tool takes only one command line argument: ``--submission-url``,
that should be followed by the url to the certificate revocation request submission endpoint.

40
docs/source/running-dev-keystore-generator.rst
View File

@ -1,40 +0,0 @@
Running the dev keystore generator
==================================
The dev keystore generator is a utility tool designed only for internal use. Sometimes our certificates change (e.g. new
extensions are added, some of them are modified...). In order to stay consistent with the rest of the Corda platform and in
particular with Corda node (and its DEV execution mode), we need a facility that would allow us to easily create keystore containing
both root and doorman certificates together with their keys. Those certificates will reflect the most recent state of the Corda certificates.
In addition, a truststore file (containing the root certificate) is also generated. Once generated, those files (i.e. keystore and truststore)
can be copied to an appropriate node directory.
Although, the output of the tool is strongly bound to the node execution process (i.e. expected key store file name, trust store file name, passwords are hardcoded),
it can be used to generate arbitrary keystore and truststore files with Corda certificates. Therefore, the tool supports a custom configuration.
Configuration file
------------------
At startup the dev generator tool reads a configuration file, passed with ``--config-file`` on the command line.
This is an example of what a generator configuration file might look like:
.. literalinclude:: ../../network-management/dev-generator.conf
Invoke the tool with ``-?`` for a full list of supported command-line arguments.
If no configuration file is provided, all the options default to the node expected values.
Configuration parameters
------------------------
Allowed parameters are:
:privateKeyPass: Password for both Root and Doorman private keys. Default value: "cordacadevkeypass".
:keyStorePass: Password for the keystore file. Default value: "cordacadevpass".
:keyStoreFileName: File name for the keystore file. Default value: "cordadevcakeys.jks".
:trustStorePass: Password for the truststore file. Default value: "trustpass".
:trustStoreFileName: File name for the truststore file. Default value: "cordatruststore.jks".
:directory: Directory in which both keystore and trustore files should be created. Default value: "./certificates"

157
docs/source/running-doorman.rst
View File

@ -1,157 +0,0 @@
Running a doorman service
=========================
See the Readme in under ``network-management`` for detailed building instructions.
Configuration file
------------------
At startup doorman reads a configuration file, passed with ``--configFile`` on the command line.
This is an example of what a doorman configuration file might look like:
.. literalinclude:: ../../network-management/doorman.conf
Invoke doorman with ``-?`` for a full list of supported command-line arguments.
Configuration parameters
------------------------
Allowed parameters are:
:keystorePassword: the keystore password
:caPrivateKeyPassword: the ca private key password
:rootKeystorePassword: Password for the root store
:rootPrivateKeyPassword: Password for the root private key
:address: The host and port on which doorman runs
:database: database properties. The same (including its default value) as for node configuration (see :doc:`corda-configuration-file`).
:dataSourceProperties: datasource properties
:doorman: Doorman specific configuration
:approveAll: Whether to approve all requests (defaults to false), this is for debug only.
:approveInterval: How often to process Jira approved requests in seconds.
:crlEndpoint: URL to the CRL issued by the Doorman CA. This parameter is only useful when Doorman is executing in the local signing mode.
:jira: The Jira configuration for certificate signing requests
:address: The URL to use to connect to Jira
:projectCode: The project code on Jira
:username: Username for Jira
:password: Password for Jira
:revocation: Revocation service specific configuration
:localSigning: Configuration for local CRL signing using the file key store. If not defined then an external signing process is assumed.
:crlUpdateInterval: Validity time of the issued certificate revocation lists (in milliseconds).
:crlEndpoint: REST endpoint under which the certificate revocation list can be obtained.
It is needed as this URL is encoded in the certificate revocation list itself.
:crlCacheTimeout: Certificate revocation list cache entry expiry time (in milliseconds).
This value indicates for how long the crl is kept on the server side before querying the DB.
:approveInterval: How often to process Jira approved requests in seconds.
Processing in this context means: querying the JIRA for approved/rejected request and syncing with the Doorman persistence.
:approveAll: Whether to approve all requests (defaults to false), this is for debug only.
:caCrlPath: Path (including the file name) to the location of the file containing the bytes of the CRL issued by the ROOT CA.
Note: Byte encoding is the one given by the package java.security.cert.X509CRL.encoded method - i.e. ASN.1 DER
:emptyCrlPath: Path (including the file name) to the location of the generated file containing the bytes of the empty CRL issued by the ROOT CA.
Note: Byte encoding is the one given by the package java.security.cert.X509CRL.encoded method - i.e. ASN.1 DER
:jira: The Jira configuration for certificate revocation requests
:address: The URL to use to connect to Jira
:projectCode: The project code on Jira
:username: Username for Jira
:password: Password for Jira
:networkMap: Network map specific configuration.
:cacheTimeout: Network map cache entry expiry time (in milliseconds).
:signInterval: How often to sign the network map in seconds.
:keystorePath: Path for the keystore. If not set (or null is passed) doorman will NOT perform any signing.
This is required in case of the HSM integration where signing process is offloaded (from doorman) to an external service
that binds with an HSM.
:rootStorePath: Path for the root keystore
:caCrlPath: Path (including the file name) to the location of the generated file containing the bytes of the CRL issued by the ROOT CA.
This configuration parameter is used in the ROOT_KEYGEN mode.
Note: Byte encoding is the one given by the package java.security.cert.X509CRL.encoded method - i.e. ASN.1 DER
:caCrlUrl: URL to the CRL issued by the ROOT CA. This URL is going to be included in the generated CRL that is signed by the ROOT CA.
This configuration parameter is used in the ROOT_KEYGEN and CA_KEYGEN modes.
:emptyCrlPath: Path (including the file name) to the location of the generated file containing the bytes of the empty CRL issued by the ROOT CA.
This configuration parameter is used in the ROOT_KEYGEN mode.
Note: Byte encoding is the one given by the package java.security.cert.X509CRL.encoded method - i.e. ASN.1 DER
This CRL is to allow nodes to operate in the strict CRL checking mode. This mode requires all the certificates in the chain being validated
to point a CRL. Since the TLS-level certificate is managed by the nodes, this CRL is a facility one for infrastructures without CRL provisioning.
:emptyCrlUrl: URL to the empty CRL issued by the ROOT CA. This URL is going to be included in the generated empty CRL that is signed by the ROOT CA.
This configuration parameter is used in the ROOT_KEYGEN mode.
Bootstrapping the network parameters
------------------------------------
When doorman is running it will serve the current network parameters. The first time doorman is
started it will need to know the initial value for the network parameters.
The initial values for the network parameters can be specified with a file, like this:
.. literalinclude:: ../../network-management/network-parameters.conf
And the location of that file can be specified with: ``--update-network-parameters``.
Note that when reading from file:
1. ``epoch`` will always be set to 1,
2. ``modifiedTime`` will be the doorman startup time
``epoch`` will increase by one every time the network parameters are updated.
Bootstrapping the network map
-----------------------------
The network map is periodically refreshed, with frequency driven by the 'signInterval' parameter when local signing is in use.
In case of an external signing service it depends on that service configuration. Due to the design decisions dictated by the security concerns
around the external signing service, doorman is not allowed to connect directly with the signing sevice. Instead, the external service is
expected to access the doorman database in order to obtain signature requiring data.
Therefore, doorman takes a passive role considering all signing process related aspects.
Network map refresh happens only if there is a change to the current one (i.e. most recently created version of the network map).
See the :doc:`signing-service` for a more detailed description of the service.
When dealing with a fresh deployment (i.e. no previous data is present in the doorman database),
it may take some time until the network map is available. This is caused by the aforementioned decoupling of the signing
process from doorman itself.
Bootstrapping the certificate revocation list
---------------------------------------------
Upon doorman startup, the revocation service becomes available serving the certificate revocation list and providing endpoints
for certificate revocation request submission. It is assumed, that an empty signed CRL exists prior to the revocation service startup.
The revocation service exposes its API in two ways: via REST endpoints and via sockets.
While the former are meant to be used externally by network nodes (e.g. for the certificate revocation request submission,
certificate revocation list retrieval...), the latter is designed for internal communication with other proprietary services (e.g. HSM signing service).
The certificate revocation requests have the same lifecycle as the certificate signing requests.
For that purpose (and in the same manner) the revocation service is integrated with JIRA which is configured according
to the parameters specified in the doorman configuration file.
As mentioned, the revocation service provides the certificate revocation list. The list itself is signed externally (i.e. HSM signing service).
Therefore some delay, during the initial deployment of the service, is expected as those two services execute independently.

82
docs/source/running-hsm-cert-generator.rst
View File

@ -1,82 +0,0 @@
Running the HSM Certificate Generation tool
===========================================
The purpose of this tool is to facilitate the process of certificate generation on the HSM infrastructure.
See :doc:`hsm-cert-generator` for more details.
See the Readme under ``network-management`` for detailed building instructions.
Configuration file
------------------
At startup, the HSM Certificate Generation Tool reads a configuration file, passed with ``--config-file`` on the command line.
This is an example of what a tool configuration file might look like:
.. literalinclude:: ../../network-management/cert-generator.conf
General configuration parameters
--------------------------------
Allowed parameters are:
:hsmHost: IP address of the HSM device.
:hsmPort: Port number of the HSM device.
:userConfigs: List of user authentication configurations. See below section on User Authentication Configuration.
:certConfig: Certificate specific configuration. See below section on Certificate Configuration.
:trustStoreDirectory: Path to the directory where the generated trust store should be placed.
The name of the generated file is "network-root-truststore.jks".
If the trust store file does not exist, it will be created.
IMPORTANT - This trust store is intended to be distributed across the nodes.
Nodes are hardcoded to use "network-root-truststore.jks" file as the trust store name.
As such, it is required that the file name is as the one expected by nodes.
:trustStorePassword: Password for the generated trust store.
Certificate Configuration
-------------------------
:certificateType: Type of the certificate to be created. Allowed values are:
ROOT_CA, INTERMEDIATE_CA, NETWORK_MAP.
:rootKeyGroup: This is an HSM specific parameter that corresponds to key name spacing for the root key. It is ignored if the certificateType value is ROOT_CA. See Utimaco documentation for more details.
:subject: X500Name formatted string to be used as the certificate public key subject.
:validDays: Days number for certificate validity.
:crlDistributionUrl: Url to the certificate revocation list of this certificate. If not defined the CRL information will not be added to the certificate.
:crlIssuer: X500 name of the certificate revocation list issuer - e.g. "L=London, C=GB, OU=Org Unit, CN=Service Name". If the crlDistributionUrl configuration option is specified but this parameter is not, then the certificate issuing authority is considered to be the CRL issuer for this certificate.
:keyCurve: Key algorithm curve type. See Utimaco supported values. "NIST-P256" has been used for experiments.
:keyExport: Enables key exporting. 1 for allow, 0 for deny.
:keyGenMechanism: HSM key generation process specific options. In the experiments the integer value being the logic OR of the two following (MECH_KEYGEN_UNCOMP = 4 or MECH_RND_REAL = 0) has been used. See Utimaco documentation for more details.
:keyOverride: Whether to override the key if already exists or not. 1 for override and 0 for NOT override.
:keySpecifier: This is an HSM specific parameter that corresponds to key name spacing of the generated key. See Utimaco documentation for more details.
:keyGroup: This is an HSM specific parameter that corresponds to key name grouping of the generated key. See Utimaco documentation for more details.
User Authentication Configuration
---------------------------------
Allowed parameters are:
:username: HSM username. This user needs to be allowed to generate keys/certificates and store them in HSM.
:authMode: One of the 3 possible authentication modes:
PASSWORD - User's password as set-up in the HSM
CARD_READER - Smart card reader authentication
KEY_FILE - Key file based authentication.
:authToken: Depending on the authMode it is either user's password or path to the authentication key file. In case of the CARD_READER authMode value, this can be omitted.
:keyFilePassword: Only relevant, if authMode == KEY_FILE. It is the key file password.

93
docs/source/running-signing-service.rst
View File

@ -1,93 +0,0 @@
Running the signing service
===========================
The signing service is a bridge between the networking service and the HSM infrastructure. It is responsible for retrieving
pending requests for signatures and managing the process of securing these signatures from an HSM infrastructure.
The signing service has two execution modes. Each mode focuses on signing one of the two different types of data: certificate signing requests and network map.
Signing of the network map is an automatic process (i.e. does not require human intervention) that retrieves from the database the network map data to be signed.
Certificate signing requests, on the other hand, require human-in-the-loop to be processed and therefore the signing process relies on the console-based interface, that allows for user interaction.
Depending on the configuration each of those processes can be enabled or disabled (see below for more details).
See the :doc:`signing-service` for a more detailed description of the service.
Configuration file
------------------
At startup the signing service reads a configuration file, passed with ``--config-file`` on the command line.
This is an example of what a signing service configuration file might look like for doorman:
.. literalinclude:: ../../network-management/hsm-for-doorman.conf
For network map:
.. literalinclude:: ../../network-management/hsm-for-networkmap.conf
Invoke the signing service with ``-?`` for a full list of supported command-line arguments.
Configuration parameters
------------------------
Allowed parameters are:
:device: HSM connection string. It is of the following format 3001@127.0.0.1, where 3001 is the port number.
Default value: "3001@127.0.0.1"
:keySpecifier: HSM key specifier. This parameter is vendor specific (see Utimaco docs).
:database: Database properties.
:dataSourceProperties: Data source properties. It should describe (or point to) the Doorman database.
:doorman: CSR signing process configuration parameters. If specified, the signing service will sign CRL or approved CSRs depending on the operating mode defined in the mode parameter.
:validDays: Number of days issued signatures are valid for.
:rootKeyStoreFile: Location of the key store (trust store) containing the root certificate.
:rootKeyStorePassword: Password for the key store (trust store) containing the root certificate.
:keyGroup: HSM key group for the doorman certificate key. This parameter is vendor specific (see Utimaco docs).
:mode: Manual HSM signing mode. Allowed values:
:CSR: Run the signing service for the certificate signing requests.
:CRL: Run the signing service for the certificate revocation list.
:crlDistributionPoint: Certificate revocation list location for the node CA certificate.
:crlServerSocketAddress: Address of the socket connection serving the certificate revocation list.
:crlUpdatePeriod: Validity time of the issued certificate revocation lists (in milliseconds).
:authParameters: Authentication configuration for the CSR signing process.
:mode: Authentication mode. Allowed values are: PASSWORD, CARD_READER and KEY_FILE
:password: Key file password. Valid only if the authentication mode is set to KEY_FILE.
:keyFilePath: Key file path. Valid only if authentication mode is set to KEY_FILE.
:threshold: Minimum authentication strength threshold required for certificate signing requests.
:networkMap: Network map signing process configuration parameters. If specified, the signing service will sign the network map.
:username: HSM username to be used when communicating with the HSM.
:keyGroup: HSM key group for the network map certificate key. This parameter is vendor specific (see Utimaco docs).
:authParameters: Authentication configuration for the CSR signing process.
:mode: Authentication mode. Allowed values are: PASSWORD and KEY_FILE
:password: If the authentication mode is set to KEY_FILE, then it is the key file password.
If the authentication mode is set to PASSWORD, then it is the password string.
:keyFilePath: Key file path. Valid only if authentication mode is set to KEY_FILE.
:threshold: Minimum authentication strength threshold required for certificate signing requests.
Expected behaviour and output upon the service start-up
-------------------------------------------------------
A commandline-based interface (with different menu options) is presented to a user.

82
docs/source/signing-service.rst
View File

@ -1,82 +0,0 @@
HSM Signing Service
===================
The HSM Signing Service is designed to act as a bridge between the networking service and the HSM infrastructure.
Due to possible security concerns, the signing service is meant to be hosted on private premises and not in a cloud environment.
That does not apply to the networking service, which may be hosted by a cloud provider. Such a design allows for, and in fact
was driven by the requirement of, permitting only outgoing connections between the two deployments (i.e. private and cloud).
Having this deployment design in mind, the signing service initiates connection to the networking service database and
retrieves all the data that has to be signed.
This retrieval happens automatically (based on the pre-configured time interval) in case of Network Map and Certificate Revocation List signing.
The on-demand approach applies only in case of Certificate Signing Requests signatures as they involve human interaction (for authentication credentials input).
For that purpose, the service provides a commandline-based interface and guides the user throughout the signing process.
The signing service assumes an HSM configuration in place - i.e. all users and certificates should be set-up on the HSM box,
prior to the signing service deployment and usage. Nevertheless, currently, the signing service comes with a simple utility
that allows an authenticated HSM user to generate the root and intermediate certificates. The utility is only a temporary
solution and should NOT be used in case of production deployment. This convenience feature will be removed in a future release.
Following, are the steps for the signing service operation with respect to every kind of object it signs:
Certificate Signing Request Steps
---------------------------------
* The networking service receives a certificate signing request and approves it (more specifically the certificate signing request is approved using an external ticket tracking tool - e.g. Jira).
It is ready to be signed.
* A privileged user chooses (using the commandline interface) that she wants to sign the approved requests.
* A connection to the networking service database is established and all approved requests are fetched and listed to the user.
* After selecting an appropriate option (either signing all approved requests or just some of them) user is prompted for her username (in terms of the HSM setup).
* Next step is to confirm user's identity against the HSM. In this case, the signing service supports two authentication methods: Password or Card Reader.
* If the user's identity is confirmed (using one of the above methods) and her privileges are strong enough, then the signing process commences using the configured intermediate certificate.
* After that, the networking service database is updated with the signed certificates.
* In case of insufficient user privileges, the service will prompt for another user to be authenticated.
Visualised steps available as :download:`pdf <resources/hsm_csr_signing_flow.pdf>`
Certificate Revocation List Steps
---------------------------------
* The networking service receives a certificate revocation request and approves it (more specifically the certificate signing request is approved using an external ticket tracking tool - e.g. Jira).
It is ready to be included into the certificate revocation list.
* Periodically (the time interval is pre-configured at the deployment time), the signing service fetches all approved certificate revocation requests. If the list is empty, then nothing happens and means that the current Certificate Revocation List remains unchanged.
* If there is at least one approved certificate revocation request, it means that a new certificate revocation list needs to be created and signed.
* In such a case, the service fetches all (already) revoked certificate revocation requests
* It builds a new certificate revocation list that combines already revoked requests and approved ones.
* The list is signed on HSM with an intermediate certificate whose name (together with the auto-user credentials) was pre-configured at the signing service deployment time
* The signed list is serialised and stored in the networking service database ready to be served. Also, all approved requests become revoked now.
Signing Network Map and Network Parameters
------------------------------------------
* The networking service receives a new (or updated) node info.
* Periodically (the time interval is pre-configured at the deployment time), the signing service fetches from the database all information needed to construct new network map, which includes:
- current network map,
- all node info objects with valid certificates,
- current network parameters
- information on parameters update (if exists).
* A new network map object is created out of the fetched data.
* If the new network map hash does not differ from the current network map hash, then nothing happens and current network map remains unchanged.
* If they are different, then the newly created network map object is serialized using the Corda AMQP serialisation format and signed by the dedicated intermediate certificate stored in HSM.
The same process applies to network parameters which need to be signed separately.
* Once signed, the new network map data is stored in the networking service database and available for nodes to retrieve when they next poll for the network map.