PS3 Full 3.40 SDK Out, Sony PlayStation 3 SDK Leaked by Duplex!

libsecure (Cryptography and Security) Overview
� 2010 Sony Computer Entertainment Inc. All Rights Reserved. SCE Confidential
SCE CONFIDENTIAL
Table of Contents
1 Library Overview ............................................................................................................................. 3
Overview .............................................................................................................................................. 3
Related Files ........................................................................................................................................ 3
Sample Programs................................................................................................................................. 3
2 Usage Overview .............................................................................................................................. 5
Initialization Process ............................................................................................................................ 5
Cryptography ........................................................................................................................................ 6
Message Authentication Process ......................................................................................................... 9
Library Termination ............................................................................................................................. 11 �SCEI libsecure Library Release 2.0.0
- 2 -
SCE CONFIDENTIAL
1
Library Overview
Overview
This document provides an overview of the libsecure library and describes its use from a developer's point of view.
The libsecure library is a cross-platform API which may be used on PlayStation®Portable, PLAYSTATION®3. It provides cryptography functionalities (encryption and decryption methods) and security functionalities (such as hash calculation and message authentication).
The ciphers supported by the library include AES, Blowfish, TEA, XTEA and RSA. The hash methods supported by the library include MD5 and SHA-1.
Related Files
In order to use the libsecure library, you must have the following files:
File name
Description
libsecure.h
Header file
libsecure.a
Static library file
libSceSecure.sprx
libSceSecure_stub.a
Library module file
Stub library file
Note: the .a and .sprx files are located in the lib/ps3 directory, and the .h file is located in the Include directory.
libsecure can be used by linking the static library file within your build or by loading the library module in your application before using it.
On PlayStation®Portable and PLAYSTATION®3 systems, the MD5 and SHA-1 libraries provided in the appropriate SDK are required to use the libsecure library as well if you are linking statically (using the libsecure.a file).
File name
Description
libmd5.a
Platform specific library file for MD5
libsha1.a
Platform specific library file for SHA-1
Sample Programs
Four samples are available in the libsecure Samples directory of the libsecure package. They illustrate the usage of the libsecure library:
•
cipher - Sample that demonstrates the cryptography functionality API usage
•
cipherfw - Sample that demonstrates how to expand the cryptography methods
•
hash - Sample that demonstrates the security functionality API usage
•
hashfw - Sample that demonstrates how to expand the hash methods
samples/ps3/cipher/
This sample program demonstrates the encryption and decryption of a single message block using the libsecure API functions.
samples/ps3/cipherfw/
This sample program demonstrates how to create additional ciphers which can be used for the encryption and decryption of a single message block.
�SCEI libsecure Library Release 2.0.0
- 3 -
SCE CONFIDENTIAL
samples/ps3/hash/
This sample demonstrates the hash calculation and the authentication of a message using the libsecure API functions.
samples/ps3/hashfw/
This sample program demonstrates how to create additional hash methods which can be used for the hash calculation and authentication of a message.
�SCEI libsecure Library Release 2.0.0
- 4 -
SCE CONFIDENTIAL
2
Usage Overview
The walkthrough, described below, illustrates the most basic usage of the library. The purpose of the walkthrough is to encrypt and decrypt a message and to ensure that a message has not been tampered with.
Initialization Process
The first step is to call the sceLibSecureInit function. This requires a memory block provided with the structure SceLibSecureBlock and some flags detailing which functionality of the library are used.
The memory block should be at least 72 bytes (when using only one cipher method and one hash method), but the recommended size would be 512 bytes to use the libsecure library to its full potential.
The flags tell what functionality can be used after the initialization. The flags' descriptions are given in the table below:
Flag
Description
SCE_LIBSECURE_FLAGS_CIPHER_TEA
Specify this flag if you need the TEA cipher for encrypting messages
SCE_LIBSECURE_FLAGS_CIPHER_XTEA
Specify this flag if you need the XTEA cipher for encrypting messages
SCE_LIBSECURE_FLAGS_CIPHER_BLOWFISH
Specify this flag if you need the Blowfish cipher for encrypting messages
SCE_LIBSECURE_FLAGS_CIPHER_AES
Specify this flag if you need the AES cipher for encrypting messages
SCE_LIBSECURE_FLAGS_CIPHER_RSA
Specify this flag if you need the RSA cipher for encrypting messages
SCE_LIBSECURE_FLAGS_HASH_SHA1
Specify this flag if you need the SHA1 hash methods for message authentication
SCE_LIBSECURE_FLAGS_HASH_MD5
Specify this flag if you need the MD5 hash methods for message authentication
SCE_LIBSECURE_FLAGS_HASH_SHA256
Specify this flag if you need the SHA256 hash methods for message authentication
SCE_LIBSECURE_FLAGS_HASH_SHA384
Specify this flag if you need the SHA384 hash methods for message authentication
SCE_LIBSECURE_FLAGS_HASH_SHA512
Specify this flag if you need the SHA512 hash methods for message authentication
SCE_LIBSECURE_FLAGS_RANDOM_GENERATOR
Specify this flag if you need to generate random messages
For the purpose of this overview, we will initialize the library and we will use the random generator messages, the AES encryption and the SHA1 hash method:
SceLibSecureErrorType error;
SceLibSecureBlock runtimemem;
/* Allocate a 1KB memory block */
runtimemem.length = 1*1024;
runtimemem.pointer = malloc(runtimemem.length);
if(runtimemem.pointer != NULL)
{
/* Initialize the library */
error = sceLibSecureInit(SCE_LIBSECURE__FLAGS_CIPHER_AES |
SCE_LIBSECURE_FLAGS_HASH_SHA1 |
SCE_LIBSECURE_FLAGS_RANDOM_GENERATOR, &runtimemem);

�SCEI libsecure Library Release 2.0.0
}
- 5 -
SCE CONFIDENTIAL
Cryptography
The library supports symmetric and asymmetric ciphers. The ciphers included in the library are listed in the table below:
�SCEI libsecure Library Release 2.0.0
- 6 -
SCE CONFIDENTIAL
�SCEI libsecure Library Release 2.0.0
Cipher
Name
Type
AES
Advanced Encryption Standard
Symmetric
Blowfish
Blowfish
Symmetric
TEA
Tiny Encryption Algorithm
Symmetric
XTEA
eXtended TEA
Symmetric
RSA
Ron Rivest, Adi Shamir and Leonard Adleman
Asymmetric
The library manages different block cipher modes and does not depend on the cipher used for the encryption and decryption. Depending on the type of data access you require (sequential or direct access), you use a different block cipher mode. The list of the block cipher modes supported by the library is shown below:
Mode
Name
Data access
ECB
Electronic code book
Direct for encryption and decryption
CBC
Cipher block chaining
Sequential for encryption, direct for decryption
PCBC
Propagating cipher block chaining
Sequential for encryption and decryption
CFB
Cipher feedback
Sequential for encryption, direct for decryption
OFB
Output feedback
Sequential for encryption and decryption
CTR
Counter
Direct for encryption and decryption
Using the ECB mode may be a poor choice when you are encrypting and decrypting more than one block of data and it is not advised to use it for a long sequence of data.
Because ciphers work on units of a fixed size (depending on the cipher used and for others depending on the key size), but messages vary in length, the library manages padding to allow certain messages to be encrypted and decrypted without any problems. Padding is used depending mainly on the cipher or type of cipher used to encrypt and to decrypt data, and can be used in conjunction with other ones. The list of padding modes supported by the library is shown below:
Padding
Description
Cipher use
None
No padding is performed on the message and the remaining incomplete block is not encrypted or decrypted.
All symmetric ciphers
Normal
No padding is performed on the message and the remaining incomplete block may be encrypted or decrypted (depends on the block cipher mode).
All symmetric ciphers (NB: the last incomplete block will be encrypted for CFB, OFB and CTR block cipher modes)
Stealing
No padding is performed on the message and the remaining incomplete block is encrypted or decrypted using the stealing method.
All symmetric ciphers (NB: the last incomplete block will be encrypted for ECB, CBC and PCBC block cipher modes)
Residual block termination
No padding is performed on the message and the remaining incomplete block is encrypted or decrypted using the CBC block cipher mode.
All symmetric ciphers
Nils
The remaining incomplete block is filled with zero values.
All symmetric ciphers
Spaces
The remaining incomplete block is filled with spaces.
All symmetric ciphers
Random
The remaining incomplete block is filled with random values.
All symmetric ciphers
Size
The remaining incomplete block is filled with values equal to the size of the incomplete block.
All symmetric ciphers
Nil size
The remaining incomplete block is filled with zero values except the last one being the size of the incomplete block.
All symmetric ciphers
- 7 -
SCE CONFIDENTIAL
�SCEI libsecure Library Release 2.0.0
Padding Description Cipher use
Bit
The remaining incomplete block is filled with bit 0 except the last one being a bit 1.
All symmetric ciphers
PKCS#1
The padding used complies with the PKCS#1 v2.1 standard.
RSA cipher
OAEP
The padding used complies with the 'Optimal Asymmetric Encryption Padding' standard.
RSA cipher
A context may be needed depending on the cipher and the block cipher mode used before the encryption or decryption process.
The first step is to retrieve the context size if one is required. Retrieving the context size requires the cipher used, the block cipher mode, the key, the number of rounds (only required for TEA, XTEA and Blowfish ciphers):
u8 array_key[16]= { 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff, 0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99 };
SceLibSecureSymmetricKey key = { sizeof(array_key), array_key };
size_t context_size;
SceLibSecureErrorType error;
/* Retrieve the context size */
error = sceLibSecureCryptographyGetContextSize(SCE_LIBSECURE_CIPHER_AES,
SCE_LIBSECURE_BLOCKCIPHERMODE_ECB, &key, 0, &context_size);
if(error != SCE_LIBSECURE_OK)
{
/* Error management */

}
The second step is to set the context according to the parameters passed when retrieving the context size. Depending on the block cipher mode used, you may also specify an initialization vector (IV) and a file offset (used for CTR only).
SceLibSecureErrorType error;
SceLibSecureBlock context;
/* Allocate the context */
context.length = context_size;
context.pointer = malloc(context.length);
if(context.pointer != NULL)
{
/* Set the context */
error = sceLibSecureCryptographySetContext(&context,
SCE_LIBSECURE_CIPHER_AES, SCE_LIBSECURE_BLOCKCIPHERMODE_ECB,
&key, 0, NULL, 0);

}
Finally, the encryption and decryption process begins. You need to prepare the block or the message (succession of blocks) you want to encrypt or decrypt. The message or the block length is required to match the cipher block size, which may be retrieved by calling the sceLibSecureCryptographyGetBlockSize function. This function requires the cipher, the key (SceLibSecureSymmetricKey for symmetric ciphers, and SceLibSecureAsymmetricKey for asymmetric ciphers) and the padding scheme used:
SceLibSecureErrorType error;
SceLibSecureSymmetricKey key = { sizeof(array_key), array_key };
size_t block_size;
- 8 -
SCE CONFIDENTIAL
/* Retrieve the block size */
error = SceLibSecureCryptographyGetBlockSize(SCE_LIBSECURE_CIPHER_AES, &key,
SCE_LIBSECURE_PADDING_NONE, &block_size)
if(error != SCE_LIBSECURE_OK)
{
/* Error management */

}
Now you just need to retrieve the block matching the block size, or the message which must be a multiple of the block size. (If the message is not a multiple of the block size, you need to apply a padding scheme to the message before the encryption process. Please refer to the reference guide for information on this process.) Then call the sceLibSecureCryptographyEncrypt or sceLibSecureCryptographyDecrypt function:
SceLibSecureErrorType error;
u8 array_message[message_size];
SceLibSecureMessage message = { array_message , sizeof(array_message) };
/* Generate a random message */
error = sceLibSecureRandom(&message);
if(error == SCE_LIBSECURE_OK)
{
/* Encrypt the message */
error = sceLibSecureCryptographyEncrypt(&context, &message,
SCE_LIBSECURE_PADDING_NONE);
if(error != SCE_LIBSECURE_OK)
{
/* Error management */

}
/* Decrypt the message */
error = sceLibSecureCryptographyDecrypt(&context, &message,
SCE_LIBSECURE_PADDING_NONE);
if(error != SCE_LIBSECURE_OK)
{
/* Error management */

}
}
It is good practice to destroy the context used previously so that the data used to retrieve the original message is not used. It is also good practice if you do not plan to reuse the same context to continue the encryption or the decryption process. This is done easily using the sceLibSecureCryptographyDeleteContext function:
SceLibSecureErrorType error;
/* Destroy the context */
error = sceLibSecureCryptographyDeleteContext(&context);

Message Authentication Process
The encryption and decryption of a message may be affected in messages that are tampered with. A message authentication can be used to ensure a message is signed and has not been tampered with. It uses the hash functionality of the library, a key and the message to authenticate it and it returns an HMAC value which is then used by the receiver of the message to ensure it has not been tampered with.
The library supports different hash functions and additional hash functions can be added to the library by the developer. A list of the ciphers included in the library is shown in the table below:
�SCEI libsecure Library Release 2.0.0
- 9 -
SCE CONFIDENTIAL
Hash
Name
MD5
MD5 Message Digest Algorithm
SHA-1
SHA-1 Secure Hash Algorithm
SHA-256
SHA-256 Secure Hash Algorithm
SHA-384
SHA-384 Secure Hash Algorithm
SHA-512
SHA-512 Secure Hash Algorithm
A context is always required to use the hash functionality provided by the library.
The first step is to retrieve the context size and the digest size (which is the same as the HMAC value). Retrieving the context size or the digest size requires the hash:
SceLibSecureErrorType error;
size_t context_size, digest_size;
/* Retrieve the context size */
error = sceLibSecureHashGetContextSize(SCE_LIBSECURE_HASH_SHA1,
&context_size);
if(error != SCE_LIBSECURE_OK)
{
/* Error management */

}
/* Retrieve the digest size */
error = sceLibSecureHashGetDigestSize(SCE_LIBSECURE_HASH_SHA1,
&digest_size);
if(error != SCE_LIBSECURE_OK)
{
/* Error management */

}
The second step is to set the context according to the parameters passed when retrieving the context size, and to allocate the memory for the HMAC value:
SceLibSecureErrorType error;
SceLibSecureBlock context;
SceLibSecureHmac hmac;
/* Allocate the context */
context.length = context_size;
context.pointer = malloc(context.length);
/* Allocate the HMAC */
hmac.length = digest_size;
hmac.pointer = malloc(hmac.length);
if(context.pointer != NULL && hmac.pointer != NULL)
{
/* Set the context */
error = sceLibSecureHashSetContext(&context, SCE_LIBSECURE_HASH_SHA1);

}
Finally, you need to process the message you want to authenticate by using the sceLibSecureHashHmac function. This function requires the context, the key (SceLibSecureSymmetricKey for symmetric ciphers, and SceLibSecureAsymmetricKey for asymmetric ciphers) and the message:
SceLibSecureErrorType error;
/* Authenticate the message */
�SCEI libsecure Library Release 2.0.0
- 10 -
SCE CONFIDENTIAL
�SCEI libsecure Library Release 2.0.0
- 11 -
error = sceLibSecureHashHmac(&context, &hmac, &key, &message);
if(error != SCE_LIBSECURE_OK)
{
/* Error management */

}
It is good practice to destroy the context used previously, to avoid the data being used or if you do not plan to reuse the same context to continue the encryption or the decryption process. This is done easily using the sceLibSecureHashDeleteContext function:
SceLibSecureErrorType error;
/* Destroy the context */
error = sceLibSecureHashDeleteContext(&context);

Library Termination
The process of fully terminating the library is performed by calling the sceLibSecureDestroy function. This function ensures that the library has cleared the memory used.
/* Destroy the library */
error = sceLibSecureDestroy();