Home >

LunaSH Command Reference Guide > LunaSH Commands > partition > partition create

partition create

Create an HSM partition on the HSM. Use this command to create and initialize a new HSM Partition.

Note:  You must be logged in to the HSM as HSM SO to use the partition create command.

By default, no clients are granted access to a new HSM Partition. The SafeNet appliance “admin” can run the client assignPartition command to give a registered client access to created HSM Partitions.

For password-authenticated HSMs, if the password is not provided via the command line, the user is interactively prompted for it. Input is echoed as asterisks, and user is asked for password confirmation. This creates the Crypto Officer role.

For PED-authenticated HSMs, PED action is required, and a partition Crypto Officer PED Key (black) is imprinted. Any password provided at the command line is ignored.

CAUTION:  When labeling HSMs or partitions, never use a numeral as the first, or only, character in the name/label. Token backup commands allow slot-number or label as identifier, which can lead to confusion if the label is a string version of a slot number. For example, if the token is initialized with the label "1" then the user cannot use the label to identify the target for purposes of backup, because VTL parses "1" as signifying the numeric ID of the first slot rather than as a text label for the target in whatever slot it really occupies (the target is unlikely to be in the first slot), so backup fails.

Note:  If you create a partition with name "somename" and do not specify a label, the label by default is "somename". If later you attempt to create another partition, and specify a label of "somename" the operation fails with LUNA_RET_ATTRIBUTE_VALUE_INVALID because the first partition has that label (even though you never explicitly set it to that string.

Partition and PKI token naming

When creating partitions on the HSM, a check is performed to ensure that the new partition's name is unique (on that HSM). However, this check does not extend to any token HSMs that might be inserted in connected card-reader slots. Therefore, it is possible to create a partition on the main, on-board HSM that has the same name as a PKI token in one of the reader slots. Avoid this by running the command token pki listdeployed, and checking the output, before invoking the partition create command.

Cloning is a repeating atomic action

When you call for a cloning operation (such as backup or restore), the source HSM transfers a single object, encrypted with the source domain. The target HSM then decrypts and verifies the received blob.

If the verification is successful, the object is stored at its destination – the domains are a match. If the verification fails, then the blob is discarded and the target HSM reports the failure. Most likely the domain string or the domain PED Key, that you used when creating the target partition, did not match the domain of the source HSM partition. The source HSM moves to the next item in the object list and attempts to clone again, until the end of the list is reached.

This means that if you issue a backup command for a source partition containing several objects, but have a mismatch of domains between your source HSM partition and the backup HSM partition, then you will see a separate error message for every object on the source partition as it individually fails verification at the target HSM.

Domain matching and the default domain

If you do not specify a domain in the command line when creating a partition (partition create command),then you are prompted for it.

If you type a character string at the prompt, that string becomes the domain for the partition.

When you run the partition backup command, you are again prompted for a domain for the target partition on the backup HSM. You can specify a string at the command line, or omit the parameter at the command line and specify a string when prompted. Otherwise press [ Enter ] with no string at the prompt to apply the default domain. The domain that you apply to a backup HSM must match the domain on your source HSM partition.

Syntax

partition create -partition <name> [-haspso] [-label <label>] [-password <password>] [-domain <domain>] [-defaultdomain] [-defaultchallenge] [-size <size>] [-allfreestorage] [-force]

Rules for names and passwords

A partition name or a partition label can include any of the following characters :

!#$%'()*+,-./0123456789:=@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_abcdefghijklmnopqrstuvwxyz{}~

No spaces, unless you wish to surround the name or label in double quotation marks every time it is used.
No question marks, no double quotation marks within the string.  
Minimum name or label length is 1 character. Maximum is 32 characters.

Valid characters that can be used in a password or in a cloning domain, when entered via LunaSH [1]), are:

   !#$%'*+,-./0123456789:=?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_abcdefghijklmnopqrstuvwxyz{}~

(the first character in that list is the space character)
Invalid or problematic characters, not to be used in passwords or cloning domains are
"&';<>\`|()

Valid characters that can be used in a password or in a cloning domain, when entered via lunacm, are:

 !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~

