Top  Previous  Next


The CREATE.KEY command creates a data encryption key. The CREATE.SECURE.KEY command is similar but creates a password protected key. These commands can only be executed by users with administrator rights in the QMSYS account.





CREATE.KEY {keyname {algorithm {keystring}}}

CREATE.SECURE.KEY {keyname {algorithm {keystring {password}}}}




keynameis the name for the new encryption key.


algorithmis the encryption algorithm to be associated with the key.


keystringis the encryption key string.


passwordis the password to be used to protect the key.


The command prompts for items not supplied on the command line. For best security, the keystring and password should be entered via a prompt so that they will not appear on the command stack or in log files.



The CREATE.KEY command creates a new entry in the key vault defining the encryption algorithm and actual key string to be used. If the key vault does not already exist, this command will create it, prompting for the master key to be used to encrypt the key vault. If the key vault does exist, the user will be asked to enter the master key unless it has already been entered during this session.


The keyname may be any sequence of up to 64 letters, digits, periods and hyphens. It is case insensitive.


The algorithm may be any of AES128, AES192 and AES256. The algorithm name is case insensitive. These algorithms use a fixed initialisation vector that is the same for every use of the encryption algorithm. There are also extended forms of the algorithms named XAES128, XAES192 and XAES256 that use a random initialisation vector which is included in the encrypted form of the data. This gives greater security but increases the size of the encrypted data.


The keystring is up to 64 characters, is case sensitive and can contain any character. For best security, the length of the keystring should be close to the actual length needed by the selected algorithm. This is 16, 24 or 32 characters for the 128, 192 and 256 bit algorithms respectively. The CREATE.KEY command will automatically transform the supplied key to the required length if necessary.


Once a key has been defined, it may be referenced in commands that set up encryption without needing to enter the master key. The keyname does not need to be treated as a secure item. The keystring, on the other hand, must not be disclosed. It is strongly recommended that a copy of the keystring is maintained securely off-site in case it is ever necessary to rebuild the key vault.


Use of CREATE.SECURE.KEY applies password protection to the key such that the password must be supplied using the ENABLE.KEY command or corresponding ENABLE.KEY QMBasic statement in a QM session before the key can be used.


The CREATE.KEY and CREATE.SECURE.KEY commands automatically grant access to the key to the user that created it. Other users can be granted access using the GRANT.KEY command







The above command creates a 256 bit encryption key named CARDNO. The actual encryption string will be entered in response to a prompt.



See also: