Manual Pages for UNIX Operating System command usage for man pkcs11_kms

Standards, Environments, and Macros                 pkcs11_kms(5)



NAME
     pkcs11_kms - RSA PKCS#11 provider  for  the  Key  Management
     Server

SYNOPSIS
     /usr/lib/security/pkcs11_kms.so


     /usr/lib/security/64/pkcs11_kms.so


DESCRIPTION
     The pkcs11_kms.so object implements the  RSA  PKCS#11  v2.20
     specification  using  the Key Management Server (KMS) client
     protocols to talk to a KMS  secure  key  storage  appliance.
     This  provider implements the PKCS#11 specification and com-
     municates to a remote KMS using  the  (private)  KMS  client
     protocol.


     The following PKCS#11 mechanisms are supported in this  pro-
     vider: CKM_AES_KEY_GEN, CKM_AES_CBC_PAD, and CKM_AES_CBC.


     The following PKCS#11 interfaces are supported by this  pro-
     vider:

       C_Initialize
       C_Finalize
       C_GetInfo
       C_GetAttributeValue
       C_SetAttributeValue
       C_GetFunctionList
       C_GetSlotList
       C_GetSlotInfo
       C_GetTokenInfo
       C_GetMechanismList
       C_GetMechanismInfo
       C_InitToken
       C_SetPIN
       C_Login
       C_Logout
       C_FindObjectsInit/C_FindObjects/C_FindObjectsFinal
       C_GenerateKey
       C_EncryptInit/C_Encrypt/C_EncryptFinal
       C_DecryptInit/C_Decrypt/C_DecryptFinal
       C_DestroyObject
       C_OpenSession
       C_CloseSession
       C_CloseAllSessions





SunOS 5.11          Last change: 19 Jun 2010                    1






Standards, Environments, and Macros                 pkcs11_kms(5)



     All other functions return  CKR_FUNCTION_NOT_SUPPORTED  when
     called.

  Prerequisites
     The pkcs11_kms provider can only be used on a  system  which
     has  access to a KMS. The KMS administrator must configure a
     user profile and agent ID for  each  user  (or  application)
     that  is  accessing  the  KMS.  This is done through the KMS
     utilities that are part of the KMS administrative tools  and
     are not bundled in Solaris.


     Once the KMS administrator has configured the  KMS  for  use
     and  communicated  the  parameters  to  the client, that is,
     Solaris user or application, the Solaris  PKCS#11  KMS  pro-
     vider can be initialized for use.


     Initializing  the  KMS  is  done  through  the  use  of  the
     kmscfg(1M)  utility.  At  a minimum, the kmscfg requires the
     user to enter the name of the KMS profile, the name  of  the
     KMS  Agent, the initial password used to secure the profile,
     and the IP address of the KMS in  order  to  initialize  the
     local provider configuration files for further use.


     See the kmscfg(1M) manual page for details.


     Once kmscfg has been run and the local token  namespace  has
     been  configured, the user can then initialize the token for
     use. Initializing the token is done using the pktool(1) com-
     mand as follows:

       $ pktool inittoken currlabel=KMS




     The user has to supply the default SO (security officer) PIN
     before  being  able  to initialize the KMS provider for use.
     The default SO PIN is whatever was used by the KMS  adminis-
     trator  when  initially setting up the KMS profile. The user
     initializing the token must know this passphrase in order to
     initialize the provider.


     Once the provider  is  initialized,  the  user  PIN  can  be
     changed from the default values. Again, pktool(1) is used to
     change the PIN value.





SunOS 5.11          Last change: 19 Jun 2010                    2






Standards, Environments, and Macros                 pkcs11_kms(5)



     Use the following command to change the local PIN:

       $ pktool setpin token=KMS




     The PIN provided for the pktool setpin operation or by  cal-
     ling C_Login() and C_SetPIN() functions can be any string of
     characters with a length between 1 and 256 and  no  embedded
     nulls.


     Accessing the Token


     After a user initializes their token, they can  begin  using
     it  with  pktool(1),  decrypt(1),  encrypt(1), or by writing
     PKCS11 applications and specifying the KMS token.

EXAMPLES
     Example 1 Creating a Key in the KMS


     The following command creates a key in the KMS:


       $ pktool genkey token=KMS label=mykey1 keytype=aes keylen=256



     Example 2 Encrypting a File Using a Key from the KMS


     The following command encrypts a file using a key  from  the
     KMS:


       $ encrypt -a aes -K mykey1 -T KMS -i input.txt -o output.enc



     Example 3 Decrypting a File Using a Key From the KMS


     The following command decrypts a file using a key  from  the
     KMS:


       $ decrypt -a aes -K mykey1 -T KMS -i output.enc -o output.txt





SunOS 5.11          Last change: 19 Jun 2010                    3






Standards, Environments, and Macros                 pkcs11_kms(5)



ATTRIBUTES
     See attributes(5) for a description of the following  attri-
     butes:



     __________________________________________________________________________
   |        ATTRIBUTE TYPE       |               ATTRIBUTE VALUE             |
   | ____________________________|___________________________________________|_
   |  Availability               |  /system/library/security/crypto/pkcs11_kms|
   |_____________________________|___________________________________________|
   | Interface Stability         | Committed                                 |
   |_____________________________|___________________________________________|
   | MT-Level                    | MT-Safe with Exceptions. See below.       |
   |_____________________________|___________________________________________|
   | Standard                    | PKCS#11 v2.20                             |
   |_____________________________|___________________________________________|



     Exceptions to MT-Safe attribute are  documented  in  section
     6.5.2 of RSA PKCS#11 v2.20.

SEE ALSO
     decrypt(1),    encrypt(1),     pktool(1),     cryptoadm(1M),
     kmscfg(1M), libpkcs11(3LIB), attributes(5)


     KMS 2.2: Administration Guide

NOTES
     pkcs11_kms.so uses a private directory  for  holding  confi-
     guration  files and other data needed to initialize the con-
     nection to the KMS. The private directory is  local  to  the
     host  on  which  it  was  first created. By default, the KMS
     token directory space is in /var/kms/$USERNAME.  The default
     KMS  directory can be overridden by setting the KMSTOKEN_DIR
     environment  variable  prior  to   using   the   kmscfg(1M),
     decrypt(1), encrypt(1), and pktool(1) commands.
















SunOS 5.11          Last change: 19 Jun 2010                    4