Home

Secure Key Box User Guide

1. 3 10 1 Deriving a Key as a Substring of Bytes of Another KEY iis ccuc o te eat 38 3 10 2 Deriving a Key as Odd or Even Bytes of Another Key canina 39 3 10 3 Deriving a Key by Encrypting or Decrypting an Existing KEY ini iia 359 3 10 4 Deriving a Key as a Protected Hash Value of Another Key in 39 S105 Reversing the Order of Byles Ol a KEY AAA a a Ratan de Beat 41 3 10 6 Using the NIST 800 108 Key Derivation es 41 3 10 7 Using KDF2 of the RSAES KEM KWS Scheme Defined in the OMA DRM Specification 42 3 10 8 Derving a Key as Raw Bytes froma Private E e ois se oe ea ge ae 42 3 10 9 Deriving a Key Using the CMLA Key Derivation FAC os 42 3 10 10 Deriving a Key By Encrypting Data Using 128 bit AES With a Concatenated Key 42 3 11 Enerypting and Decrypting Iai testa o o o Sl ASe Data illa aida A O 45 SU peg Usinge theHigeh Speed A O AS 45 EE at ENS MA O E E AS IICA iaa 46 A A A Roan euanog ens 46 SM a SN A a a gO a a 47 AMBITE Keys t a EM e e o ed e e o 48 el Decryptine Encrypted AMA O 48 ASA HBTANES e a lo ol eee casi 49 A Sensitive Open 49 A ON 49 A a e a al ta al 49 42 ca a eae E cee E E A RT E A 53 A 2V OVENI EW peneana a aa adds 55 O 55 P ALS AEI EE CREE OP ARE EATE REINER IE ERECT HE BCE SE CEU UCR TE 57 SUE a Su teo 60 SUSO TE CEA st Ud 60 Sl CUStOmM ECE TONO a 60 51 2 Parameter size ana Valte RESMICUON SS 61 So URI Custo ECO TA
2. SKB supports the following ECC curve types 160 bit prime curve recommended by SECG SECP R1 192 bit prime curve recommended by NIST same as 192 bit SECG SECP R1 224 bit prime curve recommended by NIST same as 224 bit SECG SECP R1 256 bit prime curve recommended by NIST same as 256 bit SECG SECP R1 384 bit prime curve recommended by NIST same as 384 bit SECG SECP R1 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Page 19 0f 137 Secure Key Box User Guide 521 bit prime curve recommended by NIST same as 521 bit S 1 Introduction CG SECP R1 150 bit to 521 bit prime ECC curves with custom domain parameters A ElGamal bit and 256 bit prime curves ECC decryption and ElGamal ECDSA and custom domain parameters ECC key unwrapping support only 160 bit 192 bit 224 ECC key generation curve types including ECC curves with ECDH support all the listed ECC 1 4 Supported Target Platforms The following table lists operating systems and architectures supported by SKB and build systems used to build and test the SKB library Use of other platforms may require additional support from us Platform Architectures Build sy
3. Constant Value Description SKB_SUCCESS 0 The called method was successfully executed SKB FATLURE 1 The method failed to perform the requested operation SKD PRROR INTERNAL 80001 An internal SKB error occurred SKB_ERROR_INVALID_PARAMETERS 80002 Invalid parameters were supplied to the method PRE ERROR NOT SUREORTED 80003 The configuration provided to the method is not supported by SKB KE ERROR OUT OF RESOURCES 80004 The method failed to allocate the required amount of memory on the heap SRP ERROR BUFFER SOC MALS 80005 The provided memory buffer was not large enough to contain the output he A 80006 The format of the input buffer is invalid SKB ERROR TLEECAL OPERATION 80007 The method was requested to perform an operation that it cannot SKB ERROR TNVALID STATR 80008 You are trying to release the SKB_Engine object while it is still being referenced from other SKB objects Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 76 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Constant Value Description SKB ERROR OUT OF RANGE 80009 The specified offset or index of the input buffer is out of range SKB ERROR EVALUATION EXPIRED 80101 The evaluation period of the
4. 7 11 7 SKB_DataFormat This enumeration specifies the possible formats how a cryptographic key can be stored in a data buffer The enumeration is defined as follows typedef enum SKB DATA FORMAT RAW SKB DATA FORMAT PKCS8 SKB DATA FORMAT ECC BINARY _ SKB DataFormat The following table explains the values Value Description SKB DATA FORMAL 240 Buffer of raw bytes for example a DES or AES key Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 126 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Value Description SKB_DATA_FORMAT_PKCS8 RSA private key stored according to the PKCS 8 standard SKB_DATA FORMAT _ECC_BINARY ECC private key stored in the format described in 88 6 7 11 8 SKB_TransformType This enumeration specifies the available transform types used by the SKB Engine CreateTransform method to create SKB_Transform Objects see 87 9 9 The enumeration is defined as follows typedef enum SKB TRANSFORM TYPE DIGEST SKB TRANSFORM TYPE SIGN SKB TRANSFORM TYPE VERIFY SKB TransformType The following table explains the values Value Description SKB TRANSFORM TYEE DIGEST Transform for calculating a digest hash value SKB TRANSFOR
5. peer_public_key Pointer to the memory buffer where the public key received from the other party is stored For the SKB_KEY AGREEMENT ALGORITHM ECDH algorithm the public ey is expected to be stored using the format described in 88 5 For the SKB_KEY AGREEMENT ALGORITHM PRIME DH algorithm the buffer has to be 128 bytes long and it should store the public value encoded in big endian peer_public_key size Size of the peer public key parameter in bytes This size must be equal to the value returned by the SKB_KeyAgreement _GetPublicKey method used by the other key agreement party secret_size Size of the desired shared secret data output To select the largest possible shared secret size the value SKB KEY AGREEMENT MAXIMAL SECRET _S1ZE Should be passed as an input for this parameter secret Address of a pointer to the SKB_SecureData object containing the shared secret data that will be created by this method The bytes are ordered using the big endian notation 7 9 27 SKB_KeyAgreement_Release This method releases an SKB _KeyAgreement Object It should always be called when the object is no longer needed The method is declared as follows SKB Result SKB_K yAgreement Release SKB KeyAgreement self The parameter self is a pointer to the skB_KeyAgreement object that should be released 7 10
6. Mode Description Custom SKB uses your own custom implementation of key caching For information on creating your own implementation see 84 2 3 5 None ey caching is not used at all This is the default mode if there are no RSA features included in the SKB library delivered to you 4 2 3 1 Configuring Key Caching Using Visual Studio In Visual Studio the key caching mode to be used is set using a specific preprocessor definition in the SkbPlatform project properties The following preprocessor definitions can be set each corresponding to a particular key caching mode SKB USE KEY CACHE SQLITE SKB USE KEY CACHE IN MEMORY K SKB USE KEY CACHE CUSTOM K SKB USE KEY CACHE NONE 4 2 3 2 Configuring Key Caching Using SCons For SCons the key caching mode is set by passing the input parameter skb_key_ cache to the SCons script The input parameter can have the following values each corresponding to a particular key caching mode sqlite inmem custom none For more information on running the SCons build script see 82 3 3 2 4 2 3 3 Configuring Key Caching Using Android NDK For Android NDK the key caching mode is set by passing the input parameter SKB_KEY CACHE to the ndk build command The input parameter can have the following values each corresponding to a particular key caching mode
7. 3 10 3 Deriving a Key by Encrypting or Decrypting an Existing Key One way of obtaining a new key is by taking an existing key and encrypting or decrypting it with another key Since keys cannot appear in plain form the input key the encrypting decrypting key and the output key have to be secure data objects SKB supplies a special derivation algorithm for this purpose To create a new key as a result of encrypting another key call the skB_SecureData_Derive method select the SKB_ DERIVATION ALGORITHM CIPHER algorithm and specify the necessary parameters see 87 9 17 This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key 3 10 4 Deriving a Key as a Protected Hash Value of Another Key SKB provides two special key derivation algorithms that allow obtaining a new key from a hash value calculated from another key iterated SHA 1 derivation see 83 10 4 1 SHA 256 derivation with plain prefix and suffix see 83 10 4 2 SHA 384 derivation see 83 10 4 3 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 39 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations The main difference from the standard SHA operations provided by the skB_Transform Class is that the output of these specia
8. 6 3 4 SKB_Pdf_DecryptionContext_ProcessBuffer This function decrypts a part of a particular encrypted object in the PDF file The function is declared as follows SKB Result SKB Pdf DecryptionContext_ProcessBuf fer SKB Pdf DecryptionContext ctx const SKB Byte in buffer SKB Size in buffer size const SKB Byte iv SKB Byte is_last_ chunk SKB Byte out_buffer SKB Size out buffer size The following table describes the parameters Parameter Description ctx Pointer to the SKB _Pdf DecryptionContext object which you prepared before using the SKB _Pdf CreateDecryptionContext function see 86 3 3 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 72 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 6 Decrypting PDF Files Parameter Description in buffer Pointer to an input buffer containing a part of the encrypted PDF object data to be decrypted in buffer size Size of the input buffer iv Pointer to the initialization vector This parameter may be NuLL in which case the initialization vector will be taken from the PDF decryption context The last block of the processed buffer will be stored as the initialization vector in the PDF decryption context after this function is executed is last chunk Parameter that should be set to 1 if this is
9. Features utilizing RSA or ECC custom curve algorithms do not work on PlayStation 3 Before running SKB examples speed tests and unit tests on PlayStation 3 the make_fself tool When unwrapping raw bytes with RSA using OAEP padding only the SHA 1 variant of OAEP included in the PS3 SDK has to be run on the executables padding is supported SHA 256 is not supported Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 23 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 2 Building Applications Protected by SKB 2 Building Applications Protected by SKB This chapter describes the recommended manner to build and deploy an application that is integrated with SKB SKB It also provides Following these steps is important to achieve the maximum security provided by instructions for building SKB examples tests and Platform Specific Library see 84 2 for different target platforms 2 1 Building a Protected Application SKB is delivered as a precompiled static library The public interface to this library is described in the SkbSecureKeyBox h file which is located in the Include directory To build an application protected by SKB you must perform the following main steps 1 Link your application with the following libraries appropriate SecureKeyBox library from the Libraries directory depending on
10. SKB Size prime bit_length SKB Size order bit_length const unsigned int prime const unsigned int a const unsigned int gx const unsigned int gy const unsigned int order 2 SKB_EccDomainParameters The following table explains the properties Property Description prime_bit_length Bit length of the prime a gx and gy domain parameters order_bit_length Bit length of the order domain parameter prime Pointer to the prime modulo of the field Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 116 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description a Pointer to the constant from the equation y x ax b gx Pointer to the X coordinate of the base point gy Pointer to the Y coordinate of the base point order Pointer to the order of the base point All domain parameters except for prime bit length and order bit length must be provided in protected form To obtain the protected form of custom ECC domain parameters use Custom ECC Tool as described in 85 1 7 10 19 SKB_AesWrapParameters This structure provides a specific initialization vector to the AES algorithm when the SKB SecureData Wrap method is used see 87 9 16 If this structure is not provided the AES wrapping algorithm gen
11. Parameter Description buffer This parameter is either NULL or a pointer to the memory buffer where the output is to be stored If this parameter is NULL the call is simply a request to find out how many bytes are needed to store the output so the method returns in buffer size a number indicating how many bytes would be sufficient to hold the output and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and buffer size is large enough to hold the output the method places the output there and sets buffer_size to the exact number of bytes stored If the buffer is not large enough then the method sets buffer size to a number of bytes that would be sufficient and returns SKB_ERROR_BUFFER_TOO SMALL For information on the way the output buffer is formatted in case you use the AES based algorithms see 88 2 3 buffer_size Pointer to a variable that holds the size of the memory buffer in bytes where the output data is to be stored For more details see the description of the buffer parameter 7 9 17 SKB_SecureData_Derive This method creates a new skB_SecureData Object from another SKB _SecureData object using a particular derivation algorithm This method can only be used on SKB_SecureData Objects whose data type is SKB_DATA TYPE BYTES see 87 11 1 The method is declared as follows SKB Result SKB SecureData_ Derive const SKB Sec
12. Parameter Description self Pointer to the pre initialized engine wrapped Pointer to the buffer of encrypted data cryptographic key to be unwrapped f you are unwrapping a key for the Triple DES algorithm make sure the input corresponds to the format described in 88 3 f you are unwrapping an AES wrapped ECC private key for information on how the input buffer must be formatted see 88 7 For other cases of AES wrapped data see 88 2 wrapped_size Size of the buffer of encrypted data in bytes wrapped type Type of the wrapped key The available types are defined in the SKB_DataType enumeration see 87 11 1 wrapped_format Format how the wrapped key is stored in the input data buffer The available formats are defined in the skB_DataFormat enumeration see 87 11 7 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 82 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description wrapping_algorithm Cryptographic algorithm to be used for decrypting the data The available algorithms are defined inthe SKB _CipherAlgorithm enumeration see 87 11 3 For information on algorithms that support key unwrapping see 81 2 The following algorithms only support unwrapping of raw bytes meaning that the wrapped_type parameter should always be SKB DATA
13. SKB ECC CURVE SECP Rl 160 SKB ECC CURVE NIST 192 SKB ECC CURVE NIST 224 SKB ECC CURVE NIST 256 SKB ECC CURVE NIST 384 SKB ECC CURVE NIST 521 SKB ECC _ CURVE CUSTOM SKB EccCurve The following table explains the values Value Description SKB_ECC_CURVE_SECP_R1_160 160 bit prime curve recommended by SECG SECP R1 SKB_ECC_CURVE_NIST_192 192 bit prime curve recommended by NIST same as 192 bit SECG SECP R1 SKB_ECC_CURVE_NIST_224 224 bit prime curve recommended by NIST same as 224 bit SECG SECP R1 SKB_ECC_CURVE_NIST_256 256 bit prime curve recommended by NIST same as 256 bit SECG SECP R1 SKB_ECC_CURVE_NIST_384 384 bit prime curve recommended by NIST same as 384 bit SECG SECP R1 Currently this curve type is supported only for ECDSA ECDH and key generation but not for decrypting and unwrapping SKB_ECC_CURVE_NIST_521 521 bit prime curve recommended by NIST same as 521 bit SECG SECP R1 Currently this curve type is supported only for ECDSA ECDH and key generation but not for decrypting and unwrapping SKB BCG CURVE CUSTOM Prime ECC curve with custom domain parameters Currently this curve type is supported only for ECDSA ECDH and key generation but not for decrypting and unwrapping Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 128 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 11 11 SKB_KeyA
14. void operator new size_t size const std nothrow t amp K return operator new size void operator delete void ptr const std nothrow t amp E return operator delete ptr void operator delete void ptr const std nothrow t return operator delete ptr Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 78 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 8 Classes This section describes the classes of the API Most operations are performed via these classes and their related methods 7 8 1 SKB_Engine SKB Engine is the first object that you create before using the API It is used to initialize other API objects 7 8 2 SKB _SecureData SKB_SecureData contains any data whose value is white box protected and hidden from the outside world but can be internally operated on by SKB Usually the SKB_SecureData object is the container for cryptographic keys protected by SKB Secure data objects can be operated by SKB cryptographic functions but their contents cannot be accessed There are several ways how SKB_SecureData objects are obtained loading encrypted or plain keys importing previously exported keys obtaining as a shared secret via a key agreement algorithm generating a new random SKB _SecureData object to be used as a cryptographic key deriving an SKB _Secure
15. It should always be called when the object is no longer needed The method is declared as follows SKB Result SKB _SecureData_Release SKB SecureData self The parameter self is a pointer to the skB_SecureData object that should be released Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 91 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 9 14 SKB _SecureData_GetInfo This method provides the size and type of contents stored within a particular skB_SecureData object The method is declared as follows SKB Result SKB _SecureData_GetInfo const SKB SecureData self SKB Datalnfo info The following table explains the parameters Parameter Description self Pointer to the skB_SecureData object whose size and type you want to know info Pointer to the skB_DataInfo Structure which will be populated by this method to return the characteristics of the skB_SecureData object see 87 10 3 7 9 15 SKB_SecureData_Export This method returns a protected form of the contents of a particular SKB_SecureData Object This protected data is intended for exporting to a persistent storage Later the exported data can be imported back into the same SKB instance with the same export key using the SKB Engine CreateDataFromExported method see 87 9 6 The method is declare
16. ALGORITHM AES 192 ECB SKB CIPHER ALGORITHM AES 192 CBC SKB CIPHER ALGORITHM AES 192 CTR SKB CIPHER ALGORITHM AES 256 ECB SKB CIPHER ALGORITHM AES 256 CBC SKB CIPHER ALGORITHM AES 256 CTR SKB CIPHER ALGORITHM DES ECB SKB CIPHER ALGORITHM TRIPLE DES ECB SKB CIPHER ALGORITHM NIST AES SKB CIPHER ALGORITHM AES CMLA SKB CIPHER ALGORITHM RSA CMLA SKB CIPHER ALGORITHM XOR 3 SKB CipherAlgorithm The following table explains the values Value Description SKB_CIPHER_ALGORITHM_NULL Value that identifies that no algorithm was used meaning that the corresponding data is not encrypted This value is used by the SKB Engine CreateDataFromWrapped method to specify that the data to be loaded is in plain form see 83 2 SKB CIPHER ALGORITHM AES 128 ECB 28 bit AES in the ECB mode SKB CIPHER ALGORITHM AES 128 CBC 28 bit AES in the CBC mode SKB CIPHER ALGORITHM AES 128 CTR 28 bit AES in the CTR mode SKB I PEER ALGORLTHMARSA 024 bit and 2048 bit RSA with no padding SKB_CIPHER_ALGORITHM RSA_1_5 024 bit and 2048 bit RSA with PKCS 1 version 1 5 padding SKB_ CIPHER ALGORITHM RSA_OAEP 1024 bit and 2048 bit RSA with OAEP padding SKB_CIPHER_ ALGORITHM ECC_ELGAMAL ElGamal ECC Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 121 of 137 Copyright 2004 2015
17. CBC SKB CIPHER ALGORITHM AES 256 ECB SKB CIPHER ALGORITHM AES 256 CBC cipher_direction Parameter that specifies whether the input data should be encrypted or decrypted Available directions are defined in the skB_CipherDirection enumeration see 87 11 6 cipher_flags Optional flags for the cipher Currently the only defined flag is SKB_CIPHER_ FLAG HIGH SPEED This flag can be used only for the AES cipher when it is intended to be used with high throughput for example when used for media content decryption cipher_parameters Pointer to a structure that provides additional parameters for the cipher Currently this parameter must always be NULL cipher key Pointer to the skB_SecureData object containing the encryption or decryption key iv Pointer to the initialization vector iv_size Size in bytes of the initialization vector 7 10 11 SKB_Sha1DerivationParameters This structure is used by the SKB_SecureData_Derive method see 87 9 1 7 if the SKB DERIVATION ALGORITHM SHA 1 algorithm is used see 83 10 4 1 The purpose of this structure is to specify how many times the SHA 1 algorithm should be executed on the source Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 111 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference SKB_SecureData object an
18. E 9 i AP SUID OO MCE Target Pao Ms cds 20 tS Directoy or C E E O e NS 21 A e os e tg eta ed aia a asada 23 2 B ilding Applications Protected Dy SKB reien e ad a 24 2 KB ldn a e ee Temes 24 2 2 Distributing a Protected a a 25 2 3 Building Examples Tests and Platform Specific ID cares 25 2 A O e 26 232 Building tor Windows Runtime and Windows POMC ai a is 26 poros 10 llo ro A gle p AAA O O A 27 a a E R 28 BP Do UCU DTS tOr OS A e eea ee e ee ea e ee 29 2 3 6 Building for Google Native Client NaCl Ravan ene e e ed a o 30 las Schecter ll ee ou lage oi a th Sousa io oes Saul te uaa 31 dlls a 32 341 L adinge Wrapped e o o eo ll e ite 32 3 1 1 Unwrapping Keys Wrapped with the ElGamal ECC Algorithm ciciccicicicicicninnicnicnonnncncoronconos 33 Be loading A ce ac aaa Ca a ica aS 34 ER AIM EIS scien ahaa a acai ere A cs eae ta cea uaa case sa once wloeaae 34 els ad ee JA ODE EO Gee Oe Rs Oe Be O SOONERS Ot ME GEE EEOC COE SE Mae Oe Serer 35 a KEV Srne eene a cana E E a E A AE EA E RE E 35 XO IMPONE KVS ee eaae eaa e E E EE aa E EOE E EEE aaa EOE TEE RAE ERE E eau EEEE EESE 36 E EEO EAE SEE E eae EE E EE E E E 36 3 8 Generatie e o e e Oc el aes oa hae 38 3 9 Deriving a Public Key froma Private e 38 O 38 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 4 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide
19. Include directory 6 3 1 SKB_Pdf_AuthenticateUserPassword This function verifies if the provided user password is valid Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 69 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 6 Decrypting PDF Files The function is declared as follows SKB Result SKB Pdf AuthenticateUserPassword const SKB SecureData password const SKB Byte o SKB_Size o size int py const SKB Byte file id SKB Size file id size const SKB Byte u SKB_Size u_size SKB_Byte is user password valid The following table describes the parameters Parameter Description password Pointer to an SKB_SecureData Object containing the user password a Pointer to the value of parameter O in the encryption dictionary of the PDF file o_size Size of the o value p Value of parameter P in the encryption dictionary of the PDF file file_id Pointer to the first element of the file identifier array This array is the value of the ID entry in the document s trailer dictionary file_id_size Size of the file id value Y Pointer to the value of parameter U in the encryption dictionary of the PDF file u_size Size of the u value is_user_password_ valid Pointer to an skB_Byte variable that will be set to 1 if the user password is correct and O ot
20. Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Value Description SKB CIPHER ALGORITHM AES 192 ECB 192 bit AES in the ECB mode SKB CIPHER ALGORITHM AES 192 CBC 192 bit AES in the CBC mode SKB CIPHER ALGORITHM AES 192 CTR 192 bit AES in the CTR mode SKB CIPHER ALGORITHM AES 256 ECB 256 bit AES in the ECB mode SKB CIPHER ALGORITHM AES 256 CBC 256 bit AES in the CBC mode SKB CIPHER ALGORITHM AES 256 CTR 256 bit AES in the CTR mode SKB CIPHER ALGORITHM DES ECB DES in the ECB mode SKB_CIPHER_ALGORITHM_TRIPLE_DES_ECB Triple DES in the ECB mode SKB CIPHER ALGORITHM NIST AES C S AES key unwra ipher is supported only by the KB Engine C 57 9 5 pping algorithm defined by NIST This reateDataFromWrapped method see SKB CIPHER ALGORITHM A ES CMLA CM Specitication A AES unwrapping defined by the CMLA Technical SKB CIPHER ALGORITHM RSA CMLA CM Specitication LA RSA unwrapping defined by the CMLA Technical SKB CIPHER ALGORITHM XOR Wrapping and unwrapping using XOR If the SKB_SecureData_Wrap function is used see 87 9 16 th e key to be wrapped is XOR ed with the wrapping key If the SKB function is Engine CreateDataFromWrapped used se
21. Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries 4 1 2 7 SKB_CreatePlainFromRsaPrivate This function derives plain RSA private key components from an skB_SecureData Object A The output data buffers will be provided in big endian encoding The function is declared as follows SKB_Result SKB CreatePlainFromRsaPrivate const SKB SecureData data SKB Byte P SKB Byte ar SKB_Byte d SKB Byte ny SKB Size key size The following table explains the parameters Parameter Description data Pointer to the SKB_SecureData from which the plain RSA private key components must be derived plain_p This parameter is either NULL or a pointer to the memory buffer where the prime number p is to be written If this parameter is NULL the method simply returns in key_size a number of bytes that would be sufficient to hold the prime number p and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size is large enough to hold the prime number p the method stores the value there Sets key_size to the exact number of bytes stored and returns SKB_SUCCESS If the buffer is not large enough then the method sets key_size to a number of bytes that would be sufficient and returns SKB_ERROR_BUFFER_TOO SMALL plain_q Pointer
22. OS 61 A ss A a Aat 62 Se MIME IN TO NAS IS 62 A ai O 62 AS 64 a T RO EA EA AE SE I Se 64 ad ss A A 64 S4 Bina Update A RA 65 SIM Update TO el ere o eo De 66 ll lo inson ne E R E Cerra trier iaer emma erae ear a a 66 ELE dB el Spee E cee a 68 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 5 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 61 PDE Brie y ENO OVERVIEW sass 2 scars a nag a naa ones E baus anne A ass E N A AES 68 62 PIE TREC TING IES inenen a a E unten sacetoel e t e e eea et 68 6 3 Deciyotinega PDE DOCUMENT Using SKBerrerncren eenean ne n aE E E a ORS 69 6 3 1 SKB Pdf _AuthenticateUserPasSword oo e cc cccccccccccsccscescescescesecescesceseeseescesscsecsesseesecseveenteessesetatenseess 69 63 2 SKB PAf COmp t EncryptioNKE A A tale Bitatah teks 70 6 3 3 SKB PETC Pea bee Cry DEI CORON t nnn reece cactus ernst sect a EA tal cal aed il 71 G34 SKE Pa Dechy DOM CONTEXT Process UM oiia 72 oa aso il o A NEON 74 et PIRET ORCI e e de e e e e enc ae ay ear 75 ARSS A ER 75 ras a O A 75 SA A ien 75 TAME Return Vale e o a e e es RE 76 O e a o e dl oC 77 TO REA e a A 77 7 7 Overriding Memory Allocation eee oO 78 FARE EES E E E SENE A AA A E A ENAA AS 79 To PIESA D EENE E E E EE R E A EEEE EE 79 4 022 RDSI RED n a att aot AT E A cables aoa on E
23. Reference ManPages man1 codesign 1 html 5 4 2 Running the Binary Update Tool To process an executable with the Binary Update Tool execute the following command Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 66 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 5 Utilities scp update binary binary compiled executable nwdb file The scp update binary file and the nwdb file are located in the Libraries directory Each target platform for which tamper resistance is supported has a separate nwdb file he binary parameter specifies a path to the application executable that contains the SKB library As the final parameter you must provide the nwdb file of the particular target platform After the application executable is successfully processed by the Binary Update Tool you can safely distribute the application to customers Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 67 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 6 Decrypting PDF Files 6 Decrypting PDF Files SKB provides functions specifically dedicated to decrypting encrypted PDF files without revealing the user password and the derived encryption key This chapter describes how to use these functions 6 1 PDF Encryption
24. SHA 1 as the hash function SKB SIGNATURE ALGORITHM ECDSA SHA256 ECDSA with either standard or custom curves using SHA 256 as the hash function SKB SIGNATURE ALGORITHM RSA PSS SHA1 1024 bit and 2048 bit RSA signature algorithms based on the Probabilistic Signature Scheme using SHA 1 as the hash function Salt length is fixed at 20 bytes The mask generation function is using SHA 1 SKB SIGNATURE ALGORITHM RSA PSS SHA1 EX F E Same as SKB SIGNATURE ALGORITHM RSA PSS_SHA1 but allows specifying the salt value and length SKB SIGNATURE ALGORITHM RSA PSS SHA256 1024 bit and 2048 bit RSA signature algorithms based on the Probabilistic Signature Scheme using SHA 256 as the hash function Salt length is fixed at 32 bytes The mask generation function is using SHA 256 SKB SIGNATURE ALGORITHM RSA PSS SHA256 EX G E Same as SKB SIGNATURE ALGORITHM RSA PSS SHA256 but allows specifying the salt value and length 7 11 5 SKB_DerivationAlgorithm This enumeration specifies the possible algorithms that can be used for deriving one SKB_SecureData Object from another using the SKB_SecureData_Derive method see 87 9 17 The enumeration is defined as follows Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 124 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User
25. SKB CIPHER ALGORITHM AES 192 CBC SKB CIPHER ALGORITHM AES 256 CBC If you use any of the algorithms above and set the wrapping parameters value to NULL CBC mode with the XML encryption padding will be used by default which is the equivalent of the SKB_CBC_PADDING TYPE XMLENC value of the SKB _CbcPadding enumeration see 87 11 13 If you are using the SKB_CIPHER_ ALGORITHM ECC_ELGAMAL algorithm this parameter must be a pointer to the SKB_EccParameters structure see 87 10 22 For special instructions for using the ElGamal ECC unwrapping algorithm see 83 1 1 For all other cases set this parameter to NULL unwrapping_key SKB_SecureData object containing the key needed to decrypt the data data Address of a pointer to the SKB_SecureData that will contain the unwrapped key after this method is executed 7 9 6 SKB_Engine_CreateDataFromExported This method imports data that was previously exported using the skB_SecureData Export method see 87 9 15 This operation can be performed only if the importing SKB instance has the same export key as the one that exported the data see 81 1 6 The method is declared as follows SKB Result SKB Engine CreateDataFromExported SKB Engine self const SKB Byte exported SKB Size xported size SKB SecureData data The following table explains the parameters Copyr
26. SKB USE KEY CACHE SQLITE SKB USE KEY CACHE IN MEMORY K SKB USE KEY CACHE CUSTOM K SKB USE KEY CACHE NONE 4 2 3 4 Configuring Key Caching Using Xcode In Xcode the key caching mode to be used is set using a specific preprocessor macro Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 58 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries For OSX the macro is set in the SecureKeyBox project properties For iOS the macro is set in the SkbPlatform target properties The following preprocessor macros can be set each corresponding to a particular key caching mode SKB USE KEY CACHE SQLITE SKB USE KEY CACHE IN MEMORY SKB USE KEY CACHE CUSTOM SKB USE KEY CACHE NONE 4 2 3 5 Creating a Custom Key Caching Implementation In some cases you might want to create your own implementation of key caching for example to avoid including the additional SQLite code in your application In such cases the key cache API must be reimplemented according to the API description in the skbPlatform h file Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 59 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserv
27. SMALL E After successfully executing the method the content of the output parameter will be a pointer to a buffer of bytes containing the public key For information on the format used see 88 5 output_size Pointer to a variable that holds the size of the memory buffer in bytes where the public key is to be stored For more details see the description of the output parameter 7 9 19 SKB_Transform_Release This method releases the specified SKB_Transform Object The method is declared as follows SKB Result SKB_ Transform Release SKB_Transform self The parameter self is a pointer to the SKB_Transform Object to be released 7 9 20 SKB_Transform_AddBytes This method appends a plain buffer of bytes to a previously created SKB _ Transform Object Data must be added to an SKB_Transform object before the actual transform algorithm digest signing or verifying can be executed The method is declared as follows SKB_Result SKB_ Transform _AddBytes SKB_Transform self const SKB Byte data SKB Size data_size The following table explains the parameters Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 98 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description self Pointer to the previously created SKB_Transform object
28. TYPE BYTES and wrapped_format should always be SKB DATA FORMAT RAW SKB CIPHER ALGORITHM ECC_ELGAMAL SKB CIPHER ALGORITHM RSA SKB CIPHER ALGORITHM RSA 1 5 SKB CIPHER ALGORITHM RSA _OAEP SKB CIPHER ALGORITHM NIST AES SKB CIPHER ALGORITHM AES CMLA SKB CIPHER ALGORITHM RSA CMLA S KB CIPHER ALGORITHM XOR If the SKB_CIPHER ALGORITHM NIST_AES algorithm is used in the case of integrity check failure this method will return the SKB ERROR INVALID FORMAT error If the SKB CIPHER ALGORITHM NULL algorithm is used the method assumes that the key in the input buffer is in plain form Then you do not have to provide the unwrapping key or unwrapping parameters If the SKB_CIPHER ALGORITHM ECC_ELGAMAL algorithm is used see the special instructions described in 83 1 1 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 83 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description wrapping_parameters Additional parameters for the unwrapping algorithm You can optionally point this parameter to the SKB AesUnwrapParameters Structure see 87 10 20 to specify the CBC padding type if you are using one of the following algorithms SKB CIPHER ALGORITHM AES 128 CBC
29. a DES or AES key but not an RSA or ECC private key 3 10 5 Reversing the Order of Bytes of a Key SKB provides a simple derivation algorithm that allows you to reverse the order of bytes within a secure data object With this method you can not only derive new keys but also convert a little endian data buffer to big endian and vice versa To create a new secure data object with a reversed order of bytes call the SKB _SecureData_ Derive method and select the SKB_DERIVATION ALGORITHM REVERSE BYTES algorithm see 87 9 1 7 This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key 3 10 6 Using the NIST 800 108 Key Derivation Function SKB provides a derivation algorithm that is based on the MST Special Publication 800 108 which is available here http csrc nist gov publications nistpubs 800 108 sp800 108 pdf The following special notes apply to the SKB implementation 128 bit AES CMAC is used as the pseudorandom function The key derivation function works in counter mode The size of the iteration counter and its binary representation parameters i and r is 8 bits The size of the integer specifying the length of the derived key parameter L is 32 bits and is encoded using the big endian notation To execute this derivation
30. a buffer of plain or secure data and calculating the hash value The output is a plain buffer of bytes To calculate a digest proceed as follows 1 Create a transform object by calling the sKB_ Engine CreateTransform method select the SKB_ TRANSFORM TYPE DIGEST type and specify the necessary parameters as described in 87 9 9 2 Supply a buffer of plain or secure data as an input to the transform object by calling the SKB Transform AddBytes method 87 9 20 and SKB Transform AddSecureData method 87 9 21 You can call these methods more than once to pass a large buffer of input data consisting of several smaller data chunks 3 To calculate the digest call the SKB Transform GetOutput function as described in 87 9 22 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 45 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations 4 Release the transform object when it is no longer needed by calling the skB_Transform Release method as described in 87 9 19 3 13 Creating a Signature Calculating a signature involves executing the signing algorithm on a buffer of plain or secure data using a particular signing key The output is a plain buffer of bytes containing the signature To calculate a signature proceed as follows 1 Obtain a secure data object containing the signing key 2 Create a transf
31. algorithm call the SKB_SecureData_Derive method select the SKB DERIVATION ALGORITHM NIST 800 108 COUNTER CMAC AES128 algorithm and specify the necessary parameters see 87 9 1 7 E This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 41 0f 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations 3 10 7 Using KDF2 of the RSAES KEM KWS Scheme Defined in the OMA DRM Specification SKB provides a derivation algorithm that is based on KDF2 used in the RSAES KEM KWS scheme of the OMA DRM specification To execute this derivation algorithm call the SKB_SecureData_Derive method select the SKB DERIVATION ALGORITHM OMA DRM KDF2 algorithm and specify the necessary parameters see 87 9 17 This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key 3 10 8 Deriving a Key as Raw Bytes from a Private ECC Key In some scenarios you may want to derive a new key as raw bytes for example a DES or AES key from an ECC private key To execute this derivation algorithm call the SkKB_Secu
32. as follows SKB Result SKB Engine CreateKeyAgr SKB_Engine ment self SKB KeyAgreementAlgorithm key agreement algorithm const void SKB KeyAgreement key agreement parameters key agreement The following table explains the parameters Parameter Description self Pointer to the pre initialized engine key agreement algorithm Key agreement algorithm to be used Available algorithms are defined in the skB_KeyAgreementAlgorithm enumeration see 87 11 11 key agreement parameters Pointer to a structure providing the necessary parameters for the ey agreement algorithm For the SKB_KEY AGREEMENT ALGORITHM ECDH algorithm this parameter must point to an SKB_EccParameters Structure see 87 10 22 For the SKB _KEY AGREEMENT ALGORITHM PRIME DH algorithm this parameter must point to an SKB_PrimeDhParameters structure see 87 10 23 key agreement Address of a pointer to the SKB_KeyAgreement object which will be created by this method 7 9 12 SKB_Engine_UpgradeExportedData This method upgrades an exported SKB_SecureData Object to the latest version as described in 83 7 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 90 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference The method is declared
33. as follows SKB Result SKB Engine UpgradeExportedData SKB Engine engine const SKB Byte input SKB Size input_size SKB Byte buffer SKB Size buffer size The following table explains the parameters Parameter Description engine Pointer to the pre initialized engine input Input data buffer containing the previously exported SKB_SecureData Object that needs to be upgraded to the latest export format input_size Size of the input data buffer in bytes buffer This parameter is either NULL or a pointer to the memory buffer where the upgraded data is to be written If this parameter is NULL the method simply returns in buffer size a number of bytes that would be sufficient to hold the output and returns SKB SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size is large enough to hold the output the method stores the output there sets buffer size to the exact number of bytes stored and returns SKB_SUCCESS If the buffer is not large enough then the method sets buffer sizetoa number of bytes that would be sufficient and returns SKB_ ERROR BUFFER TOO SMALL buffer_size Pointer to a variable that holds the size of the memory buffer in bytes where the output is to be stored For more details see the description of the buffer parameter 7 9 13 SKB_SecureData_Release This method releases an SKB_SecureData Object
34. block size for AES O x Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 132 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 8 Data Formats 16 BYTES N BYTES AES wrapped buffer in the CTR mode 8 2 3 CBC Mode In SKB two CBC types are used with no padding and with XML encryption padding In both cases the wrapped data buffer begins with the initialization vector which is 16 bytes followed by a data buffer that is a multiple of 16 bytes block size for AES The following subsections describe the two CBC mode types available 8 2 3 1 No Padding If no CBC padding is used it is assumed that the size of the encrypted data buffer is an exact multiple of 16 bytes and nothing is suffixed to the end of the buffer 16 BYTES 16 BYTES 16 BYTES 16 BYTES AES wrapped buffer in the CBC mode with no padding This CBC type cannot be used to unwrap RSA keys If you are unwrapping ECC keys this CBC type can only unwrap keys of the 256 bit and 384 bit curves recommended by NIST Other ECC curve types are not supported 8 2 3 2 XML Encryption Padding SKB supports the CBC mode with padding conventions of the standard XML encryption which is described in http www w3 org TR xmlenc core This means that if the size of the encrypted message within the data buffer is not an exact multiple of the block
35. ee ese leo os 79 ES CIDHE ere een mene emer ee me tere re ere ee are ne arnt Ee AR een ee eRe nese ee etree mere 79 TS AVSKB sia STOMM dotan o aca e to o o a eos 79 18 5 SKB KEVAgrEeM eN E dende iia 79 AO MeO S e tg R 80 IL SBS ES Gel AS Cea IGE en n e Ai 80 ASS KB Emene A A AO 80 79 3 a A a eae E N ca ea a Ont ites 80 FO AUS SEE NS GEUN os 81 POS She Engine Ore are aba poli Viale AAA A ele aln seas 82 79 6 SKB Engine Creare DalabromeExpOnte suse cute athe mi alee oo os a 84 79A SKBEneineMWrapData ION I PlaMat rer uir gets ts essa coal Matera et E E E tutes au tata G E 85 799 5KB ENSIne Genera CUIDA ai 86 199 do li so A One Cnr ent Seer neem Rema ane 87 TIO SE CER UC ROE E EE EA EEE es REET 88 LAN ela A a AA O n a a 90 TOW She on Ple lo o dales ly altel AAA A 90 7 9 13 SKB SecureData Release enanas 91 7 9 14 SKB_SecureData_ Gettin 92 e Vea La A E va assis os eo R aad ano Ronse 92 Ae Or e hata ce Abe cok Lah adbe cuenta Ah cael ail aaa cau ul tabi oat 93 9 AF SKBESCCUrE Datas WO a tates a toe 95 7918 SB Sec Une Data GetPUBICKEY sisi o o ol eo al 97 7 9 19 SKB Transform Release ens 98 FOZ IB ASTON CI By CS Src o fe NG A EE Sta Mice een ae 98 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 6 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 9 21 SKB_Transform_Ad
36. hacker attacks Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 13 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction ote SKB tamper resistance is implemented using Code Protection a comprehensive tool for hardening software applications on multiple platforms For information on Code Protection see www whitecryption com code protection A If your SKB package has tamper resistance applied you have to run the Binary Update Tool on your final application executable every time it is built Otherwise the application will crash at run time For more information on running the Binary Update Tool see 85 4 1 1 9 1 Security Features SKB s implementation of tamper resistance consists of a combination of the following security features Security feature Description Integrity protection Hundreds of embedded overlapping checksums can prevent modifications of the binary code of the entire executable not just SKB Code obfuscation Library code is transformed to make it difficult to analyze and reverse engineer Anti debug protection Platform specific anti debug code adds protection against main stream debuggers providing another barrier to code analysis iOS jailbreak detection Normally a cracked or modified iOS application can be run only on jailbroken iOS devices i
37. instance and sets the pointer to refer to the new instance Every subsequent call of the SKB _Engine GetInstance method will return the same skB_Engine object until this object is released 7 9 2 SKB_Engine_Release This method releases an SKB_Engine instance once it is no longer needed Ah Make sure that every skB_ Engine GetInstance Call has a corresponding SKB Engine Release Call to correctly release the memory AX All other SKB objects created via the SKB_Engine object must be released before you call the SKB Engine Release method The method is declared as follows SKB_Result SKB Engine Release SKB_Engine self The parameter self is a pointer to the engine instance that should be released 7 9 3 SKB_Engine_SetDeviceld This method sets the device ID which is a byte array of arbitrary length that will be combined with the export key to form a unique format for exported keys This method enables you to bind exported keys to a specific device see 83 16 By default when an engine is initialized there is no device ID set and the export format depends only on the export key The method is declared as follows Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 80 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference SKB_Result SKB Engine SetDevice
38. is stored in _ bytes with indices 12 to 27 Remember that data is in big endian so when i you add 4 bytes before the 16 byte AES key in encryption process the E whole 20 bytes go to bytes with indices 12 to 31 the 4 added bytes are ify stored in bytes with indices 28 to 31 Z Extract the AES key from bytes 12 to 27 SKB SliceDerivationParameters params 12 16 from size Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 33 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations SKB SecureData Derive temp data SKB DERIVATION ALGORITHM SLICE amp params amp secret_ key Z Release temporary data SKB SecureData_Release temp_data Y Now use secret key that contains the 16 byte AES key EZ ay Release the secret key when it is no longer needed SKB _SecureData_R lease secret key 3 2 Loading Plain Keys SKB is designed to always work with keys in protected form If a key needs to be loaded into SKB normally you should delivered and load it in encrypted form However for very rare cases SKB does support direct loading of plain keys A Loading a plain key is a very insecure operation and should be avoided if possible There are better alternatives for achieving this as described in 81 1 7 Normally importing of plain keys is
39. properties Property Description major minor Version numbers specified in the API header file revision flags Currently this property is not used because there are no engine specific flags defined property count Number of elements in the properties array Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 105 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description properties Array of engine properties with property count elements where each property specified is an SKB_EngineProperty structure see 87 10 1 The following properties are used implementation Cryptographic technique used by SKB Available values are the following vy identifies an implementation based on composite automata p identifies an implementation based on polynomial encryption key cache Key caching mechanism used by SKB Available values are sqlite memory and custom For information on key caching and its modes see 84 2 3 key cache max items Maximum number of keys that can be cached in the memory This property is available only if the memory key caching mechanism is used diversification guid Unique diversification identifier consisting of 16 bytes in the hexadecimal format SKB packages with the same binary implementation will have the same ident
40. provides the output in plain form see 83 11 2 The unwrapped key is directly transformed into a secure data object and is never exposed in plain form To unwrap a key call the skB_Engine CreateDataFromWrapped method see 87 9 5 and provide the necessary parameters such as the following wrapped key type of the wrapped key format of the wrapped key algorithm for unwrapping the data for the special case of using the ElGamal ECC unwrapping algorithm see 83 1 1 additional parameters for the unwrapping algorithm unwrapping key Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 32 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations 3 1 1 Unwrapping Keys Wrapped with the ElGamal ECC Algorithm Since there are no widely accepted standards for storing the output of ElGamal ECC decryption this section describes the format used by SKB In connection with this you may have to perform additional steps to extract the actual unwrapped key from the output as described below In the case of the ElGamal ECC unwrapping algorithm the wrapped buffer of the SKB Engine CreateDataFromWrapped method see 87 9 5 should contain two points on an ECC curve as described in 88 4 After the unwrapping method is successfully executed the data variable will point to a buffer that contains the X coordina
41. secure data meaning that SKB cannot generate private RSA keys generate_parameters Pointer to a structure that specifies the necessary parameters for generating the secure data object For different secure data types different structures must be provided as follows For SKB DATA TYPE BYTES this parameter must point to the SKB_RawBytesParameters structure see 87 10 24 which specifies the number of bytes to be generated For SKB DATA TYPE ECC PRIVATE KEY this parameter must point to the skB_EccParameters Structure see 87 10 22 which specifies the ECC curve type to be used data Address of a pointer to the SKB_SecureData object that will be created by this method This object will contain the generated data 7 9 9 SKB_Engine_CreateTransform This method creates a new SKB_Transform Object based on the provided parameters The SKB_Transform Object is used to calculate a digest sign data or verify a signature The method is declared as follows SKB Result SKB Engine CreateTransform SKB Engine self l SKB TransformType transform type const void transform parameters SKB Transform transform Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 87 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Refer
42. size the last block must be padded by suffixing additional bytes to the data buffer to reach a multiple of the block size The last byte in the last block must contain a number that specifies how many bytes must be stripped from the end of the decrypted data Other added bytes are arbitrary Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 133 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 8 Data Formats LAST BLOCK i 1 E j N BYTES 16 BYTES 16 BYTES 16 BYTES 16 BYTES AES wrapped buffer in the CBC mode with XML encryption padding In the preceding diagram N is the number of bytes added to the last block If the message size happens to be an exact multiple of 16 bytes an additional block is added in which the contents are arbitrary but the last byte must contain the number 16 8 3 Key Format for the Triple DES Cipher SKB supports two keying options for the Triple DES cipher All three keys are distinct Key 1 and key 2 are distinct and key 3 is identical to key 1 In both cases keys have to be provided as one buffer of bytes SKB determines the keying option to be used based on the buffer size If the buffer is 192 bits long SKB assumes the keys are provided in the following format KEY 1 KEY 2 KEY 3 8 BYTES 8 BYTES 8 BYTES Triple DES key buffer containing three distinct keys If the buffe
43. subdirectories for supported target operating systems and architectures Each subdirectory contains build files required for building SKB examples tests and Platform Specific Library For information on building SKB examples tests and Platform Specific Library see 82 3 Documents Contains SKB documentation Examples Contains SKB examples For information on building the examples see 82 3 Include Contains the following header files SkbConfiguration h Tells which features are enabled and disabled in the current SKB package SkbExtensions h Interface to functions that are considered to be an extension to the main SKB API Currently this interface only contains the functions for PDF file decryption see 86 SkbInternalExposed h Interface that is internally used by unit tests and speed tests L 109 kbInternalHelpers h Interface of Sensitive Operations Library see 84 1 SkbPlatform h Interface of Platform Specific Library see 84 2 SkbSecureKeyBox h Entire public interface of SKB see 87 This is the main API that you use with SKB Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 21 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Directory or file Description Libraries Contains the following b
44. the exported keys so that they are no longer readable by the previous SKB version With this approach you can even upgrade keys exported by older SKB releases Note Alternatively you can upgrade exported keys with Key Export Tool as described in 85 3 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 37 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations A Key upgrading should be performed only once To avoid security risks do not perform key upgrading and importing every time SKB is run After the upgrade make sure all keys of previous versions are permanently deleted 3 8 Generating Keys SKB provides a way for generating new symmetric and private keys The generated keys will contain random content based on the native system s random generator for Windows the CryptoAPI is used for other systems the dev random device is used If necessary you can create a custom implementation for the random generator function as described in 84 To generate a new random key call the SKB _Engine GenerateSecureData method specify what type of key you want to generate and provide the necessary parameters See 87 9 8 With the help of this method you can generate random buffer of bytes for example a DES or AES key private ECC keys Currently SKB does no
45. the following directories depending on the compilation mode Build Targets universal apple macosx build Debug Build Targets universal apple macosx build Release OS One of the following directories depending on the compilation mode Build Targets arm apple ios build Debug iphoneos Build Targets arm apple ios build Release iphoneos 2 3 6 Building for Google Native Client NaCl The SCons build tool is used to build SKB examples tests and Platform Specific Library This section describes how to set up the build environment and compile the source code 2 3 6 1 Prerequisites The following prerequisites must be met before building the source files 1 Download and install SCons 2 3 0 2 Download and install Native Client SDK 2 3 6 2 Compiling Compiling for Google Native Client is performed the same way as described in 82 3 3 2 with the target parameter set to one of the following depending on the necessary architecture nacl arm nacl pnacl Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 30 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 2 Building Applications Protected by SKB nacl x86 32 nacl x86 64 A If your application is using SKB algorithms that depend on random generation you must use the SKB_InitRng and SKB_DestroyRng functions of Platform Specific Library as de
46. the target platform Platform Specific Library which provides certain functions that have different implementations for different operating systems see 84 2 SQLite library if you are using SQLite based key caching see 84 2 3 82 2 dh Make sure you are not linking or distributing any of the unsafe SKB components listed in 2 Build your application and make sure you use the following compiler and linker settings depending on your build system Build system Settings to use Visual Studio enable references to remove unnecessary code OPT REF enable COMDAT folding to remove duplicated code OPT ICF GCC if compiling for OS X via the command line use the w1 dead_strip option to remove unnecessary code sections if compiling for Linux use the w1 gc sections option to remove unnecessary code sections Xcode enable Deployment Postprocessing to remove information that can be used to reverse engineer the code enable Strip Linked Product to remove information that can be used to reverse engineer the code Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 24 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 2 Building Applications Protected by SKB 3 To ensure that symbol information is correctly stripped from the executable open the executable in a binary editor and se
47. this derivation algorithm see 83 10 6 The structure is declared as follows typedef struct const SKB Byte label SKB Size label size const SKB Byte context SKB Size context size SKB Size output size E SKB_Nist800108CounterCmacAes128Parameters The following table explains the properties Property Description label Pointer to the label a binary buffer that identifies the purpose for the derived key as defined by the M ST Special Publication 800 108 label size Size of the label in bytes context Pointer to the context a binary buffer containing the information related to the derived key as defined by the MST Special Publication 800 108 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 113 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description context_size Size of the context in bytes output_size Size of the derivation output in bytes It cannot exceed 4096 bytes and must be a multiple of 16 7 10 14 SKB_RawBytesFromEccPrivateDerivationParameters This structure may be used by the SKB _SecureData_Derive method to specify the endianness of the output if the skB_DERIVATION ALGORITHM RAW BYTES FROM ECC PRIVATE derivation algorithm is used see 87 9 17 The purpose of this structure is to specify whet
48. to the prime number q This parameter works similar to plain_p and will have the same size plain_d Pointer to the decryption exponent a This parameter works similar to plain_p and will have the same size plain_n Pointer to the modulus n This parameter works similar to plain_p and will have the same size key_size Pointer to the size of the prime number p prime number q decryption exponent a and modulus n Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 54 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries 4 2 Platform Specific Library This section describes the purpose and details of Platform Specific Library delivered together with SKB 4 2 1 Overview Although the largest part of SKB is delivered as a single library a small subset of functions used by SKB depends on the target operating system and may be implemented differently on the same architecture Therefore these functions are externalized as a separate module called Platform Specific Library This library is available as source code in the Tools SkbPlat form directory and as a precompiled binary in the Libraries directory Platform Specific Library has its own interface defined in the Include SkbPlatform h file You can use the provided implementation as is or create your own custom implementation of lib
49. 015 whiteCryption Corporation All rights reserved Page 136 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 8 Data Formats Once the AES wrapped content is decrypted the first N 7 8 bytes are taken as the actual unwrapped ECC private key 8 8 ECDSA Output The output of the ECDSA algorithm is the following buffer of bytes N BYTES gt N BYTES gt ECDSA output format R and S are the two parameters of a signature used in the ECDSA algorithm encoded using the big endian notation and N depends on the ECC curve used as follows SKB ECC CURVE _SECP_R1_160 21 bytes SKB ECC CURVE NIST 192 24 bytes SKB ECC CURVE NIST 224 28 bytes SKB ECC CURVE NIST 256 32 bytes SKB ECC CURVE NIST 384 48 bytes SKB ECC CURVE NIST 521 66 bytes SKB ECC CURVE CUSTOM specified bit length of the order domain parameter plus 7 divided by 8 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 137 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved
50. 1 parameter is omitted To execute this derivation algorithm call the skB_SecureData_Derive method see 87 9 17 select the SKB_ DERIVATION ALGORITHM SHA AES algorithm and supply SKB ShaAesDerivationParameters as the parameters structure see 87 10 15 This operation can only be performed on secure data objects that contain raw bytes and are 12 bytes long 3 11 Encrypting and Decrypting Data This section describes operations related to encrypting and decrypting data 3 11 1 Encrypting Data Encryption is a process where a cryptographic cipher and a cryptographic key are applied to plain data to produce encrypted data DES Triple DES and AES are the only supported encryption ciphers The main reason for this is that encryption for asymmetric key ciphers RSA and ElGamal ECC require a public key which is usually known and therefore does not require protection To encrypt data proceed as follows 1 Create a cipher object using the skB_Engine CreateCipher method specify the encryption algorithm and key specify the direction skB_CIPHER DIRECTION ENCRYPT and provide the necessary parameters as described in 87 9 10 2 Encrypt the input buffer by calling the skB_Cipher ProcessBuffer method as described in 87 9 23 This method returns a byte buffer containing the encrypted data Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 44 of 137 Copyright 2004 2015 In
51. B_SecureData object containing the encryption key iv Pointer to the initialization vector if the encryption algorithm used is AES in CBC mode If the initialization vector is not used or if it is all Zeros the value of this parameter should be NULL iv_size Size of the initialization vector in bytes If the value of the iv parameter is NULL this parameter should be 0 data Address of a pointer to the SKB_SecureData object that will contain the output when this method is executed 7 9 8 SKB_Engine_GenerateSecureData This method creates a new random skB_SecureData Object based on the provided parameters This operation is typically used for generating new random keys The method is declared as follows Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 86 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference SKB Result SKB Engin _GenerateSecureData SKB Engine self SKB DataType data_type const void generate parameters SKB SecureData data The following table explains the parameters Parameter Description self Pointer to the pre initialized engine data_type Type of data to be generated The available types are defined in the SKB_DataType enumeration see 87 11 1 Currently the SKB_DATA TYPE RSA PRIVATE KEY type is not supported for generating
52. C 128 bit AES CMAC based on OMAC1 SKB SIGNATURE ALGORITHM HMAC SHA1 AC using SHA 1 with up to 64 byte keys SKB SIGNATURE ALGORITHM HMAC SHA256 AC using SHA 256 with up to 64 byte keys SKB SIGNATURE ALGORITHM HMAC SHA384 AC using SHA 384 with up to 64 byte keys SKB SIGNATURE ALGORITHM HMAC SHA512 AC using SHA 512 with up to 64 byte keys SKB SIGNAT RE ALGORITHM RSA 1024 bit and 2048 bit RSA signature algorithms standardized in version 1 5 of PKCS 1 without a hash function can only be executed on plain input which is a digest of some hash function SKB SIGNATURE ALGORITHM RSA SHA1 T 1024 bit and 2048 bit RSA signature algorithms standardized in version 1 5 of PKCS 1 using SHA 1 as the hash function Copyright 2000 2015 whiteCryption Corporation All rights reserved Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Page 123 of 137 Secure Key Box User Guide 7 API Reference Value Description SKB SIGNATURE ALGORITHM RSA SHA256 1024 bit and 2048 bit RSA signature algorithms standardized in version 1 5 of PKCS 1 using SHA 256 as the hash function SKB SIGNATURE ALGORITHM ECDSA ECDSA with either standard or custom curves can only be executed on plain input which is a digest of some hash function SKB SIGNATURE ALGORITHM ECDSA SHA1 ECDSA with either standard or custom curves using
53. C with up to 64 byte keys using SHA 1 SHA 256 SHA 384 or SHA 512 as the hash function 1024 bit and 2048 bit RSA signature algorithms standardized in version 5 of PKCS 1 without a hash function 1024 bit and 2048 bit RSA signature algorithms standardized in version 5 of PKCS 1 using SHA 1 or SHA 256 as the hash function 1024 bit and 2048 bit RSA signature algorithms based on the Probabilistic Signature Scheme using SHA 1 or SHA 256 as the hash function ECDSA without a hash function for supported curve types see 81 3 ECDSA using SHA 1 or SHA 256 as the hash function for supported curve types see 81 3 Verification 128 bit AES CMAC based on OMAC1 HMAC with up to 64 byte keys using SHA 1 SHA 256 SHA 384 or SHA 512 as the hash function T Key importing plain bytes for example DES and AES keys plain RSA private keys plain ECC private keys Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 17 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Function Algorithms Unwrapping unwrapping raw bytes for example DES and AES keys using 128 bit 192 bit and 256 bit AES in ECB mode no padding CBC mode no padding or XML encryption padding and CTR mode unwrapping R
54. Data Object from another SKB_SecureData object using the SKB SecureData Derive method wrapping plain keys 7 8 3 SKB_Cipher SKB_Cipher is an object that can encrypt or decrypt data It encapsulates the attributes and parameters necessary to perform cryptographic operations on data buffers 7 8 4 SKB Transform SKB Transform is an object that can calculate a digest sign data or verify a signature This object can operate both on plain data and secure data The output is always a plain buffer of data 7 8 5 SKB_KeyAgreement SKB KeyAgreement iS an object used to perform the key agreement algorithm Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 79 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 9 Methods This section describes all the methods provided by the API 7 9 1 SKB_Engine_Getinstance This method creates an SKB_Engine instance see 87 8 1 This instance is the first object that you must obtain before using the API dh Make sure that every SKB Engine GetInstance Call has a corresponding SKB Engine Release Call to correctly release the memory The method is declared as follows SKB_Result SKB Engine GetInstance SKB Engine engine The parameter engine is an address of a pointer to the skB_Engine object After execution this method creates an SKB_Engine
55. Guide 7 API Reference typedef enum SKB DERIVATION ALGORITHM SLICE SKB DERIVATION ALGORITHM BLOCK SLICE SKB DERIVATION ALGORITHM SELECT BYTES SKB DERIVATION ALGORITHM CIPHER SKB DERIVATION ALGORITHM SHA 1 SKB DERIVATION ALGORITHM SHA 256 SKB DERIVATION ALGORITHM SHA 384 SKB DERIVATION ALGORITHM REVERSE BYTES SKB DERIVATION ALGORITHM NIST 800 108 COUNTER CMAC AES128 SKB DERIVATION ALGORITHM OMA DRM KDF2 SKB DERIVATION ALGORITHM RAW BYTES FROM ECC PRIVATE SKB DERIVATION ALGORITHM CMLA KDF SKB DERIVATION ALGORITHM SHA AES E SKB_DerivationAlgorithm The following list explains the values SKB_DERIVATION ALGORITHM SLICE Derives anew SKB_SecureData Object as a substring of bytes of another SKB_SecureData object For more information see 83 10 1 E SKB DERIVATION ALGORITHM BLOCK SLICE Same as the SKB DERIVATION ALGORITHM SLICI algorithm but it requires the index of the first byte and the number of bytes in the substring to be multiples of 16 For more information see 83 10 1 SKB DERIVATION ALGORITHM SELECT BYTES Derives a new SKB_SecureData Object from the input SKB_SecureData Object by copying only odd or even bytes from it For more information see 83 10 2 E E SKB DERIVATION ALGORITHM CIPHER Derives a new SKB_SecureDat
56. HM AES 192 CBC SKB CIPHER ALGORITHM AES 256 CBC SKB CIPHER ALGORITHM XOR The AES based algorithms can only be used on SKB_SecureData objects whose data type is SKB_DATA TYPE BYTES Or SKB DATA TYPE ECC PRIVATE KEY see 87 11 1 The SKB CIPHER ALGORITHM XOR algorithm can only be used on SKB SecureData Objects whose data type is SKB_DATA TYPE BYTES wrapping parameters Pointer to a structure that provides additional parameters for the wrapping algorithm This parameter is applicable only if you use one of the following algorithms SKB CIPHER ALGORITHM AES 128 CBC SKB CIPHER ALGORITHM AES 192 CBC SKB CIPHER ALGORITHM AES 256 CBC Then this parameter can be used to provide a specific initialization vector to the AES wrapping algorithm In that case you should point this parameter to the SkB_AesWrapParameters Structure see 87 10 19 where the initialization vector is specified If this structure is not provided wrapping parameters iS NULL the AES algorithm generates a random initialization vector wrapping key Pointer to the skB_SecureData object containing the wrapping key Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 94 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference
57. KB CbcPadding The following table explains the values Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 129 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Value Description e PADDING DYEB ONE CBC mode with no padding see 88 2 3 1 SKB_CBC_PADDING_TYPE_XMLENC CBC mode with the XML encryption padding 88 2 3 2 7 11 14 SKB_SelectBytesDerivationVariant The enumeration is defined as follows This enumeration is used by the SKB _SelectBytesDerivationParameters Structure see 87 10 9 to specify whether odd or even bytes should be selected typedef enum SKB_SE SKB SE E SKB Selec ECT BYT ECT BYTES _ tBytesDerivationVariant ES DERIVATION ODD BYTE ES DERIVATION EVEN BYTES The following table explains the values Value Description SKB SELECT BYTES DERIVATION ODD BYTES Odd bytes should be selected SKB SELECT BYTES DERIVATION EVEN BYTES Even bytes should be selected Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 130 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 8 Data Formats 8 D
58. KB_CreatePlainFromRawBytes This function returns a plain data buffer from an skB_SecureData object The function is declared as follows SKB Result SKB CreatePlainFromRawBytes const SKB SecureData data SKB _Byte plain SKB Size plain size The following table explains the parameters Parameter Description data Pointer to the skB_SecureData from which the plain data buffer must be created Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 50 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries Parameter Description plain This parameter is either NULL or a pointer to the memory buffer where the plain ey is to be written f this parameter is NULL the method simply returns in plain _size a number of bytes that would be sufficient to hold the plain key and returns SKB_SUCCESS f this parameter points to a memory buffer it is not NULL and the buffer size is arge enough to hold the plain key the method stores the plain key there sets plain_size to the exact number of bytes stored and returns SKB_SUCCESS If the buffer is not large enough then the method sets plain size to a number of bytes that would be sufficient and returns SKB_ERROR_BUFFER_TOO SMALL plain_size Pointer to the size of the plain data buffer in bytes 4 1 2 3 SKB_Cre
59. L For information on the exported data format see 88 1 buffer _size Pointer to a variable that holds the size of the memory buffer in bytes where the exported data is to be stored For more details see the description of the buffer parameter 7 9 16 SKB_SecureData_Wrap This method wraps encrypts the contents of a particular SKB_SecureData object using a specified cipher and wrapping key For more information on wrapping secure data see 83 3 The method is declared as follows SKB_Result SKB _SecureData_Wrap const SKB SecureData self E SKB CipherAlgorithm wrapping algorithm const void wrapping parameters const SKB SecureData wrapping key SKB Byte buffer SKB Size buffer size The following table explains the parameters Parameter Description self Pointer to the SKB_SecureData object whose contents need to be wrapped Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 93 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description wrapping algorithm Wrapping algorithm to be used The available algorithms are defined in the SKB_CipherAlgorithm enumeration see 87 11 3 Currently only the following algorithms are supported for wrapping SKB CIPHER ALGORITHM AES 128 CBC SKB CIPHER ALGORIT
60. M TYPE STON Transform for creating a signature SKB TRANSFORM LYBE VERTEY Transform for verifying a signature 7 11 9 SKB_Exportlarget This enumeration specifies the various export types used by the skB_SecureData_Export method see 87 9 15 The enumeration is defined as follows typedef enum SKB EXPORT TARGET CLEARTEXT SKB EXPORT TARGET PERSISTENT SKB EXPORT TARGET CROSS ENGINE EXPORT TARGET CUSTOM Currently only the SKB_EXPORT TARGET PERSISTENT type is supported With this type the exported data can be reloaded in an engine even after a complete reboot of the system hosting the engine Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 127 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 11 10 SKB_EccCurve This enumeration ElGamal ECC algorithms are used This enumeration specifies the available is defined as follows 7 API Reference ECC curve types These values must be provided when the typedef enum
61. OS jailbreak detection protects the application from being executed on a jailbroken device Android rooting detection Rooting is a security risk to Android applications that deal with sensitive data or enforce certain usage restrictions Rooting detection will protect the application if a rooted device is detected Inlining of static void functions Static void functions with simple declarations are inlined into the calling functions Such operation increases the obfuscation level of the final protected code and makes it more difficult to trace String literal obfuscation Large portion of string literals or string constants are encrypted in the code and are decrypted only before they are actually used The purpose of this feature is to hide useful and sensitive information from potential attackers Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 14 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Security feature Description Customizable defense Optionally you can request a tamper resistance SKB library that is action configured to execute specific callback functions depending on the type of attack it detects Additionally when requesting the SKB library you can choose whether the program state should be corrupted or the application should be left running after a callback f
62. Overview A PDF document can be encrypted to protect its contents from unauthorized access Encryption applies only to string and stream objects in the PDF file Other objects such as integers and Boolean values which are used primarily to convey information about the document s structure rather than its content are left unencrypted In an encrypted PDF file every string and stream object is encrypted with a different key All these keys are derived from one primary encryption key which in turn is derived from the user password document is not encrypted Encryption related information is stored in the document s encryption dictionary which itself is stored in the Encrypt entry of the document s trailer dictionary The trailer dictionary is a collection of ey and value pairs in the very end of the PDF file The absence of the Encrypt entry means that the The encryption dictionary is also a collection of key and value pairs describing all necessary parameters of the particular encryption used 6 2 PDF Requirements SKB supports only encrypted PDF files that match the following criteria PDF version is either 1 6 or Ye The following values are set Key Value Filter Standard Length 128 R 3 V 2 in the encryption dictionary These restrictions ensure that 128 bit AES in CBC mode is used for content encryption and that the proper key handling al
63. SA keys using 128 bit 192 bit and 256 bit AES in CBC mode XML encryption padding and CTR mode unwrapping ECC keys using 128 bit 192 bit and 256 bit AES in CBC mode no padding or XML encryption padding and CTR mode A A G C unwrapping using XOR unwrapping raw bytes for example DES and AES keys using 1024 bit and 2048 bit RSA no padding PKCS 1 version 1 5 padding or OAEP padding unwrapping raw bytes for example DES and AES keys using ElGamal ECC for supported curve types see 81 3 ES key unwrapping defined by NIST with 128 bit 192 bit and 256 bit ES keys A AES unwrapping defined by the CMLA Technical Specification LA RSA unwrapping defined by the CMLA Technical Specification Wrapping wrapping raw bytes for example DES and AES keys using 128 bit 192 bit and 256 bit AES in CBC mode XML encryption padding wrapping ECC keys using 128 bit 192 bit and 256 bit AES in CBC mode XML encryption padding wrapping plain data using 128 bit 192 bit and 256 bit AES in ECB mode no padding and CBC mode no padding wrapping using XOR Digests S S S A 1 A 256 A 384 A 512 Key agreement C Elliptic curve Diffie Hellman ECDH for supported curve types see 81 3 assical Diffie Hellman DH with up to 1024 bit pr
64. Supporting Structures This section describes various Supporting structures used by the API Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 104 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 10 1 SKB_EngineProperty SKB _EngineProperty iS a name value pair representing a particular SKB_Engine property in the SKB_EngineInfo structure see 87 10 2 The SKB _EngineProperty Structure is declared as follows typedef struct e const char name E const char value SKB EngineProperty For information on available properties see 87 10 2 7 10 2 SKB_Enginelntfo SKB_EngineInfo is a structure that is populated by the skB_Engine GetInfo method see 87 9 4 to provide information about a particular skB_Engine instance Ad The contents of a populated skB_EngineIn o structure will not be valid after the corresponding skB_Engine object is released from memory During examination of the SKB_EngineInfo Object the SKB_ Engine object must exist The SKB_EngineInfo Structure is declared as follows typedef struct struct unsigned int major unsigned int minor unsigned int revision api version unsigned int flags unsigned int property count SKB EngineProperty properties B EnginelInfo The following table describes the
65. _SecureData object The structure is declared as follows typedef struct const SKB Byte plainl SKB Size plainl size const SKB Byte plain2 SKB Size plain2 size a SKB Sha256DerivationParameters The following table explains the properties Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 112 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description plainl Pointer to a buffer of bytes that should be prepended to the source SKB_SecureData object before calculating the SHA 256 hash value This property can be NULL in which case there will be no plain data prepended to the skB_SecureData Object plainl size Number of bytes in the plain1 buffer plain2 Pointer to a buffer of bytes that should be appended to the source SKB_SecureData Object before calculating the SHA 256 hash value This property can be NULL in which case there will be no plain data appended to the SKB SecureData object plain2 size Number of bytes in the plain2 buffer 7 10 13 SKB_Nist800108CounterCmacAes1 28Parameters This structure is used by the SKB_SecureData_Derive method if the SKB DERIVATION ALGORITHM NIST 800 108 COUNTER CMAC AES128 derivation algorithm is used see 87 9 17 The purpose of this structure is to specify the necessary input parameters For more information on
66. a Object from the input KB_SecureData Object by encrypting or decrypting it with another key For more information see 83 10 3 n SKB DERIVATION ALGORITHM SHA 1 Obtains a hash value from the referenced SKB _SecureData object by executing SHA 1 one or several times and stores the specified substring of bytes from the output as a new SKB SecureData Object For more information see 83 10 4 1 SKB DERIVATION ALGORITHM SHA 256 Obtains a SHA 256 hash value from a buffer that contains a SKB_SecureData Object prefixed and suffixed with plain data and stores the output as a New SKB_SecureData Object For more information see 83 10 4 2 SKB DERIVATION ALGORITHM SHA 384 Obtains a hash value from the referenced SKB_SecureData object by executing SHA 384 one time and stores the entire 48 byte output as a New SKB_SecureData Object For more information see 83 10 4 3 SKB DERIVATION ALGORITHM REVERSE BYTES Derives a new SKB_SecureData Object where the order of bytes is reversed You can use this derivation type to convert little endian data buffers to big endian and vice versa For more information see 83 10 5 SKB DERIVATION ALGORITHM NIST 800 108 COUNTER CMAC AES128 Derives a new KB_SecureData Object according to the key derivation function specified in the MST Special n Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 125 of 137 Copyrigh
67. able Consistent with 48 C F R 812 212 or 48 C F R 88227 7202 1 through 227 7202 4 as applicable the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U S Government end users a only as Commercial Items and b with only those rights as are granted to all other end users pursuant to the terms and conditions herein Unpublished rights reserved under the copyright laws of the United States Contact Information whiteCryption Corporation 920 Stewart Drive Suite 100 Sunnyvale California 94085 USA contact whitecryption com www whitecryption com Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 3 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide Table of Contents Ms O E AEEA NAAS 9 Ie I etka foe sees eee ant n e e ay e na RPE ty Mee OP A O er 9 MEIENI iso co aereainnmrn ae reine AA 9 AP Co ay sip a AA A A or NEE a Wer Geom ee ART We ORR NT eT es 0 A e anata eb cal eee n a le eb Sela Sette eh celeste aan NN 0 SE IGS TS OSI A A A e Ea AEE E 0 ASS Dat O a et eA a a a ar a ee R 1 AS A A O 1 A CU let a teeta anh aA tet MR het tale ast en Rs a see 2 A E inal deheRneat 3 AS Tamper Resistance ee E eae aE iv eat 3 1 10 Evaluation and roja Aa ero aarti Di Ee es canter 6 Mets A A A ot 6 13 Supported ECE AA O O
68. algorithms see 87 10 22 To generate a protected form of any of these parameters simply run Custom ECC Tool at command prompt and specify the type of the parameter and the input value The utility will write the protected binary form of the input parameter to the standard output Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 60 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 5 Utilities Custom ECC Tool generates only one parameter at a time To generate multiple parameters run the utility multiple times specifying a different parameter each time 5 1 2 Parameter Size and Value Restrictions The size of all input parameters must be between 150 and 521 bits and none of the parameters should have an equal or greater value than the order of the base point Note that SKB contains two run time instances of ECC One instance corresponds to 150 to 256 bit curves and the other corresponds to 257 to 521 bit curves The 150 to 256 bit ECC instance is faster than the 257 to 521 bit ECC instance If the size of the order of the base point is greater than 256 bits at run time SKB will use the 257 to 521 bit ECC instance which is slower 5 1 3 Running Custom ECC Tool Custom ECC Tool is located in the Libraries directory along with the precompiled SKB library You can run the utility by simply executing it at the com
69. an Tool The SKB implementation of DH key agreement algorithm operates on encrypted parameters Diffie Hellman Tool is used to generate the protected forms of these parameters which must then be provided to the SkB_PrimeDhParameters Structure see 87 10 23 when you use DH key agreement 5 2 1 Diffie Hellman Tool Overview The DH algorithm requires the following basic input parameters prime P generator G random value X By design these parameters are used in plain form but for increased security the SKB implementation requires that they are operated on in protected form To generate a protected form of any of these parameters simply run Diffie Hellman Tool at command prompt and specify the type of the parameter and the input value The utility will write the protected form of the input parameter either to the standard output or to a binary file depending on your choice Diffie Hellman Tool generates only one output value at a time To generate multiple values run the utility multiple times specifying a different parameter each time 5 2 2 Running Diffie Hellman Tool Diffie Hellman Tool is located in the Libraries directory along with the precompiled SKB library You can run the utility by simply executing it at the command line and passing several parameters to it The following is the pattern to be used to run Diffie Hellman Tool PrimeDHTool arguments The following table explains the input argum
70. and this application uses SKB algorithms that depend on random generation including but not limited to key generation key exporting ECDSA and ECDH you must call the skB_InitRng function before the first instance of random generation Otherwise SKB will return the SKB_ERROR_INVALID STATE 80008 error code The SKB_DestroyRng function must be called after the last instance of random generation We recommend calling the SkKB_InitRng function before the first invocation of the SKB Engine GetInstance function see 87 9 1 In a similar manner we recommend calling the SKB_DestroyRng function after the ast invocation of the SKB Engine Release function see 87 9 2 For details on these functions see the comments in the SkbPlatform h y ile Mutex handling The purpose of mutexes is to avoid the simultaneous use of common resources SKB uses mutex functions to ensure the correct use of threads The following functions are related to mutex handling KB Mutex Create KB Mutex LockAutoCreate KB Mutex Lock S S S S KB Mutex Unlock SKB Mutex Destroy Logging SKB uses the function SKB_LogMessage to write log messages to a particular output Logging is only used in the debug mode Debugging SKB calls the function skB_StopInDebugger when an exception occurs at run time It is only used in the debug mode For details on each function see the comments i
71. application is run under a debugger Rooting void SKB_Callback_Root This function is called by SKB when it detects that the application is run on a rooted Android device Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 15 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Attack Callback function Description Jailbreak void SKB_ Callback _Jailbreak This function is called by SKB when it detects that the application is run on a jailbroken iOS device Please note that you have to provide implementations for the above functions only if you specifically requested an SKB library that uses them 1 1 10 Evaluation and Production Packages Two editions of the SKB package are available to customers Edition Description Evaluation The evaluation package is free and is typically given to new customers who want to try out SKB before purchasing a license You should not use an evaluation edition in a production environment for two reasons Firstly you do not have the right to do so Secondly all evaluation packages have the same export key see 81 1 6 This means that all encrypted data that you export from SKB can be decrypted by other evaluation packages Additionally evaluation packages have an expiration date set Once the date is reached SKB will no longer be
72. arameters Structure which specifies whether the output should be encoded in little endian or big endian see 87 10 14 If the parameter is NULL the output will be encoded in little endian Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 96 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description Ifthe SKB DERIVATION ALGORITHM SHA AES algorithm is used this parameter must point to the SKB_ShaAesDerivationParameters Structure which provides the necessary input parameters see 87 10 15 For all other key derivation algorithms this parameter is not used and therefore should be NULL data Address of a pointer that will point to the new derived SKB_SecureData Object when this method is executed 7 9 18 SKB_SecureData_GetPublickey This method returns a public key that corresponds to the supplied private key Currently this method supports only ECC keys but not RSA The method is declared as follows SKB Result SKB SecureData_GetPublicKey const SKB SecureData self SKB DataFormat format const void parameters SKB Byte output SKB Size output size The following table explains the parameters Parameter Description self Pointer to the SKB_SecureData Object containing the private key From this key the public key w
73. arch for a string whitebox The string should not be present in the code If it is ensure you have completed the items in step 2 4 If the SKB package delivered to you has tamper resistance applied see 81 1 9 run the Binary Update Tool on the final built application as described in 85 4 2 2 Distributing a Protected Application SKB consists of a number of binary libraries and supporting files Some of these components are secure and can be safely included in the final protected application However some components expose Sensitive operations that can lead to key exposure and therefore should be considered insecure These components serve a specific purpose and are usually not required in the final deliverable that is delivered to end users The following table shows groups of safe and unsafe SKB components Safe components Unsafe components SKB library SecureKeyBox Key Export Too Platform Specific Library SkbPlat form Custom ECC Tool examples Diffie Hellman Tool sQLite library unit tests and speed tests Sensitive Operations Library InternalHelpers utilities SkbUtils LibTomCrypt and LibTomMath libraries only required by tests Components in the left hand column are self sufficient and can be considered safe Including these components in your application will not compromise the security provided by SKB Components in the right hand column however shou
74. ase SKB_Cipher self The parameter self is a pointer to the skB_Cipher object that should be released 7 9 25 SKB_KeyAgreement_GetPublickey This method creates a new public key that should be sent to the other party of the key agreement algorithm The method is declared as follows SKB_Result SKB K yAgreement GetPublicKey SKB KeyAgreement self SKB_Byte public key buffer SKB Size public_key buffer size The following table explains the parameters Parameter Description Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 102 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description self Pointer to the previously created SKB _KeyAgreement Object which contains all the necessary parameters public_key_buffer This parameter is either NULL or a pointer to the memory buffer where the public key will be stored If this parameter is NULL the method returns in _ size a number of bytes sufficient to hold the public key and returns SkB_SUCCESS public key buffer If this parameter points to a memory buffer it is not NULL and the buffer size public key buffer sizeis large enough to hold the public key the method stores the output there and sets public key buffer size to the exact number of bytes stored If the buffer is not large enough the me
75. ata Formats This is a reference chapter describing various data formats used in SKB 8 1 Export Data Format Data exported from SKB is a binary buffer that consists of a header and an encrypted content The header can provide valuable information especially if you are dealing with several SKB packages with different export keys or if you are employing the one way data upgrade deployment see 83 7 The following diagram shows the format of exported data mm HEADER up EXPORTED CONTENT CONTROL BYTES FORMAT VERSION KEY TYPE KEY SIZE KEY VERSION EXPORT KEY ID ENCRYPTED DATA Y x x gt RSS Fj a a ma cei haa ti a 4 BYTES 1 BYTE 4 BYTES i 4 BYTES gt 4 BYTES i 16 BYTES Export data format The following table explains the components of the header Component Description Control bytes Random bytes with specific properties that identify data exported by SKB Format version Version of the export format Currently it is always 02 Key type Type of the exported key The following values are used 00 identifies raw bytes for example an AES or DES key 01 identifies an ECC key 02 identifies an RSA key Key size Size of the exported key Key version Key version in the one way data upgrade scheme described in 83 7 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 131 of 137 Copyrig
76. ata in bytes data_type Type of data stored in the input buffer The available types are defined in the SKB _DataType enumeration see 87 11 1 Currently this method supports only the SKB_DATA TYPE BYTES data type Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 85 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description plain format Format how the plain data is stored in the input buffer The available formats are defined in the skB_DataFormat enumeration see 87 11 7 Currently this method supports only the SKB_DATA FORMAT RAW data type algorithm Algorithm to be used for encrypting the input data Available algorithms are defined in the SKB_CipherAlgorithm enumeration see 87 11 3 Currently this method supports only the following algorithms KB CIPHER ALGORITHM AES 128 ECB SKB CIPHER ALGORITHM AES 128 CBC ES 192 ECB Z KB CIPHER ALGORITH S S SKB CIPHER ALGORITHM S S KB CIPHER ALGORITHM AES 256 ECB Al AES 192 CBC Al SKB CIPHER ALGORITHM AES 256 CBC encryption parameters Pointer to a structure that provides additional parameters for the cipher Currently this parameter must always be NULL encryption key Pointer to the SK
77. ateEccPrivateFromPlain This function creates an SKB_SecureData Object from a plain ECC private key The function is declared as follows SKB Result SKB CreateEccPrivateFromPlain const SKB Engine engine const SKB Byte plain SKB Size plain size SKB SecureData data The following table explains the parameters Parameter Description engine Pointer to the pre initialized engine plain Pointer to the data buffer containing the ECC private key For information on the ECC key format see 87 11 7 dh The data must be provided in big endian encoding plain_size Size of the buffer in bytes data Address of a pointer to the SKB_SecureData that will contain the loaded key after this function is executed 4 1 2 4 SKB_CreatePlainFromEccPrivate This function derives a plain ECC private key from an skB_SecureData object The function is declared as follows Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 51 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries SKB_Result SKB CreatePlainFromEccPrivate const SKB SecureData data SKB Byte plain SKB Size plain size The following table explains the parameters Parameter Description data Pointer to the skB_SecureData from which the plain ECC private key must be created plain This pa
78. be derived from one skB_SecureData Object into another SKB_SecureData object The structure is declared as follows Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 115 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference typedef struct e unsigned int first E unsigned int size D SKB SliceDerivationParameters The following table explains the properties Property Description first Index of the first byte of the source SKB_SecureData Object where the derived range starts Bytes are numbered starting with 0 If you are using the SKB_DERIVATION ALGORITHM BLOCK SLICE algorithm the value must be a multiple of 16 size Number of bytes to derive starting with the byte with offset first If you are using the SKB_DERIVATION ALGORITHM BLOCK SLICE algorithm the value must be a multiple of 16 7 10 18 SKB_EccDomainParameters This structure defines domain parameters for a custom ECC curve and therefore should be employed only when the SKB_ECC_CURVE_CUSTOM Curve type of the SKB_EccCurve enumeration is used see 87 11 10 Currently custom ECC curves are supported only for the ECDSA ECDH and ECC key generation algorithms For all other cases this structure is not used The structure is declared as follows typedef struct
79. be selected output_size Size of the output in bytes which is the number of bytes copied from the input 7 10 10 SKB_CipherDerivationParameters This structure is used by the SKB_SecureData_Derive method if the SKB DERIVATION ALGORITHM CIPHER algorithm is used see 87 9 17 The purpose of this structure is to specify all the necessary parameters to execute the derivation The structure is declared as follows typedef struct SKB CipherAlgorithm cipher algorithm SKB CipherDirection cipher direction unsigned int cipher flags const void cipher parameters const SKB SecureData cipher key const SKB Byte iv Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 110 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference E SKB Size iv_ size SKB _CipherDerivationParameters The following table explains the properties Property Description cipher_algorithm Cipher algorithm to be executed on the input data This is a reference to the SKB_CipherAlgorithm enumeration see 87 11 3 Currently the SKB_DERIVATION ALGORITHM CIPHER algorithm supports only the following ciphers SKB CIPHER ALGORITHM AES 128 ECB SKB CIPHER ALGORITHM AES 128 CBC SKB CIPHER ALGORITHM AES 192 ECB SKB CIPHER ALGORITHM AES 192
80. ble verification algorithms are tureAlgorithm enumeration see 87 11 4 ms are supported for verification ES 128 CMAC MAC SHA1 MAC SHA256 MAC SHA384 MAC _SHA512 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 109 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description key Pointer to the SKB_SecureData object which contains the verification key This key must not be released before the skB_Transform Object that uses it is released signature Pointer to the data buffer containing the signature to be verified signature size Size of the signature in bytes 7 10 9 SKB_SelectBytesDerivationParameters This structure is used by the SKB_SecureData_Derive method if the SKB DERIVATION ALGORITHM SELECT BYTES algorithm is used see 87 9 1 7 It specifies whether odd or even bytes should be copied from the input and how many bytes to copy The structure is declared as follows typedef struct SKB_SelectBytesDerivationVariant variant E unsigned int output size SKB SelectBytesDerivationParameters The following table explains the properties Property Description variant Reference to a value of the skB_SelectBytesDerivationVariant enumeration see 87 11 14 which tells whether odd or even bytes should
81. crypts the actual contents of the referenced secure data object not its binary representation with the embedded export key see 81 1 6 The export key of the exporting instance must match the export key of the importing instance To export a key call the SKB_SecureData_Export method specify the secure data object to be exported and provide a memory buffer where the exported data should be written see 87 9 15 For information on the format used to store exported keys see 88 1 3 6 Importing Keys If you have a protected buffer of data containing a key previously exported from SKB or obtained using Key Export Tool or Sensitive Operations Library you can import it into SKB The export key of the exporting instance must match the export key of the importing instance To import a key call the SKB _Engine CreateDataFromExported method and provide the exported data buffer see 87 9 6 This method will create a new secure data object containing the imported key 3 7 Upgrading Exported Keys SKB supports one way data upgrade deployments This means that you have an option to request multiple SKB packages where each package is assigned a version number starting with version 1 These packages are configured so that an SKB instance with a greater version number can upgrade and import keys exported by all SKB instances with a smaller version number but not the other way round The practical application of thi
82. current SKB package has expired SKB ERROR KEY CACHE FAILED 80102 A key cache operation failed Typically this occurs when the key cache database is not available or is write protected VERSION SKB_ERROR_INVALID_EXPORT_KEY 80103 Either you are trying to upgrade a key whose version number is equal or greater than that of the current SKB instance See 83 7 or you are trying to import a key whose version is not equal to that of the current SKB instance SKB_ERROR_INVALID EXPORT KEY 80104 The export key of the current SKB instance does not match the export key that was used for exporting the data that you are trying to import or upgrade 7 5 Object Lifecycle To avoid exceptions and correctly release memory you have to follow certain rules regarding the lifecycle of SKB objects All SKB objects must be released when they are no longer needed by calling the corresponding release methods SKB Engine See 87 8 1 is the first SKB object to be created and the last one to be released All other objects created via the SKB _ Engine Object must be released before it SKB SecureData See 87 8 2 cannot be released while it is being used as a key in other objects such aS SKB Cipher SKB Transform and SKB KeyAgreement 7 6 Restrictions of Multithreading As a general rule SKB methods and objects are not synchroni
83. d as follows SKB Result SKB SecureData_ Export const SKB SecureData self SKB ExportTarget target const void target parameters SKB Byte buffer SKB Size buffer size The following table explains the parameters Parameter Description self Pointer to the skB_SecureData Object to be exported target Export type to be used Available export types are defined in the SKB _ExportTarget enumeration see 87 11 9 target_parameters Currently this parameter is not used Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 92 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description buffer This parameter is either NULL or a pointer to the memory buffer where the exported data is to be written If this parameter is NULL the method simply returns in buffer _size a number of bytes that would be sufficient to hold the exported data and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size is large enough to hold the exported data the method stores the exported data there sets buffer size to the exact number of bytes stored and returns SkKB_SUCCESS If the buffer is not large enough then the method sets buffer size to a number of bytes that would be sufficient and returns SKB_ERROR BUFFER TOO SMAL
84. d how many bytes should be derived from the final hash value as a new SKB SecureData object The structure is declared as follows typedef struct unsigned int round_count E unsigned int output size _ SKB_ShalDerivationParameters The following table explains the properties Property Description round_count How many times the SHA 1 algorithm should be executed in a sequence O is also a valid value In this case the SHA 1 value will not be calculated the derived SKB_SecureData Object will simply contain the first output_size bytes of the source skB_SecureData object output_size Number of bytes to be derived from the final output of the SHA 1 algorithm For example if output_size is 4 the first four bytes of the hash value will be derived as a New SKB _SecureData Object The standard size of the SHA 1 output is 20 bytes Hence output_size Cannot exceed 20 7 10 12 SKB_Sha256DerivationParameters This structure is used by the SkKB_SecureData_Derive method see 87 9 17 if the SKB DERIVATION ALGORITHM SHA 256 algorithm is used see 83 10 4 2 The purpose of this structure is to provide the two plain data buffers that should be prepended and appended to the source SKB_SecureData Object before the SHA 256 algorithm is executed This structure may be omitted provided as NULL In that case SKB will assume that there are no plain data buffers prepended or appended to the source skB
85. dSecureData cenas 99 AO 22 SKB TAN ONE OU asian 99 79 23 wd O18 fd ON et SA lee rc ter cee 00 EEES A A O a alate aaa ae a ANS 02 TIL RU A dd ad 02 29 20 SKB KeyAgreement Com UI aii 03 FO DF SI ES AS A EE ET E E Masha E E deuea tag aetese 04 ND SAU eC GE IRS 2c acc E EAE aaan ens cnet aiaeaaenn TEE 04 ae a A A E 05 A SKB ENGINE Ona BO RS A Ne a see tt eh ad re ce eae late ud eee At ace a acta 05 FAO Re AeA DIENEN aIo e E E AE tection meet tcl 06 PAO e hane a e aei 07 as SE A E A A AE E 07 AS o A atl gte west 07 TOF SKB SienTransformParameterS AA O A a a Ste Bas 08 7 10 8 SKB Ve RIN Pan STOR PAV ARVO UCN Sterol cea so tan othe toa aust seat cd ualsie uece oe Laelia cause tans dncealinae 09 71009 SKB SelectBytesDerivationP arameo 0 TAO Ella er A A TORE Er 0 10 SKB ShalDerivationPara Mete Su ce eee o coa ad e ra dee do o dedos e ba 1 FAOAZSKB Sha256DerivatlonPara Meter ennan a n E ovens totes E ketenes 2 7 10 13 SKB_Nist800108CounterCmacAes1 28ParaMe tel oo cececececceseccececcesseseseessssecteecteestesentees 3 7 10 14 SKB_RawBytesFromeEccPrivateDerivatiONParaMetels sesine 4 7 10 15 SKB_ShaAesDerivationParameters ccccccccecceccccccsceescecsccesscescesecseesecesscseeseesteeseeseseentecseesevstenseess 4 7 10 16 SKB_OmaDrmKdf2DerivationParamMeterS ccccccccccccccccccssceccesccscesscesecsecseeseeesecseeeenteesseseestensess 5 7 10 17 SKB SliceDerivatioNParaMete srs cceccccccccccsecceccessecscesccsccsscescesecsecsecescessesecseeeseeseseeatec
86. data Pointer to the buffer of data to be appended to the skB_Transform Object data_size Size of the data buffer in bytes 7 9 21 SKB_Transform_AddSecureData This method appends the contents of an SKB_SecureData Object to a previously created SKB Transform Object Data must be added to an SKB_Transform Object before the actual transform algorithm digest signing or verifying can be executed A This method cannot be used for the SKB SIGNATURE ALGORITHM RSA and SKB SIGNATURE ALGORITHM ECDSA Signing algorithms because they can operate only on plain input The method is declared as follows SKB_Result SKB Transform _AddSecureData SKB_Transform self const SKB SecureData data The following table explains the parameters Parameter Description selt Pointer to the previously created SKB Transform Object data Pointer to the SKB_SecureData Object whose contents must be appended to the SKB Transform object 7 9 22 SKB_Transform_GetOutput This method executes a transform algorithm on a particular SKB_Transform Object The transform algorithm is specified during the creation of the SKB_Transform object and the input data is then provided using the SKB Transform AddBytes and SKB Transform AddSecureData methods The SKB Transform GetOutput method is declared as follows SKB_Result SKB Transform GetOutput SKB Transform self SKB Byte output SKB Size output_siz
87. de this library from a client application that is exposed to attacks see 1 1 7 If importing of plain data is disabled in SKB the SKB _ Engine CreateDataFromWrapped method will not allow loading plain keys see 87 9 5 This however will not affect how Sensitive Operations Library works ote Sensitive Operations Library is required to run unit tests and Key Export Tool 4 1 2 Library Functions Sensitive Operations Library has its own interface defined in the Include SkbInternalHelpers h file This section describes the functions declared in this interface Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 49 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries 4 1 2 1 SKB_CreateRawBytesFromPlain This function creates an SKB_SecureData object from a plain data buffer The function is declared as follows SKB Result SKB CreateRawBytesFromPlain const SKB Engine engine l const SKB Byte plain SKB Size plain size SKB SecureData data The following table explains the parameters Parameter Description engine Pointer to the pre initialized engine plain Pointer to the data buffer containing the plain key plain_size Size of the buffer in bytes data Address of a pointer to the SKB_SecureData that will contain the loaded key after this function is executed 4 1 2 2 S
88. disabled in SKB To directly load a plain key as a secure data object call the SKB Engine CreateDataFromWrapped method see 87 9 5 and specify the unwrapping algorithm SKB_ CIPHER ALGORITHM NULL In this case the unwrapping key and parameters do not have to be provided This operation will work only if importing of plain keys is enabled in SKB 3 3 Wrapping Keys A cryptographic key that is stored within a secure data object can be encrypted with another key This process is called wrapping The wrapped key can then be passed to any other cryptographic library not necessarily SKB where it can be unwrapped and used Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 34 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations SECURE KEY BOX or WRAPPING KEY KEY WRAPPING UNWRAPPED KEY WRAPPED KEY Wrapping a key Wrapping is not the same operation as regular encryption because regular encryption requires plain data as input see 83 11 1 The wrapping operation takes a secure data object as an input and therefore the wrapped key is never exposed in plain form Wrapping is also not the same operation as secure data exporting because exporting encrypts keys with a hidden export key that is unique to the particular SKB instance see 83 5 Wrapping allows using any arbitrary key as a wrappin
89. e The following table explains the parameters Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 99 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description self Pointer to the SKB_Transform object on which the transform algorithm must be executed output This parameter is either NULL or a pointer to the memory buffer where the transform output will be stored If this parameter is NULL the method returns in output_size a number of bytes sufficient to hold the output and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size output_size is large enough to hold the output the method stores the output there and sets output_size to the exact number of bytes stored If the buffer is not large enough then the method sets output_size to anumber of bytes that would be sufficient and returns skB_ERROR_BUFFER_TOO_ SMALL In the case of the SKB_TRANSFORM TYPE VERIFY transform the output will be a single byte with the value 1 if the signature is verified and 0 if it is not In the case of the ECDSA signature algorithm the output will be a pointer to a buffer with a format described in 88 8 output_size Pointer to a variable that holds the size of the memory buffer in bytes where the transform outp
90. e 87 9 5 the wrapped buffer is XOR ed with the unwrapping key Ah in both ca ses the two XOR ed buffers must be of equal size Copyright O 2000 2015 whiteCryption Corporation All rights reserved Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Page 122 of 137 Secure Key Box User Guide 7 11 4 SKB_SignatureAlgorithm This enumeration specifies the possible signing and verifying algorithms for the SKB _Transform object The enumeration is defin 7 API Reference type ed as follows def enum SKB SIGNATURE ALGORITHM AES 128 CMAC SKB SIGNATURE ALGORITHM HMAC SHA1 SKB SIGNATURE ALGORITHM HMAC SHA256 SKB SIGNATURE ALGORITHM HMAC SHA384 SKB SIGNATURE ALGORITHM HMAC SHA512 SKB SIGNATURE ALGORITHM RSA SKB SIGNATURE ALGORITHM RSA SHAl SKB SIGNATURE ALGORITHM RSA SHA256 SKB SIGNATURE ALGORITHM ECDSA SKB SIGNATURE ALGORITHM ECDSA SHAl SKB SIGNATURE ALGORITHM ECDSA SHA256 SKB SIGNATURE ALGORITHM RSA PSS SHAl SKB SIGNATURE ALGORITHM RSA PSS SHA1 EX SKB SIGNATURE ALGORITHM RSA PSS SHA256 SKB SIGNATURE ALGORITHM RSA PSS SHA256 EX 3 SKB SignatureAlgorithm ins the values The following table expla Value Description SKB SIGNATURE ALGORITHM AES 128 CMA
91. e ECB or CBC mode this parameter must be a multiple of the cipher block size which is 16 bytes For the RSA cipher this parameter must be the size of the entire encrypted message but no more than the length of the RSA key out_buffer This parameter is either NULL or a pointer to the memory buffer where the output is to be stored If this parameter is NULL the call is simply a request to find out how many bytes are needed for the cipher output so the method returns in out_buffer size a number indicating how many bytes would be sufficient to hold the output and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size out buffer size is large enough to hold the cipher output the method places the output there and sets out_buffer_ size to the exact number of bytes stored If the buffer is not large enough then the method sets out_buffer_size to a number of bytes that would be sufficient and returns SKB_ERROR_BUFFER_TOO SMALL For the ElGamal ECC cipher the output buffer contains the X coordinate of the decrypted point in big endian notation It is caller s responsibility to extract the decrypted message from this output according to the way the message was encrypted SKB supports in place encryption and decryption which means that the out_buffer parameter may be the same as the in buffer parameter Then the output of this method will
92. e obtained using either Key Export Tool see 85 3 or Sensitive Operations Library see 84 1 A Key Export Tool and Sensitive Operations Library must never be delivered with the final protected application see 82 2 ote The same protected form is used when SKB exports a key see 83 5 3 Key agreement SKB exchanges public keys with another party and then 83 15 internally generates a secret key 4 Key generation SKB internally generates a new key 83 8 1 1 8 Diversification A significant feature of SKB is code diversification It means that each customer receives one or several packages whose binary code differs from other packages SKB achieves this by generating unique representations of white box algorithms individually for each customer Although the API provided by each SKB instance is the same the way the operations are physically implemented in the program code varies This feature improves security For example if an adversary manages to compromise a particular system that uses SKB systems of other customers would not be directly affected 1 1 9 Tamper Resistance Tamper resistance is an optional feature that you can request for the SKB library delivered to you Tamper resistance guards the library code against analysis and modification Although this feature slightly reduces performance of the protected application it significantly increases security against
93. ebug Bridge ADB tool which is included in the Android SDK The following is a sample ADB script that copies compiled SKB examples to the data local directory on the connected Android device this directory always allows executing files makes them executable and runs them adb shell rm data local SkbExamples adb push SkbExamples data local adb shell chmod 777 data local SkbExamples adb shell cd data local amp amp SkbExamples 2 3 5 Building for OS X and iOS Xcode is used to build SKB examples tests and Platform Specific Library This section describes how to set up the build environment and compile the source code Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 29 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 2 Building Applications Protected by SKB 2 3 5 1 Prerequisites To compile the source files you will need a computer with the OS X system that has Xcode installed For information on the supported Xcode version see 81 4 2 3 5 2 Compiling To compile the source files proceed as follows 1 Goto the Build Targets your_target directory Open the Xcode project 2 3 Select the required scheme 4 Compile the project The location where compiled files are placed depends on the system System Location of compiled files OS X One of
94. ed Secure Key Box User Guide 5 Utilities 5 Utilities This chapter describes the command line utilities provided together with the SKB package The following utilities are available Utility Description Section Custom ECC Tool Generates protected forms of ECC domain parameters which 85 1 are used for defining custom curves Diffie Hellman Tool Generates protected forms of parameters for the DH key 85 2 agreement algorithm Key Export Tool Creates a white box protected exported form of an 85 3 SKB SecureData object from plain input data and upgrades previously exported data Binary Update Tool Adjusts the final application executable if the tamper resistant 85 4 SKB library is used 5 1 Custom ECC Tool Custom ECC Tool generates protected forms of ECC domain parameters which are used for defining custom curves The generated protected forms of custom ECC domain parameters must then be specified in the SKB_EccDomainParameters Structure see 87 10 18 when you use custom ECC curves 5 1 1 Custom ECC Tool Overview Custom ECC Tool can generate protected forms for the following ECC domain parameters constant a in the curve equation prime p of the elliptic curve order n of the base point X coordinate of the base point Y coordinate of the base point fixed random value to be passed to the ECDSA and ECDH
95. ed see 81 1 9 you have to run the final built application executable through a binary update process to correctly adjust the embedded integrity protection checksums Adjustment of the binary code is done using a command line utility called Binary Update Tool which is included in the SKB package Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 65 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 5 Utilities Alf the binary update process is not executed on a tamper resistant SKB library the built application will crash at run time 5 4 1 Binary Update Tool Overview The binary code must be adjusted using the Binary Update Tool after every build of the final application As an input the Binary Update Tool requires the binary executable of the protected application and the target nwdb file that is delivered together with SKB 0 TAMPER RESISTANT BUILD SYSTEM APP SOURCE SKB LIBRARY PP BINARY 1101101 l UPDATE 1101010 TOOL 1000111 APP BINARY UPDATED APP BINARY Building an application that uses a tamper resistant SKB library os Xand iOS applications must be re signed after running the Binary Update Tool because the binary footprint will be modified You can perform signing using the codesign tool from the command line as described here https developer apple com library mac documentation Darwin
96. efined as follows typedef enum SKB DATA TYPE BYTES SKB DATA TYPE RSA PRIVATE KEY SKB DATA TYPE ECC PRIVATE KEY 0 SKB DataType As shown an SKB_SecureData object can contain raw bytes for example a DES or AES key an RSA private key or an ECC private key 7 11 2 SKB_DigestAlgorithm This enumeration specifies the available digest algorithms and is defined as follows typedef enum SKB DIGEST ALGORITHM SHA1 SKB DIGEST ALGORITHM SHA256 SKB DIGEST ALGORITHM SHA384 SKB DIGEST ALGORITHM SHA512 3 SKB DigestAlgorithm 7 11 3 SKB_CipherAlgorithm This enumeration specifies cryptographic algorithms that are used for encrypting and decrypting data Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 120 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference The enumeration is defined as follows typedef enum SKB CIPHER ALGORITHM NULL SKB CIPHER ALGORITHM AES 128 ECB SKB CIPHER ALGORITHM AES 128 CBC SKB CIPHER ALGORITHM AES 128 CTR SKB CIPHER ALGORITHM RSA SKB CIPHER ALGORITHM RSA 1 5 SKB CIPHER ALGORITHM RSA OAEP SKB CIPHER ALGORITHM ECC ELGAMAL SKB CIPHER
97. ence The following table explains the parameters Parameter Description self Pointer to the pre initialized engine transform type Transform type to be created Available transform types are defined in the SKB _TransformType enumeration see 87 11 8 transform parameters Pointer to a structure that provides the necessary parameters for the transform For different transform types a different structure must be provided For the SKB_TRANSFORM TYPE DIGEST transform this parameter must point to the SKB _DigestTransformParameters structure see 87 10 5 For the SKB_TRANSFORM TYPE SIGN transform this parameter must point to one of the following structures f one of the following algorithms is to be used this parameter must point to the SKB _SignTransformParametersEx structure see 87 10 7 KB SIGNATURE ALGORITHM RSA PSS SHAl EX KB SIGNATURE ALGORITHM RSA PSS SHA256 EX KB SIGNATURE ALGORITHM ECDSA_SHA1 S S SKB SIGNATURE ALGORITHM ECDSA S S KB SIGNATURE ALGORITHM ECDSA SHA256 For all other algorithms this parameter must point to the SKB_SignTransformParameters Structure see 87 10 6 For the SKB_TRANSFORM TYPE VERIFY transform this parameter must point to the SKB _VerifyTransformParameters structure see 7 10 8 transform Address of a pointer to the SKB_Transform object that
98. ents Argument Description s value Maximum bit length of P This argument is mandatory Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 62 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 5 Utilities Argument Description p value Prime P as an unsigned integer If this parameter is specified the generator G argument g must also be provided The output will be a single protected buffer containing both the P and G parameters The greatest common divisor of P and G must be 1 g value Generator G as an unsigned integer If this parameter is specified the prime P argument p must also be provided The output will be a single protected buffer containing both the P and G parameters The value of this parameter must be less than P and the greatest common divisor of P and G must be 1 x value Random value X as an unsigned integer The output of this parameter can be used to provide a fixed random value to the DH algorithm as described in 87 10 23 If this parameter is provided the parameters p and g must not be supplied The output will be a buffer containing the protected random value output_format value Specifies the format of the output Possible values are the following binary Output is a binary file containing a buffer of bytes s
99. erates a random initialization vector The structure is declared as follows typedef struct const SKB Byte iv _ SKB AesWrapParameters iv s a pointer to the byte buffer containing the initialization vector 7 10 20 SKB_AesUnwrapParameters A pointer to this structure can be passed to the SKB Engine CreateDataFromWrapped method see 87 9 5 in case the CBC mode of the AES algorithm is used This structure specifies the CBC padding type to be used For information on available CBC padding types see 88 2 3 The structure is declared as follows typedef struct l SKB CbcPadding padding _ SKB_AesUnwrapParameters padding specifies the CBC padding type to be used The available padding types are defined in the SKB_CbcPadding enumeration see 87 11 13 7 10 21 SKB_RsaPssParameters This structure provides additional parameters when the SKB SIGNATURE ALGORITHM RSA PSS SHAl EX Or SKB SIGNATURE ALGORITHM RSA PSS SHA256 EX Signature algorithm is used Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 117 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference The structure is declared as follows _ typedef struct const SKB Byte salt E SKB Size salt length _ SKB_RsaPssParameters The following table describes the properties Property Description
100. es the SKB_ EccParame see 87 10 22 SKB SIGNATURE ALGORITHM _ SKB SIGNATURE ALGORITHM _ SKB SIGNATURE ALGORITHM _ If the skB_SIGNATURE_ALGORIT SKB SIGNATURE ALGORITHM _ this pointer must point to the s the salt and sa t length see 87 ECDSA ECDSA SHA 1 ECDSA SHA256 HM RSA PSS SHA1 ECC curve type to be used EX Or RSA_PSS_SHA256_Ex Signature algorithm is used KB _RsaPssParameters Structure which specifies 0 21 7 10 8 SKB_VerifyTransformParameters This structure is used by the sKB SKB TRANSFORM TYPE V Engine CreateTransform method if the ERIFY transform is used see 87 9 9 The purpose of this structure is to specify the verification algorithm verification key and the signature The structure is declared as follows typedef struct SKB SignatureAlgorithm const SKB SecureData const SKB Byte E SKB Size 3 SKB VerifyTransformParameters algorithm key signature signature size The following table explains the properties Property Description algorithm S S 5 S n defined inthe s KB SIGNAT KB SIGNAT KB SIGNAT KB SIGNAT KB SIGNAT KB Signa Only the following algorith RIT RIT RIT RIT URE ALGO URE ALGO URE ALGO URE ALGO URE ALGO RIT Verification algorithm to be used The availa
101. export key see 81 1 6 regardless of the device it is run on In some cases you may want to bind exported keys to a specific device so that they cannot be imported on any other device SKB provides device binding via the method SKB _ Engine SetDevicela See 87 9 3 which can be called after initializing the engine By calling this method you set the device ID which is a byte array of arbitrary length typically derived from the hardware details or other environment specific parameters This ID is combined with SKB export key to create a unique format for exported keys The SKB instance that imports keys must have the same export key and same device ID set as the instance that exports the keys When the device ID is no longer needed you can restore the default export format that depends only on the export key 3 17 Decrypting Encrypted PDF Documents SKB provides several functions for safely decrypting contents of encrypted PDF files without revealing the user password and the derived encryption key A typical PDF decryption process involves the following steps 1 Obtain a user password 2 Authenticate the user password to verify that the password is valid 3 Derive the encryption key from the user password which is then used in the actual decryption process 4 Decrypt parts of encrypted PDF objects with the derived encryption key For detailed instructions on how to perform PDF decryption us
102. ey Format tor the Triple DES CIPRE a teste e e e 34 8 4 Mp t Buffer fortheElsamal ECC CMS e etten daa 35 ea A AEE N E E EN E E E E E E E A A STR ee 25 SA A A A O NA 36 Sd AES O Pilate E A tal 36 O MEE o tae saeco coe caution fan E EA gash sone ream aodau neal ee 37 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 8 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction 1 Introduction This chapter provides a general overview of the Secure Key Box SKB technology 1 1 General Concepts This section describes the general concepts that you should know before working with SKB 1 1 1 What Is SKB SKB is a library that provides a set of high level classes and methods for working with common cryptographic algorithms The library s white box implementation hides and protects cryptographic keys In SKB keys are encrypted and cryptographic algorithms operate directly with encrypted keys SKB exposes an API that provides access to a set of functions which the calling application uses to implement various cryptographic operations A UNPROTECTED CODE AND DATA SKB API SECURE KEY BOX CRYPTOGRAPHIC ALGORITHMS CRYPTOGRAPHIC KEYS SKB overview Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 9 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reser
103. g directories depending on your needs Build Targets all microsoft winrt vs2012 Visual Studio 2012 solution for Windows Runtime Build Targets all microsoft winrt vs2013 Visual Studio 2013 solution for Windows Runtime Build Targets arm windows phone vs2012 Visual Studio 2012 solution for Windows Phone 8 0 Build Targets arm windows phone vs2013 Visual Studio 2013 solution for Windows Phone 8 1 The solution contains the following specific projects Project Description SkbExamplesApp Runs SKB examples as a Microsoft design language app SkbExamplesUnitTest Runs SKB examples as a Visual Studio unit test SkbSpeedTestsApp Runs SKB speed tests as a Microsoft design language app SkbSpeedTestsUnitTest Runs SKB speed tests as Visual Studio unit tests SkbTestSuiteUnitTest Runs SKB unit tests as Visual Studio unit tests 2 Compile the solution 2 3 3 Building for Linux The SCons build tool is used to build SKB examples tests and Platform Specific Library This section describes how to set up the build environment and compile the source code 2 3 3 1 Prerequisites The following prerequisites must be met before building the source files 1 Download and install SCons 2 3 0 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 27 0f 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights rese
104. g key provided that it is supported by the wrapping algorithm To wrap a key contained within a secure data object call the SkKB_SecureData_Wrap method specify the secure data object specify the wrapping algorithm and key and provide the necessary parameters see 87 9 16 3 4 Wrapping Plain Data In some cases you may want to take a plain input buffer encrypt it with a key and store the output as a new secure data object For example this operation is suitable for deriving new keys from some input seed and a specific key To wrap plain data call the SkKB_Engine WrapDataFromPlain method see 87 9 7 The input is plain data but the encryption key and the output of the method are secure data objects 3 5 Exporting Keys SKB operates on keys in memory If you need some key to be persistent or if you want it to be available to multiple engines you can request SKB to provide a protected form of the key which can then be securely exported and stored Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 35 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations When the exported key is needed again later you can request SKB to import it as a new secure data object similar to the one whose data was initially exported For information on importing exported keys see 83 6 When SKB is asked to export a key it en
105. ghts reserved Secure Key Box User Guide 7 API Reference Property Description random_value Property that allows you to provide a fixed random value to the ECDSA and ECDH algorithms Typically the value of this property should be NULL in which case SKB uses an internally generated random value However you can also pass a fixed number to be used as the random value The fixed number must be passed as an integer array containing the value in protected form To obtain the protected form of a fixed random value use Custom ECC Tool as described in 85 1 7 10 23 SKB_PrimeDhParameters This structure is required by the SKB Engine CreateKeyAgreement method when the classical DH algorithm SKB_KEY AGREEMENT ALGORITHM PRIME DH is selected The structure supplies parameters necessary to execute the DH key agreement operation The structure is declared as follows typedef struct SKB_PrimeDhLength length const SKB Byte data const unsigned int random value E SKB PrimeDhParameters The following table describes the properties Property Description length Maximum bit length of the DH prime P The available values are defined in the SKB_PrimeDhLength enumeration see 87 11 12 data Pointer to an integer array containing a combination of the prime P and generator G in protected form to be used by the DH algorithm To obtain this protected data buffer u
106. gorithms are chosen Optionally the R and V values can both be set to 4 but then the following additional rules must be met All crypt filters in the crypt filter dictionary must use AFSV2 as the value for the CFM parameter and 76for the Length parameter Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 68 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 6 Decrypting PDF Files The EncryptMetadata parameter in the encryption dictionary must be absent or set to true Note PDF versions 1 5 and earlier use RC4 for content decryption PDF versions above 1 7 use AES 256 These encryption algorithms are currently not supported by SKB 6 3 Decrypting a PDF Document Using SKB SKB provides the necessary algorithms to perform the following typical PDF decryption process 1 Obtain the user password in secure format To ensure security SKB requires that the user password is delivered as an SKB_SecureData object containing the password as raw bytes data type is SKB_DATA TYPE BYTES It is up to you to decide how to import the user password as an SKB_SecureData Object For information on SKB_SecureData Objects and how they can be obtained see 87 8 2 2 Authenticate the user password using the skB_Pdf AuthenticateUserPassword function see 56 3 1 This algorithm verifies that the user password can actually decrypt the doc
107. greementAlgorithm This enumeration specifies the available key agreement algorithms used by the SKB Engine CreateKeyAgreement method to create SKB KeyAgreement objects see 87 9 11 The enumeration is defined as follows typedef enum SKB KEY AGREEMENT ALGORITHM ECDH E SKB KEY AGREEMENT ALGORITHM PRIME DH 3 SKB KeyAgreementAlgorithm The following table explains the values Value Description SKB KEY AGREEMENT ALCGORTIHM gt ECDH Elliptic curve Diffie Hellman SKB_KEY_AGREEMENT_ALGORITHM_PRIME_DH Classical Diffie Hellman with protected prime P and generator G 7 11 12 SKB_PrimeDhLength This enumeration specifies the available maximum bit lengths of prime P for the classical DH key agreement algorithm The values of this enumeration are referenced by the length parameter of the SKB _PrimeDhParameters Structure see 87 10 23 The enumeration is defined as follows typedef enum SKB PRIME DH LENGTH 1024 SKB PrimeDhLength The value SKB PRIME DH LENGTH 1024 specifies that the maximum bit length of prime P is 1024 bits 7 11 13 SKB_CbcPadding This enumeration specifies the CBC mode types that can be referenced by the SKB AesUnwrapParameters Structure see 87 10 20 The enumeration is defined as follows typedef enum SKB_CBC_ PADDING TYPE NONE SKB CBC PADDING TYPE XMLENC S
108. her the output should be encoded in little endian or big endian For more information on this derivation algorithm see 83 10 8 The structure is declared as follows typedef struct unsigned int derivation flags SKB RawBytesFromEccPrivateDerivationParameters If derivation flags includes the SKB DERIVATION FLAG OUTPUT _IN BIG ENDIAN flag the output will be encoded in big endian Otherwise the output will be encoded in little endian 7 10 15 SKB_ShaAesDerivationParameters This structure is used by the SKB_SecureData_Derive method if the SKB DERIVATION ALGORITHM SHA AES derivation algorithm is used see 87 9 17 The purpose of this structure is to specify the necessary input parameters For more information on this derivation algorithm see 83 10 10 The structure is declared as follows typedef struct const SKB SecureData secure p const SKB Byte plain 1 SKB Size plain 1 size const SKB Byte plain 2 SKB ShaAesDerivationParameters The following table explains the properties Property Description secure p Pointer to the SKB_SecureData object containing the secure_p value Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 114 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description plain_1 Pointer to the plai
109. herwise 6 3 2 SKB_Pdf_ComputeEncryptionKey This function derives the encryption key from the user password The function is declared as follows SKB_Result SKB_Pdf ComputeEncryptionKey const SKB SecureData password const SKB Byte Ov SKB Size o size Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 70 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 6 Decrypting PDF Files int Pp const SKB Byte file id SKB Size file id size SKB SecureData encryption key The following table describes the parameters Parameter Description password Pointer to an SKB_SecureData object containing the user password 2 Pointer to the value of parameter O in the encryption dictionary of the PDF file o_size Size of the o value p Value of parameter P in the encryption dictionary of the PDF file file_id Pointer to the first element of the file identifier array This array is the value of the ID entry in the document s trailer dictionary file_id_size Size of the file id value encryption_key Address of a pointer to the SKB_SecureData that will contain the derived encryption key after this function is executed 6 3 3 SKB_Pdf_CreateDecryptionContext This function prepares a PDF decryption context object that is later used in the SKB Pdf DecryptionCon
110. hm creates a hash value of a buffer that contains three parts in the following sequence 1 plain data of arbitrary size 2 secure data object key 3 plain data of arbitrary size The output is stored as a new secure data object which can serve as a new key To create a new key using this SHA 256 derivation call the skB_SecureData Derive method select the SKB DERIVATION ALGORITHM SHA 256 algorithm and specify the plain prefix and suffix buffers see 87 9 17 This operation can only be performed with secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 40 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations 3 10 4 3 SHA 384 Derivation The SHA 384 derivation algorithm applies SHA 384 to the input secure data object key and stores the output as a new secure data object key Unlike the SHA 1 derivation algorithm this operation is executed only once and the entire 48 byte hash value is returned as an output To create a new key as a SHA 384 hash value of another key call the skB_SecureData_Derive method and select the SKB_DERIVATION ALGORITHM SHA 384 algorithm see 87 9 17 This operation can only be performed on secure data objects that contain raw bytes for example
111. hnologies Corporation All rights reserved Secure Key Box User Guide 8 Data Formats SKB ECC CURVE _SECP_R1_160 20 bytes SKB ECC CURVE NIST 192 24 bytes SKB ECC CURVE NIST 224 28 bytes SKB ECC CURVE NIST 256 32 bytes SKB ECC CURVE NIST 384 48 bytes SKB ECC CURVE NIST 521 66 bytes SKB ECC CURVE CUSTOM Specified bit length of the prime domain parameter plus 7 divided by 8 8 6 Private ECC Key SKB stores private ECC keys using the following format this corresponds to the SKB DATA FORMAT ECC _ BINARY value of the SKB _DataFormat Structure 4 BYTES gt N 7 8 BYTES gt ECC private key format N is the bit length of the ECC curve X is an X coordinate containing the ECC key Both parameters are encoded in big endian 8 7 AES Wrapped Private ECC Key If you are unwrapping an AES wrapped ECC private key the input buffer to the unwrapping algorithm must have the following format all data must be encoded in big endian ENCRYPTED ECC PRIVATE KEY E R AES WRAPPED DATA AES wrapped ECC private key The first 4 bytes must contain the number N in plain which is the bit length of the ECC curve used The rest of the buffer is AES wrapped data containing the wrapped ECC private key and possibly some padding bytes The AES wrapped portion of the buffer must be formatted as described in 88 2 Copyright 2000 2
112. ht 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 8 Data Formats Component Description Export key ID Identifier of the export key that was used in exporting the data An SKB instance that needs to import this data has to have the same export key with the same identifier You can find out the identifier of the export key of the current SKB instance using one of the following approaches Look into the export id file delivered with the SKB package see 81 5 Callthe SKB Engine GetInfo method and read the value of the export guid property see 87 9 4 8 2 AES Wrapped Data Buffer This section describes the format of an encrypted data buffer raw bytes or RSA private key that is either to be passed to the AES unwrapping algorithm 83 1 or is the output of the AES wrapping algorithm 83 3 Different modes of operation are described in separate subsections In all modes big endian encoding is used 8 2 1 ECB Mode In ECB mode the size of the wrapped data buffer is an exact multiple of 16 bytes block size for AES DATA DATA DATA DATA 16 BYTES 16 BYTES 16 BYTES 16 BYTES AES wrapped buffer in the ECB mode 8 2 2 CTR Mode n CTR mode the wrapped data buffer begins with the initialization vector which is 16 bytes followed y a data buffer of N bytes N is an arbitrary number not necessarily a multiple of 16
113. hts reserved Secure Key Box User Guide 4 Supporting Libraries Parameter Description plain Pointer to the data buffer containing the RSA private key stored according to the PKCS 8 standard plain_size Size of the buffer in bytes data Address of a pointer to the SKB_SecureData that will contain the loaded key after this function is executed 4 1 2 6 SKB_CreateRsaPrivateFromPlain This function creates an SKB_SecureData object from a plain RSA private key defined as a Set of key components A The input parameters must be provided in big endian encoding The function is declared as follows SKB Result SKB CreateRsaPrivateFromPlain const SKB Engine engine void plain p void plain q void plain d void plain_n SKB_Size key size SKB SecureData data The following table explains the parameters Parameter Description engine Pointer to the pre initialized engine plain_p Pointer to the prime number p plain_q Pointer to the prime number q plain_d Pointer to the decryption exponent d plain_n Pointer to the modulus n key_size Size of the key in bytes data Address of a pointer to the SKB_SecureData that will contain the loaded key after this function is executed Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 53 of 137 Copyright 2004 2015
114. ifier export guid Export key identifier consisting of 16 bytes in the hexadecimal format SKB packages with the same export key will have the same identifier export key version Current export key version in the one way data upgrade scheme see 83 7 7 10 3 SKB_Datalnfo This structure is used by the SKB_SecureData_GetInfo method to return the size and type of a particular SKB_SecureData Object see 87 9 14 The structure is declared as follows typedef struct SKB DataType type E SKB Size size SKB DataInfo The following table explains the properties Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 106 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description type Type of the data stored within the SKB_SecureData object Available types are defined in the skB_DataType enumeration see 87 11 1 size Size of the contents in bytes Value O means that the information is not available For the data type SKB DATA TYPE RSA PRIVATE KEY this value is the modulus in bytes 7 10 4 SKB_CtrModeCipherParameters This structure provides an additional parameter for the SKB Engine CreateCipher method when the SKB CIPHER ALGORITHM AES 128 CTR SKB CIPHER ALGORITHM AES 192 CTR and SKB CIPHER ALGORITHM AES 256 cTRalgorithm
115. ight 2000 2015 whiteCryption Corporation All rights reserved Page 84 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description self Pointer to the pre initialized engine exported Pointer to the memory buffer containing the exported data xported_siz Size of the memory buffer data Address of a pointer to the SKB_SecureData object that will be created by this method This object will contain the imported data 7 9 7 SKB_Engine_WrapDataFromPlain This method takes a plain data buffer encrypts it with a key stored in an SKB_SecureData object and stores the output as a new SKB_SecureData Object For more information on this method see 83 4 The method is declared as follows SKB Result _ SKB Engine WrapDataFromPlain SKB Engine const SKB Byte SKB Size SKB DataType SKB DataFormat SKB CipherAlgorithm const void const SKB SecureData const SKB Byte SKB Size SKB SecureData self plain plain size data_type plain format algorithm encryption parameters encryption key iv iv_size data The following table explains the parameters Parameter Description self Pointer to the pre initialized engine plain Pointer to the memory buffer where the plain input data is stored plain size Pointer to a variable that holds the size of the input d
116. ill be derived format Format in which the derived public key should be stored in the returned buffer of bytes The available formats are defined in the SKB_DataFormat enumeration see 87 11 7 Currently the only valid value is SkKB_DATA FORMAT ECC_BINARY parameters Pointer to a structure containing parameters necessary for the deriving of the public key Since SKB supports only ECC key generation this parameter should point to the SKB_EccParameters Structure which specifies the ECC curve type see 87 10 22 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 97 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description output If this parameter is NULL the call is simply a request to find out how many bytes are needed to store the public key Then the method returns in output_size a number indicating how many bytes would be sufficient to hold the output and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size output_size is large enough to hold the public key output the method places the output there and sets output_size to the exact number of bytes stored If the buffer is not large enough then the method sets output_size to a number of bytes that would be sufficient and returns SKB_ERROR_BUFFER_TOO
117. ime P Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 18 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Function Algorithms ey generation random buffer of bytes for example DES and AES keys ECC key pairs for supported curve types see 81 3 Key derivation slicing Selecting a substring of bytes from another key selecting odd or even bytes mode no padding iterated SHA 1 SHA 256 with plain prefix and suffix SHA 384 byte reversing NIST 800 108 key derivation with 128 bit A encrypting decrypting raw bytes for example DES and AES keys using 128 bit 192 bit and 256 bit AES in ECB mode no padding and CBC KDF2 used in the RSAES KEM KWS scheme of the Open Mobile Alliance ES CMAC in counter mode OMA DRM specification key CMLA key derivation defined by the CMLA key and optional SHA 1 function deriving raw bytes for example DES and AES keys from an ECC private 128 bit AES encryption in ECB mode no padding with a concatenated Technical Specitication Miscellaneous device binding decryption of PDF files of version 1 6 and 1 mode 7 using 128 bit AES in CBC 1 3 Supported ECC Curves
118. inaries for different target platforms SKB static library Sensitive Operations Library see 84 1 Platform Specific Library see 84 2 Custom ECC Tool see 85 1 Diffie Hellman Tool see 85 2 Key Export Tool see 85 3 SQLite library see 84 2 3 Binary Update Tool see 85 4 If you have ordered a tamper resistant SKB library see 81 1 9 you always have to run the Binary Update Tool on the final protected application once it is built as described in 85 4 Otherwise the protected application will crash at run time Source Contains the source files and configuration files used by SKB examples and tests SpeedTests Contains speed tests for measuring the performance of various cryptographic algorithms For information on building tests see 82 3 Test Contains unit tests You can compile and run them to verify that SKB is running correctly For information on building tests see 82 3 ThirdParty Contains third party files needed to compile the source files delivered along with SKB Tools SkbPlatform Contains source code for Platform Specific Library This library is also available in a binary format in the Libraries directory For more information on Platform Specific Library see 84 2 Tools SkbUtils Contains source code for several functions and variables used by the SKB tests Copyright 2000 2015 wh
119. ing SKB see 86 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 48 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries 4 Supporting Libraries The core of SKB is delivered as a single binary library However for several reasons certain functions are externalized as separate libraries that are delivered together with SKB The following supporting libraries are available Library Description Sensitive Operations Library Contains functions for importing plain keys into SKB For information on this library see 84 1 Platform Specific Library Contains functions that may be implemented differently on the same architecture For information on this library see 84 2 4 1 Sensitive Operations Library This section describes Sensitive Operations Library internally called skbInternalHelpers 4 1 1 Overview Sensitive Operations Library is used to perform the following operations load plain keys as secure data objects export secure data objects as plain keys Since importing and exporting plain keys are very insecure operations this library is separated from the main API and there is no dependency from one to another For example you may want to use Sensitive Operations Library on a secure server that operates with plain keys but you will definitely want to exclu
120. ion see 87 10 2 Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 81 0f 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 9 5 SKB_Engine_CreateDataFromWrapped This method creates a new skB_SecureData Object from a wrapped buffer of data usually a cryptographic key by unwrapping it with a previously loaded key The unwrapped data is never exposed in plain form For more information on using this method see 83 1 As a special case of calling this method you can also load a plain buffer of data as an SKB_SecureData Object see 83 2 In this case the unwrapping algorithm and the decryption key are not specified This operation should be used with extreme care because you are providing the key in plain form Use this approach only in a highly protected environment The loading of plain keys can be executed only if loading of plain data is enabled in SKB see 84 1 The SKB Engine CreateDataFromWrapped method is declared as follows SKB Result SKB Engine CreateDataFromWrapped SKB Engine self const SKB Byte wrapped SKB Size wrapped _ size SKB DataType wrapped type SKB DataFormat wrapped format SKB CipherAlgorithm wrapping algorithm const void wrapping parameters const SKB SecureData unwrapping key SKB SecureData data The following table explains the parameters
121. iteCryption Corporation All rights reserved Page 22 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Directory or file Description export id Text file containing the identifier of the export key see 81 1 6 included in this SKB instance as well as identifiers of all export keys whose exported data this SKB instance is capable of upgrading see 83 7 The file structure is as follows Legacy key 0 ID export key identifier Legacy key 1 ID export key identifier Legacy key 2 ID export key identifier Current key version N ID export key identifier Legacy key specifies identifiers of export keys whose exported data can be upgraded by this SKB instance current key specifies the identifier of the export key that is used by this SKB instance to encrypt exported data To find out which export key was used to export particular data you can compare export key identifiers in this file to the export key identifier in the header of exported data as described in 88 1 SConstruct This file is used by SCons to build the source files delivered along with SKB For information on using SCons for building the files see 52 3 1 6 Limitations and Known Problems Please carefully review the following list of limitations and known problems before including SKB into your applications
122. l algorithms is a secure data object whereas the skB_Transform Class provides the hash value in plain form This feature makes these algorithms suitable for deriving new keys 3 10 4 1 Iterated SHA 1 Derivation The iterated SHA 1 derivation algorithm creates a new key as a substring of bytes from a SHA 1 hash value obtained from another key This algorithm functions as follows 1 The SHA 1 hash value is calculated from the contents of the provided secure data object key The result is 20 bytes containing the hash value 2 Optionally if requested by the caller number of rounds is greater than 1 the specified number of bytes is taken from the beginning of the 20 byte hash value and passed to the SHA 1 algorithm again one or several times Each time the result again is 20 bytes containing the hash value 3 Finally the specified number of bytes is taken from the beginning of the 20 byte hash value and returned as a new secure data object To create a new key as a Substring of bytes of a SHA 1 hash value of another key call the SKB SecureData_ Derive method select the SKB DERIVATION ALGORITHM SHA 1 algorithm and specify the necessary parameters see 87 9 1 7 This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key 3 10 4 2 SHA 256 Derivation with Plain Prefix and Suffix This derivation algorit
123. ld SKB Engine self const SKB Byte id SKB Size size The following table describes the parameters Parameter Description self Pointer to the pre initialized engine id Pointer to the byte array containing the device ID You have to generate this byte array yourself based on some hardware details or other environment specific parameters size Number of bytes in the ia parameter The device ID can be of arbitrary length If the size is 0 SKB will remove the previously set device ID This can be useful when the device ID is no longer needed and the default export format based only on the export key needs to be restored 7 9 4 SKB_Engine_Getinfo This method populates an SKB_EngineInfo structure see 87 10 2 with the generic information about an initialized engine The contents of a populated skB_EngineInfo Structure will not be valid after the corresponding SKB_Engine object is released from memory During examination of the SKB EngineInfo object the SkKB_Engine object must exist The method is declared as follows SKB Result SKB Engine GetInfo const SKB Engine self SKB EngineInfo info The following table describes the parameters Parameter Description self Pointer to the pre initialized engine that you want to get the information about info Pointer to the SKB_EngineInfo Structure to be populated with the engine informat
124. ld be considered unsafe and must never be included in an application that is deployed in an open environment They can only be used on a protected computer that is not accessible to end users 2 3 Building Examples Tests and Platform Specific Library A number of additional C source files are delivered together with SKB These files include examples tests and Platform Specific Library see 84 2 Platform Specific Library is a mandatory component that is necessary for the execution of SKB Other components are optional Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 25 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 2 Building Applications Protected by SKB The following subsections describe the recommended and supported way of building these files for different targets 2 3 1 Building for Windows API Visual Studio is used to build SKB examples tests and Platform Specific Library This section describes how to set up the build environment and compile the source files 2 3 1 1 Prerequisites F To compile the source files you will need a computer with the Windows operating system that has Visual Studio installed For information on supported Visual Studio versions see 81 4 2 3 1 2 Compiling To compile the source files proceed as follows 1 Open the Visual Studio solution named SecureKeyBox sln in
125. lications are not accessing the same skb ab file The path to this file varies for different operating systems You can adjust the path by modifying the skb target KeyCacheFilePath cpp file located in the Tools SkbPlatform target directory For instance if you are protecting an Android application the file name is SkbAndroidKeyCacheFilePath cpp and it is located in the Tools SkbPlatform Android directory To use SQLite based key caching you will need an SQLite static library version 3 7 14 or later to be included in your project You can obtain the library in the Libraries directory In memory An internal in memory map like data structure is used for key caching If the SKB library delivered to you includes any RSA features this is the default mode for the Google Native Client and PlayStation 3 targets The implementation of this key caching mode is defined in the SkbProtectedKeyCacheInMemory cpp file which is located in the Tools SkbPlatform KeyCacheImp1 directory By default only the last 10 keys are cached If you want to change the number of cached keys define the skB_KEY CACHE MAX IN MEMORY ITEMS preprocessor definition as the required number for example as follows define SKB KEY CACHE MAX IN MEMORY ITEMS 20 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 57 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries
126. logies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations ORIGINAL KEY 12 bytes TAKE LAST 12 secure_p BYTES 4 bytes plain_2 128 BIT AES 16 bytes ECB MODE DERIVED KEY Key derivation based on 128 bit AES encryption with a concatenated key and SHA 1 The diagram contains the following elements ORIGINAL KEY is the secure data object used as an input of the derivation algorithm must be 12 bytes long plain_1 and plain_2 are plain data buffers provided as input parameters to the algorithm plain_2 must be 16 bytes long secure_p is a secure data object provided as an input parameter to the algorithm must be 4 bytes long DERIVED KEY is a new secure data object provided in the output Additionally this derivation algorithm supports a simplified mode of operation when plain_1 is not provided is NULL Then the algorithm is executed as follows Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 43 of 137 Copyright O 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations ORIGINAL KEY 12 bytes secure_p 4 bytes plain_2 128 BIT AES 16 bytes ECB MODE DERIVED KEY Key derivation based on 128 bit AES encryption with a concatenated key without SHA 1 As can be seen this algorithm is similar to the first one except the SHA 1 step involving the plain_
127. lue inaccessible in plain form to the outside world safe safely safer and variations of these terms refer to actions or objects that when processed in accordance with this User Guide will not compromise the security protections provided by SKB tamper resistance and variations of this term refer to the application of whiteCryption s Code Protection product to render it more difficult for unauthorized parties to engage in reverse engineering and code modification 1 1 3 Purpose of SKB Cryptographic algorithms and keys are used to protect sensitive data authenticate communication partners verify signatures and implement various other security schemes A common weak point of cryptographic algorithms in today s open architectures such as smartphones tablets and desktops is that the cryptographic keys are revealed in the code or memory at some point Hackers can monitor such devices with special tools and extract the secret cryptographic keys Without an efficient protection of cryptographic keys security features may be compromised SKB is designed to prevent such attacks by encrypting and hiding cryptographic keys in the code and memory 1 1 4 White Box Cryptography The term white box cryptography is used to describe a secure implementation of cryptographic algorithms in an execution environment that is fully observable and modifiable by an attacker such as a desktop computer or a m
128. mand line and passing several parameters to it The following is the pattern to be used to run Custom ECC Tool CustomEccTool parameter type parameter value The following table explains the input parameters Parameter Description parameter type Type of the ECC domain parameter for which the protected form must be generated The following types are available a constant a in the curve equation p prime p of the elliptic curve n order n of the base point x X coordinate of the base point y Y coordinate of the base point r fixed random value to be passed to the ECDSA and ECDH algorithms parameter_value Plain parameter value which must be specified as an unsigned integer If you are passing the parameter a and it is a negative number it must be provided as p a where p is the prime of the elliptic curve You can see the list of all available parameters by running Custom ECC Tool with the help parameter Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 61 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 5 Utilities The skbEccCustomDomainParameters h file located in the Examples directory contains examples of protected ECC domain parameters for different curve types 5 2 Diffie Hellm
129. mport it as an SKB_SecureData Object Ifthe input file is previously exported data containing an old key version upgrade the data 2 Export the output to a file in protected format The output format can be either binary data or C code in which the exported data is defined as an array of bytes Once the output is created you can import it into SKB using the SKB Engine CreateDataFromExported method see 87 9 6 This operation can be performed only if the importing SKB instance has the same export key as the one that exported the data 5 3 2 Running Key Export Tool Key Export Tool is located in the Libraries directory along with the precompiled SKB library To run the utility simply execute it at the command line and pass several parameters to it as follows ExportTool input format input_format output format output_format ut input_file output output_file device id file_with_device_id The following table explains the input parameters Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 64 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 5 Utilities Parameter Description zzinp t format Specifies the format of the input file Possible values are the following bytes raw bytes in plain for example a DES or AES key If you are importing a key for
130. n key The output is 1 if the signature is verified and 0 if it is not To verify a signature proceed as follows 1 Obtain a secure data object containing the verification key 2 Create a transform object by calling the skB_ Engine CreateTransform method select the SKB_ TRANSFORM TYPE VERIFY type and specify the necessary parameters including the verification key as described in 87 9 9 3 Supply a buffer of plain or secure data as an input to the transform object by calling the SKB Transform AddBytes method 87 9 20 and SKB Transform AddSecureData method 87 9 21 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 46 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations You can call these methods more than once to pass a large buffer of input data consisting of several smaller data chunks 4 To verify the signature against the supplied data buffer call the skB_Transform GetOutput function as described in 87 9 22 5 Release the transform object when it is no longer needed by calling the skKB_ Transform Release method as described in 87 9 19 3 15 Executing a Key Agreement Algorithm The key agreement algorithm involves two parties that want to obtain a shared secret usually a cryptographic key that is known only to them First both parties each generate a public value or key that is gi
131. n the skbPlat orm h file Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 56 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries 4 2 3 Key Caching In SKB RSA operations might take a significant amount of time To address this problem SKB provides functionality called RSA key caching It speeds up operations with RSA keys by caching them after their initialization RSA related algorithms are the only ones that use key caching Before compiling Platform Specific Library you can set a particular key caching mode as described in the following table Mode Description SQLite The SQLite implementation of key caching is used If the SKB library delivered to you includes any RSA features this is the default mode for all targets except Google Native Client NaCl and PlayStation 3 In this mode the key caching data is stored in an SQLite database named skb db in protected form The implementation of this key caching mode is defined in the SkbProtectedKeyCacheSQLite cpp file which is located in the Tools SkbPlatform KeyCacheImp1 directory You can either use this implementation in your application as is or treat it as an example implementation for key caching If you use this implementation without modification make sure that different app
132. n_1 buffer This property may be set to NULL In that case the simplified version of the derivation algorithm will be executed see 83 10 10 plain_1_size Size of the plain_1 buffer It must be 0 if plain_1 is set to NULL plain_2 Pointer to the plain_2 buffer which must be 16 bytes long 7 10 16 SKB_OmaDrmkdf2DerivationParameters This structure is used by the SKB_SecureData_Derive method if the SKB DERIVATION ALGORITHM OMA DRM KDF2 derivation algorithm is used see 87 9 17 The purpose of this structure is to specify the necessary input parameters For more information on this derivation algorithm see 83 10 7 The structure is declared as follows typedef struct const SKB Byte label SKB Size label size SKB Size output _ size 3 SKB OmaDrmKdf2DerivationParameters The following table explains the properties Property Description label Pointer to the buffer containing the otherInfo parameter as defined in the OMA DRM specification label_size Size of the label buffer in bytes output_size Size of the derivation output in bytes 7 10 17 SKB_SliceDerivationParameters This structure is used by the SKB_SecureData_Derive method if the SKB DERIVATION ALGORITHM SLICE Of SKB_ DERIVATION ALGORITHM BLOCK SLICE derivation algorithm is used see 87 9 17 The purpose of this structure is to specify the range of bytes first byte and the number of bytes that should
133. obile device It is different from black box cryptography where the Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 10 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction algorithm s internal processing data is unavailable to the attacker The white box environment puts certain restrictions on implementations of the cryptographic algorithms For instance an encryption key may never appear in plain text otherwise it can be retrieved by an attacker 1 1 5 Secure Data Objects A secure data object represented by the skB_SecureData Class in the API is one of the basic concepts in the SKB protection scheme It is a container of any sensitive data whose value is white box protected and hidden from the outside world Secure data objects can be operated on by SKB functions even though the contents of secure data objects are not revealed in plain form Because secure data objects usually hold cryptographic keys in this document the terms secure data object and cryptographic key are used interchangeably 1 1 6 Export Key Secure data objects cryptographic keys are operated on in the device memory Because the memory is not persistent there needs to be a mechanism for safely storing secure data objects Each SKB package contains an embedded key called the export key This export key is used for encrypting other cr
134. one of the following directories depending on your needs Build Targets all microsoft win32 vs2010 Visual Studio 2010 solution for Windows API Build Targets all microsoft win32 vs2012 Visual Studio 2012 solution for Windows API Build Targets all microsoft win32 vs2013 Visual Studio 2013 solution for Windows API This solution contains the following specific projects Project Description SkbExamples Runs SKB examples SkbSpeedTests Runs SKB speed tests SkbTestSuite Runs SKB unit tests 2 Compile the solution 2 3 2 Building for Windows Runtime and Windows Phone Visual Studio is used to build SKB examples tests and Platform Specific Library This section describes how to set up the build environment and compile the source files Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 26 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 2 Building Applications Protected by SKB 2 3 2 1 Prerequisites E To compile the source files you will need a computer with the Windows operating system that has Visual Studio installed For information on supported Visual Studio versions see 81 4 2 3 2 2 Compiling To compile the source files proceed as follows 1 Open the Visual Studio solution named SecureKeyBox sln in one of the followin
135. orm object by calling the skB_Engine CreateTransform method select the SKB_ TRANSFORM TYPE SIGN type and specify the necessary parameters as described in 87 9 9 3 Supply a buffer of plain or secure data as an input to the transform object by calling the SKB Transform AddBytes method 87 9 20 and SKB Transform AddSecureData method 87 9 21 You can call these methods more than once to pass a large buffer of input data consisting of several smaller data chunks An exception is those signing algorithms that do not have their own hash functions SKB_SIGNATURE_ALGORITHM RSA and SKB_ SIGNATURE ALGORITHM ECDSA These algorithms assume that the input is already a message digest calculated using an arbitrary hash function Therefore these algorithms will accept only one data buffer of plain data as an input This means that only the skB_Transform_AddBytes method can be used not SKB Transform AddSecureData and only once Since these signing algorithms operate only on plain data they are significantly faster than other algorithms that employ a hash function 4 To calculate the signature call the skB_Transform GetOutput function as described in 87 9 22 Release the transform object when it is no longer needed by calling the skB_Transform_ Release method as described in 87 9 19 3 14 Verifying a Signature Verifying a signature involves executing the verification algorithm on a signature buffer using a particular verificatio
136. ource Output is a definition of a C array which you can then copy directly into your source code Optionally you can use the command line argument i value to specify how many elements should be displayed on each line The default value is 8 hex Output is a string containing the exported data in hexadecimal format output value File name of the output file generated by Diffie Hellman Tool f this argument is not provided Diffie Hellman Tool writes the result to the standard output help Displays the help Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 63 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 5 Utilities 5 3 Key Export Tool Key Export Tool is used for the following purposes creating a protected exported form of an SKB_SecureData object from plain input data The input data can be raw bytes for example a DES or AES key an RSA private key or an ECC private key upgrading previously exported data to the current version in the one way data upgrade scheme see 3 7 A Key Export Tool must always be used in a secure environment see 81 1 7 5 3 1 Key Export Tool Overview Key Export Tool performs the following actions 1 Depending on the input file format do one the following Ifthe input file is in plain form i
137. overwrite the input Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 101 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description out_buffer_size Pointer to a variable that holds the size of the memory buffer in bytes where the output data is to be stored For more details see the description of the out_buffer parameter iv Pointer to the initialization vector if you use the AES cipher in the CBC or CTR mode or NULL in other cases The initialization vector must be provided in the first call of this method In subsequent calls you may set the iv parameter to NULL in which case SKB will interpret the provided input buffer as continuation of the same message and will use the initialization vector that is internally preserved from the last method call this approach is useful for processing very large data buffers that may not fit in the memory In other words if you provide the initialization vector SKB interprets the input buffer as a new message iv_size Size in bytes of the initialization vector It should be 0 if the iv parameter is NULL 7 9 24 SKB_Cipher_Release This method releases an SKB_Cipher object It should always be called when the object is no longer needed The method is declared as follows SKB Result SKB_ Cipher Rele
138. pherDerivationParameters Object see 87 10 10 If the SKB_ DERIVATION ALGORITHM SHA_1 algorithm is used this parameter may point to the skB_ShalDerivationParameters Structure which specifies how many times the SHA 1 algorithm should be executed and how many bytes from the result should be derived see 87 10 11 If the parameter is NULL the SHA 1 algorithm will be executed once and the whole output of 20 bytes will be returned as a new SKB_SecureData Object If the skB_DERIVATION ALGORITHM SHA 256 algorithm is used this parameter may point to the skB_Sha256DerivationParameters structure which provides the plain buffers that should be prepended and appended to the SKB_SecureData Object processed see 87 10 12 If the parameter is NULL SKB will assume that there are no plain data buffers to be prepended or appended If the skB_DERIVATION ALGORITHM NIST 800 108 COUNTER CMAC AES128 algorithm is used this parameter must point to the SKB Nist800108CounterCmacAes128Parameters Structure which provides the necessary input parameters see 87 10 13 If the SKB_DERIVATION ALGORITHM OMA DRM KDF2 algorithm is used this parameter must point to the SKB_OmaDrmKdf2DerivationParameters structure which provides the necessary input parameters see 87 10 16 If the SKB_DERIVATION ALGORITHM RAW BYTES FROM ECC PRIVATE algorithm is used this parameter may point to the SKB RawBytesFromEccPrivateDerivationP
139. r complete This User Guide contains no express or implied warranties covenants or grants of rights or licenses and does not modify or supplement any express warranty covenant or grant of rights or licenses that is set forth in the Agreement This User Guide is current as of the date set forth in the header that appears above on this page but may be modified at any time without prior notice Future revisions and updates of this User Guide shall be distributed as part of Secure Key Box new releases whiteCryption shall under no circumstances bear any responsibility for your failure to operate Secure Key Box Licensed Technology in compliance with the then current version of this User Guide Your remedies with respect to your use of this User Guide and whiteCryption s liability for your use of this User Guide Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 2 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide Last updated March 9 2015 including for any errors or inaccuracies that appear in this User Guide are limited to those remedies expressly authorized by the Agreement if any Notice to U S Government End Users This User Manual is a Commercial Item as that term is defined at 48 C F R 82 101 consisting of Commercial Computer Software Documentation as such terms are used in 48 C F R 812 212 or 48 C F R 8227 7202 as applic
140. r is 128 bits long SKB assumes the keys are provided in the following format Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 134 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 8 Data Formats 8 BYTES 8 BYTES Triple DES key buffer containing only the first two keys In the latter case it is assumed that key 3 is identical to key 1 8 4 Input Buffer for the ElGamal ECC Cipher The buffer that is passed as an input to the ElGamal ECC decryption and unwrapping algorithms must contain two points on an ECC curve using the following format Input buffer for the ElGamal ECC algorithm C1 X and C1 Y are the X and Y coordinates of the encrypted ciphertext 1 and C2 X and C2 Y are the X and Y coordinates of ciphertext 2 using the big endian notation N is the number of bytes used to store each coordinate calculated as follows N L 7 8 where L is the length of the curve in bits 8 5 Public ECC Key SKB stores public ECC keys using the following format N BYTES gt N BYTES gt Public ECC key format X and Y are the coordinates of the public key encoded using the big endian notation and N is the number of bytes used to store each coordinate N depends on the ECC curve used as follows Copyright O 2000 2015 whiteCryption Corporation All rights reserved Page 135 of 137 Copyright O 2004 2015 Intertrust Tec
141. rameter is either NULL or a pointer to the memory buffer where the plain key is to be written If this parameter is NULL the method simply returns in plain_size a number of bytes that would be sufficient to hold the plain key and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size is large enough to hold the plain key the method stores the plain key there sets plain size to the exact number of bytes stored and returns SKB_SUCCESS If the buffer is not large enough then the method sets plain _sizeto a number of bytes that would be sufficient and returns SKB ERROR BUFFER TOO SMALL h The data will be provided in big endian encoding plain_size Pointer to the size of the plain data buffer in bytes 4 1 2 5 SKB_CreateRsaPrivateFromPlainPKCS8 This function creates an SKB_SecureData Object from a plain RSA private key stored according to the PKCS 8 standard The function is declared as follows SKB Result SKB CreateRsaPrivateFromPlainPKCS8 const SKB Engine engine const SKB Byte plain SKB Size plain size SKB SecureData data The following table explains the parameters Parameter Description engine Pointer to the pre initialized engine Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 52 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rig
142. rary functions to suit your specific needs for example to run SKB on an operating system that is not directly supported All the necessary implementation information is provided in the comments of the SkbPlatform h file For information on compiling Platform Specific Library see 82 3 4 2 2 Library Functions The functions in Platform Specific Library can be grouped according to their logical purpose Purpose Description Key caching Key caching speeds up operations with RSA keys For details on this component see 84 2 3 The following functions are related to key caching KB KeyCache Creat KB KeyCache Destroy KB KeyCache GetInfo KB KeyCache GetGUID S S S SKB KeyCache SetGUID S SKB KeyCache ClearData S KB KeyCache SetData SKB KeyCache GetData Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 55 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 4 Supporting Libraries Purpose Description Random generation The function SkKB_GetRandomBytes s Used to generate a buffer of random bytes of a specific size There are two additional random generator related functions that are intended for the Google Native Client NaCl target only SKB InitRng SKB DestroyRng If you are building an application for the Google Native Client target
143. reData_Derive method select the SKB DERIVATION ALGORITHM RAW BYTES FROM ECC PRIVATE algorithm and specify the necessary parameters see 87 9 1 7 The derived data buffer will contain the ECC private key in little endian or big endian encoding depending on the provided parameters and its size will be the same as the size of the ECC private key rounded up to whole bytes You can then use other derivation algorithms to obtain new keys This operation can only be performed on secure data objects that contain an ECC private key 3 10 9 Deriving a Key Using the CMLA Key Derivation Function SKB provides a derivation algorithm that is based on the key derivation function specified in the CMLA Technical Specitication To execute this derivation algorithm call the SKB_SecureData_Derive method select the SKB DERIVATION ALGORITHM CMLA KDF algorithm and specify the necessary parameters see 87 9 17 This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key 3 10 10 Deriving a Key By Encrypting Data Using 128 bit AES With a Concatenated Key This derivation algorithm consists of several steps executed one after another as shown in the following diagram Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 42 of 137 Copyright 2004 2015 Intertrust Techno
144. rved Secure Key Box User Guide 2 Building Applications Protected by SKB 2 Depending on your target architecture download and install the necessary build system as listed in 81 4 2 3 3 2 Compiling To compile the source files go to the root directory of the SKB package and execute the following command The following table describes parameters used in this command Parameter Description target Specifies the target platform corresponding to an appropriate subdirectory in the Build Targets directory arm unknown linux GNU Linux edition for the ARM architecture x86 unknown linux GNU Linux edition for the x86 architecture x86 64 unknown linux GNU Linux edition for the x86_64 architecture mips unknown linux GNU Linux edition for the MIPS architecture mipsel broadcom linux GNU Linux edition for the MIPSel architecture If the target is not specified the source files will be built for the default target which is your build machine build_config Specifies whether the binaries should be compiled in release or debug mode The following values can be set Debug Produces binary files in debug mode and places them in the Build Targets your_target Debug directory This is the default value Release Produces binary files in release mode and places them in the Build Targets your_target Release directory 2 3 4 Building for Android Android NDK is used
145. s Property Description algorithm Signing algorithm to be used The available signing algorithms are defined in the SKB SignatureAlgorithm enumeration see 87 11 4 key Pointer to the SKB_SecureData object which contains the signing key This key must not be released before the skB_Transform Object that uses it is released 7 10 7 SKB_SignTransformParametersEx This structure is an extension to the SKB_SignTransformParameters structure It provides the additional ability to specify the ECC curve type in case the ECDSA signature algorithm is used or salt and Salt length in case the RSA signature algorithm based on the Probabilistic Signature Scheme is used The structure is declared as follows typedef struct SKB_SignTransformParameters base E const void extension 3 SKB SignTransformParametersEx The following table explains the properties Property Description base SKB_SignTransformParameters structure that specifies the signature algorithm and the key to be used see 87 10 6 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 108 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Property Description extension If one of the following signature algorithms is used this pointer must point to the ters Structure which specifi
146. s flag can be used only for the AES cipher when it is intended to be used with high throughput for example when used for media content decryption cipher parameters Pointer to a structure that provides additional parameters for the cipher For the SKB CIPHER ALGORITHM AES 128 CTR SKB CIPHER ALGORITHM AES 192 CTR and SKB CIPHER ALGORITHM AES 256 cTRCiphers it must point to the SKB _CtrModeCipherParameters structure see 87 10 4 or NULL for the default counter size of 16 For the SKB CIPHER ALGORITHM ECC ELGAMAL Cipher it must point to the SKB EccParameters Structure which specifies the curve type see 87 10 22 For all other ciphers this parameter must be NULL cipher_key Pointer to the SKB_SecureData object containing the encryption or decryption key Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 89 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description cipher Address of a pointer to the SKB_Cipher object which will be created by this method 7 9 11 SKB_Engine_CreateKeyAgreement This method creates a new SKB KeyAgreement Object based on the provided parameters The SKB KeyAgreement Object is used to calculate a shared secret based on the key agreement algorithm The method is declared
147. s are used see 87 9 10 The structure is declared as follows typedef struct E SKB Size counter size SKB _CtrModeCipherParameters The property counter _size specifies the counter size in bytes 7 10 5 SKB_DigestTransformParameters This structure is used by the SKB _ Engine CreateTransform method if the SKB_ TRANSFORM TYPE DIGEST transform is used See 87 9 9 The purpose of this structure is to specify the digest algorithm The structure is declared as follows typedef struct E SKB DigestAlgorithm algorithm _ SKB DigestTransformParameters The property algorithm specifies the digest algorithm to be used The available algorithms are defined in the SKB _DigestAlgorithm enumeration see 87 11 2 7 10 6 SKB_SignTransformParameters This structure is used by the SKB _Engine_ CreateTransform method if the SKB_ TRANSFORM TYPE SIGN transform is used see 87 9 9 The purpose of this structure is to specify the signing algorithm and the signing key The structure is declared as follows Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 107 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference typedef struct l SKB SignatureAlgorithm algorithm E const SKB SecureData key F SKB SignTransformParameters The following table explains the propertie
148. s is that older versions of your protected application will not be able to read data exported by newer versions of that application For example if someone successfully cracks your application the attack will not be directly applicable to newer releases of that application The one way data key upgrade mechanism is implemented by embedding into each SKB package all export keys of its previous versions as shown in the following diagram Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 36 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations KEYS EXPORTED WITH EXPORT KEY 0 APP V2 UPGRADE EXPORT KEYO 7 SECURE KEY BOX V2 5 RY O ExPORTKEY1 i AS KEYS EXPORTED WITH EXPORT KEY 1 APP V3 SECURE KEY BOX V3 EXPORT KEY One way data upgrading To implement the one way data upgrading process proceed as follows 1 Order multiple versioned SKB packages 2 Integrate SKB package with version 1 into your application 3 When creating an updated version of your application execute the following steps Inthe application code replace the SKB library with the subsequent version Inthe process of upgrading your application execute the SKB Engine UpgradeExportedData method on each key exported by the previous SKB version as described in 87 9 12 This function will upgrade
149. salt Pointer to a byte buffer containing the salt value to be used If this parameter is NULL a random salt value with the length specified in the salt_length parameter will be generated salt_length Length of the salt value in bytes It must be equal or greater than O and must not exceed the hash function block size 7 10 22 SKB_EccParameters This structure provides additional parameters when the ECC functions are used The structure is declared as follows typedef struct SKB_EccCurve curve SKB_EccDomainParameters domain parameters const unsigned int random value a SKB EccParameters The following table describes the properties Property Description curve Specifies the ECC curve type to be used The available curve types are defined in the SKB _EccCurve enumeration see 87 11 10 domain_parameters Pointer to the skB_EccDomainParameters Structure which provides domain parameters for a custom ECC curve see 87 10 18 This parameter should be set only when the SKB_ECC_CURVE_CUSTOM curve type is used Currently custom ECC curves are supported only for the ECDSA ECDH and ECC key generation algorithms For all other cases there is no point setting this parameter Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 118 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All ri
150. same class The data type that represents references to object instances is a pointer to an opaque C structure It may be considered as analogous to a pointer to a C object A concrete example is that for the class named SKB_Cipher the data type SKB Cipher is the name of a C structure The function name for one of the methods of skB_Cipher is SKB Cipher ProcessBuffer and the function takes SKB _Cipher as its first parameter 7 2 Obtaining Class Instances An instance of a class is obtained by declaring a pointer to an object for the class and passing the address of that pointer to a particular method The method creates the instance and sets the pointer to refer to it For example the first object you need to create is SKB_Engine which represents an instance of an engine that can initialize other API objects SKB_Engine is obtained by calling the method SKB Engine GetInstance which is declared as follows SKB Result SKB Engine GetInstance SKB Engine engine The parameter is the address of a pointer to an SKB_Engine object This method creates an SKB Engine instance and sets the pointer to refer to the new instance Here is a sample call SKB_Engine engine NULL SKB Result result _ result SKB Engine GetInstance amp engine 7 3 Making Method Calls A call to a method of a particular instance is done by calling a function and passing a pointer to the in
151. scribed in 84 2 2 2 3 7 Building for PlayStation 3 The SCons build tool is used to build SKB examples tests and Platform Specific Library This section describes how to set up the build environment and compile the source code 2 3 7 1 Prerequisites The following prerequisites must be met before building the source files 1 Download and install SCons 2 3 0 2 Download and install PlayStation 3 Programmer Tool Runtime Library 460 001 2 3 7 2 Compiling Compiling for PlayStation 3 is performed the same way as described in 82 3 3 2 with the target parameter set tO ppu playstation3 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 31 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations 3 Cryptographic Operations This chapter provides high level task based information about the main cryptographic operations that can be performed with SKB 3 1 Loading Wrapped Keys Awrapped key is a cryptographic key encrypted with another key Loading wrapped keys unwrapping is a more secure way for importing keys into SKB SKB loads a wrapped key and internally decrypts it using a pre loaded unwrapping key SECURE KEY BOX c UNWRAPPING KEY KEY UNWRAPPING UNWRAPPED KEY WRAPPED KEY Loading a wrapped key Unwrapping is not the same operation as regular decryption because regular decryption
152. se Diffie Hellman Tool as described in 85 2 random_value Property that allows you to provide a fixed random value to the DH algorithm Typically the value of this property should be NULL in which case SKB uses an internally generated random value However you can also pass a fixed number to be used as the random value The fixed number must be passed as an integer array containing the value in protected form To obtain the protected form of a fixed random value use Diffie Hellman Tool as described in 85 2 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 119 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 10 24 SKB_RawBytesParameters This structure is required by the SKB Engine GenerateSecureData method see 87 9 8 to generate an SKB_SecureData object containing a protected buffer of random raw bytes The only purpose of this structure is to specify the number of bytes to generate The structure is declared as follows typedef struct E SKB Size byte count _ SKB _RawBytesParameters The byte count is the number of bytes to be generated 7 11 Enumerations This section describes various enumerations defined in the API 7 11 1 SKB_DataType This enumeration specifies the possible data types of the content encapsulated by an SKB SecureData object The enumeration is d
153. seeseeseenteess 5 7 10 18 SKB_EccDomainParametersS ieee ececcccecscccsscecseeceeeceseectsceeseecereectsescteesteeseeeeeteecteseteeetasentees 6 Ll O19 SRB SAOSW a DP aran tdco d 7 TOO EAE D e EE EE A A eR 7 PANO AEN e E s iae EEE AEA EEA E EA Do AEE E eA a EA oles 7 11022 SKB EECParametel Sinans o e e e E a te ie oe Mee O e ei a 8 7 10 23 SKB PrimeDhParameteS ens 9 SS Co Mipteh imi hak gic le AAA O A 20 AE OS O 20 ES A A cas ernie aa S a aaa Se o rala aE aai S 20 Tec oe SIO RST DG IE Meh ere a er a Salt TA E 20 FAN ee Olle aid A Cnn Te EIS EEM 20 wpe ees cies ii diare Wl ga F2 lt 6 1g M20 meee ce me a eer ree 23 SN OIE DN AA o o TRE aCe 24 ANS A renee tnt ark A a rer ert E mrre ene 26 FMF SKB RRA RR 26 MIRS A A a canoe hu heal oes ti 27 AMES te INTE cAI ee det en anu thu ered toh asta ah igen E Sud ue E a N NaNO achn ets 27 PA OS e ECECUIVO AN S EEA EEA EE EAEE do a hh 28 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 7 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 11 11 SKB_KeyAgreementAlgorithm A ener 29 SF ed Ug ZS ESP UIT UVES I Ie aS acetate O anad sa dese A a E e Maze 29 TS SB a 29 FV TA SKB si elo AAA A a uel al eines 30 A Ste GTA attuned A A TN 31 SN EXPO MDG Ea Fai 31 S2 AES Wrapped DU tt os 32 RESENO EA E ENEN E N E 32 O Ai E e de ene ope rT 32 2 S CBCMOI OA 33 8 3 K
154. stance as the first parameter For example once an SKB_Engine instance is created as shown in the previous section all the SKB Engine methods can be called to operate on that instance One such method is SKB Engine GetInfo which is used to obtain information about the engine version number properties and so on This method is declared as follows Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 75 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Gu ide SKB Result SKB Engine GetInfo const SKB Engine self 7 API Reference SKB Enginelnfo info It stores the engine information in the skB_1 EngineInfo Structure pointed to by the info parameter Assuming engine is a pointer previously set by SKB_Engine GetInstance to refer to the Engine GetInfo Can be invoked as follows SKB Engine instance it created SKB_1 result E _ Result result SKB Enginelnfo enginelnfo SKB Engine GetInfo engine senginelnfo 7 4 Method Return Values All methods return an integer value of type skB_Result When a method call succeeds the return value is SKB_ SUCCESS Otherwise it is a negative number as defined by constants in the header file The following table lists the defined return value constants
155. stems Windows Vista 7 8 8 1 Windows API x86 x86_64 Visual Studio 2010 2012 and 2013 Windows 8 8 1 Windows Runtime x86 x86_64 Visual Studio 2012 and 2013 OS X x86 x86_64 Xcode 5 0 GNU Linux x86 x86_64 GCC 4 4 3 GNU Linux ARM Sourcery CodeBench Lite 2012 03 57 GNU Linux MIPS Sourcery CodeBench Lite 2014 05 27 Android x86 x86_64 Android NDK r10d ARM 32 bit and 64 bit MIPS 32 bit and 64 bit IOS ARM 32 bit and Xcode 5 0 64 bit Windows Phone 8 ARM Visual Studio 2012 Windows Phone 8 1 ARM Visual Studio 2013 Google Native Client NaCl X86 x86_64 ARM PNacCl Native Client SDK Pepper 39 PlayStation 3 Cell PPU PlayStation 3 Programmer Tool Runtime Library 460 001 Copyright 2000 2015 whiteCryption Corporation All rights reserved Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Page 20 of 137 Secure Key Box User Guide 1 Introduction Platform Architectures Build systems uClibc Linux MIPSel Broadcom CrossTools GCC 4 2 1 5 Directory Structure and Contents The following table describes the directory structure of the SKB package Directory or file Description Build Contains the files needed to build SKB examples tests and Platform Specific Library for various target operating systems For information on building these files see 82 3 Build Targets Contains several
156. t 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Publication 800 108 using 128 bit AES CMAC as the pseudorandom function in counter mode For more information see 83 10 6 SKB DERIVATION ALGORITHM OMA DRM KDF2 Derives a New SKB_SecureData Object according to DF2 used in the RSAES KEM KWS scheme of the OMA DRM specification For more information see 83 10 7 SKB DERIVATION ALGORITHM RAW BYTES FROM ECC PRIVATE Derives a New SKB _SecureData bject with the type skB_DATA TYPE BYTES from another SKB SecureData object with the type SKB DATA TYPE ECC PRIVATE KEY For more information see 83 10 8 O SKB DERIVATION ALGORITHM CMLA KDF Derives a new SKB_SecureData Object according to the key derivation function defined in the CMLA Technical Specification For more information see 83 10 9 SKB DERIVATION ALGORITHM SHA AES Derives a new SKB _SecureData Object using an algorithm described in 3 10 10 7 11 6 SKB_CipherDirection This enumeration specifies the possible directions encryption or decryption for the SKB Cipher object Encryption is supported only for the DES Triple DES and AES ciphers The enumeration is defined as follows typedef enum SKB CIPHER DIRECTION ENCRYPT SKB CIPHER DIRECTION DECRYPT J SKB CipherDirection
157. t support generating private RSA keys 3 9 Deriving a Public Key from a Private Key As described in 83 8 SKB can generate new random private ECC keys In connection with this it may be necessary to get the corresponding public keys as well A public key can be derived from a private key To derive a public key from a private key call the skB_SecureData_GetPublicKey method provide the secure data object containing the private key and supply the necessary parameters See 87 9 18 This method will return a buffer of bytes containing the corresponding public key Currently this operation is supported only for ECC keys but not for RSA keys 3 10 Deriving Keys This section describes several operations that can be used to derive one cryptographic key from another 3 10 1 Deriving a Key as a Substring of Bytes of Another Key In some cases it is necessary to securely derive a new key as a Substring of bytes of another key To do this call the SKB_SecureData_Derive method select either the SKB DERIVATION ALGORITHM SLICE Of SKB_ DERIVATION ALGORITHM BLOCK SLICE algorithm and specify the range of bytes to be derived as a new key see 87 9 1 7 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 38 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations The only difference between
158. te of the decrypted point on the ECC curve The actual unwrapped key is stored within the X coordinate using the big endian notation You must then extract the unwrapped key bytes from the X coordinate using the SKB_SecureData_ Derive method and the SKB DERIVATION ALGORITHM SLICE algorithm see 87 9 17 according to your ElGamal ECC encryption padding scheme used With this approach you can use any padding scheme for encryption For example assume you use ElGamal ECC with the NIST 256 curve to wrap a secret 16 byte AES key by adding 4 bytes to its beginning to map it to a point on an ECC curve Then the unwrapping code should resemble the following SKB SecureData secret key This will contain the unwrapped AES key SKB SecureData temp data SKB SecureData ecc_key Previously obtained ECC private key SKB_Byte wrapped buffer 256 8 4 SKB Size wrapped buffer size sizeof wrapped buffer n _ ECC parameters SKB EccParameters params params curve SKB ECC CURVE NIST 256 params domain parameters NULL params random_ value NULL SKB Engine CreateDataFromWrapped engine e wrapped buffer wrapped buffer size SKB DATA TYPE BYTES SKB DATA FORMAT RAW SKB CIPHER ALGORITHM ECC_ELGAMAL amp params ecc_key amp temp data _ Now temp data contains 256 8 32 bytes The secret AES key
159. tertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations 3 When no longer needed release the cipher object by calling the SKB Cipher Release method as described in 87 9 24 3 11 2 Decrypting Data Decryption is a process where a cryptographic cipher and a cryptographic key are applied to encrypted data to produce plain data To decrypt data proceed as follows 1 Create a cipher object by calling the skB_Engine CreateCipher method specify the decryption algorithm and key specify the direction skB_CIPHER DIRECTION DECRYPT and provide the necessary parameters as described in 87 9 10 2 Decrypt the input buffer by calling the SKB _Cipher ProcessBuffer method as described in 879 23 This method returns a byte buffer containing the decrypted data 3 When no longer needed release the cipher object by calling the SKB Cipher Release method as described in 87 9 24 3 11 3 Using the High Speed AES SKB provides an alternative high speed implementation of AES which is intended for encrypting and decrypting high volume data such as a video stream High speed AES performance is very close to the performance of unprotected AES To use high speed AES specify the SKB_ CIPHER _ FLAG HIGH SPEED flag when creating the SKB Cipher object as described in 87 9 10 3 12 Calculating a Digest Calculating a digest involves taking
160. text ProcessBuffer function see 86 3 4 The function is declared as follows SKB Result SKB Pdf CreateDecryptionContext const SKB SecureData encryption key int object number int generation number const SKB Byte iv SKB Pdf DecryptionContext ctx The following table describes the parameters Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 71 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 6 Decrypting PDF Files Parameter Description encryption_key Pointer to an SKB_SecureData Object containing the encryption key which you can obtain using the SKB_Pdf_ ComputeEncryptionKey function see 86 3 2 The encryption key is combined with metadata of the particular PDF object to calculate a decryption key which is then stored in the PDF decryption context object object_number Object number in the PDF file generation_number Generation number of the object iv Pointer to an initialization vector to be stored in the PDF decryption context You can set this parameter to NULL in which case the initialization vector must be passed in the first call of the SKB Pdf DecryptionContext ProcessBuffer function see 86 3 4 ctx Address of a pointer to the skxB_Pdf DecryptionContext object that will contain the PDF decryption context after this function is executed
161. the SKB_DERIVATION ALGORITHM SLICE and SKB DERIVATION ALGORITHM BLOCK SLICE algorithms is that the latter requires the index of the first byte and the number of bytes in the substring to be multiples of 16 You can use the SKB DERIVATION ALGORITHM SLICE algorithm to extract the unwrapped key from the output of the ElGamal ECC unwrapping algorithm as described in 83 1 1 This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key not an RSA or ECC private key 3 10 2 Deriving a Key as Odd or Even Bytes of Another Key SKB allows you to derive new keys from an existing key by selecting a number of its odd or even bytes For example if you have a 256 byte key you can derive two 128 byte keys from it the size of the derived keys can be smaller One key would have the bytes of the input key with indices 0 2 4 6 and so on odd bytes The other key would have the bytes of the input key with indices 1 3 5 7 and so on even bytes To create a new key as odd or even bytes of another key call the SkKB_SecureData_Derive method select the SKB_ DERIVATION ALGORITHM SELECT BYTES algorithm and specify the necessary parameters see 87 9 1 7 This operation can only be performed on secure data objects that contain raw bytes for example a DES or AES key but not an RSA or ECC private key
162. the Triple DES algorithm make sure the input corresponds to the format described in 88 3 rsa plain RSA private key in the PKCS 8 format ecc plain ECC private key in the format that corresponds to the format described in 88 6 upgrade previously exported data that needs to be upgraded to the current version see 83 7 output format Specifies the format of the output file Possible values are the following binary Output is a binary file containing a buffer of bytes source Output is a definition of a C array which you can then copy directly into your source code input File name of the input file output File name of the output file generated by Key Export Tool device id Optional parameter that allows you to set the device ID Device ID is combined with the export key to create a unique format for exported keys as described in 83 16 If this parameter is not specified the export format depends only on the export key If you want to set the device ID this parameter must contain a path to a binary file that contains the device ID Note This parameter is available only if the SKB package you requested has the device binding feature enabled You can see the list of all available parameters by running Key Export Tool with the help parameter 5 4 Binary Update Tool If the SKB library that you link with your application has tamper resistance appli
163. the last part of the encrypted object data and O otherwise This information is used to process the CBC mode padding in the encrypted data and calculate the precise decrypted content length If this parameter is 1 then the PDF decryption context will no longer contain an initialization vector after the function is executed and the next call of the sSkB_Pdf DecryptionContext ProcessBuffer function using the same PDF decryption context has to provide an initialization vector out buffer This parameter is either NULL or a pointer to the memory buffer where the decrypted content is to be written If this parameter is NULL the function simply returns in out_buffer size a number of bytes that would be sufficient to hold the output and returns SKB_SUCCESS If this parameter points to a memory buffer it is not NULL and the buffer size is large enough to hold the output the method stores the output there sets out_buffer size to the exact number of bytes stored and returns SKB_SUCCESS If the buffer is not large enough then the method sets out_buffer size to a number of bytes that would be sufficient and returns SKB_ERROR BUFFER TOO SMALL out_buffer size Pointer to a variable that holds the size of the memory buffer in bytes where the output is to be stored For more details see the description of the out_buffer parameter You can actually point the in buffer and out_buffer to
164. the same memory buffer in which case the encrypted input data will be overwritten with the decrypted content Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 73 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 6 Decrypting PDF Files 6 3 5 SKB_Pdf_DecryptionContext_Release This function releases a PDF decryption context object from the memory You must always call this function when you have completed decrypting PDF object data and no longer need the PDF decryption context The function is declared as follows SKB_Result SKB_Pdf_DecryptionContext_Release SKB _Pdf_DecryptionContext ctx ctx iS a pointer to the SKB Pdf DecryptionContext object to be released Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 74 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference 7 API Reference This chapter provides full reference information about the SKB API 7 1 API Overview The SKB API is a C interface composed of a number of object classes Even though the interface is an ANSI C interface it adopts an object oriented style The header file declares a set of classes and class methods Each method of a class interface is a function whose first argument is a reference to an instance of the
165. thod sets public key buffer size to anumber of bytes that would be sufficient and returns SKB_ERROR BUFFER TOO SMALL For the SKB_KEY AGREEMENT ALGORITHM ECDH algorithm the public ey is stored using the format described in 88 5 For the SKB_KEY AGREEMENT ALGORITHM PRIME DH algorithm the buffer size is 128 bytes and it stores the public value encoded in big endian public_key buffer _size Pointer to a variable that holds the size of the memory buffer in bytes where the public key is to be stored For more details see the description of the public key buffer parameter 7 9 26 SKB_KeyAgreement_ComputeSecret This method takes the public key received from the other party of the key agreement algorithm and computes the shared secret The method is declared as follows SKB Result SKB KeyAgreement ComputeSecret SKB K yAgreement self const SKB Byte peer public key SKB Size peer public key size SKB_Size secret size SKB SecureData secret The following table explains the parameters Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 103 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description self Pointer to the previously created SKB _KeyAgreement Object which contains all the necessary parameters
166. to build SKB examples tests and Platform Specific Library This section describes how to set up the build environment compile the source code and run the compiled examples 2 3 4 1 Prerequisites To build the source files for Android you will need a computer with Android NDK installed For information on Android NDK requirements see 81 4 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 28 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 2 Building Applications Protected by SKB Make sure the Android NDK root directory is added to the system s PATH variable 2 3 4 2 Compiling To compile the source files proceed as follows 1 Go to one of the following directories depending on the architecture used Build Targets arm64 google android Build Targets arm google android Build Targets mips64 google android Build Targets mips google android Build Targets x86 64 google android Build Targets x86 google android 2 Execute the following command APP_OPTIM Specifies whether the binaries should be compiled in release or debug mode The following values can be set release default value debug The compiled binary files will be placed in the 1ibs directory 2 3 4 3 Running Once the files are compiled you can transfer the files to the Android device via the Android D
167. to gain any access to this User Guide Shall violate the Agreement and subject your company or other entity to liability therefor Copyright and Trademark Information Copyright 2000 2015 whiteCryption Corporation All rights reserved Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved whiteCryption and Cryptanium are either registered trademarks or trademarks of whiteCryption Corporation in the United States and or other countries Microsoft Visual Studio and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and or other countries OS X and Xcode are trademarks of Apple Inc registered in the United States and other countries IOS is a trademark or registered trademark of Cisco in the U S and other countries and is used under license Google is a registered trademark of Google Inc used with permission Android is a trademark of Google Inc registered in the United States and other countries PlayStation is a trademark or registered trademark of Sony Computer Entertainment Inc Sourcery CodeBench is a trademark of Mentor Graphics Corporati on Broadcom is a registered trademark of Broadcom Corporation Disclaimer The remainder of this User Guide notwithstanding this User Guide is provided as is without any warranty whatsoever including that it is error free o
168. ument Authentication is done only once typically when the PDF document is opened The user password is always handled as a secure data object in protected form 3 Derive the encryption key from the user password using the skB_Pdf ComputeEncryptionKey function see 86 3 2 Since the user password is not directly used for data decryption an encryption key needs to be derived This is done only once before any decryption is performed 4 Prepare a PDF decryption context represented by the SKB Pdf DecryptionContext Object using the SKB Pdf CreateDecryptionContext function see 86 3 3 A PDF decryption context must be created for every PDF object whose data you want to decrypt The context is passed to the decryption function The context holds a PDF object decryption key and optionally the initialization vector 5 Decrypt a buffer from a PDF object using the SKB _Pdf DecryptionContext ProcessBuffer function see 86 3 4 You can call this function as many times as necessary to decrypt the required parts of a PD object for which the PDF decryption context was created 6 When the PDF decryption context is no longer needed release it from the memory using the SKB Pdf DecryptionContext Release function see 86 3 5 The functions mentioned above are not considered part of the main SKB API Therefore they are defined in a separate header file SkbExtensions h which is located in the
169. unction is invoked For more information on this feature see 81 1 9 3 1 1 9 2 Supported Platforms Tamper resistant SKB libraries are currently available only for the following target platforms a Windows for Visual Studio 2010 2012 and 2013 x86 and x86_64 architectures a GNU Linux x86 and x86_64 architectures OS X x86 and x86_64 architectures iOS ARMv7 ARMv7s and ARMv8 architectures Android ARM and x86 architectures 1 1 9 3 Callback Functions When you request a tamper resistant edition of SKB you may optionally specify whether you want SKB to invoke specific callback functions when threats are detected If you do not choose to use callback functions SKB will corrupt the application state typically resulting in a crash whenever it detects a threat Callback functions allow you to implement custom response to attacks Additionally when requesting an SKB library that uses callback functions you may also specify if you want the attacked application to continue execution after a callback function is invoked If the SKB library that you received is configured to use callbacks you have to provide implementation for the callback functions in the source code The following table describes the attack types for which callback functions are supported Attack Callback function Description Debugger void SKB_ Callback AntiDebug This function is called by SKB when it detects that the
170. ureData self SKB DerivationAlgorithm algorithm const void parameters SKB SecureData data The following table explains the parameters Parameter Description self Pointer to the SKB_SecureData object from which a new skB_SecureData object needs to be derived algorithm Derivation algorithm to be used The available algorithms are defined in the SKB_DerivationAlgorithm enumeration see 87 11 5 Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 95 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description parameters Pointer to a structure containing parameters for the derivation algorithm For different algorithms a different structure must be provided If the SKB_DERIVATION ALGORITHM SLICE Or SKB DERIVATION ALGORITHM BLOCK SLICE algorithm is used this parameter must point to the SKB _SliceDerivationParameters structure which defines the range of bytes to be derived as a new SKB _SecureData Object see 87 10 17 If the SKB_DERIVATION ALGORITHM SELECT BYTES algorithm is used this parameter must point to the skB_SelectBytesDerivationParameters structure which provides the necessary input parameters see 87 10 9 If the SKB_DERIVATION ALGORITHM CIPHER algorithm is used this parameter must point to the SKB _Ci
171. usable Production The production package is given to customers who have licensed SKB Each production package has a unique export key and no expiration date 1 2 Supported Algorithms This section lists algorithms supported by SKB Note Not all distributions of SKB include all the algorithms listed below Function Algorithms Encryption DES in ECB mode no padding Triple DES in ECB mode no padding with two keying options All three keys are distinct Key 1 is the same as key 3 128 bit 196 bit and 256 bit AES in ECB mode no padding CBC mode no padding and CTR mode Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 16 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Function Algorithms Decryption DES in ECB mode no padding Triple DES in ECB mode no padding with two keying options All three keys are distinct Key 1 is the same as key 3 128 bit 196 bit and 256 bit AES in ECB mode no padding CBC mode no padding and CTR mode 1024 bit and 2048 bit RSA no padding PKCS 1 version 1 5 padding and OAEP padding ElGamal ECC for supported curve types see 81 3 Signing 128 bit AES CMAC based on OMAC1 HMA
172. ut data is to be stored For more details see the description of the output parameter 7 9 23 SKB_Cipher_ProcessBuffer This method performs either data encryption or decryption depending on the previously created SKB Cipher object see 87 8 3 The method is declared as follows SKB Result SKB Cipher ProcessBuffer SKB Cipher self const SKB Byte in buffer SKB Size in buffer size SKB Byte out_buffer SKB Size out_buffer size const SKB Byte iv SKB Size iv size The following table explains the parameters Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 100 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Parameter Description self Pointer to the previously created SKB Cipher object which contains all the necessary parameters in buffer Pointer to a buffer of data to be encrypted or decrypted For block ciphers this parameter must point to the beginning of a cipher block For the ElGamal ECC cipher this parameter must be a pointer to a buffer of bytes described in 88 4 in buffer size Size in bytes of the data buffer to be encrypted or decrypted For the DES and Triple DES cipher in the ECB mode this parameter must be a multiple of the cipher block size which is 8 bytes For the AES cipher in th
173. ved Secure Key Box User Guide 1 Introduction 1 1 2 Nomenclature nou mon man This User Guide uses the terms secure protect white box protected safe tamper resistance and variations of each to convey very specific concepts indeed concepts that are far more specific and limited in their meanings than many meanings often associated with such terms in everyday usage At the risk of stating the obvious as used herein none of these terms describe an absolute condition Use of SKB in compliance with this User Guide will not render any application or data absolutely secure absolutely protected or absolutely safe from unauthorized accessing use or manipulation Nor will it render any application or data absolutely tamper resistant In addition use of these terms is not intended to convey a promise or warranty that SKB will never contain a bug or error or that SKB will always operate without error As used in this User Guide secure and variations of secure refer to data objects the values of which reside in a cryptographic container and are white box protected and that can be operated on by SKB functions despite the fact that they are not revealed in plain form protected white box protected and variations of these terms mean that a value has been subjected to some cryptographic processing that has resulted in it being placed in a container that seeks to render the va
174. ven to the other party Then each party takes the other party s public key and generates a shared secret The shared secret is identical to both parties This algorithm is shown in the following diagram PARTY A PARTY B GENERATE THE PUBLIC KEY A PUBLIC KEY B GENERATE THE PUBLIC KEY 4 A PUBLIC KEY COMPUTE THE SHARED SECRET COMPUTE THE SHARED SECRET SHARED SECRET SHARED SECRET Key agreement algorithm To perform the key agreement algorithm using SKB proceed as follows 1 Create a key agreement object by calling the SKB Engine CreateKeyAgreement method and specify the necessary parameters as described in 87 9 11 2 Generate a public key by calling the skB_KeyAgreement_GetPublicKey method as described in 87 9 25 3 Exchange the public keys with the other party Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 47 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 3 Cryptographic Operations 4 With the other party s public key on hand compute the shared secret by calling the SKB KeyAgreement_ComputeSecret method as described in 87 9 26 5 Release the key agreement object when it is no longer needed by calling the SKB _KeyAgreement Release method as described in 87 9 27 3 16 Binding Keys to a Specific Device Normally keys exported by SKB can be imported by any other SKB instance that has the same
175. whiteCryption Secure Box 4 20 Secure Key Box User Guide Last updated March 9 2015 The software referenced herein this User Guide and any associated documentation is provided to you pursuant to the agreement between your company governmental body or other entity you and whiteCryption Corporation whiteCryption under which you have received a copy of Secure Key Box Licensed Technology and various related documentation including this User Guide such agreement the Agreement Defined terms not defined herein shall have the meanings ascribed to them in the Agreement In the event of conflict between the terms of this User Guide and the terms of the Agreement the terms of the Agreement Shall prevail Without limiting the generality of the remainder of this paragraph a this User Guide is provided to you for informational purposes only b your right to access view use and copy this User Guide is limited to the rights and subject to the applicable requirements and limitations set forth in the Agreement and c all of the content of this User Guide constitutes Confidential Information of whiteCryption or the equivalent term used in the Agreement and is subject to all of the limitations and requirements pertinent to the use disclosure and safeguarding of such information Permitting anyone who is not directly involved in the authorized use of Secure Key Box Licensed Technology by your company or other entity
176. will be created by this method 7 9 10 SKB_Engine_CreateCipher This method creates a new skB_Cipher object based on the provided parameters The SKB Cipher object is used to encrypt or decrypt data The method is declared as follows Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 88 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference SKB Result SKB Engin _CreateCipher SKB Engine self SKB CipherAlgorithm cipher algorithm SKB CipherDirection cipher direction unsigned int cipher flags const void cipher parameters const SKB SecureData cipher key SKB Cipher cipher The following table explains the parameters Parameter Description self Pointer to the pre initialized engine cipher algorithm Algorithm to be used for encrypting or decrypting data Available algorithms are defined in the skB_CipherAlgorithm enumeration see 87 113 cipher direction Parameter that specifies whether the provided data should be encrypted or decrypted Available directions are defined in the SKB_CipherDirection enumeration see 87 11 6 Encryption is supported only for the DES Triple DES and AES ciphers cipher flags Optional flags for the cipher T Currently the only defined flag is SkB_CIPHER_FLAG_ HIGH SPEED Thi
177. wo environments The unsafe environment on the left is where potentially anyone can gain access to the hardware code and memory of the device such as a desktop computer or mobile device This is the environment where SKB is primarily intended to be used dh asa general rule secret cryptographic keys should never appear in unsafe environments in plain form The safe environment on the right is a place where cryptographic keys will be exposed in plain form and that you must maintain as safe as possible in terms of potential risks of breaking in reverse engineering and exposure to unwelcome parties such as a closed off facility or encrypted server with controlled access The following table explains the four methods of loading the first key into SKB highlighted in the diagram Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 12 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction Method Description Reference 1 Import from plain SKB directly loads a plain key within an insecure environment 83 2 dh This is an insecure approach for loading keys and should be avoided if possible In normal circumstances importing of plain keys is disabled in SKB 2 Import SKB loads a key in protected form encrypted with the export 83 6 ey as described in 81 1 6 The protected form of a key can b
178. yptographic keys exported from the protected SKB domain into the unprotected outside world The same export key is used for importing and decrypting the exported data back into SKB SECURE KEY BOX EXPORT KEY St ENCRYPTION DECRYPTION Using an export key The export key is embedded inside the SKB package and is white box protected which means that it is not revealed in plain form in the program code or memory Exported data can only be imported into an SKB instance that has the same export key Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 11 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 1 Introduction 1 1 7 Loading the First Key Typically if you need to load a new key you encrypt it with another key pass it to SKB and then internally decrypt it as a new secure data object However at some point the first key needs to be loaded into SKB The challenge is to safely deliver this key into SKB without revealing it in plain form The following diagram shows four ways how the first key can be obtained UNSAFE ENVIRONMENT SAFE ENVIRONMENT SECURE KEY BOX INSECURE a PLAIN KEY PROTECTED KEY KEYEXPORT TOOL oR of SENSITIVE OPERATIONS PLAIN KEY EXPORTED KEY HERAN PROTECTED KEY PUBLIC KEY PROTECTED KEY Four ways of loading the first cryptographic key into SKB The diagram features t
179. zed and therefore they should not be shared between multiple threads However there are two exceptions to this rule The SKB Engine Object is thread safe and can be shared between multiple threads using the SKB Engine GetInstance method see 87 9 1 This method will always return the same SKB_Engine instance Copyright 2000 2015 whiteCryption Corporation All rights reserved Page 77 of 137 Copyright 2004 2015 Intertrust Technologies Corporation All rights reserved Secure Key Box User Guide 7 API Reference Since the SKB SecureData object is immutable it can also be shared between multiple threads 7 7 Overriding Memory Allocation Operators You may want to override the new and delete operators to implement custom memory allocation for your application To successfully achieve this you must take into account that SKB uses the non throwing new operator for memory allocation Assume you have the following code for overriding the new and delete operators void operator new size t size your implementation void operator new size t size your implementation void operator delete void ptr K your implementation void operator delete void ptr your implementation SKB requires that you also provide the following implementations for the non throwing operators void operator new size_t size const std nothrow t amp return operator new size

Secure Key Box User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents