|
Home > |
FM SDK Programming Guide > FM Samples
|
|---|
There are eight sample FMs provided with the SDK:
•smfs
Most have similar file layout.
The sample files included as part of the FM development kit consist of six sample FMs and two examples of how to communicate with the HSM from Java.
Each of the FM samples are structured in a similar way. In each sample directory there is –
•Makefile: makefile to build host and HSM side code
•Fm: directory holding HSM side source
•Host: directory holding host side source
•Include: optional directory to hold common header files
Within the FM directory are files like these -
•hdr.c: header file for the production build of the FM binary image.
•sample.c: HSM side; main source for FM
•Makefile: Makefile to build the FM and the application
Within the host directory are files like this -
•stub_sample.c: host side stub (request encoder/decoders) (needed only for custom API)
•sample.c: main source for host side test application
•Makefile: Makefile to build the host-side application for emulation, or production.
The samples are built using gnumake and the provided Makefiles. When working on a platform that has a native gnumake, such as Linux, you can use the system make command. When building the host part of the samples on Windows, a copy of gnumake is provided in <fm_installation_path>\bin.
•Production build, no debug information in binaries:
make
•Production build, with debug information in binaries:
make DEBUG=1
•Emulation build, no debug information in binaries:
make EMUL=1
•Emulation build, with debug information in binaries:
make EMUL=1 DEBUG=1
Binary files generated by the above variants are placed in different directories. Therefore, all variants can be generated in the same directory. The directory names used are:
•obj-win32: Binaries for the production, non-debug host build on win32 environment
•obj-win32d: Binaries for the production, debug host build on win32 environment
•obj-linux-i386: Binaries for the production, non-debug host build on Linux/i386 environment
•obj-linux-i386d: Binaries for the production, debug host build on Linux/i386 environment
•obj-ppcfm: Binaries for the production, non-debug FM build for the HSM environment
•obj-ppcfmd: Binaries for the production, debug FM build for the HSM environment
•obj-linux-i386e: Binaries for the emulation, non-debug FM build on Linux/i386 environment
•obj-linux-i386ed: Binaries for the emulation, debug FM build on Linux/i386 environment
The binaries generated from each variant can be deleted using the target ‘clean’. E,g,:
make EMUL=1 clean
The build scripts generate the unsigned FM binary image when the HSM builds are performed. The binary images are named ‘<samplename>.bin’. Since these images are not signed yet, it is not possible to download them to the HSM. To use the key management scheme #1 (using self-signed FM download certificates), follow the steps listed below:
1.Generate the key/certificate pair on the first token. From a command prompt, execute:
ctcert c –s0 –k –trsa –z2048 –lfm
This will generate a 2048 bit RSA key pair, and a self-signed certificate. The minimum key size for FM signing should be 2048 bit. The labels of the generated keys are as shown below:
Private Key:fm (Pri)
Public Key:fm (Pub)
Certificate:fm
2.You must copy the certificate to the Admin Token. This can be done using by using ctcert to export the certificate to a file.
ctcert x –lfm –s0 –ffmcert.crt
3.Then import the certificate to the Admin Token. For this operation, the password of the Admin Token is required.
ctcert i –ffmcert.crt –s2 –lfm
4.You must mark the certificate as “Trusted”. This can be done using the ctcert utility with the ‘t’ command line option.
ctcert t –lfm –s2
Please refer to the SafeNet ProtectToolkit-C Programming Guide for a full account of the ctcert utility.
5.Now, the binary image can be signed using mkfm. In the directory where the binary image is generated, execute the following command:
mkfm –k “<TokenLabel>/<fm (Pri)>” -fsampleN –osampleN.fm
where <TokenLabel> is the label of the token in Slot 0, <fm (Pri)> is the label of the private signing key that was previously generated and sampleN is the binary image of the sample FM being signed. This will generate a signed FM binary image, named “sampleN.fm”. This command requires the user password of the token to be entered.
6.Exit from all cryptoki applications that are still active, and download the FM image to the HSM. Execute:
ctconf –b<fm> –jsampleN.fm
where <fm> is the name of the certificate in Admin Token used to verify the FM binary image integrity. After a while, the command will report a successful download. The download operation can be checked by executing the command:
ctconf –s
and ensuring that the FM name is correct, and the FM status is “Enabled”.
When running FMs in emulation mode, the HSM Software Emulation library is used and the above steps for signing and installing the FM do not apply. The emulated HSM does require basic initialization using the same steps as a real HSM, as described in the SafeNet ProtectToolkit-C Administration Guide.
1.Initialize the slot (0):
ctconf –n0
2.Initialize the slot's user PIN:
ctkmu p –s0
3.List slots:
ctkmu l