PKCS#11 Server Business Processes
MTG KMS PKCS#11 Server Authentication
A client must identify and authenticate itself by using a client certificate while connecting to the MTG KMS PKCS#11 Server by TLS. The client certificate must belong to a user of a tenant in the KMS server. This authentication is sufficient to access public objects of the tenant in the KMS server.
However, for cryptographic operations an additional login is needed using credentials of another user of the tenant having the right to perform cryptographic operations. This additional login is also necessary when the value of a private or secret key is requested by calling the C_GetAttributeValue function.
The login must be performed as a Cryptoki user by using the function C_LoginUser to be able to specify a username and a password as PIN. Alternatively, the function C_Login may be used by encoding the credentials in the PIN separating username and password by a comma. In this case the username must not contain commas.
| The login of the security officer (SO) is not supported. |
MTG KMS PKCS#11 Server Application Context
When a client connects to MTG KMS PKCS#11 Server, a PKCS#11 application context will be created as part of a Web session (which will exist as long as the Web session exists). The PKCS#11 application context will hold the state of the PKCS#11 application including login status and possibly created Cryptoki sessions.
| Do not mix up Web sessions and Cryptoki sessions. |
After MTG KMS PKCS#11 Server has created a Web session it will send a cookie as value of a "Set-Cookie" header field within the header of the HTTP response. The client must then send this cookie as a value of a "Cookie" header field within the header of the following HTTP requests. If the cookie is not sent or an invalid cookie is sent via an HTTP request, MTG KMS PKCS#11 Server will create a new Web session and the status of the PKCS#11 application will be lost, unless the right cookie is sent assumed the cookie is still valid.
Example:
HTTP/1.1 200 OK
Set-Cookie: yummy_cookie=choco
Set-Cookie: tasty_cookie=strawberryGET /sample_page HTTP/1.1
Cookie: yummy_cookie=choco; tasty_cookie=strawberryA cookie will become invalid after some time of inactivity. The default validity period is 30 minutes. The period can be configured by a Spring property (see [IM]).
Calling MTG KMS PKCS#11 Server functions
The names of the functions of the REST-API are exact the same as in Cryptoki library.
E.g., instead of calling the C function C_Sign make an HTTP request to /kms-pkcs11-server/pkcs11/C_Sign.
| The URL path is case-sensitive. |
This might be easy but the handling of parameters and return values is different. The Cryptoki library defines C functions using reference parameters for both input of argument values and output of result values. The return value just is an error code which indicates the status of a function. However, in Java language and especially when using a REST-API, there are no reference parameters. Therefore, the C reference parameters have to be split into input parameters and return values with result values.
Input parameters
Every function has a parameter object with the name of the function and "_Params" appended e.g., C_GetSlotList_Params.
A parameter object contains all input parameters of a function.
The names of these input parameters are the same as in Cryptoki library.
| The MTG KMS PKCS#11 Server expects the parameter objects serialized as JSON strings. |
Special handling of return values with dynamic length
As specified in Cryptoki library the length of some output parameters of some functions is unknown before calling these functions. Therefore, the caller may set the pointer to the output value to NULL to get the length of this output value in a second output parameter.
In the MTG KMS PKCS#11 Server there is a boolean input parameter for an output parameter of dynamic length. The name of this input parameter is the name of the output parameter with "IsNull" appended. Additionally, the parameter object of the function contains the (expected) length of the output value because in Cryptoki library this length parameter is specified both as input and as output parameter. The value of the length parameter will be ignored when the boolean parameter is true. With this boolean parameter and the length parameter the implementation in the MTG KMS PKCS#11 Server behaves as specified in Cryptoki library.
Example:
public class C_GetSlotList_Params
{
public boolean tokenPresent;
public boolean pSlotListIsNull;
public long pulCount;
}Return values
Every function has a return value object with the name of the function and "_RV" appended e.g., C_GetSlotList_RV.
All return value objects contain a long value called CK_RV, which matches the return value of the C functions in Cryptoki library and an optional error message (see Exceptions below).
Additionally, the most return value objects contain an object which corresponds to a structure specified in the Cryotoki library given as a reference parameter to a C function.
Each of these objects has the same name as the respective structure.
Example:
public class C_RV
{
public long CK_RV;
public String errorMessage;
}
public class C_GetSlotInfo_RV extends C_RV
{
public CK_SLOT_INFO CK_SLOT_INFO;
}The object (CK_SLOT_INFO in the example above) will not be set in the return value object if an error occurs. If a function succeeds the object will be set and will contain all output values of the function. The names of the output values are the same as in Cryptoki library.
Example:
public class CK_SLOT_INFO
{
public String slotDescription;
public String manufacturerID;
public long flags;
public CK_VERSION hardwareVersion;
public CK_VERSION firmwareVersion;
}| The MTG KMS PKCS#11 Server serializes all return value objects as JSON strings. |
Exceptions
If the authentication of the client fails or if an unknown function is called (or in another but similar situation), the MTG KMS PKCS#11 Server will return an exception within an HTTP response message with one of the status codes 401, 403, 404, …
However, if an exception occurs after a function of the REST-API has been invoked, this exception will be caught and a return value object with CK_RV set to CKR_VENDOR_DEFINED will be returned within an HTTP response message with status code 200.
If the property kms-pkcs11-server.return-exception-cause is set to true in application.properties, the return value object will contain an error message describing the cause of the exception.
Additional error messages
In certain error scenarios (like an error received by the KMS server),
the MTG KMS PKCS#11 Server will return an error message within the return value object if the property kms-pkcs11-server.return-error-messages is set to true in application.properties.
Mapping of C types to Java types
The following table describes how the types in the Cyrptoki library are mapped to types in the MTG KMS PKCS#11 Server.
| Cryproki library | MTG KMS PKCS#11 Server |
|---|---|
CK_BYTE |
byte |
CK_BBOOL |
boolean |
CK_LONG |
long |
CK_ULONG |
long |
CK_CHAR[] or CK_CHAR_PTR |
String |
CK_UTF8CHAR[] or CK_UTF8CHAR_PTR |
String |
CK_BYTE[] or CK_BYTE_PTR |
String (Base64 encoded byte array. In this case the name of the parameter will be appended by "Base64", e.g. pDataBase64.) |
Parameters of type void*
Some functions in Cryptoki library have structures as input parameters like CK_ATTRIBUTE and CK_MECHANISM containing members of type void*. These structures contain a discriminator like "type" of type CK_ATTRIBUTE_TYPE or "mechanism" of type CK_MECHANISM_TYPE. The discriminator determines the real type of the parameter value hidden by the void pointer.
The client is responsible for serializing the void* parameter using the correct type before sending the parameter to the MTG KMS PKCS#11 Server. The latter provides input parameters for every supported type.
MTG KMS PKCS#11 Server Deviation from Cryptoki library
-
The Cryptoki user type CKU_CONTEXT_SPECIFIC is not supported. The use of this type will lead to error CKR_USER_TYPE_INVALID.
-
The Cryptoki user type CKU_SO is not supported in the current version of the MTG KMS PKCS#11 Server. The use of this type will lead to error CKR_PIN_INCORRECT.
MTG KMS PKCS#11 Server Supported features
Functions
Supported functions
Click to reveal supported functions
C_GetInfo, C_GetSlotList, C_GetSlotInfo, C_GetTokenInfo, C_GetMechanismList, C_GetMechanismInfo C_OpenSession, C_CloseSession, C_CloseAllSessions, C_GetSessionInfo C_Login, C_LoginUser, C_Logout, C_SeedRandom, C_GenerateRandom, C_SessionCancel, C_GetAttributeValue, C_FindObjectsInit, C_FindObjects, C_FindObjectsFinal C_DigestInit, C_Digest, C_DigestUpdate, C_DigestFinal, C_SignInit, C_Sign, C_SignUpdate, C_SignFinal, C_VerifyInit, C_Verify, C_VerifyUpdate, C_VerifyFinal
Non-supported functions
Click to reveal non-supported functions
C_Initialize, C_Finalize, C_GetFunctionList, C_InitToken, C_InitPIN, C_SetPIN, C_GetFunctionStatus, C_CancelFunction, C_WaitForSlotEvent, C_GetOperationState, C_SetOperationState, C_CreateObject, C_CopyObject, C_DestroyObject, C_GetObjectSize, C_SetAttributeValue, C_EncryptInit, C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_DecryptInit, C_Decrypt, C_DecryptUpdate, C_DecryptFinal, C_DigestKey, C_SignRecoverInit, C_SignRecover, C_VerifyRecoverInit, C_VerifyRecover, C_DigestEncryptUpdate, C_DecryptDigestUpdate, C_SignEncryptUpdate, C_DecryptVerifyUpdate, C_GenerateKey, C_GenerateKeyPair, C_WrapKey, C_UnwrapKey, C_DeriveKey C_GetInterfaceList, C_GetInterface C_MessageEncryptInit, C_EncryptMessage, C_EncryptMessageBegin, C_EncryptMessageNext, C_MessageEncryptFinal C_MessageDecryptInit, C_DecryptMessage, C_DecryptMessageBegin, C_DecryptMessageNext, C_MessageDecryptFinal C_MessageSignInit, C_SignMessage, C_SignMessageBegin, C_SignMessageNext, C_MessageSignFinal C_MessageVerifyInit, C_VerifyMessage, C_VerifyMessageBegin, C_VerifyMessageNext, C_MessageVerifyFinal
Attributes
Supported attributes
Click to reveal supported attributes
CKA_CLASS, CKA_LABEL, CKA_UNIQUE_ID, CKA_CERTIFICATE_TYPE, CKA_ISSUER, CKA_SERIAL_NUMBER, CKA_KEY_TYPE, CKA_SUBJECT, CKA_ID, CKA_SENSITIVE, CKA_ENCRYPT[1], CKA_DECRYPT[1], CKA_WRAP[1], CKA_UNWRAP[1], CKA_SIGN[1], CKA_VERIFY[1], CKA_DERIVE[1], CKA_MODULUS, CKA_MODULUS_BITS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT, CKA_EXTRACTABLE, CKA_LOCAL, CKA_NEVER_EXTRACTABLE, CKA_ALWAYS_SENSITIVE, CKA_EC_PARAMS, CKA_EC_POINT, CKA_ALWAYS_AUTHENTICATE, CKA_ALLOWED_MECHANISMS
Non-supported attributes
Click to reveal non-supported attributes
CKA_TOKEN, CKA_PRIVATE, CKA_APPLICATION, CKA_OBJECT_ID, CKA_AC_ISSUER, CKA_OWNER, CKA_ATTR_TYPES, CKA_TRUSTED, CKA_CERTIFICATE_CATEGORY, CKA_JAVA_MIDP_SECURITY_DOMAIN, CKA_URL, CKA_HASH_OF_SUBJECT_PUBLIC_KEY, CKA_HASH_OF_ISSUER_PUBLIC_KEY, CKA_NAME_HASH_ALGORITHM, CKA_CHECK_VALUE, CKA_SIGN_RECOVER, CKA_VERIFY_RECOVER, CKA_DERIVE, CKA_START_DATE, CKA_END_DATE, CKA_PUBLIC_KEY_INFO, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, CKA_PRIME_BITS, CKA_SUBPRIME_BITS, CKA_SUB_PRIME_BITS, CKA_KEY_GEN_MECHANISM, CKA_MODIFIABLE, CKA_COPYABLE, CKA_DESTROYABLE, CKA_SECONDARY_AUTH, CKA_AUTH_PIN_FLAGS, CKA_WRAP_WITH_TRUSTED, CKA_WRAP_TEMPLATE, CKA_UNWRAP_TEMPLATE, CKA_DERIVE_TEMPLATE, CKA_OTP_FORMAT, CKA_OTP_LENGTH, CKA_OTP_TIME_INTERVAL, CKA_OTP_USER_FRIENDLY_MODE, CKA_OTP_CHALLENGE_REQUIREMENT, CKA_OTP_TIME_REQUIREMENT, CKA_OTP_COUNTER_REQUIREMENT, CKA_OTP_PIN_REQUIREMENT, CKA_OTP_COUNTER, CKA_OTP_TIME, CKA_OTP_USER_IDENTIFIER, CKA_OTP_SERVICE_IDENTIFIER, CKA_OTP_SERVICE_LOGO, CKA_OTP_SERVICE_LOGO_TYPE, CKA_GOSTR3410_PARAMS, CKA_GOSTR3411_PARAMS, CKA_GOST28147_PARAMS, CKA_HW_FEATURE_TYPE, CKA_RESET_ON_INIT, CKA_HAS_RESET, CKA_PIXEL_X, CKA_PIXEL_Y, CKA_RESOLUTION, CKA_CHAR_ROWS, CKA_CHAR_COLUMNS, CKA_COLOR, CKA_BITS_PER_PIXEL, CKA_CHAR_SETS, CKA_ENCODING_METHODS, CKA_MIME_TYPES, CKA_MECHANISM_TYPE, CKA_REQUIRED_CMS_ATTRIBUTES, CKA_DEFAULT_CMS_ATTRIBUTES, CKA_SUPPORTED_CMS_ATTRIBUTES, CKA_PROFILE_ID, CKA_X2RATCHET_BAG, CKA_X2RATCHET_BAGSIZE, CKA_X2RATCHET_BOBS1STMSG, CKA_X2RATCHET_CKR, CKA_X2RATCHET_CKS, CKA_X2RATCHET_DHP, CKA_X2RATCHET_DHR, CKA_X2RATCHET_DHS, CKA_X2RATCHET_HKR, CKA_X2RATCHET_HKS, CKA_X2RATCHET_ISALICE, CKA_X2RATCHET_NHKR, CKA_X2RATCHET_NHKS, CKA_X2RATCHET_NR, CKA_X2RATCHET_NS, CKA_X2RATCHET_PNS, CKA_X2RATCHET_RK, CKA_VENDOR_DEFINED
Object Classes
Key Types
Supported key types
Click to reveal supported key types
CKK_RSA, CKK_DSA, CKK_DH, CKK_EC, CKK_RC2, CKK_RC4, CKK_RC5, CKK_DES, CKK_DES3, CKK_CAST5, CKK_IDEA, CKK_SKIPJACK, CKK_AES, CKK_BLOWFISH, CKK_TWOFISH, CKK_CAMELLIA, CKK_ARIA, CKK_MD5_HMAC, CKK_SHA_1_HMAC, CKK_SHA224_HMAC, CKK_SHA256_HMAC, CKK_SHA384_HMAC, CKK_SHA512_HMAC, CKK_SHA3_224_HMAC, CKK_SHA3_256_HMAC, CKK_SHA3_384_HMAC, CKK_SHA3_512_HMAC, CKK_SEED, CKK_GOSTR3410, CKK_GOSTR3411, CKK_GOST28147, CKK_CHACHA20, CKK_POLY1305, CKK_EC_EDWARDS
Non-supported key types
Click to reveal non-supported key types
CKK_X9_42_DH, CKK_KEA, CKK_GENERIC_SECRET, CKK_DES2, CKK_CAST, CKK_CAST3, CKK_CAST128, CKK_BATON, CKK_JUNIPER, CKK_CDMF, CKK_SECURID, CKK_HOTP, CKK_ACTI, CKK_RIPEMD128_HMAC, CKK_RIPEMD160_HMAC, CKK_AES_XTS, CKK_BLAKE2B_160_HMAC, CKK_BLAKE2B_256_HMAC, CKK_BLAKE2B_384_HMAC, CKK_BLAKE2B_512_HMAC, CKK_SALSA20, CKK_X2RATCHET, CKK_EC_MONTGOMERY, CKK_HKDF, CKK_SHA512_224_HMAC, CKK_SHA512_256_HMAC, CKK_SHA512_T_HMAC
Cryptographic Usages
Digest Mechanisms
Signature Mechanisms
Supported signature mechanisms
Click to reveal supported signature mechanisms
CKM_RSA_PKCS, CKM_MD2_RSA_PKCS, CKM_MD5_RSA_PKCS, CKM_SHA1_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, CKM_SHA3_256_RSA_PKCS, CKM_SHA3_384_RSA_PKCS, CKM_SHA3_512_RSA_PKCS, CKM_RSA_PKCS_PSS, CKM_SHA1_RSA_PKCS_PSS, CKM_SHA224_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS, CKM_SHA3_224_RSA_PKCS_PSS, CKM_SHA3_256_RSA_PKCS_PSS, CKM_SHA3_384_RSA_PKCS_PSS, CKM_SHA3_512_RSA_PKCS_PSS, CKM_ECDSA, CKM_ECDSA_SHA1, CKM_ECDSA_SHA224, CKM_ECDSA_SHA256, CKM_ECDSA_SHA384, CKM_ECDSA_SHA512, CKM_EDDSA
Non-supported signature mechanisms
Click to reveal non-supported signature mechanisms
CKM_DSA_SHA1, CKM_DSA_SHA224, CKM_DSA_SHA256, CKM_DSA_SHA384, CKM_DSA_SHA512, CKM_DSA_SHA3_224, CKM_DSA_SHA3_256, CKM_DSA_SHA3_384, CKM_DSA_SHA3_512, CKM_ECDSA_SHA3_224, CKM_ECDSA_SHA3_256, CKM_ECDSA_SHA3_384, CKM_ECDSA_SHA3_512