25.5.28 ndb_sign_keys — Create, Sign, and Manage TLS Keys and Certificates for NDB Cluster

Management of TLS keys and certificates in implemented in NDB Cluster as the executable utility program ndb_sign_keys, which can normally be found in the MySQL bin directory. The program performs such functions as creating, signing, and retiring keys and certificates, and normally works as follows:

1. ndb_sign_keys connects to ndb_mgmd and fetches the cluster' configuration.

2. For each cluster node that is configured to run on the local machine, ndb_sign_keys finds the node' private key and sign it, creating an active node certificate.

Some additional tasks that can be performed by ndb_sign_keys are listed here:

• Obtaining configuration information from a config.ini file rather than a running ndb_mgmd

• Creating the cluster' certificate authority (CA) if it does not yet exist

• Creating private keys

• Saving keys and certificates as pending rather than active

• Signing the key for a single node as specified using command-line options described later in this section

• Requesting a CA located on a remote host to sign a local key

Options that can be used with ndb_sign_keys are shown in the following table. Additional descriptions follow the table.

Table 25.48 Command-line options used with the program ndb_sign_keys

Format	Description	Added, Deprecated, or Removed
--bind-host=host	Create certificate bound to hostname list of node types that should have certificate hostname bindings, from set (mgmd, db, api)	ADDED: 8.3.0
--bound-hostname=hostname	Create certificate bound to this hostname	ADDED: 8.3.0
--CA-cert=name, -C	Cluster CA Certificate file name	ADDED: 8.3.0
--CA-key=name, -K	Cluster CA Private Key file name	ADDED: 8.3.0
--CA-ordinal=name	Ordinal CA name; defaults to "First" for --create-CA and "Second" for --rotate-CA	ADDED: 8.3.0
--CA-search-path=name	Cluster CA file search path	ADDED: 8.3.0
--CA-tool=name, -X	Path to local executable helper tool	ADDED: 8.3.0
--check	Run periodic check of certificate expiry dates	ADDED: 8.3.0
--config-file=file, -f file	Read cluster configuration from this file.	ADDED: 8.3.0
--connect-retries=#	Number of times to retry connection before giving up	ADDED: 8.3.0
--connect-retry-delay=#	Number of seconds to wait between attempts to contact management server	ADDED: 8.3.0
--create-CA	Create cluster CA	ADDED: 8.3.0
--create-key	Creat or replace private keys	ADDED: 8.3.0
--curve=name	Named curve to use for node keys	ADDED: 8.3.0
--defaults-extra-file=path	Read given file after global files are read	ADDED: 8.3.0
--defaults-file=path	Read default options from given file only	ADDED: 8.3.0
--defaults-group-suffix=string	Also read groups with concat(group, suffix)	ADDED: 8.3.0
--duration=#	Lifetime of certificate signing request, in seconds	ADDED: 8.3.0
--help, -?	Display help text and exit	ADDED: 8.3.0
--keys-to-dir=dirname	Output directory for private keys (only); overrides --to-dir	ADDED: 8.3.0
--login-path=path	Read given path from login file	ADDED: 8.3.0
--ndb-connectstring=connection_string, -c connection_string	Set connect string for connecting to ndb_mgmd. Syntax: "[nodeid=id;][host=]hostname[:port]". Overrides entries in NDB_CONNECTSTRING and my.cnf	ADDED: 8.3.0
--ndb-mgm-tls=level	ndb_mgm client TLS requirement level	ADDED: 8.3.0
--ndb-tls-search-path=list	List of directories containing TLS keys and certificates	ADDED: 8.3.0
--no-config, -l	Do not obtain cluster configuration; create a single certificate	ADDED: 8.3.0
--no-defaults	Do not read default options from any option file other than login file	ADDED: 8.3.0
--no-login-paths	Do not read login paths from the login path file	(Supported in all NDB releases based on MySQL 8.3)
--passphrase=phrase	Passphrase used to sign keys	ADDED: 8.3.0
--node-id=#, -n	Create or sign key for node having this ID	ADDED: 8.3.0
--node-type=set, -t	Create or sign keys for one or more of node types mgmd, db, api	ADDED: 8.3.0
--pending	Save keys or certificates as pending, rather than as active	ADDED: 8.3.0
--print-defaults	Print program argument list and exit	ADDED: 8.3.0
--promote	Promote pending files to active, then exit	ADDED: 8.3.0
--remote-CA-host=hostname	address of remote CA host	ADDED: 8.3.0
--remote-exec-path	Full path to executable on remote CA host; must end in 'ndb_sign_keys[.exe]' or 'openssl[.exe]'	ADDED: 8.3.0
--remote-openssl	Run OpenSSL on CA host for key signing	ADDED: 8.3.0
--replace-by=#	Suggested certificate replacement date for periodic checks, as a number of days after expiration. Negative number indicates days before expiration	ADDED: 8.3.0
--rotate-CA	Rotate cluster CA	ADDED: 8.3.0
--schedule=list	Schedule of expiration dates assigned to certificates; see documentation for details	ADDED: 8.3.0
--sign	Create signed certificates. Used by default; disable with --skip-sign	ADDED: 8.3.0
--skip-sign	Create certificate signing requests	ADDED: 8.3.0
--stdio	Read CSR from stdin, write X.509 to stdout	ADDED: 8.3.0
--to-dir=dirname	Output directory for created files	ADDED: 8.3.0
--usage, -?	Display help text and exit; same as --help	ADDED: 8.3.0
--version, -V	Display version information and exit	ADDED: 8.3.0

• --bind-host

  Command-Line Format	--bind-host=host
  Type	String
  Default Value	mgmd, api

  Create a certificate bound to a hostname list of node types that should have certificate hostname bindings, from the set (mgmd,db,api).

• --bound-hostname

  Command-Line Format	--bound-hostname=hostname
  Type	String
  Default Value	[none]

  Create a certificate bound to the hostname passed to this option.

• --CA-cert

  Command-Line Format	--CA-cert=name
  Type	File name
  Default Value	NDB-Cluster-cert

  Use the name passed to this option for the CA Certificate file.

• --CA-key

  Command-Line Format	--CA-key=name
  Type	File name
  Default Value	NDB-Cluster-private-key

  Use the name passed to this option for the CA private key file.

• --CA-ordinal

  Command-Line Format	--CA-ordinal=name
  Type	String
  Default Value	[none]
  Valid Values	First Second

  Set the ordinal CA name; defaults to First for --create-CA and Second for --rotate-CA. The Common Name in the CA certificate is “MySQL NDB Cluster ordinal Certificate”, where ordinal is the ordinal name passed to this option.

• --CA-search-path

  Command-Line Format	--CA-search-path=name
  Type	File name
  Default Value	[none]

  Specify a list of directories to search for a CA file. On Unix platforms, the directory names are separated by colons (:); on Windows systems, the semicolon character (;) is used as the separator. A directory reference may be relative or absolute; it may contain one or more environment variables, each denoted by a prefixed dollar sign ($), and expanded prior to use.

  Searching begins with the leftmost named directory and proceeds from left to right until a file is found. An empty string denotes an empty search path, which causes all searches to fail. A string consisting of a single dot (.) indicates that the search path is limited to the current working directory.

  If no search path is supplied, the compiled-in default value is used. This value depends on the platform used: On Windows, this is $HOMEPATH\ndb-tls; on other platforms (including Linux), it is $HOME/ndb-tls. This default can be overridden by compiling NDB Cluster using -DWITH_NDB_TLS_SEARCH_PATH.

• --CA-tool

  Command-Line Format	--CA-tool=name
  Type	File name
  Default Value	[none]

  Designate an executable helper tool, including the path.

• --check

  Command-Line Format	--check

  Check certificate expiry dates.

• --config-file

  Command-Line Format	--config-file=file
  Disabled by	no-config
  Type	File name
  Default Value	[none]

  Supply the path to the cluster configuration file (usually config.ini).

• --connect-retries

  Command-Line Format	--connect-retries=#
  Type	Integer
  Default Value	12
  Minimum Value	-1
  Maximum Value	12

  Set the number of times that ndb_sign_keys attempts to connect to the cluster. If you use -1, the program keeps trying to connect until it succeeds or is forced to stop.

• --connect-retry-delay

  Command-Line Format	--connect-retry-delay=#
  Type	Integer
  Default Value	5
  Minimum Value	0
  Maximum Value	5

  Set the number of seconds after a failed connection attempt which ndb_sign_keys waits before trying again, up to the number of times determined by --connect-retries.

• --create-CA

  Command-Line Format	--create-CA

  Create the CA key and certificate.

• --create-key

  Command-Line Format	--create-key

  Create or replace private keys.

• --curve

  Command-Line Format	--curve=name
  Type	String
  Default Value	P-256

  Use the named curve for encrypting node keys.

• --defaults-extra-file

  Command-Line Format	--defaults-extra-file=path
  Type	String
  Default Value	[none]

  Read this option file after the global files are read.

• --defaults-file

  Command-Line Format	--defaults-file=path
  Type	String
  Default Value	[none]

  Read this option file only.

• --defaults-group-suffix

  Command-Line Format	--defaults-group-suffix=string
  Type	String
  Default Value	[none]

  Read not only the usual option groups, but also groups with the usual names and a suffix of string.

• --duration

  Command-Line Format	--duration=#
  Type	Integer
  Default Value	0
  Minimum Value	-500000
  Maximum Value	0
  Unit	seconds

  Set the lifetime of certificates or signing requests, in seconds.

• --help

  Command-Line Format	--help

  Print help text and exit.

• --keys-to-dir

  Command-Line Format	--keys-to-dir=dirname
  Type	Directory name
  Default Value	[none]

  Specify output directory for private keys (only); for this purpose, it overrides any value set for --to-dir.

• --login-path

  Command-Line Format	--login-path=path
  Type	String
  Default Value	[none]

  Read this path from the login file.