(the first character in that list is the space character)

Minimum password length is 7 characters; maximum is 255 characters in lunash or lunacm.  

Minimum domain string length is 1 character; maximum domain length is 128 characters via lunash.  No arbitrary maximum domain string length is enforced for domain strings entered via lunacm, and we have successfully input domain strings longer than 1000 characters in testing.  

[1] LunaSH on the SafeNet Network HSM has a few input-character restrictions that are not present in LunaCM, run from a client host. It is unlikely that you would ever be able to access, via LunaSH, a partition that received a password or domain via LunaCM, but the conservative approach would be to avoid the few "invalid or problematic characters" generally.

Names and labels have an additional restriction, in that you should avoid a leading space.

Option Shortcut Parameter Description
-allfreestorage -a . Create the partition using all the remaining, unused storage space on the HSM. After creating a partition with this option, you cannot create another without first deleting or resizing partitions to regain some space.
-defaultdomain -defaultd . This "partition create" command, and the "setLegacyDomain" command both have the "-defaultdomain" option, which allows the use of the same default domain that would have been applied if you had just pressed [Enter] when prompted for a cloning domain with earlier SafeNet HSM versions.
The current and future HSM versions do not allow you to omit providing a domain, unless you include this "-defaultdomain" option, which is an insecure choice and generally not recommended.
The "-defaultdomain" option applies to Password-authenticated HSMs only.
For PED-authenticated HSMs the PED always prompts for a physical PED Key and either reuses the value on the key that you insert, or generates a new value and imprints it on the PED Key.
-defaultchallenge -defaultc . Specifies that the default Partition Challenge Secret 'PASSWORD' be used when the partition is created. This is useful when deploying many partitions automatically, for fully-automated testing, and when using Crypto Command Center (CCC) to create an HA group, which requires all member partitions to share the same password. The challenge password 'PASSWORD' is reserved, so it is not possible to change an existing challenge password to 'PASSWORD'.
-domain -do <domain> Specifies the cloning domain to be used when this partition needs to clone objects to/from another HSM, such as during backup/restore, or if the partition is included as a member of an HA group. For PED authenticated SafeNet Network HSM, the domain is either generated on the HSM and imprinted on a red PED Key, or is accepted from an existing domain PED Key and imprinted on the HSM (for this partition).
-force -f . Force the partition creation with no prompting - you are still prompted by SafeNet PED, if yours is a PED authenticated HSM.
-haspso -h . Create the partition with its own security officer. See About Configuring an Application Partition with Its Own SO   in the Configuration Guide.
-label -l <partition-label> Specifies a label for the partition. This option does not apply to partitions with SO. If you include this option with the -haspso option, it will be ignored.
A partition label is applied later by the Partition SO, using the client-side lunacm tool.
-partition -par <partition-name> Specifies the name to assign to the HSM Partition. The name must be unique among all HSM Partitions on the HSM.
-password -pas <password>

Specifies the password to be used as login credential by the password-authenticated HSM partition's Crypto Officer or client application. If you omit the password from the command, for a password-authenticated SafeNet Network HSM, you are prompted for it.
For PED authenticated SafeNet Network HSM, the password is not needed as input - one is generated and presented to you by the PED - and the black PED Key becomes the administrative authentication (for activation, etc.)

-policyTemplate -po <template-name> The named template (which must already exist) is read, and the policy values for the new partition are set according to the template. If a template by that name is not found, the command fails.
-size -s <size> Specifies the size, in bytes, to allocate to the partition, from the remaining storage available on the HSM. If you specify a size, the HSM attempts to use it after calculating overhead requirements. If you do not specify a size, the HSM creates the partition with the default size, as determined by your purchased options for number of partitions and total storage on the HSM.

Example

lunash:> partition -create -par alreadyused
 
Error:  'partition -create' failed. (1006)
Error:  The name you provided for the new partition is not unique. Partitions must have unique names.
Use 'partition -list' for a list of existing partition names.
 
lunash:> partition -create -par b1
 
Please enter password
Please enter domain
Please enter size
'partition -create' successful.