Building and Signing an FM
Once you have written your FM code, you must build the binary and then sign it using a private key on the HSM. A self-signed certificate is used to confirm the authenticity of the FM. This procedure will allow you to install the FM into your HSM firmware. Luna FMs must be built on a Linux system, so you can use the native make command. The following example uses the skeleton sample FM, included with the Luna FM SDK.
The FM binary must be signed with a private key, and loaded into the HSM firmware with a self-signed certificate from the same keypair to verify its authenticity. You can use mkfm, included with the Luna HSM Client FM Tools, to sign your FM using a Luna application partition or your own Cryptoki signing station. The procedure below will show you how to use mkfm.
Prerequisites
>The FM binary must be built on a Linux client. You can use either a Windows or Linux client to perform the signing operation.
>The FM Tools option in the Luna HSM Client software must be installed on the client or signing station.
>mkfm requires access to a Cryptoki token (such as a Luna application partition) capable of using the CKM_SHA512_RSA_PKCS mechanism.
To build an FM binary
1.On your Linux client, navigate to the directory containing your FM code (<filename>.c). By default, FM samples provided with the Luna FM SDK are installed in /usr/safenet/lunafmsdk/samples/.
[user@myLunaClient ~]# cd /usr/safenet/lunafmsdk/samples/skeleton/fm/ [user@myLunaClient fm]# ls hdr.c makefile skeleton.c
2.Use the Linux make command to build the FM binary.
# make
The make process creates two new sub-directories, bin-ppc and obj-ppc. Your FM binary is located in bin-ppc, named <filename>.bin.
[user@myLunaClient ~]# cd /usr/safenet/lunafmsdk/samples/skeleton/fm/bin-ppc/ [user@myLunaClient bin-ppc]# ls skeleton.bin
To create an FM signing certificate on an application partition
1.If this is the first FM you are signing, you must first create a keypair and self-signed certificate on the application partition. If you already have a certificate for FM signing stored on the
NOTE A certificate used to sign an FM must have attribute CKA_PRIVATE set as true.
If an existing certificate has Private=F, you can use the CMU tool to export that cert, then re-import it while setting -private=T.
Or, if the partition retains the FM signing keypair, you can run cmu selfsigncertificate again to re-create the certificate, this time setting -private=T explicitly.
To sign an FM with mkfm, you must use an RSA private key at least 2048 bits long. The Crypto Officer can use the cmu utility to create the keypair. You will be prompted for the CO credential.
NOTE Always provide unique labels for your keys. If multiple private keys exist with the same label, mkfm will use the newest key (with the greatest object handle value).
cmu generatekeypair -labelpublic=<public_key_label> -labelprivate=<private_key_label> -keytype=rsa -sign=1 -verify=1
[user@myLunaClient bin]# ./cmu generatekeypair -labelpublic=FMpub -labelprivate=FMpriv -keytype=rsa -sign=1 -verify=1 Certificate Management Utility (64-bit) v7.4.0-208. Copyright (c) 2018 SafeNet. All rights reserved. Select token [3] Token Label: myPartition [4] Token Label: myPCIeHSM Enter choice: 3 Please enter password for token in slot 3 : ******** Select RSA Mechanism Type - [1] PKCS [2] FIPS 186-3 Only Primes [3] FIPS 186-3 Auxiliary Primes : 2 Enter modulus length (8 bit multiple) : 2048
2.Check the contents of the partition to find the key handles.
[user@myLunaClient bin]# ./cmu list Certificate Management Utility (64-bit) v7.4.0-208. Copyright (c) 2018 SafeNet. All rights reserved. Select token [3] Token Label: myPartition [4] Token Label: pcie7pwd45 Enter choice: 3 Please enter password for token in slot 3 : ******** handle=48 label=FMpriv handle=45 label=FMpub
3.Create a self-signed certificate on the partition by specifying a label, the public and private key handles, and any other attributes you wish to assign. You are prompted for required attributes (Common Name, serial number, start/end dates) that you do not specify.
cmu selfsigncertificate -slot <slot_number> -label <cert_label> -publichandle=<handle> -privatehandle=<handle>
[user@myLunaClient bin]# ./cmu selfsigncertificate -slot 3 -publichandle=45 -privatehandle=48 -label FMsign Certificate Management Utility (64-bit) v7.4.0-208. Copyright (c) 2018 SafeNet. All rights reserved. Please enter password for token in slot 3 : ******** Enter certificate serial number : 1 Enter Subject 2-letter Country Code (C) : CA Enter Subject State or Province Name (S) : ON Enter Subject Locality Name (L) : Ottawa Enter Subject Organization Name (O) : Thales Enter Subject Organization Unit Name (OU) : Enter Subject Common Name (CN) : FMsign Enter EMAIL Address (E) : Enter validity start date Year : 2018 Month : 12 Day : 05 Enter validity end date Year : 2019 Month : 12 Day : 31 Using "CKM_SHA256_RSA_PKCS" Mechanism
4.Export the certificate to the
cmu export -slot <slot_number> -label <cert_label> -outputfile=<filename.cert>
[user@myLunaClient bin]# ./cmu export -slot 3 -label FMsign -outputfile=FMsign.cert Certificate Management Utility (64-bit) v7.4.0-208. Copyright (c) 2018 SafeNet. All rights reserved. Please enter password for token in slot 3 : ********
To sign an FM
1.Use the mkfm utility included with the Luna HSM Client FM Tools to sign the FM, specifying the unsigned FM binary, the desired FM filepath/filename (with .fm extension), the slot number/name of the partition/token where the keypair is stored, and the private key label.
If you are specifying a slot number, include -k SLOTID=<#> instead of the partition name. If you are using a Cryptoki signing station other than a Luna 7.x application partition, include the -c option. You are prompted for the partition/token credential. By default, the Crypto Officer role is used; to use the Crypto User role instead, include the -u option.
mkfm -f <filepath/name>.bin -o <filepath/name>.fm -k <token_or_partition_name/<private_key_label> [-c] [-u]
[root@k7tower bin-ppc]# ./mkfm -f /usr/safenet/lunafmsdk/samples/skeleton/fm/bin-ppc/skeleton.bin -o /usr/safenet/lunafmsdk/samples/skeleton/fm/bin-ppc/skeleton.fm -k myLunaPartition/FMpriv Luna Functionality Module Signer Utility (64-bit) v7.4.0-208. Copyright (c) 2018 SafeNet. All rights reserved. Please Enter the PIN: (for user 'co' on slot 3) ******** mkfm: Processing ELF file /usr/safenet/lunafmsdk/samples/skeleton/fm/bin-ppc/skeleton.bin File successfully signed
The signed FM is now located in the directory you specified:
[user@myLunaClient ~]# cd /usr/safenet/lunafmsdk/samples/skeleton/fm/bin-ppc/ [user@myLunaClient bin-ppc]# ls skeleton.bin skeleton.fm
Next, see Loading an FM Into the HSM Firmware.
