ctbrowse - token browser

The ctbrowse utility is a Windows GUI application for creating tokens and objects that perform simple operations, such as encryption, decryption, signing and verification of a signature, using the mechanisms provided by the token.

This utility allows you to create or view a key pair and certificates. By selecting an object, you can view its properties. If a certificate object is selected, you can view the structure (ASN.1 format) of the certificate and encode it to various formats such as Base64 or DER.

With ctbrowse, you can create and verify a signature based on the signing mechanism.

ctbrowse is part of the ProtectToolkit-C SDK and is installed as part of that product. However, you can use ctbrowse with tokens and keys created with ProtectToolkit-J and any tokens and keys set up with ctbrowse will be fully compatible with ProtectToolkit-J. For more information, see Key management.

Compliance

This application expects PKCS#11 V 2.20-compliant implementation and will use SafeNet extensions (see the next section) if they are available.

PKCS#11 extensions used

SafeNet's PKCS#11 implementation provides additional services beyond the standard definition of PKCS#11, particularly in the area of Certificate services. For example:

• Uses non-standard Attribute enumeration extension, although this version will fall back to standard methods to enumerate attributes where this extension is not available.

• PKCS#10 and X.509 creation from public key (see Drag and drop)

• ASN.1 decoder/dumper

• Allows use of additional vendor defined mechanisms and extensions to PKCS#11

See ProtectToolkit-C mechanisms for a table of SafeNet vendor-defined mechanisms and extensions to PKCS#11.

User interface

When opened, the ctbrowse window contains two panels, left and right. The left panel contains slots, tokens, and objects; the right panel contains services.

Initially, the left panel lists only one item, representing the linked PKCS#11 version. This item represents a tree control. Double-clicking items on the tree will expand the available slots. Double-click new slot items to show tokens in slots.

The left panel shows a typical ctbrowse session, where the first token (0) has been opened to display its objects and mechanisms. The numbers in square brackets [ ] represent the slot identifiers used to address these items.

The browser can show more than one slot and can be combined with other ProtectToolkit-C products, such as the remote client/server, ProtectToolkit-C ProtectServer (PCI adapter) and ProtectToolkit-C ProtectHost, to allow it to show slots from other PKCS#11 devices, including foreign (non-SafeNet) PKCS#11 devices.

Tree view

The figure below depicts the tree hierarchy. Tree items are identified by labeled icons. The asterisk symbol (*) indicates more than one item at that level of the tree.

Tree hierarchy

PKCS#11
│
└── Slot*
    │
    └── Token
            │
            ├── Session*
            │
            ├── Objects
            │    │
            │    └── Object*
            │         │
            │         └── Attribute
            │
            └── Mechanisms
                │
                └── Mechanism*

Token management services

Token management operations are invoked by right-clicking the desired tree item and selecting a service from the menu.

CRYPTOKI

Slot

Token

Session

Objects

Object

Attribute

Mechanism

Example

The following example demonstrates how to use ctbrowse to generate a key pair.

Generating a key pair is one of the management services available. The Generate Key Pair dialog is opened by right-clicking on an objects tree item in the Token Browser window and choosing Generate Key Pair from the context menu.

The figures below show how the labels and fields of the Generate Key Pair dialog box typically change according to the mechanism selected for key pair generation.

Cryptographic services

The service buttons in the right-hand panel allow key objects to be used for cryptographic operations such as encryption and digital signing. To use these services, select the key item from the tree and then select the required button.

Clicking a button opens the associated dialog to guide the user through the operation of that service.

The next figure shows a typical dialog for Encrypt/decrypt and sign/verify services.

The Key field shows the type of key being used, and the Mechanism list shows mechanisms valid for the chosen key. A parameter for the mechanism should be entered if required. See ProtectToolkit-C mechanisms for more information on mechanism parameters.

The Parameter, Input, and Result fields all allow display in either hexadecimal or ASCII (text) format. The hexadecimal display is useful for the input, or display, of binary data that cannot normally be displayed. Use the [Hex]/[Asc] buttons to toggle between the two display options.

To encrypt information

1. Enter a parameter (if required by the mechanism).

2. Select Init.

3. Enter an Input value (information to be encrypted).

4. Select Encrypt.

   The encrypted text is displayed in the result field.

   

Drag and drop

Objects such as key values can be copied from one token to another by dragging and dropping the object.

Dropping a public key object onto a private key object will create an X.509 certificate request (PKCS #10 format). This is used to encode a public key together with a subject name (the owner of the key) for distribution to a Certification Authority (CA).

The public key used is from the object being dragged. The subject's name is taken from the CKA_SUBJECT or CKA_SUBJECT_STR attributes of that public key. These attributes were supplied when the key was generated.

The secret key used to sign the PKCS#10 encoding may be from another token, but should be the secret key that matches the public key being encoded.

Dropping a PKCS#10 certificate request object onto a private key object will create an X.509 certificate. X.509 certificates are the standard way to securely bind a public key together with a subject name (the owner of the key) for public distribution. X.509 certificates are normally signed by a trusted Certification Authority (CA), also known as the certificate's "issuer". The public key and subject name is extracted from the PKCS#10 object (the one being dragged) and the issuer's name is taken from the CKA_SUBJECT or CKA_SUBJECT_STR attributes of the private key used to sign the certificate (the target of the drag).

X.509 certificates also have a serial number that is taken from the CKA_USAGE_COUNT attribute that must also be present on the signing key. The certificate is created as an object on the token from where the certificate was requested. The secret key used to sign the X.509 encoding may be from another token and is normally a highly trusted (CA) signing key.

Calculate parameter value for CK_RSA_PKCS_PSS_PARAMS

A new mechanism parameter structure was created, CK_RSA_PKCS_PSS_PARAMS, for use by RSA_PKCS_PSS mechanisms. When RSA_PKCS_PSS mechanisms are selected as signing mechanisms in ctbrowse, the parameter value must be properly configured. Providing an incorrect parameter value will result in ctbrowse reporting a Mechanism Invalid error.

To calculate the parameter value for CK_RSA_PKCS_PSS_PARAMS

1. Determine the value of hashAlg, mgf, and sLen.

   Field	Value
   hashAlg	The value for hashAlg is based on the mechanism selected from the Mechanism Field in ctbrowse. For example if the selected mechanism is SHA265_RSA_PKCS_PSS then the value for hashAlg would be CKM_SHA256.
   mgf	The value for mgf is based on the mechanism selected from the Mechanism Field in ctbrowse. For example if the selected mechanism is SHA265_RSA_PKCS_PSS then the value for mgf would be CKG_MGF1_SHA256.
   sLen	The length, in bytes, of the salt value used in the PSS encoding; typical values are the length of the message hash and zero. For example, if hashAlg, mgf, and sLen are 4 bytes each, the salt length value would be 0x0000000C.

2. Convert the value of hashAlg, mgf, and sLen to network byte order using htonl.

3. Enter the values in network byte order into the Parameter field in ctbrowse without any delimiters in the order of hashAlg, mgf, and sLen.

4. Select the Init button.