CryptoTokenKit Network Cryptographic Tokens

There are two parts to this:

• Integrating the HSM token with your Mac

• Accessing its credentials from your code

For the first part, you need a CryptoTokenKit (CTK) app extension that acts as a driver for your HSM. Normally that’d be created by the HSM vendor. Presumably that’s not you, so you should ask your HSM vendor if they have CTK support.

If they don’t have CTK support but they do publish their network protocol, you could implement your own CTK app extension. This is a bunch of work, but there’s nothing stopping you.

Once you have the CTK app and you’ve configured it to publish your HSM’s credentials to the system, it’s time to use those credentials from your code. You do this in two steps:

1. Call the SecItem API to find the credential. Typically you want to sign or encrypt something, so the credential is a digital identity (SecIdentity) or private key (SecKey).

2. Use standard Security framework APIs to do your crypto operations. For example, if you have a digital identity you might call:

   • SecIdentityCopyCertificate to get its certificate

   • SecIdentityCopyPrivateKey to get its private key

   and then SecKeyCreateSignature to sign with that private key.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Thank you Quinn for the reply.

@OShv Did you find code sample ?

In my case, I have access to the HSM API and I want to create a driver for it to store iOS signing keys.

@DTS Engineer There is something I don't understand when you mention the keychain would "get the HSM private key" using SecIdentityCopyPrivateKey.

The objectives of HSM is to not expose secrets outside of its secured hardware. The way an HSM signature works is to send the digest to sign and the key ID to the HSM. The HSM computes the signature inside its security perimeter and returns the signature, without exposing the secret key. Example with AWS Key Management Service (which uses a HSM behind the scene) https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html

Do you imply HSM must be able to exprt their secrets to work with the CryptoTokenKit ?

OShv, I didn’t see your comments from back in Feb 2023. Sorry. In future, I recommend that you reply as a reply, rather than in the comments. See Quinn’s Top Ten DevForums Tips for this and other titbits.

If you’re still looking for answers to anything, reply here and I’ll take another look.

Do you imply HSM must be able to exprt their secrets to work with the CryptoTokenKit?

No. The key (ahem) thing to note here is that SecIdentityCopyPrivateKey returns a SecKey object. That object isn’t the key itself, it’s a ‘handle’ to the key. To perform a cryptographic operation with that key, you have to pass it back to another API. Let’s say you want to sign some data. You pass the SecKey object to SecKeyCreateSignature. That routine knows that the key is backed by a CTK module, and so passes the operation on to the module. That module knows that the key is backed by a hardware token, so it passes the operation on to the token. The token gets that request, performs the operation, and passes back the signature, which flows back to you via the reverse path.

Critically, if you pass a hardware-backed SecKey object to SecKeyCopyExternalRepresentation, in an attempt to get the raw bytes of the key, that’ll fail.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"