new-world

Creates a new security world, or adds or restores a HSM to an existing security world.

new-world [ACTION] [OPTION] [-m MODULE] [FEATURES]

Prerequisites for using new-world

  • Most options of new-world require a privileged connection between the host machine on which you run it and the HSM that it uses to administer the security world.

  • The HSM must be in pre-initialization mode for the new-world utility to work with the HSM to create, configure, erase a security world or to enrol the HSM into the security world. Furthermore, if you use new-world to re-configure an HSM, you will have to restart the HSM into operational state.
    If the HSM is not in the pre-initialization mode, new-world advises you that you must put the HSM in this mode and waits until you have changed the HSM mode before continuing. See

  • If the HSM is ready for creating, repprogramming, or erasing a security world (that is, it’s in the pre-initialization mode), new-world prompts you for smart cards and passphrases as required.

  • If new-world cannot interpret the command line, it displays its usage message and exits. It does not create a security world and does not modify the existing security world.

  • If you attempt to set a quorum for a feature that you have disabled or if you attempt to set a quorum too high, new-world displays an error and exits.

  • If new-world cannot find the key-management data, it displays the message new-world: no existing world to load

new-world [ACTIONS]

You can use new-world in three different ways to perform three different ACTIONs. Each ACTION has its own options.

If you do not enter a specific action, new-world selects one of [-i] or [-l], depending on whether you have already created a security world.

Action Description

-i, --initialize

Initializes a new security world according to the specified parameters and programs it into the given module.

new-world [-i] [-SRG] [-m MODULE] [--mode=SWORLD-MODE] [-c CIPHER-SUITE] -Q K/N [FEATURES]

Creating a new security world replaces any existing /opt/nfast/kmdata/local/ (Linux) or %NFAST_KMDATA%\local (Windows) directory.

Replacing an existing security world in this way does not delete the security world’s host data and recovery and replacement data, but renames the existing /opt/nfast/kmdata/local/ (Linux) or %NFAST_KMDATA%\local (Windows) directory in which these reside as %NFAST_KMDATA%\localN (Linux) or /opt/nfast/kmdata/localN (Windows) where N is an integer assigned depending on how many security worlds have been previously saved during overwrites.

-l --program

Programs a module with an existing security world (enrols the module into the security world).

new-world [-l] [-S] [-m MODULE]

Adds an HSM to an existing security world in the Key Management Data directory.
If you have multiple HSMs available, you can use the -m option to specify one HSM. If you do not specify an HSM, new-world adds all available HSMs to the security world.

-e --factory

Restores a module to its factory default condition:

  • the only module key is KM0

  • no operations require NSO certificates

  • KNSO is the single-DES key 0101010101010101

You must run new-world -m=<module-id> separately for each HSM that you want to factory state.

new-world [-e] [-m MODULE]

new-world [OPTIONS]

Option Description

c, --cipher-suite=<CIPHER-SUITE>

Specifies the Cipher suite and type of key that is used to protect the new security world. In v3 security worlds, you must set <CIPHER-SUITE> to DLf3072s256mAEScSP800131Ar1.

-R, --no-recovery

Disables OCS and softcard replacement; see Replacing Operator Card Sets.

Equivalent to setting !r.

By default, new-world creates key recovery and replacement data that is protected by the cryptographic keys on the ACS. This option does not give Entrust or any other third party access to your keys. Keys can only be recovered if authorization from the ACS is available. We recommend that you leave OCS and softcard recovery and replacement functionality enabled.

Entrust recommend that you do not disable the recovery and replacement option because if you set the --no-recovery option, you can never replace lost or damaged OCSs generated for that security world. Therefore, you could never recover any keys protected by lost or damaged OCSs, even if the keys themselves were generated as recoverable (which is the default for key generation).
OCS and softcard replacement cannot be enabled after security world creation without reinitializing the security world and discarding all the existing keys within it.

Default: disabled

--reduced-features

Uses a reduced default feature set when it creates the security world:

  • no passphrase recovery (-R)

  • no NVRAM

  • no RTC

  • no FTO

  • no NSO delegate keys

Such a reduced-features security world can perform many operations faster than more fully featured security worlds.

This option must be the first option on the command line: new-world -i --reduced-features

Default: *dis*abled