• --ndb-connectstring

  Command-Line Format	--ndb-connectstring=connection_string
  Type	String
  Default Value	[none]

  Set the connection string to use for connecting to ndb_mgmd, using the syntax [nodeid=id;][host=]hostname[:port]. If this option is set, it overrides the value set for NDB_CONNECTSTRING (if any), as well as any value set in a my.cnf. file.

• --ndb-mgm-tls

  Command-Line Format	--ndb-mgm-tls=level
  Type	Enumeration
  Default Value	relaxed
  Valid Values	relaxed strict

  Sets the level of TLS support required for the ndb_mgm client; one of relaxed or strict. relaxed (the default) means that a TLS connection is attempted, but success is not required; strict means that TLS is required to connect.

• --ndb-tls-search-path

  Command-Line Format	--ndb-tls-search-path=list
  Type	Path name
  Default Value (Unix)	$HOME/ndb-tls
  Default Value (Windows)	$HOMEDIR/ndb-tls

  Specify a list of directories containing TLS keys and certificates.

  For syntax, see the description of the --CA-search-path option.

• --no-config

  Command-Line Format	--no-config

  Do not obtain the cluster configuration; create a single certificate based on the options supplied (including defaults for those not specified).

• --no-defaults

  Command-Line Format	--no-defaults

  Do not read default options from any option file other than the login file.

• --no-login-paths

  Command-Line Format	--no-login-paths

  Do not read login paths from the login path file.

• --passphrase

  Command-Line Format	--passphrase=phrase
  Type	String
  Default Value	[none]

  Specify a CA key pass phrase.

• --node-id

  Command-Line Format	--node-id=#
  Type	Integer
  Default Value	0
  Minimum Value	0
  Maximum Value	255

  Create or sign a key for the node having the specified node ID.

• --node-type

  Command-Line Format	--node-type=set
  Type	Set
  Default Value	mgmd,db,api

  Create or sign keys for the specified type or types from the set (mgmd,db,api).

• --pending

  Command-Line Format	--pending

  Save keys and certificates as pending, rather than active.

• --print-defaults

  Command-Line Format	--print-defaults

  Print the program argument list, then exit.

• --promote

  Command-Line Format	--promote

  Promote pending files to active, then exit.

• --remote-CA-host

  Command-Line Format	--remote-CA-host=hostname
  Type	String
  Default Value	[none]

  Specify the address or hostname of a remote CA host.

• --remote-exec-path

  Command-Line Format	--remote-exec-path
  Type	Path name
  Default Value	[none]

  Provide the full path to an executable on the remote CA host specified with --remote-CA-host.

• --remote-openssl

  Command-Line Format	--remote-openssl

  Use OpenSSL for signing of keys on the remote CA host specified with --remote-CA-host.

• --replace-by

  Command-Line Format	--replace-by=#
  Type	Integer
  Default Value	-10
  Minimum Value	-128
  Maximum Value	127

  Suggest a certificate replacement date for periodic checks, as a number of days after the CA expiration date. Use a negative number to indicate days before expiration.

• --rotate-CA

  Command-Line Format	--rotate-CA

  Replace an older CA with a newer one. The new CA can be created using OpenSSL, or you can allow ndb_sign_keys to create the new one, in which case the new CA is created with an intermediate CA certificate, signed by the old CA.

• --schedule

  Command-Line Format	--schedule=list
  Type	String
  Default Value	120,10,130,10,150,0

  Assign a schedule of expiration dates to certificates. The schedule is defined as a comma-delimited list of six integers, in the format shown here:

  api_valid,api_extra,dn_valid,dn_extra,mgm_valid,mgm_extra

  These values are defined as follows:

  • api_valid: A fixed number of days of validity for client certificates.

    api_extra: A number of extra days for client certificates.

    dn_valid: A fixed number of days of validity for client certificates for data node certificates.

    dn_extra: A number of extra days for data node certificates.

    mgm_valid: A fixed number of days of validity for management server certificates.

    mgm_extra: A number of extra days for management server certificates.

  In other words, for each node type (API node, data node, management node), certificates are created with a lifetime equal to a whole fixed number of days, plus some random amount of time less than or equal to the number of extra days. The default schedule is shown here:

  --schedule=120,10,130,10,150,0

  Following the default schedule, client certificates begin expiring on the 120^th day, and expire at random intervals over the next 10 days; data node certificates expire at random times between the 130^th and 140^th days; and management node certificates expire on the 150^th day (with no random interval following).

• --sign

  Command-Line Format	--sign
  Disabled by	skip-sign

  Create signed certificates; enabled by default. Use --skip-sign to create certificate signing requests instead.

• --skip-sign

  Command-Line Format	--skip-sign

  Create certificate signing requests instead of signed certificates.

• --stdio

  Command-Line Format	--stdio

  Read certificate signing requests from stdin, and write X.509 to stdout.

• --to-dir

  Command-Line Format	--to-dir=dirname
  Type	Directory name
  Default Value	[none]

  Specify the output directory for created files. For private key files, this can be overriden using --keys-to-dir.

• --usage

  Command-Line Format	--usage

  Print help text, then exit (alias for --help).

• --version

  Command-Line Format	--version

  Print version information, then exit.