-S, --no-remoteshare-cert

Prevents the HSM from becoming a target for remote shares. If you do not want an HSM to be able to read remote card sets, initialize it by running `new-world -S <module-id>.

--mode=MODE

Available modes:

(none specified)

Compliant with FIPS 140-2 Level 2
fips-140-level-3

Compliant with FIPS 140-2 Level 3
common-criteria-cmts

Supports _Common Criteria PP 419 221-5
In this mode, new-world requires a minimum K of 2

Default: no mode is specified, a FIPS 140-2 Level 2 compliant security world is created

new-world [FEATURE] syntax

The feature expressions in the new-world utility is a comma-separated list of <feature-terms>, each of which can optionally be flanked by an <operator> and the <quorum-info> for the ACS that is required to manage the feature:

<operator><feature-term><quorum-info>
Term Description

<feature-term>

Name of the feature, see new-world [FEATURES].

<operator>

double dash (--) to enable the feature
exclamation point (!), or no- to turn off the feature
Three features remain available for use on presentation of the standard ACS quorum, even if turned off using the ! operator. Setting the quorum of these features to 0 has the same effect as turning them off using the ! operator.

  • nvram

  • rtc

  • fto

    Some Linux shells interpret ! character as history expansion. You must escape and must be escaped with a backslash, \!. The dash may be interpreted as being the start of an command-line option unless you have used the -f option or specified an HSM without including the -m flag.

<quorum-info>

=<n>
The quorum of cards from the ACS required to use the feature

new-world [FEATURES]

Feature Description

--disablepkcs1pad

Disables the use of PKCS#1 v1.5 padding. All attempts to use PKCS#1 v1.5 padding for encryption or decryption operations will be rejected.
PKCS#1 v1.5 signature operations are not affected.
PSS and OAEP are not affected.
Default: enabled

--dsee

Specifies that that ACS authorization is needed to enable SEE World debugging. See Debugging SEE machines.
Default: enabled

--dseeall

Enables SEE World debugging for all users.
See Debugging SEE machines.
If you try to set the Cmd_CreateSEEWorld_Args_flags_EnableDebug CodeSafe flag in a security world that does not allow SEE debugging, the CreateSEEWorld command returns AccessDenied. This also occurs if you call CreateSEEWorld in a security world where SEE debugging is restricted and an appropriate certifier is not present.

The dseeall option is designed for testing purposes only and to use extended debugging for the HSM, you must enable dseeall. Do not enable this feature on production security worlds as it may enable SEE applications to leak security information.
Default: *dis*abled

-G, --audit-logging

Configures the security world and the HSM on which it is being created for audit logging, creating a log signing key for each HSM. The log destination must have already been set in the hardserver configuration file. See Audit Logging.
Audit logging is automatically enabled when the security world is created in common-criteria-cmts mode.
Default: enabled

--fto

Specifies that ACS authorization is needed to enable foreign token operations (FTO).
If you set the !fto flag, that is, turn off FTO, you will not be able to use smart cards to import keys.

+ This feature remains available for use on presentation of the standard ACS quorum, even if turned off using the ! operator. Setting the quorum of this feature to 0 has the same effect as turning it off using the ! operator.
Default: enabled

--max-keyusage

Specifies a maximum reauthorization condition in terms of number of key usages since authorization for Assigned keys in common-criteria-cmts mode. A use limit compatible with the specified maximum will be applied at key creation time and can be verified for Assigned keys. If this is not set then no --max-keyusage limit is applied to Assigned keys on creation.
Only in common-criteria-cmts mode
Satisfies the Protection Profile requirement for the administrator to set re-authorization conditions when they are creating an Assigned Key.
Default: enabled

--max-keytimeout

Specifies a maximum reauthorization condition in terms of a TIMEOUT since authorization for Assigned keys in common-criteria-cmts mode. By default, an integer given for TIMEOUT is interpreted in seconds, but you can supply values for TIMEOUT in the form Ns, Nh, or Nd where N is an integer and s specifies second, h specifies hours, and d specifies days. A use limit compatible with the specified maximum will be applied at key creation time and can be verified for Assigned keys. If this is not set then no limit is applied to Assigned keys on creation.
Only in common-criteria-cmts mode
Satisfies the Protection Profile requirement for the administrator to set re-authorization conditions when they are creating an Assigned Key.
Default: enabled

--no-remoteshare-cert

This option prevents making the HSM from becoming a target for remote shares.
Default: enabled

--no-strict-rsa-keygen

If you have not specified a mode parameter you can use the -no-strict-rsa-keygen flag to disable the UseStrongPrimes setting. Otherwise it will be enabled by default. See secworld-admin:secworld-options.adoc#UseStrongPrimes.
Default: enabled

t, --nso-timeout=<TIMEOUT>

This option allows you to specify the time-out for new security worlds. By default, an integer given for TIMEOUT is interpreted in seconds, but you can supply values for TIMEOUT in the form N s, N h, or N d where N is an integer and s specifies second, h specifies hours, and d specifies days.
See security-manual:access-control.adoc#nso-timeout-guidance.
Default: enabled

nvram

This feature specifies that ACS authorization is needed to enable nonvolatile memory (NVRAM) allocation.
See Designing SEE machines and SEE-ready HSMs.
This feature remains available for use on presentation of the standard ACS quorum, even if turned off using the ! operator. Setting the quorum of this feature to 0 has the same effect as turning it off using the ! operator.
Default: enabled

p

This feature enables passphrase replacement; see passphrase replacement and Changing card and softcard passphrase.
Default: *dis*abled

--pp-min=LENGTH

Enables a minimum passphrase length check for the Administrator Card Set (ACS) the Operator Card Set (OCS) and any associated softcards when you create a security world. The minimum passphrase length check is then applied after the security world is created. When enabled and you attempt to create a card passphrase with fewer characters than the specified minimum length, the following warning message displays:

WARNING
Warning: short passphrase.
---- +
However, the passphrase can still be used. +
Example: +
[source]

new-world --initialize --acs-quorum=K/N --pp-min=14 ----
If --pp-min=<length> is not used, the minimum passphrase length is set to the default value (0).

--p-strength

Enables passphrases to have at least one uppercase, lowercase, number, and symbol.
If the --pp-strength argument is omitted, the complexity requirements are not enforced.
Default: enabled

-Q, --acs-quorum=<K>/<N>

This feature only takes effect if you are creating a new security world.
<K> specifies the minimum number of smart cards needed from the ACS to authorize a feature. You can specify lower K values for a particular feature. All the K values must be less than or equal to the total number of cards in the set. If a value for K is not specified, new-world creates an ACS that requires a single card for authorization.
When the security world is created in common-criteria-cmts mode, new-world requires a minimum K of 2.
Some applications do not have mechanisms for requesting that cards be inserted. Therefore any OCSs that you create for use with these applications must have K=1.
<N> specifies the total number of smart cards to be used in the ACS. This must be a value in the range 1-64. If a value for this option is not specified, new-world creates an ACS that contains a single card.+ We recommend that you do not create an ACS for which the required number of cards is equal to the total number of cards because you will not be able to replace the ACS if even a single card is lost or damaged.
Default: enabled

rtc

This feature specifies that ACS authorization is needed to set the real-time clock (RTC); (see rtc). This feature remains available for use on presentation of the standard ACS quorum, even if turned off using the ! operator. Setting the quorum of this feature to 0 has the same effect as turning it off using the ! operator.
Default: enabled

+ Not available on the nShield 5c.

Module selection

-m, --module=MODULE

Specifies the number ID to use.
If you only have one module, MODULE is 1.
If you do not specify a module ID, new-world uses all modules by default.

You must reference an HSM with -m whenever you run the new-world utility. See the examples for the impact of new-world on the HSM.

Help options

-h, --help

Displays help for new-world.

-u, --usage

Displays a brief usage summary for new-world.

-v, --version

Displays the version number of the Security World Software that deploys new-world.

new-world examples

Example 1

new-world m=1, r, !p, nv=2, rtc=1

Create a security world for which:

m=1
r

y
!p

passphrase replacement is not enabled
nv=2

Two cards are required to allocate nonvolatile memory
rtc=1

1 card is required to set the real-time clock (applies to SEE only)
(--acs-quorum is omitted)

The default number is required to replace an OCS
(--acs-quorum is omitted)

A single card from the ACS is required to add a new HSM