Renesas Secure IP (r_rsip_protected)

Functions
fsp_err_t	R_RSIP_Open (rsip_ctrl_t *const p_ctrl, rsip_cfg_t const *const p_cfg)
fsp_err_t	R_RSIP_Close (rsip_ctrl_t *const p_ctrl)
fsp_err_t	R_RSIP_RandomNumberGenerate (rsip_ctrl_t *const p_ctrl, uint8_t *const p_random)
fsp_err_t	R_RSIP_KeyGenerate (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t *const p_wrapped_key)
fsp_err_t	R_RSIP_KeyPairGenerate (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t *const p_wrapped_public_key, rsip_wrapped_key_t *const p_wrapped_private_key)
fsp_err_t	R_RSIP_EncryptedKeyWrap (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_key_update_key, void const *const p_initial_vector, void const *const p_encrypted_key, rsip_wrapped_key_t *const p_wrapped_key)
fsp_err_t	R_RSIP_RFC3394_KeyWrap (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_kek, rsip_wrapped_key_t const *const p_wrapped_target_key, uint8_t *const p_rfc3394_wrapped_target_key)
fsp_err_t	R_RSIP_RFC3394_KeyUnwrap (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_kek, uint8_t const *const p_rfc3394_wrapped_target_key, rsip_wrapped_key_t *const p_wrapped_target_key)
fsp_err_t	R_RSIP_PublicKeyExport (rsip_wrapped_key_t const *const p_wrapped_public_key, uint8_t *const p_raw_public_key)
fsp_err_t	R_RSIP_AES_Cipher_Init (rsip_ctrl_t *const p_ctrl, rsip_aes_cipher_mode_t const mode, rsip_wrapped_key_t const *const p_wrapped_key, uint8_t const *const p_initial_vector)
fsp_err_t	R_RSIP_AES_Cipher_Update (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_input, uint8_t *const p_output, uint32_t const length)
fsp_err_t	R_RSIP_AES_Cipher_Finish (rsip_ctrl_t *const p_ctrl)
fsp_err_t	R_RSIP_AES_AEAD_Init (rsip_ctrl_t *const p_ctrl, rsip_aes_aead_mode_t mode, rsip_wrapped_key_t const *const p_wrapped_key, uint8_t const *const p_nonce, uint32_t const nonce_length)
fsp_err_t	R_RSIP_AES_AEAD_LengthsSet (rsip_ctrl_t *const p_ctrl, uint32_t const total_aad_length, uint32_t const total_text_length, uint32_t const tag_length)
fsp_err_t	R_RSIP_AES_AEAD_AADUpdate (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_aad, uint32_t const aad_length)
fsp_err_t	R_RSIP_AES_AEAD_Update (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_input, uint32_t const input_length, uint8_t *const p_output, uint32_t *const p_output_length)
fsp_err_t	R_RSIP_AES_AEAD_Finish (rsip_ctrl_t *const p_ctrl, uint8_t *const p_output, uint32_t *const p_output_length, uint8_t *const p_tag)
fsp_err_t	R_RSIP_AES_AEAD_Verify (rsip_ctrl_t *const p_ctrl, uint8_t *const p_output, uint32_t *const p_output_length, uint8_t const *const p_tag, uint32_t const tag_length)
fsp_err_t	R_RSIP_AES_MAC_Init (rsip_ctrl_t *const p_ctrl, rsip_aes_mac_mode_t const mode, rsip_wrapped_key_t const *const p_wrapped_key)
fsp_err_t	R_RSIP_AES_MAC_Update (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_message, uint32_t const message_length)
fsp_err_t	R_RSIP_AES_MAC_SignFinish (rsip_ctrl_t *const p_ctrl, uint8_t *const p_mac)
fsp_err_t	R_RSIP_AES_MAC_VerifyFinish (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_mac, uint32_t const mac_length)
fsp_err_t	R_RSIP_ECDSA_Sign (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, uint8_t const *const p_hash, uint8_t *const p_signature)
fsp_err_t	R_RSIP_ECDSA_Verify (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, uint8_t const *const p_hash, uint8_t const *const p_signature)
fsp_err_t	R_RSIP_PKI_ECDSA_CertVerify (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, uint8_t const *const p_hash, uint8_t const *const p_signature)
fsp_err_t	R_RSIP_PureEdDSA_Sign (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, rsip_wrapped_key_t const *const p_wrapped_public_key, uint8_t const *const p_message, uint64_t const message_length, uint8_t *const p_signature)
fsp_err_t	R_RSIP_PureEdDSA_Verify (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, uint8_t const *const p_message, uint64_t const message_length, uint8_t const *const p_signature)
fsp_err_t	R_RSIP_ECDH_KeyAgree (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, rsip_wrapped_key_t const *const p_wrapped_public_key, rsip_wrapped_secret_t *const p_wrapped_secret)
fsp_err_t	R_RSIP_ECDH_PlainKeyAgree (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, uint8_t const *const p_plain_public_key, rsip_wrapped_secret_t *const p_wrapped_secret)
fsp_err_t	R_RSIP_KDF_SHA_Init (rsip_ctrl_t *const p_ctrl, rsip_hash_type_t const hash_type)
fsp_err_t	R_RSIP_KDF_SHA_ECDHSecretUpdate (rsip_ctrl_t *const p_ctrl, rsip_wrapped_secret_t const *const p_wrapped_secret)
fsp_err_t	R_RSIP_KDF_SHA_Update (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_message, uint32_t const message_length)
fsp_err_t	R_RSIP_KDF_SHA_Finish (rsip_ctrl_t *const p_ctrl, rsip_wrapped_dkm_t *const p_wrapped_dkm)
fsp_err_t	R_RSIP_KDF_SHA_Suspend (rsip_ctrl_t *const p_ctrl, rsip_kdf_sha_handle_t *const p_handle)
fsp_err_t	R_RSIP_KDF_SHA_Resume (rsip_ctrl_t *const p_ctrl, rsip_kdf_sha_handle_t const *const p_handle)
fsp_err_t	R_RSIP_KDF_HMAC_DKMKeyImport (rsip_ctrl_t *const p_ctrl, rsip_wrapped_dkm_t const *const p_wrapped_dkm, uint32_t const key_length, rsip_wrapped_key_t *const p_wrapped_key)
fsp_err_t	R_RSIP_KDF_HMAC_ECDHSecretKeyImport (rsip_ctrl_t *const p_ctrl, rsip_wrapped_secret_t const *const p_wrapped_secret, rsip_wrapped_key_t *const p_wrapped_key)
fsp_err_t	R_RSIP_KDF_HMAC_Init (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_key)
fsp_err_t	R_RSIP_KDF_HMAC_DKMUpdate (rsip_ctrl_t *const p_ctrl, rsip_wrapped_dkm_t const *const p_wrapped_dkm)
fsp_err_t	R_RSIP_KDF_HMAC_ECDHSecretUpdate (rsip_ctrl_t *const p_ctrl, rsip_wrapped_secret_t const *const p_wrapped_secret)
fsp_err_t	R_RSIP_KDF_HMAC_Update (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_message, uint32_t const message_length)
fsp_err_t	R_RSIP_KDF_HMAC_SignFinish (rsip_ctrl_t *const p_ctrl, rsip_wrapped_dkm_t *const p_wrapped_dkm)
fsp_err_t	R_RSIP_KDF_HMAC_Suspend (rsip_ctrl_t *const p_ctrl, rsip_kdf_hmac_handle_t *const p_handle)
fsp_err_t	R_RSIP_KDF_HMAC_Resume (rsip_ctrl_t *const p_ctrl, rsip_kdf_hmac_handle_t const *const p_handle)
fsp_err_t	R_RSIP_KDF_DKMConcatenate (rsip_wrapped_dkm_t *const p_wrapped_dkm1, rsip_wrapped_dkm_t const *const p_wrapped_dkm2, uint32_t const wrapped_dkm1_buffer_length)
fsp_err_t	R_RSIP_KDF_DerivedKeyImport (rsip_ctrl_t *const p_ctrl, rsip_wrapped_dkm_t const *const p_wrapped_dkm, uint32_t const position, rsip_wrapped_key_t *const p_wrapped_key)
fsp_err_t	R_RSIP_KDF_DerivedIVWrap (rsip_ctrl_t *const p_ctrl, rsip_wrapped_dkm_t const *const p_wrapped_dkm, rsip_initial_vector_type_t const initial_vector_type, uint32_t const position, uint8_t const *const p_tls_sequence_num, uint8_t *const p_wrapped_initial_vector)
fsp_err_t	R_RSIP_OTF_Init (rsip_ctrl_t *const p_ctrl, rsip_otf_channel_t const channel, rsip_wrapped_key_t *const p_wrapped_key, uint8_t const *const p_seed)
fsp_err_t	R_RSIP_PKI_VerifiedCertInfoExport (rsip_ctrl_t *const p_ctrl, rsip_verified_cert_info_t *const p_verified_cert_info)
fsp_err_t	R_RSIP_PKI_VerifiedCertInfoImport (rsip_ctrl_t *const p_ctrl, rsip_verified_cert_info_t const *const p_verified_cert_info)
fsp_err_t	R_RSIP_PKI_CertKeyImport (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_cert, uint32_t const cert_length, uint8_t const *const p_key_param1, uint32_t const key_param1_length, uint8_t const *const p_key_param2, uint32_t const key_param2_length, rsip_hash_type_t const hash_function, rsip_wrapped_key_t *const p_wrapped_public_key)
fsp_err_t	R_RSIP_RSA_Encrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, uint8_t const *const p_plain, uint8_t *const p_cipher)
fsp_err_t	R_RSIP_RSA_Decrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, uint8_t const *const p_cipher, uint8_t *const p_plain)
fsp_err_t	R_RSIP_RSAES_PKCS1_V1_5_Encrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, uint8_t const *const p_plain, uint32_t const plain_length, uint8_t *const p_cipher)
fsp_err_t	R_RSIP_RSAES_PKCS1_V1_5_Decrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, uint8_t const *const p_cipher, uint8_t *const p_plain, uint32_t *const p_plain_length, uint32_t const plain_buffer_length)
fsp_err_t	R_RSIP_RSAES_OAEP_Encrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, rsip_hash_type_t const hash_function, rsip_mgf_type_t const mask_generation_function, uint8_t const *const p_label, uint32_t const label_length, uint8_t const *const p_plain, uint32_t const plain_length, uint8_t *const p_cipher)
fsp_err_t	R_RSIP_RSAES_OAEP_Decrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, rsip_hash_type_t const hash_function, rsip_mgf_type_t const mask_generation_function, uint8_t const *const p_label, uint32_t const label_length, uint8_t const *const p_cipher, uint8_t *const p_plain, uint32_t *const p_plain_length, uint32_t const plain_buffer_length)
fsp_err_t	R_RSIP_RSASSA_PKCS1_V1_5_Sign (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, rsip_hash_type_t const hash_function, uint8_t const *const p_hash, uint8_t *const p_signature)
fsp_err_t	R_RSIP_RSASSA_PKCS1_V1_5_Verify (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, rsip_hash_type_t const hash_function, uint8_t const *const p_hash, uint8_t const *const p_signature)
fsp_err_t	R_RSIP_RSASSA_PSS_Sign (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, rsip_hash_type_t const hash_function, rsip_mgf_type_t const mask_generation_function, uint32_t const salt_length, uint8_t const *const p_hash, uint8_t *const p_signature)
fsp_err_t	R_RSIP_RSASSA_PSS_Verify (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, rsip_hash_type_t const hash_function, rsip_mgf_type_t const mask_generation_function, uint32_t const salt_length, uint8_t const *const p_hash, uint8_t const *const p_signature)
fsp_err_t	R_RSIP_PKI_RSASSA_PKCS1_V1_5_CertVerify (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, rsip_hash_type_t const hash_function, uint8_t const *const p_hash, uint8_t const *const p_signature)
fsp_err_t	R_RSIP_PKI_RSASSA_PSS_CertVerify (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, rsip_hash_type_t const hash_function, rsip_mgf_type_t const mask_generation_function, uint32_t const salt_length, uint8_t const *const p_hash, uint8_t const *const p_signature)
fsp_err_t	R_RSIP_SHA_Compute (rsip_ctrl_t *const p_ctrl, rsip_hash_type_t const hash_type, uint8_t const *const p_message, uint32_t const message_length, uint8_t *const p_digest)
fsp_err_t	R_RSIP_SHA_Init (rsip_ctrl_t *const p_ctrl, rsip_hash_type_t const hash_type)
fsp_err_t	R_RSIP_SHA_Update (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_message, uint32_t const message_length)
fsp_err_t	R_RSIP_SHA_Finish (rsip_ctrl_t *const p_ctrl, uint8_t *const p_digest)
fsp_err_t	R_RSIP_SHA_Suspend (rsip_ctrl_t *const p_ctrl, rsip_sha_handle_t *const p_handle)
fsp_err_t	R_RSIP_SHA_Resume (rsip_ctrl_t *const p_ctrl, rsip_sha_handle_t const *const p_handle)
fsp_err_t	R_RSIP_HMAC_Compute (rsip_ctrl_t *const p_ctrl, const rsip_wrapped_key_t *p_wrapped_key, uint8_t const *const p_message, uint32_t const message_length, uint8_t *const p_mac)
fsp_err_t	R_RSIP_HMAC_Verify (rsip_ctrl_t *const p_ctrl, const rsip_wrapped_key_t *p_wrapped_key, uint8_t const *const p_message, uint32_t const message_length, uint8_t const *const p_mac, uint32_t const mac_length)
fsp_err_t	R_RSIP_HMAC_Init (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_key)
fsp_err_t	R_RSIP_HMAC_Update (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_message, uint32_t const message_length)
fsp_err_t	R_RSIP_HMAC_SignFinish (rsip_ctrl_t *const p_ctrl, uint8_t *const p_mac)
fsp_err_t	R_RSIP_HMAC_VerifyFinish (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_mac, uint32_t const mac_length)
fsp_err_t	R_RSIP_HMAC_Suspend (rsip_ctrl_t *const p_ctrl, rsip_hmac_handle_t *const p_handle)
fsp_err_t	R_RSIP_HMAC_Resume (rsip_ctrl_t *const p_ctrl, rsip_hmac_handle_t const *const p_handle)
fsp_err_t	R_RSIP_InitialKeyWrap (rsip_ctrl_t *const p_ctrl, void const *const p_wrapped_user_factory_programming_key, void const *const p_initial_vector, void const *const p_encrypted_key, rsip_wrapped_key_t *const p_wrapped_key)
fsp_err_t	R_RSIP_SB_InitialCommonKeyWrap (rsip_ctrl_t *const p_ctrl, void const *const p_wrapped_user_factory_programming_key, void const *const p_initial_vector, void const *const p_encrypted_key, rsip_sb_common_key_t *const p_injected_key)
fsp_err_t	R_RSIP_AuthPasswordHashCompute (rsip_ctrl_t *const p_ctrl, void const *const p_wrapped_user_factory_programming_key, void const *const p_initial_vector, rsip_auth_type_t const authentication_type, void const *const p_encrypted_password, rsip_hashed_auth_password_t *const p_hashed_password)
fsp_err_t	R_RSIP_PKI_InitialRootCertWrap (rsip_ctrl_t *const p_ctrl, void const *const p_wrapped_user_factory_programming_key, void const *const p_initial_vector, void const *const p_encrypted_cert, uint32_t const cert_length, uint8_t *const p_cert, rsip_root_cert_mac_t *const p_cert_mac)
fsp_err_t	R_RSIP_PKI_RootCertKeyImport (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_cert, rsip_root_cert_mac_t const *const p_cert_mac, uint8_t const *const p_key_param1, uint32_t const key_param1_length, uint8_t const *const p_key_param2, uint32_t const key_param2_length, rsip_wrapped_key_t *const p_wrapped_public_key)
fsp_err_t	R_RSIP_KDF_TLS12PRFVerifyDataCompute (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_key, rsip_tls12_prf_label_t const label, uint8_t const *const p_hash, uint8_t *const p_verify_data)
fsp_err_t	R_RSIP_TLS12_RSAPremasterSecretGenerate (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t *const p_wrapped_premaster_secret)
fsp_err_t	R_RSIP_TLS12_RSAPremasterSecretEncrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_public_key, rsip_wrapped_key_t const *const p_wrapped_premaster_secret, uint8_t *const p_encrypted_premaster_secret)
fsp_err_t	R_RSIP_TLS12_RSAPremasterSecretDecrypt (rsip_ctrl_t *const p_ctrl, rsip_wrapped_key_t const *const p_wrapped_private_key, uint8_t const *const p_encrypted_premaster_secret, rsip_wrapped_key_t *const p_wrapped_premaster_secret)
fsp_err_t	R_RSIP_SB_ManifestVerify (rsip_ctrl_t *const p_ctrl, uint8_t const *const p_key_cert, uint32_t const key_cert_max_length, uint8_t const *const p_code_cert, uint32_t const code_cert_max_length)

Detailed Description

Driver for the Renesas Secure IP on RZ microprocessors. This module implements the RSIP Interface.

Overview

This library is a highly secure cryptographic driver using Renesas Secure IP, a peripheral function of RZ microprocessors, and is called RSIP driver.

The keys handled by the RSIP driver (keys to be input and keys to be output) are opaque keys wrapped in device-specific keys that can only be accessed by the Renesas Secure IP. Secure key management in the RSIP driver is achieved by wrapping the keys with device-specific keys, which enables key secrecy and tamper detection capabilities outside of the Renesas Secure IP. Only the Renesas Secure IP can unwrap the key, and the unwrapped key exists only inside the Renesas Secure IP during cryptographic operations. Because the key is wrapped with a device-specific key, even if the key is copied to another device, the key cannot be unwrapped by another device with a different device-specific key. Because keys can be securely managed in this way, a secure storage function can be built into user applications by encrypting data to be kept secret using symmetric cryptography such as AES and storing it in flash.

Unauthorized access monitoring by Renesas Secure IP covers all cryptographic operations provided by this driver and is always enabled during cryptographic operation. If the cryptographic operation tampering is detected during using this driver, this driver stops operation.

Features

The RSIP module supports for the following features.

For more information, please refer to these application notes.

Device group	Document number	Document title
RZ/T2M, RZ/T2L	R01AN6547EJ	RZ/T2, RZ/N2 Renesas Secure IP Driver
RZ/T2ME	R01AN7375EJ	RZ/T2ME Group Renesas Secure IP Driver
RZ/T2H	R01AN7451EJ	RZ/T2H and RZ/N2H Groups Renesas Secure IP Driver

• Key Management
  • Key import by key update key
  • Key generation and key pair generation
  • Public key export
• Random Number Generation
• Symmetric Cryptography
  • AES
    • Encryption
      • ECB/CBC/CTR/XTS
    • Authenticated Encryption with Associated Data (AEAD)
      • GCM
      • CCM
    • Message authentication code (MAC)
      • CMAC
• Asymmetric Cryptography
  • ECC
    • Signature
      • ECDSA
      • EdDSA
  • RSA
    • Cryptographic primitive
    • Encryption scheme
      • RSAES-OAEP
      • RSAES-PKCS1-v1_5
    • Signature scheme
      • RSASSA-PSS
      • RSASSA-PKCS1-v1_5
• Hash Functions
  • Message digest
    • SHA1, SHA2
  • Message authentication code (MAC)
    • HMAC (SHA-1, SHA-2)
• Key Agreement
  • ECDH
• Key Derivation
  • Key Derivation Function (KDF) using HMAC
  • Key Import by derived keying material
  • IV output by derived keying material
  • Computation of TLS1.2 verify_data
• TLS1.2 RSA Key Exchange
  • Premaster secret generation
  • Premaster secret encryption
  • Premaster secret decryption
• Public Key Infrastructure (PKI)
  • Certificate Verification
    • ECDSA
    • RSASSA-PSS
    • RSASSA-PKCS1-v1_5
  • Key Import from Certificate
    • ECC
    • RSA
• Secure boot and Secure Update
• Secure Provisioning
  • Key import by key wrap service
  • Root certificate import by key wrap service
  • Expected value (hash IDs) generation for JTAG and SCI/USB boot authentication
• On-the-Fly Decryption (OTFD)
  • Initializing

Supported devices

IP Type	Device group	Description
Type 1	RZ/T2M, RZ/T2ME, RZ/T2L	Computational speed per clock of ECC, RSA-3072 and RSA-4096 is lower than Type 2.
Type 2	RZ/T2H	-

Supported algorithms

The following algorithms are available on each devices.

To use the algorithm, enable it in the configuration and then specify it with arguments such as rsip_wrapped_key_t::type (rsip_key_type_t) or rsip_hash_type_t.

AES

Category	Function	Key I/O	AES-128	AES-192	AES-256
Key Management	R_RSIP_KeyGenerate()	out	Supported	-	Supported
Key Management	R_RSIP_EncryptedKeyWrap()	out	Supported	-	Supported
Key Management	R_RSIP_InitialKeyWrap()	out	Supported	-	Supported
Key Derivation	R_RSIP_KDF_DerivedKeyImport()	out	Supported	-	Supported
Key Wrap	R_RSIP_RFC3394_KeyWrap() (KEK)	in	Supported	-	Supported
Key Wrap	R_RSIP_RFC3394_KeyWrap() (Target Key)	in	Supported	-	Supported
Key Wrap	R_RSIP_RFC3394_KeyUnwrap() (KEK)	in	Supported	-	Supported
Key Wrap	R_RSIP_RFC3394_KeyUnwrap() (Target Key)	out	Supported	-	Supported
AES-ECB	R_RSIP_AES_Cipher_Init()	in	Supported	-	Supported
AES-CBC	R_RSIP_AES_Cipher_Init()	in	Supported	-	Supported
AES-CBC (wrapped IV)	R_RSIP_AES_Cipher_Init()	in	Supported	-	Supported
AES-CTR	R_RSIP_AES_Cipher_Init()	in	Supported	-	Supported
AES-GCM	R_RSIP_AES_AEAD_Init()	in	Supported	-	Supported
AES-GCM (wrapped IV)	R_RSIP_AES_AEAD_Init()	in	Supported	-	Supported
AES-CCM	R_RSIP_AES_AEAD_Init()	in	Supported	-	Supported
AES-CMAC	R_RSIP_AES_MAC_Init()	in	Supported	-	Supported
OTF Initialization	R_RSIP_OTF_Init()	in	Supported	-	Supported

XTS-AES

Category	Function	Key I/O	XTS-AES-128	XTS-AES-256
Key Management	R_RSIP_KeyGenerate()	out	Supported	Supported
Key management	R_RSIP_EncryptedKeyWrap()	out	Supported	Supported
Key Management	R_RSIP_InitialKeyWrap()	out	Supported	Supported
XTS-AES	R_RSIP_AES_Cipher_Init()	in	Supported	Supported

ECC - Weierstrass Curves

Category	Function	Key I/O	secp256r1	secp384r1	secp521r1	secp256k1	brainpoolP256r1	brainpoolP384r1	brainpoolP512r1
Key Management	R_RSIP_KeyPairGenerate()	out	Supported	Supported	-	-	Supported	Supported	-
Key Management	R_RSIP_EncryptedKeyWrap()	out	Supported	Supported	-	-	Supported	Supported	-
Key Management	R_RSIP_InitialKeyWrap()	out	Supported	Supported	-	-	Supported	Supported	-
Key Management	R_RSIP_PublicKeyExport()	in	Supported	Supported	-	-	Supported	Supported	-
ECDSA	R_RSIP_ECDSA_Sign()	in	Supported	Supported	-	-	Supported	Supported	-
ECDSA	R_RSIP_ECDSA_Verify()	in	Supported	Supported	-	-	Supported	Supported	-
PKI	R_RSIP_PKI_ECDSA_CertVerify()	in	Supported	-	-	-	-	-	-
PKI	R_RSIP_PKI_CertKeyImport()	out	Supported	-	-	-	-	-	-
PKI	R_RSIP_PKI_RootCertKeyImport()	out	Supported	-	-	-	-	-	-
ECDH	R_RSIP_ECDH_KeyAgree()	in	Supported	-	-	-	-	-	-
ECDH	R_RSIP_ECDH_PlainKeyAgree()	in	Supported	-	-	-	-	-	-

ECC - Twisted Edwards Curves

Category	Function	Key I/O	edwards25519
Key Management	R_RSIP_KeyPairGenerate()	out	Supported
Key Management	R_RSIP_EncryptedKeyWrap()	out	Supported
Key Management	R_RSIP_InitialKeyWrap()	out	Supported
Key Management	R_RSIP_PublicKeyExport()	in	Supported
EdDSA	R_RSIP_PureEdDSA_Sign()	in	Supported
EdDSA	R_RSIP_PureEdDSA_Verify()	in	Supported
PKI	R_RSIP_PKI_CertKeyImport()	out	-
PKI	R_RSIP_PKI_RootCertKeyImport()	out	-

RSA

Category	Function	Key I/O	RSA-1024	RSA-2048	RSA-3072	RSA-4096
Key Management	R_RSIP_KeyPairGenerate()	out	Supported	Supported	Supported	Supported
Key Management	R_RSIP_EncryptedKeyWrap()	out	Supported	Supported	Supported	Supported
Key Management	R_RSIP_InitialKeyWrap()	out	Supported	Supported	Supported	Supported
Key Management	R_RSIP_PublicKeyExport()	in	Supported	Supported	Supported	Supported
RSA Primitive	R_RSIP_RSA_Encrypt()	in	Supported	Supported	Supported	Supported
RSA Primitive	R_RSIP_RSA_Decrypt()	in	Supported	Supported	Supported	Supported
RSA Encryption	R_RSIP_RSAES_PKCS1_V1_5_Decrypt()	in	Supported	Supported	Supported	Supported
RSA Encryption	R_RSIP_RSAES_PKCS1_V1_5_Decrypt()	in	Supported	Supported	Supported	Supported
RSA Encryption	R_RSIP_RSAES_OAEP_Decrypt()	in	Supported	Supported	Supported	Supported
RSA Encryption	R_RSIP_RSAES_OAEP_Decrypt()	in	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PKCS1_V1_5_Sign()	in	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PKCS1_V1_5_Verify()	in	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PSS_Sign()	in	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PSS_Verify()	in	Supported	Supported	Supported	Supported
PKI	R_RSIP_PKI_RSASSA_PKCS1_V1_5_CertVerify()	in	-	Supported	-	-
PKI	R_RSIP_PKI_RSASSA_PSS_CertVerify()	in	-	Supported	-	-
PKI	R_RSIP_PKI_CertKeyImport()	out	-	Supported	-	-
PKI	R_RSIP_PKI_RootCertKeyImport()	out	-	Supported	-	-
TLS1.2	R_RSIP_TLS12_RSAPremasterSecretEncrypt()	in	-	Supported	-	-
TLS1.2	R_RSIP_TLS12_RSAPremasterSecretDecrypt()	in	-	Supported	-	-

SHA

Category	Function	SHA-1	SHA-224	SHA-256	SHA-384	SHA-512	SHA-512/224	SHA-512/256
SHA for General Purpose	R_RSIP_SHA_Compute()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
SHA for General Purpose	R_RSIP_SHA_Init()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
SHA for KDF	R_RSIP_KDF_SHA_Init()	-	-	-	-	-	-	-
RSA Encryption	R_RSIP_RSAES_OAEP_Decrypt()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
RSA Encryption	R_RSIP_RSAES_OAEP_Decrypt()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PKCS1_V1_5_Sign()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PKCS1_V1_5_Verify()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PSS_Sign()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
RSA Signature	R_RSIP_RSASSA_PSS_Verify()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
PKI	R_RSIP_PKI_RSASSA_PKCS1_V1_5_CertVerify()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
PKI	R_RSIP_PKI_RSASSA_PSS_CertVerify()	Supported	Supported	Supported	Supported	Supported	Supported	Supported
PKI	R_RSIP_PKI_CertKeyImport()	Supported	Supported	Supported	Supported	Supported	Supported	Supported

HMAC

Category	Function	Key I/O	SHA-1	SHA-224	SHA-256	SHA-384	SHA-512
Key Management	R_RSIP_KeyGenerate()	out	Supported	Supported	Supported	Supported	Supported
Key Management	R_RSIP_EncryptedKeyWrap()	out	Supported	Supported	Supported	Supported	Supported
Key Management	R_RSIP_InitialKeyWrap()	out	Supported	Supported	Supported	Supported	Supported
Key Derivation	R_RSIP_KDF_DerivedKeyImport()	out	Supported	-	Supported	-	-
HMAC for General Purpose	R_RSIP_HMAC_Compute()	in	Supported	Supported	Supported	Supported	Supported
HMAC for General Purpose	R_RSIP_HMAC_Verify()	in	Supported	Supported	Supported	Supported	Supported
HMAC for General Purpose	R_RSIP_HMAC_Init()	in	Supported	Supported	Supported	Supported	Supported
HMAC for KDF	R_RSIP_KDF_HMAC_Init()	in	-	-	Supported	-	-

KDF HMAC

Category	Function	Key I/O	SHA-256	SHA-384	SHA-512
HMAC for KDF	R_RSIP_KDF_HMAC_DKMKeyImport()	out	Supported	-	-
HMAC for KDF	R_RSIP_KDF_HMAC_ECDHSecretKeyImport()	out	Supported	-	-
HMAC for KDF	R_RSIP_KDF_HMAC_Init()	in	Supported	-	-
TLS1.2	R_RSIP_KDF_TLS12PRFVerifyDataCompute()	in	Supported	-	-
TLS1.2	R_RSIP_TLS12_RSAPremasterSecretGenerate()	out	Supported	-	-
TLS1.2	R_RSIP_TLS12_RSAPremasterSecretEncrypt()	in	Supported	-	-
TLS1.2	R_RSIP_TLS12_RSAPremasterSecretDecrypt()	out	Supported	-	-

Miscellaneous

R_RSIP_OTF_Init()

Channel assignment is device dependent.

Channel (rsip_otf_channel_t)	RZ/T2H	RZ/T2M	RZ/T2ME	RZ/T2L
RSIP_OTF_CHANNEL_0	-	-	OTFD channel 0	-
RSIP_OTF_CHANNEL_1	-	-	OTFD channel 1	-
RSIP_OTF_CHANNEL_2	-	-	-	-

R_RSIP_AuthPasswordHashCompute()

The available authentication types depend on the device.

Authenctation type (rsip_auth_type_t)	RZ/T2H	RZ/T2M	RZ/T2ME	RZ/T2L
RSIP_AUTH_TYPE_JTAG_DEBUG_LEVEL1	Supported	Supported	Supported	Supported
RSIP_AUTH_TYPE_JTAG_DEBUG_LEVEL2	Supported	Supported	Supported	Supported
RSIP_AUTH_TYPE_SCI_USB_BOOT	Supported	-	-	-

Configuration

Build Time Configurations for r_rsip_protected

The following build time configurations are defined in fsp_cfg/r_rsip_cfg.h:

Configuration	Options	Default	Description
AES > Key length > AES-128	Enabled Disabled	Enabled	Enable AES-128
AES > Key length > AES-256	Enabled Disabled	Enabled	Enable AES-256
AES > Key length > XTS-AES-128	Enabled Disabled	Enabled	Enable XTS-AES-128
AES > Key length > XTS-AES-256	Enabled Disabled	Enabled	Enable XTS-AES-256
AES > Cipher Mode > AES-ECB/CBC/CTR	Enabled Disabled	Enabled	Enable AES-ECB/CBC/CTR
AES > Cipher Mode > XTS-AES	Enabled Disabled	Enabled	Enable AES-XTS
AES > AEAD Mode > AES-GCM	Enabled Disabled	Enabled	Enable AES-GCM
AES > AEAD Mode > AES-CCM	Enabled Disabled	Enabled	Enable AES-CCM
AES > MAC Mode > AES-CMAC	Enabled only	Enabled only	Enable AES-CMAC
ECC > secp256r1	Enabled Disabled	Enabled	Enable secp256r1 (also known as NIST P-256, prime256v1)
ECC > secp384r1	Enabled Disabled	Enabled	Enable secp384r1 (also known as NIST P-384)
ECC > secp521r1	Disabled only	Disabled only	Enable secp521r1 (also known as NIST P-521)
ECC > secp256k1	Disabled only	config.driver.rsip_protected.ecc.secp256k1.disabled	Enable secp256k1
ECC > brainpoolP256r1	Enabled Disabled	Enabled	Enable brainpoolP256r1
ECC > brainpoolP384r1	Enabled Disabled	Enabled	Enable brainpoolP384r1
ECC > brainpoolP512r1	Disabled only	Disabled only	Enable brainpoolP512r1
ECC > edwards25519	Enabled Disabled	Enabled	Enable edwards25519
RSA > RSA-1024	Enabled Disabled	Enabled	Enable RSA-2048
RSA > RSA-2048	Enabled Disabled	Enabled	Enable RSA-2048
RSA > RSA-3072	Enabled Disabled	Enabled	Enable RSA-3072
RSA > RSA-4096	Enabled Disabled	Enabled	Enable RSA-4096
SHA > SHA-2 > SHA-224	Enabled only	Enabled only	Enable SHA-224
SHA > SHA-2 > SHA-256	Enabled only	Enabled only	Enable SHA-256
SHA > SHA-2 > SHA-384	Enabled only	Enabled only	Enable SHA-384
SHA > SHA-2 > SHA-512	Enabled only	Enabled only	Enable SHA-512
SHA > SHA-2 > SHA-512/224	Enabled only	Enabled only	Enable SHA-512/224
SHA > SHA-2 > SHA-512/256	Enabled only	Enabled only	Enable SHA-512/256
SHA > SHA-1	Enabled only	Enabled only	Enable SHA1
HMAC > HMAC-SHA1	Enabled Disabled	Enabled	Enable HMAC-SHA1
HMAC > HMAC-SHA224	Enabled Disabled	Enabled	Enable HMAC-SHA224
HMAC > HMAC-SHA256	Enabled Disabled	Enabled	Enable HMAC-SHA256
HMAC > HMAC-SHA384	Enabled Disabled	Enabled	Enable HMAC-SHA384
HMAC > HMAC-SHA512	Enabled Disabled	Enabled	Enable HMAC-SHA512
KDF SHA > SHA-256	Disabled only	Disabled only	Enable SHA-256 for KDF
KDF SHA > SHA-384	Disabled only	Disabled only	Enable SHA-384 for KDF
KDF HMAC > HMAC-SHA256	Enabled Disabled	Enabled	Enable HMAC-SHA256 for KDF
KDF HMAC > HMAC-SHA384	Disabled only	Disabled only	Enable HMAC-SHA384 for KDF
KDF HMAC > HMAC-SHA512	Disabled only	Disabled only	Enable HMAC-SHA512 for KDF
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Security > Renesas Secure IP Driver (r_rsip)

This module can be added to the Stacks tab via New Stack > Security > Renesas Secure IP Driver (r_rsip).

Configuration	Options	Default	Description
General > Name	Name must be a valid C symbol	g_rsip	Module name.

Clock Configuration

This module does not require a specific clock configuration.

Pin Configuration

This module does not use I/O pins.

Usage Notes

Getting Started: Creating a RSIP Project

For information on how to combine the Renesas Secure IP Driver pack with the FSP to get started with program development, refer to chapter 2 in the application note "RZ/T2, RZ/N2 Renesas Secure IP Driver (R01AN6547EJ)"

Key Management

Initialization of rsip_wrapped_key_t

All instances of rsip_wrapped_key_t must be properly initialized. Set the key type in rsip_wrapped_key_t::type, and assign the address of the wrapped key value to rsip_wrapped_key_t::p_value.

rsip_wrapped_key_t wuk = {.type = RSIP_KEY_TYPE_AES_256, .p_value = WUK_VAL_ADDR};

Key Injection

In key injection, a RAM buffer address is assigned to p_value.

You then prepare parameters such as the Wrapped User Factory Programming Key (W-UFPK) and the Encrypted User Key (E-UK), and call R_RSIP_InitialKeyWrap(). The wrapped key value is output to the buffer specified by p_value, and this value should be stored in ROM for later use.

uint8_t wuk_buf[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_AES_256)] = {0};
rsip_wrapped_key_t wuk = {.type = RSIP_KEY_TYPE_AES_256, .p_value = wuk_buf};

R_RSIP_InitialKeyWrap(&g_rsip_ctrl, wufpk, iv, euk, &wuk);

/* Write wuk_buf to Non-volatile memory. */

Key Update

In key update, the pre-injected Key Update Key (KUK) is used. Prepare two instances of rsip_wrapped_key_t: one for the KUK and one for the newly generated wrapped key. Set the p_value of the KUK to point to the KUK stored in ROM, and set the other p_value to point to a buffer in RAM. When R_RSIP_EncryptedKeyWrap() is called, the wrapped key value is output to the buffer. The value should be stored in ROM just like in key injection.

(1) Key injection phase

uint8_t kuk_buf[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_KUK)] = {0};
rsip_wrapped_key_t kuk = {.type = RSIP_KEY_TYPE_KUK, .p_value = kuk_buf};

R_RSIP_InitialKeyWrap(&g_rsip_ctrl, wufpk, iv, euk, &kuk);

/* Write kuk_buf to Non-volatile memory. */

(2) Key Update phase

uint8_t wuk_buf[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_AES_256)] = {0};
rsip_wrapped_key_t wuk = {.type = RSIP_KEY_TYPE_AES_256, .p_value = wuk_buf};
rsip_wrapped_key_t kuk = {.type = RSIP_KEY_TYPE_KUK, .p_value = KUK_VAL_ADDR};

R_RSIP_EncryptedKeyWrap(&g_rsip_ctrl, &kuk, iv, euk, &wuk);

/* Write wuk_buf to Non-volatile memory. */

Key Generation

In key generation, set p_value to point to a buffer in RAM. When R_RSIP_KeyGenerate() or R_RSIP_KeyPairGenerate() is called, the wrapped key value will be output to that buffer. If you need to retain the key, store it in ROM. If the key is an ephemeral key generated by the application and does not need to be stored, the wrapped key can be used directly for cryptographic operations.

Symmetric key

uint8_t wuk_buf[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_AES_256)] = {0};
rsip_wrapped_key_t wuk = {.type = RSIP_KEY_TYPE_AES_256, .p_value = wuk_buf};

R_RSIP_KeyGenerate(&g_rsip_ctrl, &wuk);

/* Write wuk_buf to Non-volatile memory or use wuk directly. */

Asymmetric key

uint8_t wuk_pub_buf[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_ECC_SECP256R1_PUBLIC)] = {0};
uint8_t wuk_priv_buf[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_ECC_SECP256R1_PRIVATE)] = {0};
rsip_wrapped_key_t wuk_pub = {.type = RSIP_KEY_TYPE_ECC_SECP256R1_PUBLIC, .p_value = wuk_pub_buf};
rsip_wrapped_key_t wuk_priv = {.type = RSIP_KEY_TYPE_ECC_SECP256R1_PRIVATE, .p_value = wuk_priv_buf};

R_RSIP_KeyPairGenerate(&g_rsip_ctrl, &wuk_pub, &wuk_priv);

/* Write wuk_pub_buf/wuk_priv_buf to Non-volatile memory or use wuk_pub/wuk_priv directly. */

Usage of wrapped key value stored in non-volatile memory

When use stored wrapped key value stored in non-volatile memory, set the p_value of the KUK to point to the wrapped key value stored in ROM,

rsip_wrapped_key_t wrapped_key = {.type = RSIP_KEY_TYPE_AES_256, .p_value = WUK_VAL_ADDR};

State Transition

This driver has the following states.

State Name	Details
STATE_INITIAL	Driver is not open.
STATE_MAIN	Ready to Compute.
STATE_AES	Computing AES (unauthenticated cipher)
STATE_AES_AEAD	Computing AES (AEAD).
STATE_AES_MAC	Computing AES (MAC).
STATE_SHA	Computing SHA.
STATE_HMAC	Computing HMAC.
STATE_KDF_SHA	Computing SHA for KDF.
STATE_KDF_HMAC	Computing HMAC for KDF.

There are two types of APIs provided by the RSIP driver for accelerating cryptographic operations: those that provide cryptographic operations in a single API and those that provide them in multiple APIs. In this document, the former is referred to as single-part operations and the latter as multi-part operations. Each corresponds to the following algorithms:

• Single-part operations: DRBG, Key management, ECC, RSA, SHA, HMAC
• Multi-part operations: AES, SHA, SHA for KDF, HMAC, HMAC for KDF

Multi-part operations are APIs which split a single cryptographic operation into a sequence of separate steps (e.g. Init-Update-Finish). This enables fine control over the configuration of the cryptographic operation, and allows the message data to be processed in fragments instead of all at once.

Due to the above characteristics, it is necessary to manage the operational states in the multi-part operations.

Tips

Infinite Loop

If RSIP detects software corruption of this driver, RSIP stops working. In this case, the program will stall in an infinite loop in the RSIP driver. The loop can be exited using any of the following methods.

1. Use a watchdog timer.
2. Define RSIP_POLLING_LOOP_LIMIT as an unsigned integer in the compiler options. Then the infinite loops in the driver will be replaced with a software loop with RSIP_POLLING_LOOP_LIMIT as upper bound. The recommended value is RSIP_POLLING_LOOP_LIMIT=100000000 when the CPU-to-RSIP clock ratio is 10:1. The number of loops required varies depending on the clock ratio and the content of the calculation, so adjust as necessary.

Note

If the argument p_key_udpate_key->p_value of R_RSIP_EncryptedKeyWrap() is an invalid value, it is also treated as software corruption.

CPU Core

This driver is designed to run on both Cortex-R and Cortex-A. However, the calculation speed is faster on Cortex-R because it can access RSIP faster.

Limitations

The RSIP driver of this version has no limitation.

Examples

AES cipher Example

This is an example of AES-CTR encryption/decryption.

void r_rsip_example_aes ()
{
    fsp_err_t            err;
    static const uint8_t plain[RSIP_PRV_BYTE_SIZE_AES_BLOCK * 2] =
    {
        0x52, 0x65, 0x6e, 0x65, 0x73, 0x61, 0x73, 0x20, 0x45, 0x6c, 0x65, 0x63, 0x74, 0x72, 0x6f, 0x6e,
        0x69, 0x63, 0x73, 0x20, 0x43, 0x6f, 0x72, 0x70, 0x6f, 0x72, 0x61, 0x74, 0x69, 0x6f, 0x6e, 0x00
    };

    uint8_t iv[RSIP_PRV_BYTE_SIZE_AES_BLOCK] = {0};
    uint8_t cipher_calculated[RSIP_PRV_BYTE_SIZE_AES_BLOCK * 2] = {0};
    uint8_t plain_calculated[RSIP_PRV_BYTE_SIZE_AES_BLOCK * 2]  = {0};

    /* Prepare wrapped key data area */
    uint8_t            wrapped_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_AES_256)];
    rsip_wrapped_key_t wrapped_key =
    {
        .type = RSIP_KEY_TYPE_AES_256, .p_value = &wrapped_key_value
    };

    /* Initialize the driver */
    err = R_RSIP_Open(&g_rsip_ctrl, &g_rsip_cfg);
    assert(FSP_SUCCESS == err);

    /* Generate a aes 256-bit key */
    err = R_RSIP_KeyGenerate(&g_rsip_ctrl, &wrapped_key);
    assert(FSP_SUCCESS == err);

    /* Generate a nonce */
    err = R_RSIP_RandomNumberGenerate(&g_rsip_ctrl, iv);
    assert(FSP_SUCCESS == err);

    /* Encrypt a plaintext */
    err = R_RSIP_AES_Cipher_Init(&g_rsip_ctrl, RSIP_AES_CIPHER_MODE_CBC_ENC, &wrapped_key, iv);
    assert(FSP_SUCCESS == err);
    err = R_RSIP_AES_Cipher_Update(&g_rsip_ctrl, plain, cipher_calculated, RSIP_PRV_BYTE_SIZE_AES_BLOCK * 2);
    assert(FSP_SUCCESS == err);
    err = R_RSIP_AES_Cipher_Finish(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);

    /* Decrypt a ciphertext using the same key */
    err = R_RSIP_AES_Cipher_Init(&g_rsip_ctrl, RSIP_AES_CIPHER_MODE_CBC_DEC, &wrapped_key, iv);
    assert(FSP_SUCCESS == err);
    err = R_RSIP_AES_Cipher_Update(&g_rsip_ctrl, cipher_calculated, plain_calculated, RSIP_PRV_BYTE_SIZE_AES_BLOCK);
    assert(FSP_SUCCESS == err);
    err = R_RSIP_AES_Cipher_Update(&g_rsip_ctrl,
                                   cipher_calculated + RSIP_PRV_BYTE_SIZE_AES_BLOCK,
                                   plain_calculated + RSIP_PRV_BYTE_SIZE_AES_BLOCK,
                                   RSIP_PRV_BYTE_SIZE_AES_BLOCK);
    assert(FSP_SUCCESS == err);
    err = R_RSIP_AES_Cipher_Finish(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);

    /* Compare plain and plain_calculated */
    assert(0 == memcmp(plain, plain_calculated, RSIP_PRV_BYTE_SIZE_AES_BLOCK * 2));

    /* Close the driver */
    err = R_RSIP_Close(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);
}

AES-GCM Example

This is an example of AES-GCM encryption/decryption.

#define GCM_BLOCK_LEN    (16)
#define GCM_TEXT_LEN     (31)
#define GCM_NONCE_LEN    (12)
#define GCM_AAD_LEN      (8)
#define GCM_TAG_LEN      (8)

void r_rsip_example_gcm ()
{
    fsp_err_t            err;
    static const uint8_t plain[GCM_TEXT_LEN] =
    {
        0x52, 0x65, 0x6e, 0x65, 0x73, 0x61, 0x73, 0x20, 0x45, 0x6c, 0x65, 0x63, 0x74, 0x72, 0x6f, 0x6e,
        0x69, 0x63, 0x73, 0x20, 0x43, 0x6f, 0x72, 0x70, 0x6f, 0x72, 0x61, 0x74, 0x69, 0x6f, 0x6e,
    };
    static const uint8_t aad[GCM_AAD_LEN] =
    {
        0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07
    };

    uint8_t  nonce[GCM_BLOCK_LEN]                 = {0};
    uint8_t  tag[GCM_BLOCK_LEN]                   = {0};
    uint8_t  cipher_calculated[GCM_BLOCK_LEN * 2] = {0};
    uint8_t  plain_calculated[GCM_BLOCK_LEN * 2]  = {0};
    uint32_t input_length      = 0;
    uint32_t output_length     = 0;
    uint32_t input_length_tmp  = 0;
    uint32_t output_length_tmp = 0;

    /* Prepare wrapped key data area */
    uint8_t            wrapped_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_AES_256)];
    rsip_wrapped_key_t wrapped_key =
    {
        .type = RSIP_KEY_TYPE_AES_256, .p_value = &wrapped_key_value
    };

    /* Initialize the driver */
    err = R_RSIP_Open(&g_rsip_ctrl, &g_rsip_cfg);
    assert(FSP_SUCCESS == err);

    /* Generate a aes 256-bit key */
    err = R_RSIP_KeyGenerate(&g_rsip_ctrl, &wrapped_key);
    assert(FSP_SUCCESS == err);

    /* Generate a nonce */
    err = R_RSIP_RandomNumberGenerate(&g_rsip_ctrl, nonce);
    assert(FSP_SUCCESS == err);

    /* Encrypt a plaintext */
    err = R_RSIP_AES_AEAD_Init(&g_rsip_ctrl, RSIP_AES_AEAD_MODE_GCM_ENC, &wrapped_key, nonce, GCM_NONCE_LEN);
    assert(FSP_SUCCESS == err);

    /* Input AAD */
    err = R_RSIP_AES_AEAD_AADUpdate(&g_rsip_ctrl, aad, GCM_AAD_LEN);
    assert(FSP_SUCCESS == err);

    /* Input plaintext (one-shot) */
    err            = R_RSIP_AES_AEAD_Update(&g_rsip_ctrl, plain, GCM_TEXT_LEN, cipher_calculated, &output_length_tmp);
    output_length += output_length_tmp;
    assert(FSP_SUCCESS == err);

    /* Output remaining text and generate a tag */
    err = R_RSIP_AES_AEAD_Finish(&g_rsip_ctrl, cipher_calculated + output_length, &output_length_tmp, tag);
    assert(FSP_SUCCESS == err);

    /* Decrypt a ciphertext using the same key */
    err = R_RSIP_AES_AEAD_Init(&g_rsip_ctrl, RSIP_AES_AEAD_MODE_GCM_DEC, &wrapped_key, nonce, GCM_NONCE_LEN);
    assert(FSP_SUCCESS == err);

    /* Input AAD */
    err = R_RSIP_AES_AEAD_AADUpdate(&g_rsip_ctrl, aad, GCM_AAD_LEN);
    assert(FSP_SUCCESS == err);
    input_length  = 0;
    output_length = 0;

    /* Input ciphertext (multi-shot) */
    input_length_tmp = 10;
    err              = R_RSIP_AES_AEAD_Update(&g_rsip_ctrl,
                                              cipher_calculated + input_length,
                                              input_length_tmp,
                                              plain_calculated + output_length,
                                              &output_length_tmp);
    input_length  += input_length_tmp;
    output_length += output_length_tmp;
    assert(FSP_SUCCESS == err);
    input_length_tmp = GCM_TEXT_LEN - input_length;
    err              = R_RSIP_AES_AEAD_Update(&g_rsip_ctrl,
                                              cipher_calculated + input_length,
                                              input_length_tmp,
                                              plain_calculated + output_length,
                                              &output_length_tmp);
    output_length += output_length_tmp;
    assert(FSP_SUCCESS == err);

    /*
     * Output remaining text and verify the tag
     * Attention: Do not use the output plaintext by R_RSIP_AES_Cipher_DecryptUpdate()
     * before R_RSIP_AES_Cipher_DecryptFinal() returns FSP_SUCCESS.
     * The integrity is checked in this function.
     */
    err = R_RSIP_AES_AEAD_Verify(&g_rsip_ctrl, plain_calculated + output_length, &output_length_tmp, tag, GCM_TAG_LEN);
    assert(FSP_SUCCESS == err);

    /* Compare plain and plain_calculated */
    assert(0 == memcmp(plain, plain_calculated, GCM_TEXT_LEN));

    /* Close the driver */
    err = R_RSIP_Close(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);
}

AES-GMAC Example

This is an example of AES-GMAC signature/verification.

#define GMAC_NONCE_LEN    (12)
#define GMAC_AAD_LEN      (8)
#define GMAC_TAG_LEN      (16)

void r_rsip_example_gmac ()
{
    fsp_err_t err;

    static const uint8_t aad[GMAC_AAD_LEN] =
    {
        0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07
    };

    uint8_t  nonce[GMAC_NONCE_LEN] = {0};
    uint8_t  tag[GMAC_TAG_LEN]     = {0};
    uint8_t  output_dummy_buf[1]   = {0};
    uint32_t output_length         = 0;

    /* Prepare wrapped key data area */
    uint8_t            wrapped_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_AES_256)];
    rsip_wrapped_key_t wrapped_key =
    {
        .type = RSIP_KEY_TYPE_AES_256, .p_value = &wrapped_key_value
    };

    /* Initialize the driver */
    err = R_RSIP_Open(&g_rsip_ctrl, &g_rsip_cfg);
    assert(FSP_SUCCESS == err);

    /* Generate a aes 256-bit key */
    err = R_RSIP_KeyGenerate(&g_rsip_ctrl, &wrapped_key);
    assert(FSP_SUCCESS == err);

    /* Generate a nonce */
    err = R_RSIP_RandomNumberGenerate(&g_rsip_ctrl, nonce);
    assert(FSP_SUCCESS == err);

    /* Initialize GMAC signature */
    err = R_RSIP_AES_AEAD_Init(&g_rsip_ctrl, RSIP_AES_AEAD_MODE_GCM_ENC, &wrapped_key, nonce, GMAC_NONCE_LEN);
    assert(FSP_SUCCESS == err);

    /* Input AAD */
    err = R_RSIP_AES_AEAD_AADUpdate(&g_rsip_ctrl, aad, GMAC_AAD_LEN);
    assert(FSP_SUCCESS == err);

    /* Finalize GMAC generation */
    err = R_RSIP_AES_AEAD_Finish(&g_rsip_ctrl, output_dummy_buf, &output_length, tag);
    assert(FSP_SUCCESS == err);

    /*Initialize GMAC verification*/
    err = R_RSIP_AES_AEAD_Init(&g_rsip_ctrl, RSIP_AES_AEAD_MODE_GCM_DEC, &wrapped_key, nonce, GMAC_NONCE_LEN);
    assert(FSP_SUCCESS == err);

    /* Input AAD */
    err = R_RSIP_AES_AEAD_AADUpdate(&g_rsip_ctrl, aad, GMAC_AAD_LEN);
    assert(FSP_SUCCESS == err);

    /* Finalize GMAC verification*/
    err = R_RSIP_AES_AEAD_Verify(&g_rsip_ctrl, output_dummy_buf, &output_length, tag, GMAC_TAG_LEN);
    assert(FSP_SUCCESS == err);

    /* Close the driver */
    err = R_RSIP_Close(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);
}

ECC Example

This is an example of ECDSA signature generation/verification.

#define SECP256R1_KEY_SIZE    (32)

void r_rsip_example_ecc ()
{
    fsp_err_t err;

    static const uint8_t message[] = "sample";

    uint8_t hash[SECP256R1_KEY_SIZE]          = {0};
    uint8_t signature[SECP256R1_KEY_SIZE * 2] = {0};

    /* Prepare wrapped key data area */
    uint8_t            wrapped_public_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_ECC_SECP256R1_PUBLIC)];
    rsip_wrapped_key_t wrapped_public_key =
    {
        .type = RSIP_KEY_TYPE_ECC_SECP256R1_PUBLIC, .p_value = &wrapped_public_key_value
    };
    uint8_t            wrapped_private_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_ECC_SECP256R1_PRIVATE)];
    rsip_wrapped_key_t wrapped_private_key =
    {
        .type = RSIP_KEY_TYPE_ECC_SECP256R1_PRIVATE, .p_value = &wrapped_private_key_value
    };

    /* Initialize the driver */
    err = R_RSIP_Open(&g_rsip_ctrl, &g_rsip_cfg);
    assert(FSP_SUCCESS == err);

    /* Generate a key pair of secp256r1 */
    err = R_RSIP_KeyPairGenerate(&g_rsip_ctrl, &wrapped_public_key, &wrapped_private_key);
    assert(FSP_SUCCESS == err);

    /* Generate the message hash */
    err = R_RSIP_SHA_Compute(&g_rsip_ctrl, RSIP_HASH_TYPE_SHA256, message, sizeof(message), hash);
    assert(FSP_SUCCESS == err);

    /* Generate the signature */
    err = R_RSIP_ECDSA_Sign(&g_rsip_ctrl, &wrapped_private_key, hash, signature);
    assert(FSP_SUCCESS == err);

    /* Verify the signature*/
    err = R_RSIP_ECDSA_Verify(&g_rsip_ctrl, &wrapped_public_key, hash, signature);
    assert(FSP_SUCCESS == err);

    /* Close the driver */
    err = R_RSIP_Close(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);
}

RSA Example

This is an example of RSA encryption/decryption (RSAES-OAEP) and RSA signature generation/verification (RSASSA-PSS).

#define SHA256_HASH_SIZE     (32)
#define RSA_2048_KEY_SIZE    (256)

void r_rsip_example_rsa ()
{
    fsp_err_t err;

    static const uint8_t message[] = "sample";
    static const uint8_t label[]   = "label";

    uint8_t  cipher_calculated[RSA_2048_KEY_SIZE] = {0};
    uint8_t  plain_calculated[RSA_2048_KEY_SIZE]  = {0};
    uint32_t plain_calculated_length              = 0;
    uint8_t  hash[SHA256_HASH_SIZE]               = {0};
    uint8_t  signature[RSA_2048_KEY_SIZE]         = {0};

    /* Prepare wrapped key data area */
    uint8_t            wrapped_public_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_RSA_2048_PUBLIC)];
    rsip_wrapped_key_t wrapped_public_key =
    {
        .type = RSIP_KEY_TYPE_RSA_2048_PUBLIC, .p_value = &wrapped_public_key_value
    };
    uint8_t            wrapped_private_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_RSA_2048_PRIVATE)];
    rsip_wrapped_key_t wrapped_private_key =
    {
        .type = RSIP_KEY_TYPE_RSA_2048_PRIVATE, .p_value = &wrapped_private_key_value
    };

    /* Initialize the driver */
    err = R_RSIP_Open(&g_rsip_ctrl, &g_rsip_cfg);
    assert(FSP_SUCCESS == err);

    /* Generate a key pair of RSA-2048 */
    err =
        R_RSIP_KeyPairGenerate(&g_rsip_ctrl, &wrapped_public_key, &wrapped_private_key);
    assert(FSP_SUCCESS == err);

    /*
     * RSAES-OAEP
     */

    /* Encrypt a plaintext */
    err = R_RSIP_RSAES_OAEP_Encrypt(&g_rsip_ctrl,
                                    &wrapped_public_key,
                                    RSIP_HASH_TYPE_SHA256,
                                    RSIP_MGF_TYPE_MGF1_SHA256,
                                    label,
                                    sizeof(label),
                                    message,
                                    sizeof(message),
                                    cipher_calculated);
    assert(FSP_SUCCESS == err);

    /* Decrypt a ciphertext using the same key */
    err = R_RSIP_RSAES_OAEP_Decrypt(&g_rsip_ctrl,
                                    &wrapped_private_key,
                                    RSIP_HASH_TYPE_SHA256,
                                    RSIP_MGF_TYPE_MGF1_SHA256,
                                    label,
                                    sizeof(label),
                                    cipher_calculated,
                                    plain_calculated,
                                    &plain_calculated_length,
                                    sizeof(plain_calculated));
    assert(FSP_SUCCESS == err);

    /* Verify calculated plaintext */
    assert(sizeof(message) == plain_calculated_length);
    assert(0 == memcmp(message, plain_calculated, plain_calculated_length));

    /*
     * RSASSA-PSS
     */

    /* Generate the message hash */
    err = R_RSIP_SHA_Compute(&g_rsip_ctrl, RSIP_HASH_TYPE_SHA256, message, sizeof(message), hash);
    assert(FSP_SUCCESS == err);

    /* Generate the signature */
    err = R_RSIP_RSASSA_PSS_Sign(&g_rsip_ctrl,
                                 &wrapped_private_key,
                                 RSIP_HASH_TYPE_SHA256,
                                 RSIP_MGF_TYPE_MGF1_SHA256,
                                 RSIP_RSA_SALT_LENGTH_AUTO,
                                 hash,
                                 signature);
    assert(FSP_SUCCESS == err);

    /* Verify the signature*/
    err = R_RSIP_RSASSA_PSS_Verify(&g_rsip_ctrl,
                                   &wrapped_public_key,
                                   RSIP_HASH_TYPE_SHA256,
                                   RSIP_MGF_TYPE_MGF1_SHA256,
                                   RSIP_RSA_SALT_LENGTH_AUTO,
                                   hash,
                                   signature);
    assert(FSP_SUCCESS == err);

    /* Close the driver */
    err = R_RSIP_Close(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);
}

HASH Example

This is an example of calculating the SHA-256 message digest.

#define SHA256_HASH_SIZE    (32)

void r_rsip_example_hash ()
{
    fsp_err_t err;

    static const uint8_t message[] =
    {
        0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
        0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    };

    static const uint8_t hash[] =
    {
        0x63, 0x0d, 0xcd, 0x29, 0x66, 0xc4, 0x33, 0x66, 0x91, 0x12, 0x54, 0x48, 0xbb, 0xb2, 0x5b, 0x4f,
        0xf4, 0x12, 0xa4, 0x9c, 0x73, 0x2d, 0xb2, 0xc8, 0xab, 0xc1, 0xb8, 0x58, 0x1b, 0xd7, 0x10, 0xdd
    };

    uint8_t digest_single[SHA256_HASH_SIZE] = {0};
    uint8_t digest_multi[SHA256_HASH_SIZE]  = {0};

    /* Initialize the driver */
    err = R_RSIP_Open(&g_rsip_ctrl, &g_rsip_cfg);
    assert(FSP_SUCCESS == err);

    /* (1) Calculate SHA-256 digests with single-part API */
    err = R_RSIP_SHA_Compute(&g_rsip_ctrl, RSIP_HASH_TYPE_SHA256, message, sizeof(message), digest_single);
    assert(FSP_SUCCESS == err);

    /* Compare digest and hash */
    assert(0 == memcmp(digest_single, hash, SHA256_HASH_SIZE));

    /* (2) Calculate SHA-256 digests with multi-part API */
    err = R_RSIP_SHA_Init(&g_rsip_ctrl, RSIP_HASH_TYPE_SHA256);
    assert(FSP_SUCCESS == err);

    err = R_RSIP_SHA_Update(&g_rsip_ctrl, message, sizeof(message));
    assert(FSP_SUCCESS == err);

    err = R_RSIP_SHA_Finish(&g_rsip_ctrl, digest_multi);
    assert(FSP_SUCCESS == err);

    /* Compare digest and hash */
    assert(0 == memcmp(digest_multi, hash, SHA256_HASH_SIZE));

    /* Close the driver */
    err = R_RSIP_Close(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);
}

HMAC Example

This is an example of HMAC signature/verification.

#define HMAC_MESSAGE_LEN    (34)
#define HMAC_HASH_LEN       (32)

void r_rsip_example_hmac ()
{
    fsp_err_t err;

    static const uint8_t message[HMAC_MESSAGE_LEN] =
    {
        0x53, 0x61, 0x6D, 0x70, 0x6C, 0x65, 0x20, 0x6D,
        0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x20, 0x66,
        0x6F, 0x72, 0x20, 0x6B, 0x65, 0x79, 0x6C, 0x65,
        0x6E, 0x3C, 0x62, 0x6C, 0x6F, 0x63, 0x6B, 0x6C,
        0x65, 0x6E
    };
    uint8_t hash_1[HMAC_HASH_LEN] = {0};
    uint8_t hash_2[HMAC_HASH_LEN] = {0};

    /* Prepare wrapped key data area */
    uint8_t            wrapped_key_value[RSIP_BYTE_SIZE_WRAPPED_KEY(RSIP_KEY_TYPE_HMAC_SHA256)];
    rsip_wrapped_key_t wrapped_key =
    {
        .type = RSIP_KEY_TYPE_HMAC_SHA256, .p_value = &wrapped_key_value
    };

    /* Initialize the driver */
    err = R_RSIP_Open(&g_rsip_ctrl, &g_rsip_cfg);
    assert(FSP_SUCCESS == err);

    /* Generate a HMAC-SHA 256-bit key */
    err = R_RSIP_KeyGenerate(&g_rsip_ctrl, &wrapped_key);
    assert(FSP_SUCCESS == err);

    /* (1) Calculate HMAC-SHA-256 hash with single-part API */
    /* HMAC initialize to finish */
    err = R_RSIP_HMAC_Compute(&g_rsip_ctrl, &wrapped_key, message, HMAC_MESSAGE_LEN, hash_1);
    assert(FSP_SUCCESS == err);

    /* (2) Verify HMAC-SHA-256 hash with single-part API */
    /* HMAC initialize to verify */
    err = R_RSIP_HMAC_Verify(&g_rsip_ctrl, &wrapped_key, message, HMAC_MESSAGE_LEN, hash_1, HMAC_HASH_LEN);
    assert(FSP_SUCCESS == err);

    /* (3) Calculate HMAC-SHA-256 hash with multi-part API */
    /* HMAC initialize */
    err = R_RSIP_HMAC_Init(&g_rsip_ctrl, &wrapped_key);
    assert(FSP_SUCCESS == err);

    /* Inputs message */
    err = R_RSIP_HMAC_Update(&g_rsip_ctrl, message, HMAC_MESSAGE_LEN);
    assert(FSP_SUCCESS == err);

    /* Finalizes a HMAC generation */
    err = R_RSIP_HMAC_SignFinish(&g_rsip_ctrl, hash_2);
    assert(FSP_SUCCESS == err);

    /* (4) Verify HMAC-SHA-256 hash with multi-part API */
    /* HMAC initialize */
    err = R_RSIP_HMAC_Init(&g_rsip_ctrl, &wrapped_key);
    assert(FSP_SUCCESS == err);

    /* Inputs message */
    err = R_RSIP_HMAC_Update(&g_rsip_ctrl, message, HMAC_MESSAGE_LEN);
    assert(FSP_SUCCESS == err);

    /* Finalizes a HMAC verification */
    err = R_RSIP_HMAC_VerifyFinish(&g_rsip_ctrl, hash_2, HMAC_HASH_LEN);
    assert(FSP_SUCCESS == err);

    /* Close the driver */
    err = R_RSIP_Close(&g_rsip_ctrl);
    assert(FSP_SUCCESS == err);

    /* Compare hash_1 and hash_2 */
    assert(0 == memcmp(hash_1, hash_2, HMAC_HASH_LEN));
}

KDF Implementation Example

TLS1.2 PRF

This is an example of TLS1.2 PRF (RFC 5246 Section 5) implementation.

TLS1.2 PRF Exmaple

TLS1.2 PRF

This is an example of HKDF implementation.

HKDF Exmaple

Data Structures
struct	rsip_sha_handle_t
struct	rsip_hmac_handle_t
struct	rsip_kdf_sha_handle_t
struct	rsip_kdf_hmac_handle_t
struct	rsip_verified_cert_info_t
struct	rsip_wrapped_secret_t
struct	rsip_sb_common_key_t
struct	rsip_hashed_auth_password_t
struct	rsip_root_cert_mac_t
struct	rsip_instance_ctrl_t

Macros
#define	RSIP_BYTE_SIZE_PLAIN_KEY(key_type)
#define	RSIP_BYTE_SIZE_ENCRYPTED_KEY(key_type)
#define	RSIP_BYTE_SIZE_WRAPPED_KEY(key_type)
#define	FSP_ERR_SB_INTERNAL_FAIL
	An internal failure.
#define	FSP_ERR_SB_INVALID_ARG
	An invalid argument was entered.
#define	FSP_ERR_SB_UNSUPPORTED_FUNCTION
	Unsupported function executed.
#define	FSP_ERR_SB_INVALID_ALIGNMENT
	Data entered with incorrect alignment.
#define	FSP_ERR_SB_MANI_INVALID_MAGIC
	An invalid magic number is set.
#define	FSP_ERR_SB_MANI_UNSUPPORTED_VERSION
	Unsupported version is set.
#define	FSP_ERR_SB_MANI_OUT_OF_RANGE_LEN
	Out of range TLV Length is set.
#define	FSP_ERR_SB_MANI_TLV_FIELD_ERR
	Missing required TLV field.
#define	FSP_ERR_SB_MANI_TLV_INVALID_LEN
	The length exceeding the end of the manifest is specified in length of the TLV field.
#define	FSP_ERR_SB_MANI_INVALID_IMAGE_LEN
	An invalid image length is set.
#define	FSP_ERR_SB_MANI_MISMATCH_SIGN_ALGORITHM
	There is a wrong combination of signature algorithms.
#define	FSP_ERR_SB_MANI_UNSUPPORTED_ALGORITHM
	An algorithm was specified that the manifest does not support.
#define	FSP_ERR_SB_CRYPTO_FAIL
	Cryptographic processing failure.
#define	FSP_ERR_SB_CRYPTO_AUTH_FAIL
	Verification failed.
#define	FSP_ERR_SB_CRYPTO_UNSUPPORTED_ALGORITHM
	Unsupported algorithm.
#define	FSP_ERR_SB_CRYPTO_RESOURCE_CONFLICT
	CryptoIP is in use.
#define	FSP_ERR_SB_CRYPTO_PARAM_ERR
	Parameter error.

Enumerations
enum	rsip_byte_size_wrapped_key_t
enum	rsip_byte_size_encrypted_key_t
enum	rsip_byte_size_wrapped_dkm_t
enum	rsip_tls12_prf_label_t
enum	rsip_auth_type_t

---

Data Structure Documentation

rsip_sha_handle_t

struct rsip_sha_handle_t

Working area for SHA functions. DO NOT MODIFY.

rsip_hmac_handle_t

struct rsip_hmac_handle_t

Working area for HMAC functions. DO NOT MODIFY.

rsip_kdf_sha_handle_t

struct rsip_kdf_sha_handle_t

Working area for KDF SHA functions. DO NOT MODIFY.

rsip_kdf_hmac_handle_t

struct rsip_kdf_hmac_handle_t

Working area for KDF HMAC functions. DO NOT MODIFY.

rsip_verified_cert_info_t

struct rsip_verified_cert_info_t

Verified certificate information

rsip_wrapped_secret_t

struct rsip_wrapped_secret_t

Wrapped ECDH secret structure for ECDH and KDF APIs.

rsip_sb_common_key_t

struct rsip_sb_common_key_t

Secure boot common key

rsip_hashed_auth_password_t

struct rsip_hashed_auth_password_t

Hashed authentication password

rsip_root_cert_mac_t

struct rsip_root_cert_mac_t

MAC of root certificate injection

rsip_instance_ctrl_t

struct rsip_instance_ctrl_t

RSIP private control block. DO NOT MODIFY. Initialization occurs when R_RSIP_Open() is called.

Macro Definition Documentation

RSIP_BYTE_SIZE_PLAIN_KEY

#define RSIP_BYTE_SIZE_PLAIN_KEY

(

key_type

)

Returns the plain key size formatted for RSIP driver of the key type.

RSIP_BYTE_SIZE_ENCRYPTED_KEY

#define RSIP_BYTE_SIZE_ENCRYPTED_KEY

(

key_type

)

Returns the encrypted key size of the key type.

RSIP_BYTE_SIZE_WRAPPED_KEY

#define RSIP_BYTE_SIZE_WRAPPED_KEY

(

key_type

)

Returns the wrapped key size of the key type.

Enumeration Type Documentation

rsip_byte_size_wrapped_key_t

enum rsip_byte_size_wrapped_key_t

Byte size of wrapped key

Enumerator
RSIP_BYTE_SIZE_WRAPPED_KEY_AES_128	AES-128.
RSIP_BYTE_SIZE_WRAPPED_KEY_AES_192	AES-192.
RSIP_BYTE_SIZE_WRAPPED_KEY_AES_256	AES-256.
RSIP_BYTE_SIZE_WRAPPED_KEY_XTS_AES_128	XTS-AES-128.
RSIP_BYTE_SIZE_WRAPPED_KEY_XTS_AES_256	XTS-AES-256.
RSIP_BYTE_SIZE_WRAPPED_KEY_CHACHA20	ChaCha20.
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP256R1_PUBLIC	secp256r1 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP384R1_PUBLIC	secp384r1 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP521R1_PUBLIC	secp521r1 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP256K1_PUBLIC	secp256k1 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_BRAINPOOLP256R1_PUBLIC	brainpoolP256r1 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_BRAINPOOLP384R1_PUBLIC	brainpoolP384r1 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_BRAINPOOLP512R1_PUBLIC	brainpoolP512r1 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_EDWARDS25519_PUBLIC	edwards25519 public key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP256R1_PRIVATE	secp256r1 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP384R1_PRIVATE	secp384r1 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP521R1_PRIVATE	secp521r1 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_SECP256K1_PRIVATE	secp256k1 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_BRAINPOOLP256R1_PRIVATE	brainpoolP256r1 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_BRAINPOOLP384R1_PRIVATE	brainpoolP384r1 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_BRAINPOOLP512R1_PRIVATE	brainpoolP512r1 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_ECC_EDWARDS25519_PRIVATE	edwards25519 private key
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_1024_PUBLIC	RSA-1024 public key.
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_2048_PUBLIC	RSA-2048 public key.
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_3072_PUBLIC	RSA-3072 public key.
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_4096_PUBLIC	RSA-4096 public key.
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_1024_PRIVATE	RSA-1024 private key.
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_2048_PRIVATE	RSA-2048 private key.
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_3072_PRIVATE	RSA-3072 private key.
RSIP_BYTE_SIZE_WRAPPED_KEY_RSA_4096_PRIVATE	RSA-4096 private key.
RSIP_BYTE_SIZE_WRAPPED_KEY_HMAC_SHA1	HMAC-SHA1.
RSIP_BYTE_SIZE_WRAPPED_KEY_HMAC_SHA224	HMAC-SHA224.
RSIP_BYTE_SIZE_WRAPPED_KEY_HMAC_SHA256	HMAC-SHA256.
RSIP_BYTE_SIZE_WRAPPED_KEY_HMAC_SHA384	HMAC-SHA384.
RSIP_BYTE_SIZE_WRAPPED_KEY_HMAC_SHA512	HMAC-SHA512.
RSIP_BYTE_SIZE_WRAPPED_KEY_KDF_HMAC_SHA256	KDF HMAC-SHA256.
RSIP_BYTE_SIZE_WRAPPED_KEY_KDF_HMAC_SHA384	KDF HMAC-SHA384.
RSIP_BYTE_SIZE_WRAPPED_KEY_KDF_HMAC_SHA512	KDF HMAC-SHA512.
RSIP_BYTE_SIZE_WRAPPED_KEY_KUK	Key Update Key (KUK)

rsip_byte_size_encrypted_key_t

enum rsip_byte_size_encrypted_key_t

Byte size of encrypted key

Enumerator
RSIP_BYTE_SIZE_ENCRYPTED_KEY_AES_128	AES-128.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_AES_192	AES-192.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_AES_256	AES-256.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_XTS_AES_128	XTS-AES-128.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_XTS_AES_256	XTS-AES-256.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_CHACHA20	ChaCha20.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP256R1_PUBLIC	secp256r1 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP384R1_PUBLIC	secp384r1 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP521R1_PUBLIC	secp521r1 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP256K1_PUBLIC	secp256k1 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_BRAINPOOLP256R1_PUBLIC	brainpoolP256r1 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_BRAINPOOLP384R1_PUBLIC	brainpoolP384r1 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_BRAINPOOLP512R1_PUBLIC	brainpoolP512r1 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_EDWARDS25519_PUBLIC	edwards25519 public key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP256R1_PRIVATE	secp256r1 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP384R1_PRIVATE	secp384r1 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP521R1_PRIVATE	secp521r1 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_SECP256K1_PRIVATE	secp256k1 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_BRAINPOOLP256R1_PRIVATE	brainpoolP256r1 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_BRAINPOOLP384R1_PRIVATE	brainpoolP384r1 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_BRAINPOOLP512R1_PRIVATE	brainpoolP512r1 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_ECC_EDWARDS25519_PRIVATE	edwards25519 private key
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_1024_PUBLIC	RSA-1024 public key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_2048_PUBLIC	RSA-2048 public key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_3072_PUBLIC	RSA-3072 public key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_4096_PUBLIC	RSA-4096 public key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_1024_PRIVATE	RSA-1024 private key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_2048_PRIVATE	RSA-2048 private key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_3072_PRIVATE	RSA-3072 private key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_RSA_4096_PRIVATE	RSA-4096 private key.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_HMAC_SHA1	HMAC-SHA1.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_HMAC_SHA224	HMAC-SHA224.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_HMAC_SHA256	HMAC-SHA256.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_HMAC_SHA384	HMAC-SHA384.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_HMAC_SHA512	HMAC-SHA512.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_KDF_HMAC_SHA256	KDF HMAC-SHA256.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_KDF_HMAC_SHA384	KDF HMAC-SHA384.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_KDF_HMAC_SHA512	KDF HMAC-SHA512.
RSIP_BYTE_SIZE_ENCRYPTED_KEY_KUK	Key Update Key (KUK)

rsip_byte_size_wrapped_dkm_t

enum rsip_byte_size_wrapped_dkm_t

Byte size of wrapped key

Enumerator
RSIP_BYTE_SIZE_WRAPPED_DKM_HEADER	Header.
RSIP_BYTE_SIZE_WRAPPED_DKM_BLOCK_SHA256	A block of SHA-256.
RSIP_BYTE_SIZE_WRAPPED_DKM_BLOCK_SHA384	A block of SHA-384.
RSIP_BYTE_SIZE_WRAPPED_DKM_BLOCK_SHA512	A block of SHA-384.

rsip_tls12_prf_label_t

enum rsip_tls12_prf_label_t

TLS1.2 PRF labels

Enumerator
RSIP_TLS12_PRF_LABEL_CLIENT_FINISHED	"client finished"
RSIP_TLS12_PRF_LABEL_SERVER_FINISHED	"server finished"

rsip_auth_type_t

enum rsip_auth_type_t

Authentication types

Enumerator
RSIP_AUTH_TYPE_JTAG_DEBUG_LEVEL1	JTAG debug authentication level 1.
RSIP_AUTH_TYPE_JTAG_DEBUG_LEVEL2	JTAG debug authentication level 2.
RSIP_AUTH_TYPE_SCI_USB_BOOT	SCI/USB boot authentication.

Function Documentation

R_RSIP_Open()

fsp_err_t R_RSIP_Open	(	rsip_ctrl_t *const	p_ctrl,
		rsip_cfg_t const *const	p_cfg
	)

Enables use of Renesas Secure IP functionality.

Implements rsip_api_t::open.

State transition

This API can only be executed in STATE_INITIAL, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Internal key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Hardware initialization is failed.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption or hardware fault is detected.

R_RSIP_Close()

fsp_err_t R_RSIP_Close

(

rsip_ctrl_t *const

p_ctrl

)

Disables use of Renesas Secure IP functionality.

Implements rsip_api_t::close.

State transition

This API can be executed in except STATE_INITIAL, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_INITIAL
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RandomNumberGenerate()

fsp_err_t R_RSIP_RandomNumberGenerate	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t *const	p_random
	)

Generates a 128-bit random number.

Implements rsip_api_t::randomNumberGenerate.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KeyGenerate()

fsp_err_t R_RSIP_KeyGenerate	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t *const	p_wrapped_key
	)

Generates a wrapped symmetric key from a random number. In this API, user key input is unnecessary. By encrypting data using the wrapped key is output by this API, dead copying of data can be prevented.

Implements rsip_api_t::keyGenerate.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KeyPairGenerate()

fsp_err_t R_RSIP_KeyPairGenerate	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t *const	p_wrapped_public_key,
		rsip_wrapped_key_t *const	p_wrapped_private_key
	)

Generates a wrapped asymmetric key pair from a random number. In this API, user key input is unnecessary. By encrypting data using the wrapped key is output by this API, dead copying of data can be prevented.

Implements rsip_api_t::keyPairGenerate.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Here, p_wrapped_public_key->type and p_wrapped_private_key->type must match. For example, if p_wrapped_public_key->type is RSIP_KEY_TYPE_ECC_SECP256R1_PUBLIC, then p_wrapped_public_key->type must be RSIP_KEY_TYPE_ECC_SECP256R1_PRIVATE.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_EncryptedKeyWrap()

fsp_err_t R_RSIP_EncryptedKeyWrap	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_key_update_key,
		void const *const	p_initial_vector,
		void const *const	p_encrypted_key,
		rsip_wrapped_key_t *const	p_wrapped_key
	)

Decrypts an encrypted user key with Key Update Key (KUK) and wrap it with the Hardware Unique Key (HUK).

Implements rsip_api_t::encryptedKeyWrap.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input KUK is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RFC3394_KeyWrap()

fsp_err_t R_RSIP_RFC3394_KeyWrap	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_kek,
		rsip_wrapped_key_t const *const	p_wrapped_target_key,
		uint8_t *const	p_rfc3394_wrapped_target_key
	)

This function provides Key Wrap algorithm compliant with RFC3394. Using p_wrapped_kek to wrap p_wrapped_target_key, and output the result to p_rfc3394_wrapped_target_key.

Implements rsip_api_t::rfc3394_KeyWrap.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_INVALID_ARGUMENT	Input key type or mode is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RFC3394_KeyUnwrap()

fsp_err_t R_RSIP_RFC3394_KeyUnwrap	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_kek,
		uint8_t const *const	p_rfc3394_wrapped_target_key,
		rsip_wrapped_key_t *const	p_wrapped_target_key
	)

This function provides Key Unwrap algorithm compliant with RFC3394. Using p_wrapped_kek to unwrap p_rfc3394_wrapped_target_key, and output the result to p_wrapped_target_key.

Implements rsip_api_t::rfc3394_KeyUnwrap.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_INVALID_ARGUMENT	Input key type or mode is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_PublicKeyExport()

fsp_err_t R_RSIP_PublicKeyExport	(	rsip_wrapped_key_t const *const	p_wrapped_public_key,
		uint8_t *const	p_raw_public_key
	)

Exports public key parameters from a wrapped key.

Implements rsip_api_t::publicKeyExport.

Relative position of each elements in p_raw_public_key is shown in below:

• ECC (RSIP_KEY_TYPE_ECC_*) : Qx placed first and Qy placed after that.

  bit length	Qx	Qy
  256	0	32
  384	0	48
  512	0	64
  521	0	66

• RSA (RSIP_KEY_TYPE_RSA_*) : n placed first and e placed after that.

  modulus	n	e
  1024	0	128
  2048	0	256
  3072	0	384
  4096	0	512

  State transition

  This API can be executed in any state including STATE_INITIAL, and does not cause any state transitions.

  Return values

  FSP_SUCCESS	Normal termination.
  FSP_ERR_ASSERTION	A required parameter is NULL.
  FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.

R_RSIP_AES_Cipher_Init()

fsp_err_t R_RSIP_AES_Cipher_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_aes_cipher_mode_t const	mode,
		rsip_wrapped_key_t const *const	p_wrapped_key,
		uint8_t const *const	p_initial_vector
	)

Starts AES cipher operation in confidentiality mode (ECB/CBC/CTR) or XTS mode.

Implements rsip_api_t::aesCipherInit.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument mode must be the following:

• AES key
  • RSIP_AES_CIPHER_MODE_ECB_ENC, RSIP_AES_CIPHER_MODE_ECB_DEC
  • RSIP_AES_CIPHER_MODE_CBC_ENC, RSIP_AES_CIPHER_MODE_CBC_DEC
  • RSIP_AES_CIPHER_MODE_CBC_ENC_WRAPPED_IV, RSIP_AES_CIPHER_MODE_CBC_DEC_WRAPPED_IV
  • RSIP_AES_CIPHER_MODE_CTR
• XTS-AES key
  • RSIP_AES_CIPHER_MODE_XTS_ENC, RSIP_AES_CIPHER_MODE_XTS_DEC

Argument p_initial_vector must be the following:

• [ECB] Not used
• [CBC] Raw initial vector
• [CTR] Raw nonce
• [XTS] Raw initial vector

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_AES
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_INVALID_ARGUMENT	Input key type or mode is illegal.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AES_Cipher_Update()

fsp_err_t R_RSIP_AES_Cipher_Update	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_input,
		uint8_t *const	p_output,
		uint32_t const	length
	)

Encrypts plaintext or decrypts ciphertext.

Implements rsip_api_t::aesCipherUpdate.

Conditions

Argument length must be the following:

• [ECB][CBC][CTR] 0 or a multiple of 16.
• [XTS] 0 or greater than or equal to 16.

Output length

Output length to p_output is length.

State transition

This API can only be executed in STATE_AES, and does not cause any state transitions.

In XTS mode, if once an integer other than 0 or a multiple of 16 is input, this API can no longer be called.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	Input length is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Internal error.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AES_Cipher_Finish()

fsp_err_t R_RSIP_AES_Cipher_Finish

(

rsip_ctrl_t *const

p_ctrl

)

Finishes AES operation.

Implements rsip_api_t::aesCipherFinish.

State transition

This API can only be executed in STATE_AES, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Internal error.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AES_AEAD_Init()

fsp_err_t R_RSIP_AES_AEAD_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_aes_aead_mode_t	mode,
		rsip_wrapped_key_t const *const	p_wrapped_key,
		uint8_t const *const	p_nonce,
		uint32_t const	nonce_length
	)

Starts AES AEAD function.

Implements rsip_api_t::aesAeadInit.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument mode accepts any member of enumeration rsip_aes_aead_mode_t.

Argument nonce_length must be the following:

• [GCM] Any length is accepted, but 12 bytes is generally recommended.
• [CCM] 7 to 13 bytes.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_AES_AEAD
Others	No change

The next callable API functions in STATE_AES_AEAD are as below.

• [GCM] R_RSIP_AES_AEAD_AADUpdate(), R_RSIP_AES_AEAD_Update(), R_RSIP_AES_AEAD_Finish() (encryption), R_RSIP_AES_AEAD_Verify() (decryption)
• [CCM] R_RSIP_AES_AEAD_LengthsSet()

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	nonce_length is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_INVALID_ARGUMENT	Input key type is illegal.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AES_AEAD_LengthsSet()

fsp_err_t R_RSIP_AES_AEAD_LengthsSet	(	rsip_ctrl_t *const	p_ctrl,
		uint32_t const	total_aad_length,
		uint32_t const	total_text_length,
		uint32_t const	tag_length
	)

Sets text and tag lengths for CCM mode.

Implements rsip_api_t::aesAeadLengthsSet.

Conditions

Argument total_aad_length must be equal to the length of AAD and must be 110 or less.

Argument total_test_length must be equal to the length of the plaintext or ciphertext.

Argument tag_length must be 4, 6, 8, 10, 12, 14, or 16.

State transition

This API can only be executed in STATE_AES_AEAD, and does not cause any state transitions.

The next callable API functions in STATE_AES_AEAD are as below.

• [CCM] R_RSIP_AES_AEAD_AADUpdate()

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_SIZE	Input length is illegal.
FSP_ERR_INVALID_STATE	Internal state is illegal.

Note

In GCM mode, this API must NOT be called. If called, FSP_ERR_INVALID_STATE will be returned. AAD length and text length are indeterminate and output tag length is fixed to 16 bytes.

R_RSIP_AES_AEAD_AADUpdate()

fsp_err_t R_RSIP_AES_AEAD_AADUpdate	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_aad,
		uint32_t const	aad_length
	)

Inputs Additional Authentication Data (AAD).

Implements rsip_api_t::aesAeadAadUpdate.

State transition

This API can only be executed in STATE_AES_AEAD, and does not cause any state transitions.

• [GCM] R_RSIP_AES_AEAD_AADUpdate(), R_RSIP_AES_AEAD_Update(), R_RSIP_AES_AEAD_Finish() (encryption), R_RSIP_AES_AEAD_Verify() (decryption)
• [CCM] R_RSIP_AES_AEAD_AADUpdate() (AAD input is not completed), R_RSIP_AES_AEAD_Update() (AAD input is completed)

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	aad_length is illegal.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.
FSP_ERR_CRYPTO_RSIP_FAIL	Internal error.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.

R_RSIP_AES_AEAD_Update()

fsp_err_t R_RSIP_AES_AEAD_Update	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_input,
		uint32_t const	input_length,
		uint8_t *const	p_output,
		uint32_t *const	p_output_length
	)

Encrypts plaintext or decrypts ciphertext.

Implements rsip_api_t::aesAeadUpdate.

Output length

Output length to p_output (p_output_length) is calculated text that has not yet been output in multiple of 16 bytes.

State transition

This API can only be executed in STATE_AES_AEAD, and does not cause any state transitions.

• [GCM] R_RSIP_AES_AEAD_Update(), R_RSIP_AES_AEAD_Finish() (encryption), R_RSIP_AES_AEAD_Verify() (decryption)
• [CCM] R_RSIP_AES_AEAD_Update() (text input is not completed), R_RSIP_AES_AEAD_Finish() (text input is completed, encryption), R_RSIP_AES_AEAD_Verify() (text input is completed, decryption)

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_SIZE	Input length is illegal.
FSP_ERR_INVALID_STATE	Internal state is illegal.

Note

In GCM mode, if this API is skipped, GMAC will be calculated. For detailed usage, refer to example code.

R_RSIP_AES_AEAD_Finish()

fsp_err_t R_RSIP_AES_AEAD_Finish	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t *const	p_output,
		uint32_t *const	p_output_length,
		uint8_t *const	p_tag
	)

Finalizes an AES AEAD encryption.

Implements rsip_api_t::aesAeadFinish.

Output length

Output length to p_output (p_output_length) is the remaining calculated text length.

Output length to p_tag as below.

• [GCM] 16 bytes.
• [CCM] Input value as tag_length in R_RSIP_AES_AEAD_LengthsSet().

State transition

This API can only be executed in STATE_AES_AEAD, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Internal error.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AES_AEAD_Verify()

fsp_err_t R_RSIP_AES_AEAD_Verify	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t *const	p_output,
		uint32_t *const	p_output_length,
		uint8_t const *const	p_tag,
		uint32_t const	tag_length
	)

Finalizes an AES AEAD decryption.

If there is 16-byte fractional data indicated by the total data length of the value of p_cipher that was input by R_RSIP_AES_GCM_DecryptUpdate(), this API will output the result of decrypting that fractional data to p_cipher. Here, the portion that does not reach 16 bytes will be padded with zeros.

Implements rsip_api_t::aesAeadVerify.

Conditions

Argument tag_length must be as below.

• [GCM] 1 to 16 bytes.
• [CCM] Input value as tag_length in R_RSIP_AES_AEAD_LengthsSet().

Output length

Output length to p_output (p_output_length) is the remaining calculated text length.

State transition

This API can only be executed in STATE_AES_AEAD, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	tag_length is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Internal error.
FSP_ERR_CRYPTO_RSIP_AUTHENTICATION	Authentication is failed.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AES_MAC_Init()

fsp_err_t R_RSIP_AES_MAC_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_aes_mac_mode_t const	mode,
		rsip_wrapped_key_t const *const	p_wrapped_key
	)

Starts an AES MAC operation.

Implements rsip_api_t::aesMacInit.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument mode accepts any member of enumeration rsip_aes_aead_mode_t.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_AES_MAC
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

To calculate AES-GMAC, please use not R_RSIP_MAC_*() but R_RSIP_AEAD_*(). For detailed usage, refer to example code.

R_RSIP_AES_MAC_Update()

fsp_err_t R_RSIP_AES_MAC_Update	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_message,
		uint32_t const	message_length
	)

Inputs message.

Implements rsip_api_t::aesMacUpdate.

Inside this function, the data that is input by the user is buffered until the input value of p_message exceeds 16 bytes. If the input value, p_message, is not a multiple of 16 bytes, it will be padded within the function.

State transition

This API can only be executed in STATE_AES_MAC, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.

R_RSIP_AES_MAC_SignFinish()

fsp_err_t R_RSIP_AES_MAC_SignFinish	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t *const	p_mac
	)

Outputs AES MAC.

Implements rsip_api_t::aesMacSignFinish.

Output length

Output length to p_mac is 16 bytes.

State transition

This API can only be executed in STATE_AES_MAC, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Internal error.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AES_MAC_VerifyFinish()

fsp_err_t R_RSIP_AES_MAC_VerifyFinish	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_mac,
		uint32_t const	mac_length
	)

Verifies AES MAC.

Implements rsip_api_t::aesMacVerifyFinish.

Conditions

Argument mac_length must be as below.

• [CMAC] 2 to 16 bytes.

State transition

This API can only be executed in STATE_AES_MAC, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	mac_length is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Internal error.
FSP_ERR_CRYPTO_RSIP_AUTHENTICATION	Authentication is failed.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_ECDSA_Sign()

fsp_err_t R_RSIP_ECDSA_Sign	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		uint8_t const *const	p_hash,
		uint8_t *const	p_signature
	)

Generates an ECDSA signature.

Implements rsip_api_t::ecdsaSign.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance. In the case of hash length is less than the key length, padding is required to make it the same as the key length.

For secp521r1 operation, the length of p_hash must be set to 64 bytes.

For secp521r1 operation, the length of the argument p_signature must be set as 132 byte. Since 521 bit is not a 8-bit multiple, zero padding is required and the data format is as follows:

Data Format for secp521r1 (132 byte)
zero padding (7 bit)	signature r (521 bit)	zero padding (7 bit)	signature s (521 bit)

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is illegal. Signature generation is failed.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_ECDSA_Verify()

fsp_err_t R_RSIP_ECDSA_Verify	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		uint8_t const *const	p_hash,
		uint8_t const *const	p_signature
	)

Verifies an ECDSA signature.

Implements rsip_api_t::ecdsaVerify.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance. In the case of hash length is less than the key length, padding is required to make it the same as the key length.

For secp521r1 operation, the length of p_hash must be set to 64 bytes.

For secp521r1 operation, the length of the argument p_signature must be set as 132 byte. Since 521 bit is not a 8-bit multiple, zero padding is required and the data format is as follows:

Data Format for secp521r1 (132 byte)
zero padding (7 bit)	signature r (521 bit)	zero padding (7 bit)	signature s (521 bit)

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is illegal. Signature verification is failed.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_PKI_ECDSA_CertVerify()

fsp_err_t R_RSIP_PKI_ECDSA_CertVerify	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		uint8_t const *const	p_hash,
		uint8_t const *const	p_signature
	)

Verifies a public key certificate with ECDSA.

Implements rsip_api_t::pkiEcdsaCertVerify.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance. In the case of hash length is less than the key length, padding is required to make it the same as the key length.

For secp521r1 operation, the length of p_hash must be set to 64 bytes.

For secp521r1 operation, the length of the argument p_signature must be set as 132 byte. Since 521 bit is not a 8-bit multiple, zero padding is required and the data format is as follows:

Data Format for secp521r1 (132 byte)
zero padding (7 bit)	signature r (521 bit)	zero padding (7 bit)	signature s (521 bit)

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is illegal. Signature verification is failed.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_PureEdDSA_Sign()

fsp_err_t R_RSIP_PureEdDSA_Sign	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		uint8_t const *const	p_message,
		uint64_t const	message_length,
		uint8_t *const	p_signature
	)

Generates an EdDSA signature.

Implements rsip_api_t::eddsaSign.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_INVALID_SIZE	Input length is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_PureEdDSA_Verify()

fsp_err_t R_RSIP_PureEdDSA_Verify	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		uint8_t const *const	p_message,
		uint64_t const	message_length,
		uint8_t const *const	p_signature
	)

Verifies an EdDSA signature.

Implements rsip_api_t::eddsaVerify.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_INVALID_SIZE	Input length is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_ECDH_KeyAgree()

fsp_err_t R_RSIP_ECDH_KeyAgree	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		rsip_wrapped_secret_t *const	p_wrapped_secret
	)

Computes ECDH secret with wrapped private key and wrapped public key.

Implements rsip_api_t::ecdhKeyAgree.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_ECDH_PlainKeyAgree()

fsp_err_t R_RSIP_ECDH_PlainKeyAgree	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		uint8_t const *const	p_plain_public_key,
		rsip_wrapped_secret_t *const	p_wrapped_secret
	)

Computes ECDH secret with wrapped private key and plain public key.

Implements rsip_api_t::ecdhPlainKeyAgree.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

For secp521r1 operation, the length of the argument p_plain_public_key must be set as 132 byte. Since 521 bit is not a 8-bit multiple, zero padding is required and the data format is as follows:

Data Format for secp521r1 (132 byte)
zero padding (7 bit)	public_key Qx (521 bit)	zero padding (7 bit)	public_key Qy (521 bit)

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Attention

Unauthenticated public key of Diffie–Hellman key exchange generally carry the risk of man-in-the-middle (MITM) attack. Please use R_RSIP_ECDH_KeyAgree() or implement signature verification whenever possible.

R_RSIP_KDF_SHA_Init()

fsp_err_t R_RSIP_KDF_SHA_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_hash_type_t const	hash_type
	)

Prepares a SHA generation.

Implements rsip_api_t::kdfShaInit.

Conditions

Argument hash_type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_KDF_SHA
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.

R_RSIP_KDF_SHA_ECDHSecretUpdate()

fsp_err_t R_RSIP_KDF_SHA_ECDHSecretUpdate	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_secret_t const *const	p_wrapped_secret
	)

Inputs wrapped ECDH secret as a message. Input the messages required to perform the SHA operation using this API and R_RSIP_KDF_SHA_Update() in the desired order.

Implements rsip_api_t::kdfShaEcdhSecretUpdate.

Conditions

The argument p_wrapped_secret must be input the result of R_RSIP_ECDH_KeyAgree() or R_RSIP_ECDH_PlainKeyAgree(). This API can only be called if there is no previous message input, or if a 4-byte message has been input using R_RSIP_KDF_SHA_Update(). This API cannot be called multiple times in a process of performing SHA operation.

State transition

This API can only be executed in STATE_KDF_SHA, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_SHA_Update()

fsp_err_t R_RSIP_KDF_SHA_Update	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_message,
		uint32_t const	message_length
	)

Inputs message. Input the messages required to perform the SHA operation using this API and R_RSIP_KDF_SHA_ECDHSecretUpdate() in the desired order.

Implements rsip_api_t::kdfShaUpdate.

State transition

This API can only be executed in STATE_KDF_SHA, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	Input message_length is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_SHA_Finish()

fsp_err_t R_RSIP_KDF_SHA_Finish	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_dkm_t *const	p_wrapped_dkm
	)

Finalizes a SHA operation and generate DKM (Derived Keying Material).

Implements rsip_api_t::kdfShaFinish.

State transition

This API can only be executed in STATE_KDF_SHA, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_SHA_Suspend()

fsp_err_t R_RSIP_KDF_SHA_Suspend	(	rsip_ctrl_t *const	p_ctrl,
		rsip_kdf_sha_handle_t *const	p_handle
	)

Suspends SHA operation.

This API releases RSIP resource and outputs intermediate results. Therefore, it can be used in the following cases:

• Execute another cryptographic operations during inputting successive chunks of the message.
• Reuse intermediate results.

Implements rsip_api_t::kdfShaSuspend.

State transition

This API can only be executed in STATE_KDF_SHA, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_SHA_Resume()

fsp_err_t R_RSIP_KDF_SHA_Resume	(	rsip_ctrl_t *const	p_ctrl,
		rsip_kdf_sha_handle_t const *const	p_handle
	)

Resumes SHA operation suspended by R_RSIP_KDF_SHA_Suspend().

Implements rsip_api_t::kdfShaResume.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_KDF_SHA
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.

R_RSIP_KDF_HMAC_DKMKeyImport()

fsp_err_t R_RSIP_KDF_HMAC_DKMKeyImport	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_dkm_t const *const	p_wrapped_dkm,
		uint32_t const	key_length,
		rsip_wrapped_key_t *const	p_wrapped_key
	)

Converts wrapped MAC to wrapped HMAC key for KDF.

Implements rsip_api_t::kdfHmacDkmKeyImport.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration

The argument p_wrapped_dkm must be input the result of R_RSIP_KDF_HMAC_SignFinish().

Argument kdf_data_length depends on key type.

• 32 to 64 ( RSIP_KEY_TYPE_KDF_HMAC_SHA256)
• 48 to 64 ( RSIP_KEY_TYPE_KDF_HMAC_SHA384)
• 64 ( RSIP_KEY_TYPE_KDF_HMAC_SHA512)

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_HMAC_ECDHSecretKeyImport()

fsp_err_t R_RSIP_KDF_HMAC_ECDHSecretKeyImport	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_secret_t const *const	p_wrapped_secret,
		rsip_wrapped_key_t *const	p_wrapped_key
	)

Converts wrapped ECDH secret to wrapped HMAC key for KDF.

Implements rsip_api_t::kdfHmacEcdhSecretKeyImport.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_HMAC_Init()

fsp_err_t R_RSIP_KDF_HMAC_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_key
	)

Prepares a HMAC generation.

Implements rsip_api_t::kdfHmacInit.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_KDF_HMAC
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.

R_RSIP_KDF_HMAC_DKMUpdate()

fsp_err_t R_RSIP_KDF_HMAC_DKMUpdate	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_dkm_t const *const	p_wrapped_dkm
	)

Inputs wrapped Derived Keying Material (DKM) as a message.

Implements rsip_api_t::kdfHmacDkmUpdate.

Conditions

The argument p_wrapped_dkm must be input the result of R_RSIP_KDF_HMAC_SignFinish().

State transition

This API can only be executed in STATE_KDF_HMAC, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.

R_RSIP_KDF_HMAC_ECDHSecretUpdate()

fsp_err_t R_RSIP_KDF_HMAC_ECDHSecretUpdate	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_secret_t const *const	p_wrapped_secret
	)

Inputs wrapped ECDH secret as a message.

Implements rsip_api_t::kdfHmacEcdhSecretUpdate.

Conditions

The argument p_wrapped_secret must be input the result of R_RSIP_ECDH_KeyAgree() or R_RSIP_ECDH_PlainKeyAgree().

State transition

This API can only be executed in STATE_KDF_HMAC, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_HMAC_Update()

fsp_err_t R_RSIP_KDF_HMAC_Update	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_message,
		uint32_t const	message_length
	)

Inputs message.

Implements rsip_api_t::kdfHmacUpdate.

State transition

This API can only be executed in STATE_KDF_HMAC, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_HMAC_SignFinish()

fsp_err_t R_RSIP_KDF_HMAC_SignFinish	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_dkm_t *const	p_wrapped_dkm
	)

Finalizes a HMAC generation.

Implements rsip_api_t::kdfHmacSignFinish.

State transition

This API can only be executed in STATE_KDF_HMAC, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_HMAC_Suspend()

fsp_err_t R_RSIP_KDF_HMAC_Suspend	(	rsip_ctrl_t *const	p_ctrl,
		rsip_kdf_hmac_handle_t *const	p_handle
	)

Suspends HMAC operation.

This API releases RSIP resource and outputs intermediate results. Therefore, it can be used in the following cases:

• Execute another cryptographic operations during inputting successive chunks of the message.
• Reuse intermediate results.

Implements rsip_api_t::kdfHmacSuspend.

State transition

This API can only be executed in STATE_KDF_HMAC, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_HMAC_Resume()

fsp_err_t R_RSIP_KDF_HMAC_Resume	(	rsip_ctrl_t *const	p_ctrl,
		rsip_kdf_hmac_handle_t const *const	p_handle
	)

Resumes HMAC operation suspended by R_RSIP_KDF_HMAC_Suspend().

Implements rsip_api_t::kdfHmacResume.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_KDF_HMAC
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.

R_RSIP_KDF_DKMConcatenate()

fsp_err_t R_RSIP_KDF_DKMConcatenate	(	rsip_wrapped_dkm_t *const	p_wrapped_dkm1,
		rsip_wrapped_dkm_t const *const	p_wrapped_dkm2,
		uint32_t const	wrapped_dkm1_buffer_length
	)

Concatenates two wrapped derived keying materials (DKMs).

DKM1 || DKM2 is output to p_wrapped_dkm1.

Implements rsip_api_t::kdfDkmConcatenate.

State transition

This API can be executed in any state including STATE_INITIAL, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.

R_RSIP_KDF_DerivedKeyImport()

fsp_err_t R_RSIP_KDF_DerivedKeyImport	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_dkm_t const *const	p_wrapped_dkm,
		uint32_t const	position,
		rsip_wrapped_key_t *const	p_wrapped_key
	)

Outputs a wrapped key from KDF output.

Implements rsip_api_t::kdfDerivedKeyImport.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument p_wrapped_dkm must be input the result of R_RSIP_KDF_SHA_Finish(), R_RSIP_KDF_HMAC_SignFinish() or R_RSIP_KDF_DKMConcatenate().

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_KDF_DerivedIVWrap()

fsp_err_t R_RSIP_KDF_DerivedIVWrap	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_dkm_t const *const	p_wrapped_dkm,
		rsip_initial_vector_type_t const	initial_vector_type,
		uint32_t const	position,
		uint8_t const *const	p_tls_sequence_num,
		uint8_t *const	p_wrapped_initial_vector
	)

Outputs a initial vector from KDF output.

Implements rsip_api_t::kdfDerivedIvWrap

Conditions

Argument p_wrapped_dkm must be input the result of R_RSIP_KDF_SHA_Finish(), R_RSIP_KDF_HMAC_SignFinish() or R_RSIP_KDF_DKMConcatenate().

Argument initial_vector_type must be one of the following:

• RSIP_INITIAL_VECTOR_TYPE_AES_16_BYTE

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_OTF_Init()

fsp_err_t R_RSIP_OTF_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_otf_channel_t const	channel,
		rsip_wrapped_key_t *const	p_wrapped_key,
		uint8_t const *const	p_seed
	)

Initialize on-the-fly decryption on RSIP. Implements rsip_api_t::otfInit.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled or selected channel is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Attention

This function is only part of on-the-fly decryption activation process and intended to be called from a higher level FSP module. Even if a user calls this function directly, the feature will not be enabled.

R_RSIP_PKI_VerifiedCertInfoExport()

fsp_err_t R_RSIP_PKI_VerifiedCertInfoExport	(	rsip_ctrl_t *const	p_ctrl,
		rsip_verified_cert_info_t *const	p_verified_cert_info
	)

Exports verified certificate information stored in this driver.

The certificate is last called function R_RSIP_PKI_ECDSA_CertVerify(), R_RSIP_PKI_RSASSA_PKCS1_V1_5_CertVerify(), R_RSIP_PKI_RSASSA_PSS_CertVerify(), or R_RSIP_PKI_VerifiedCertInfoImport().

Implements rsip_api_t::pkiVerifiedCertInfoExport.

State transition

This API can be executed in any state including STATE_INITIAL, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.

R_RSIP_PKI_VerifiedCertInfoImport()

fsp_err_t R_RSIP_PKI_VerifiedCertInfoImport	(	rsip_ctrl_t *const	p_ctrl,
		rsip_verified_cert_info_t const *const	p_verified_cert_info
	)

Imports verified certificate information.

Implements rsip_api_t::pkiVerifiedCertInfoImport.

State transition

This API can be executed in any state including STATE_INITIAL, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.

R_RSIP_PKI_CertKeyImport()

fsp_err_t R_RSIP_PKI_CertKeyImport	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_cert,
		uint32_t const	cert_length,
		uint8_t const *const	p_key_param1,
		uint32_t const	key_param1_length,
		uint8_t const *const	p_key_param2,
		uint32_t const	key_param2_length,
		rsip_hash_type_t const	hash_function,
		rsip_wrapped_key_t *const	p_wrapped_public_key
	)

Wraps the public key in the verified public key certificate.

Implements rsip_api_t::pkiCertKeyImport.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

• Argument p_cert must correspond to the signature of the last called function R_RSIP_PKI_ECDSA_CertVerify(), R_RSIP_PKI_RSASSA_PKCS1_V1_5_CertVerify(), or R_RSIP_PKI_RSASSA_PSS_CertVerify().
• For arguments p_key_param1 and p_key_param2, specify an address inside the certificate. Addresses outside the certificate are invalid.

R_RSIP_RSA_Encrypt()

fsp_err_t R_RSIP_RSA_Encrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		uint8_t const *const	p_plain,
		uint8_t *const	p_cipher
	)

Encrypts plaintext with raw RSA.

Implements rsip_api_t::rsaEncrypt.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

This API provides RSA low-level primitives (RSAEP/RSAVP1). It should be used in conjunction with any padding scheme.

R_RSIP_RSA_Decrypt()

fsp_err_t R_RSIP_RSA_Decrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		uint8_t const *const	p_cipher,
		uint8_t *const	p_plain
	)

Decrypts ciphertext with raw RSA.

Implements rsip_api_t::rsaDecrypt.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

This API provides RSA low-level primitives (RSADP/RSASP1). It should be used in conjunction with any padding scheme.

R_RSIP_RSAES_PKCS1_V1_5_Encrypt()

fsp_err_t R_RSIP_RSAES_PKCS1_V1_5_Encrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		uint8_t const *const	p_plain,
		uint32_t const	plain_length,
		uint8_t *const	p_cipher
	)

Encrypts plaintext with RSAES-PKCS1-v1_5.

Implements rsip_api_t::rsaesPkcs1V15Encrypt.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

mLen (plain_length) and k (modulus length) must meet the following condition.

• mLen <= k - 11

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RSAES_PKCS1_V1_5_Decrypt()

fsp_err_t R_RSIP_RSAES_PKCS1_V1_5_Decrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		uint8_t const *const	p_cipher,
		uint8_t *const	p_plain,
		uint32_t *const	p_plain_length,
		uint32_t const	plain_buffer_length
	)

Decrypts with RSAES-PKCS1-v1_5.

Implements rsip_api_t::rsaesPkcs1V15Decrypt.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

plain_buffer_length must be greater than or equal to mLen(plaintext length).

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

This API skips the ciphertext length checking at RFC8017 (PKCS#1 v2.2) Section 7.2.2 Step 1.

R_RSIP_RSAES_OAEP_Encrypt()

fsp_err_t R_RSIP_RSAES_OAEP_Encrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		rsip_hash_type_t const	hash_function,
		rsip_mgf_type_t const	mask_generation_function,
		uint8_t const *const	p_label,
		uint32_t const	label_length,
		uint8_t const *const	p_plain,
		uint32_t const	plain_length,
		uint8_t *const	p_cipher
	)

Encrypts plaintext with RSAES-OAEP.

Implements rsip_api_t::rsaesOaepEncrypt.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

mLen (plain_length), hLen (hash length of hash_function), and k (modulus length) must meet the following condition.

• mLen <= k - 2 hLen - 2

Argument hash_function and mask_generation_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RSAES_OAEP_Decrypt()

fsp_err_t R_RSIP_RSAES_OAEP_Decrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		rsip_hash_type_t const	hash_function,
		rsip_mgf_type_t const	mask_generation_function,
		uint8_t const *const	p_label,
		uint32_t const	label_length,
		uint8_t const *const	p_cipher,
		uint8_t *const	p_plain,
		uint32_t *const	p_plain_length,
		uint32_t const	plain_buffer_length
	)

Decrypts ciphertext with RSAES-OAEP.

Implements rsip_api_t::rsaesOaepDecrypt.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

hLen (hash length of hash_function) and k (modulus length) must meet the following condition.

• k >= 2 hLen + 2

plain_buffer_length must be greater than or equal to mLen(plaintext length).

Argument hash_function and mask_generation_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

This API skips the ciphertext length checking at RFC8017 (PKCS#1 v2.2) Section 7.1.2 Step 1.

R_RSIP_RSASSA_PKCS1_V1_5_Sign()

fsp_err_t R_RSIP_RSASSA_PKCS1_V1_5_Sign	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		rsip_hash_type_t const	hash_function,
		uint8_t const *const	p_hash,
		uint8_t *const	p_signature
	)

Signs message with RSASSA-PKCS1-v1_5.

Implements rsip_api_t::rsassaPkcs1V15Sign.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument hash_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance with hash_function.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RSASSA_PKCS1_V1_5_Verify()

fsp_err_t R_RSIP_RSASSA_PKCS1_V1_5_Verify	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		rsip_hash_type_t const	hash_function,
		uint8_t const *const	p_hash,
		uint8_t const *const	p_signature
	)

Verifies signature with RSASSA-PKCS1-v1_5.

Implements rsip_api_t::rsassaPkcs1V15Verify.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument hash_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance with hash_function.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RSASSA_PSS_Sign()

fsp_err_t R_RSIP_RSASSA_PSS_Sign	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		rsip_hash_type_t const	hash_function,
		rsip_mgf_type_t const	mask_generation_function,
		uint32_t const	salt_length,
		uint8_t const *const	p_hash,
		uint8_t *const	p_signature
	)

Signs message with RSASSA-PSS.

Implements rsip_api_t::rsassaPssSign.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument hash_function and mask_generation_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance with hash_function.

Salt length salt_length must be one of the following:

• Any member of enumeration rsip_rsa_salt_length_t
  • RSIP_RSA_SALT_LENGTH_AUTO
  • RSIP_RSA_SALT_LENGTH_HASH
  • RSIP_RSA_SALT_LENGTH_MAX
• Integers that satisfies the formula: sLen <= emLen - hLen - 2
  • sLen is salt_length
  • emLen is the same as modulus length
  • hLen is the hash length

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_RSASSA_PSS_Verify()

fsp_err_t R_RSIP_RSASSA_PSS_Verify	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		rsip_hash_type_t const	hash_function,
		rsip_mgf_type_t const	mask_generation_function,
		uint32_t const	salt_length,
		uint8_t const *const	p_hash,
		uint8_t const *const	p_signature
	)

Verifies signature with RSASSA-PSS. Implements rsip_api_t::rsassaPssVerify.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument hash_function and mask_generation_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance with hash_function.

Salt length salt_length must be one of the following:

• Any member of enumeration rsip_rsa_salt_length_t
  • RSIP_RSA_SALT_LENGTH_AUTO
  • RSIP_RSA_SALT_LENGTH_HASH
  • RSIP_RSA_SALT_LENGTH_MAX
• Integers that satisfies the formula: sLen <= emLen - hLen - 2
  • sLen is salt_length
  • emLen is the same as modulus length
  • hLen is the hash length

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_PKI_RSASSA_PKCS1_V1_5_CertVerify()

fsp_err_t R_RSIP_PKI_RSASSA_PKCS1_V1_5_CertVerify	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		rsip_hash_type_t const	hash_function,
		uint8_t const *const	p_hash,
		uint8_t const *const	p_signature
	)

Verifies a certificate with RSASSA-PKCS1-v1_5.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument hash_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance with hash_function.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_public_key	Pointer to wrapped key of RSA public key.
[in]	hash_function	Hash function in EMSA-PKCS1-v1_5.
[in]	p_hash	Pointer to input hash.
[in]	p_signature	Pointer to input signature.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_PKI_RSASSA_PSS_CertVerify()

fsp_err_t R_RSIP_PKI_RSASSA_PSS_CertVerify	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		rsip_hash_type_t const	hash_function,
		rsip_mgf_type_t const	mask_generation_function,
		uint32_t const	salt_length,
		uint8_t const *const	p_hash,
		uint8_t const *const	p_signature
	)

Verifies a certificate with RSASSA-PSS.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Argument hash_function and mask_generation_function must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

Message hash p_hash should be computed in advance with hash_function.

Salt length salt_length must be one of the following:

• Any member of enumeration rsip_rsa_salt_length_t
  • RSIP_RSA_SALT_LENGTH_AUTO
  • RSIP_RSA_SALT_LENGTH_HASH
  • RSIP_RSA_SALT_LENGTH_MAX
• Integers that satisfies the formula: sLen <= emLen - hLen - 2
  • sLen is salt_length
  • emLen is the same as modulus length
  • hLen is the hash length

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_public_key	Pointer to wrapped key of RSA public key.
[in]	hash_function	Hash function in EMSA-PSS-VERIFY.
[in]	mask_generation_function	Mask generation function in EMSA-PSS-VERIFY.
[in]	salt_length	Salt length. RSIP_RSA_SALT_LENGTH_AUTO, RSIP_RSA_SALT_LENGTH_HASH, RSIP_RSA_SALT_LENGTH_MAX, 0, or positive integers can be set, where salt_length <= emLen - hLen - 2 (emLen is the same as the key length and hLen is the hash length).
[in]	p_hash	Pointer to input hash.
[in]	p_signature	Pointer to input signature.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_INVALID_SIZE	Any length is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_SHA_Compute()

fsp_err_t R_RSIP_SHA_Compute	(	rsip_ctrl_t *const	p_ctrl,
		rsip_hash_type_t const	hash_type,
		uint8_t const *const	p_message,
		uint32_t const	message_length,
		uint8_t *const	p_digest
	)

Generates SHA message digest. (Total input message must be less than 2^64 bits.)

Implements rsip_api_t::shaCompute.

Conditions

See R_RSIP_SHA_Init().

Output length

See R_RSIP_SHA_Finish().

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.

R_RSIP_SHA_Init()

fsp_err_t R_RSIP_SHA_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_hash_type_t const	hash_type
	)

Starts SHA operation.

Implements rsip_api_t::shaInit.

Conditions

Argument hash_type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_SHA
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.

R_RSIP_SHA_Update()

fsp_err_t R_RSIP_SHA_Update	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_message,
		uint32_t const	message_length
	)

Inputs SHA message. (Total input message must be less than 2^64 bits.)

Implements rsip_api_t::shaUpdate.

State transition

This API can only be executed in STATE_SHA, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_SHA_Finish()

fsp_err_t R_RSIP_SHA_Finish	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t *const	p_digest
	)

Outputs SHA message digest.

Implements rsip_api_t::shaFinish.

Output length

Output length to p_digest depends on hash_function.

• 20 ( RSIP_HASH_TYPE_SHA1)
• 28 ( RSIP_HASH_TYPE_SHA224, RSIP_HASH_TYPE_SHA512_224)
• 32 ( RSIP_HASH_TYPE_SHA256, RSIP_HASH_TYPE_SHA512_256)
• 48 ( RSIP_HASH_TYPE_SHA384)
• 64 ( RSIP_HASH_TYPE_SHA512)

State transition

This API can only be executed in STATE_SHA, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_SHA_Suspend()

fsp_err_t R_RSIP_SHA_Suspend	(	rsip_ctrl_t *const	p_ctrl,
		rsip_sha_handle_t *const	p_handle
	)

Suspends SHA operation.

This API releases RSIP resource and outputs intermediate results. Therefore, it can be used in the following cases:

• Execute another cryptographic operations during inputting successive chunks of the message.
• Reuse intermediate results.

Implements rsip_api_t::shaSuspend.

State transition

This API can only be executed in STATE_SHA, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_SHA_Resume()

fsp_err_t R_RSIP_SHA_Resume	(	rsip_ctrl_t *const	p_ctrl,
		rsip_sha_handle_t const *const	p_handle
	)

Resumes SHA operation suspended by R_RSIP_SHA_Suspend().

Implements rsip_api_t::shaResume.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_SHA
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.

R_RSIP_HMAC_Compute()

fsp_err_t R_RSIP_HMAC_Compute	(	rsip_ctrl_t *const	p_ctrl,
		const rsip_wrapped_key_t *	p_wrapped_key,
		uint8_t const *const	p_message,
		uint32_t const	message_length,
		uint8_t *const	p_mac
	)

Generates HMAC. (Total input message must be less than 2^64 bits.)

Implements rsip_api_t::hmacCompute.

Conditions

See R_RSIP_HMAC_Init().

Output length

See R_RSIP_HMAC_SignFinish().

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_HMAC_Verify()

fsp_err_t R_RSIP_HMAC_Verify	(	rsip_ctrl_t *const	p_ctrl,
		const rsip_wrapped_key_t *	p_wrapped_key,
		uint8_t const *const	p_message,
		uint32_t const	message_length,
		uint8_t const *const	p_mac,
		uint32_t const	mac_length
	)

Verifies HMAC. (Total input message must be less than 2^64 bits.)

Implements rsip_api_t::hmacVerify.

Conditions

See R_RSIP_HMAC_Init() and R_RSIP_HMAC_VerifyFinish().

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	mac_length is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	MAC verification is failed.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_HMAC_Init()

fsp_err_t R_RSIP_HMAC_Init	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_key
	)

Starts HMAC operation.

Implements rsip_api_t::hmacInit.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_HMAC
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.

R_RSIP_HMAC_Update()

fsp_err_t R_RSIP_HMAC_Update	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_message,
		uint32_t const	message_length
	)

Inputs HMAC message. (Total input message must be less than 2^64 bits.)

Implements rsip_api_t::hmacUpdate.

State transition

This API can only be executed in STATE_HMAC, and does not cause any state transitions.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_HMAC_SignFinish()

fsp_err_t R_RSIP_HMAC_SignFinish	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t *const	p_mac
	)

Outputs HMAC.

Implements rsip_api_t::hmacSignFinish.

Output length

Output length to p_mac depends on key type of p_wrapped_key.

• 20 ( RSIP_KEY_TYPE_HMAC_SHA1)
• 28 ( RSIP_KEY_TYPE_HMAC_SHA224)
• 32 ( RSIP_KEY_TYPE_HMAC_SHA256)
• 48 ( RSIP_KEY_TYPE_HMAC_SHA384)
• 64 ( RSIP_KEY_TYPE_HMAC_SHA512)

State transition

This API can only be executed in STATE_HMAC, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_HMAC_VerifyFinish()

fsp_err_t R_RSIP_HMAC_VerifyFinish	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_mac,
		uint32_t const	mac_length
	)

Verifies HMAC.

Implements rsip_api_t::hmacVerifyFinish.

Conditions

Argument mac_length depends on key type of p_wrapped_key. Usually the longest length is recommended.

• 4 to 20 ( RSIP_KEY_TYPE_HMAC_SHA1)
• 4 to 28 ( RSIP_KEY_TYPE_HMAC_SHA224)
• 4 to 32 ( RSIP_KEY_TYPE_HMAC_SHA256)
• 4 to 48 ( RSIP_KEY_TYPE_HMAC_SHA384)
• 4 to 64 ( RSIP_KEY_TYPE_HMAC_SHA512)

State transition

This API can only be executed in STATE_HMAC, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
FSP_ERR_ASSERTION	No change
FSP_ERR_NOT_OPEN	No change
FSP_ERR_INVALID_STATE	No change
FSP_ERR_INVALID_SIZE	No change
Others	STATE_MAIN

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_INVALID_SIZE	mac_length is illegal.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	MAC verification is failed.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_HMAC_Suspend()

fsp_err_t R_RSIP_HMAC_Suspend	(	rsip_ctrl_t *const	p_ctrl,
		rsip_hmac_handle_t *const	p_handle
	)

Suspends HMAC operation.

This API releases RSIP resource and outputs intermediate results. Therefore, it can be used in the following cases:

• Execute another cryptographic operations during inputting successive chunks of the message.
• Reuse intermediate results.

Implements rsip_api_t::hmacSuspend.

State transition

This API can only be executed in STATE_HMAC, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_MAIN
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_HMAC_Resume()

fsp_err_t R_RSIP_HMAC_Resume	(	rsip_ctrl_t *const	p_ctrl,
		rsip_hmac_handle_t const *const	p_handle
	)

Resumes HMAC operation suspended by R_RSIP_HMAC_Suspend().

Implements rsip_api_t::hmacResume.

State transition

This API can only be executed in STATE_MAIN, and causes state transition.

Return value	Next state
FSP_SUCCESS	STATE_HMAC
Others	No change

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.

R_RSIP_InitialKeyWrap()

fsp_err_t R_RSIP_InitialKeyWrap	(	rsip_ctrl_t *const	p_ctrl,
		void const *const	p_wrapped_user_factory_programming_key,
		void const *const	p_initial_vector,
		void const *const	p_encrypted_key,
		rsip_wrapped_key_t *const	p_wrapped_key
	)

Decrypts an encrypted user key with User Factory Programming Key (UFPK) and wrap it with the Hardware Unique Key (HUK).

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_user_factory_programming_key	Wrapped User Factory Programming Key (W-UFPK). The length is 32 bytes.
[in]	p_initial_vector	Initialization vector when generating encrypted_key. The length is 16 bytes.
[in]	p_encrypted_key	Encrypted user key. The length depends on the key type.
[in,out]	p_wrapped_key	Pointer to destination of wrapped key. The length depends on the key type.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

See also Section Supported Algorithms.

R_RSIP_SB_InitialCommonKeyWrap()

fsp_err_t R_RSIP_SB_InitialCommonKeyWrap	(	rsip_ctrl_t *const	p_ctrl,
		void const *const	p_wrapped_user_factory_programming_key,
		void const *const	p_initial_vector,
		void const *const	p_encrypted_key,
		rsip_sb_common_key_t *const	p_injected_key
	)

Decrypts a common key for secure boot with User Factory Programming Key (UFPK) and wrap it with the Hardware Unique Key (HUK).

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_user_factory_programming_key	Wrapped User Factory Programming Key (W-UFPK). The length is 32 bytes.
[in]	p_initial_vector	Initialization vector when generating encrypted_key. The length is 16 bytes.
[in]	p_encrypted_key	Encrypted key.
[out]	p_injected_key	Pointer to destination of injected key.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_AuthPasswordHashCompute()

fsp_err_t R_RSIP_AuthPasswordHashCompute	(	rsip_ctrl_t *const	p_ctrl,
		void const *const	p_wrapped_user_factory_programming_key,
		void const *const	p_initial_vector,
		rsip_auth_type_t const	authentication_type,
		void const *const	p_encrypted_password,
		rsip_hashed_auth_password_t *const	p_hashed_password
	)

Decrypts user password for boot/debug authentication with User Factory Programming Key (UFPK) and generates the password hash.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_user_factory_programming_key	Pointer to wrapped User Factory Programming Key (W-UFPK). The length is 32 bytes.
[in]	p_initial_vector	Pointer to initialization vector when generating encrypted_key. The length is 16 bytes.
[in]	authentication_type	Authentication type.
[in]	p_encrypted_password	Pointer to encrypted user password. The length is 32 bytes.
[out]	p_hashed_password	Pointer to destination of password The length is 32 bytes.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Selected authentication_type is not supported on this device.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_PKI_InitialRootCertWrap()

fsp_err_t R_RSIP_PKI_InitialRootCertWrap	(	rsip_ctrl_t *const	p_ctrl,
		void const *const	p_wrapped_user_factory_programming_key,
		void const *const	p_initial_vector,
		void const *const	p_encrypted_cert,
		uint32_t const	cert_length,
		uint8_t *const	p_cert,
		rsip_root_cert_mac_t *const	p_cert_mac
	)

Inputs encrypted certificate with User Factory Programming Key (UFPK) and wraps it.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_user_factory_programming_key	Wrapped User Factory Programming Key (W-UFPK). The length is 32 bytes.
[in]	p_initial_vector	Initialization vector when generating encrypted_key. The length is 16 bytes.
[in]	p_encrypted_cert	Encrypted certificate.
[in]	cert_length	Raw certificate length.
[out]	p_cert	Pointer to destination of raw certificate.
[out]	p_cert_mac	Pointer to destination of certificate MAC.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

p_cert is output with 16-byte padding. The certificate with padding is input to R_RSIP_PKI_RootCertKeyImport().

R_RSIP_PKI_RootCertKeyImport()

fsp_err_t R_RSIP_PKI_RootCertKeyImport	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_cert,
		rsip_root_cert_mac_t const *const	p_cert_mac,
		uint8_t const *const	p_key_param1,
		uint32_t const	key_param1_length,
		uint8_t const *const	p_key_param2,
		uint32_t const	key_param2_length,
		rsip_wrapped_key_t *const	p_wrapped_public_key
	)

Verifies wrapped root certificate and wraps public key included in it.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_cert	Raw certificate.
[in]	p_cert_mac	Pointer to certificate MAC.
[in]	p_key_param1	Pointer to start address of the public key parameter in certificate. [ECC] Qx [RSA] n
[in]	key_param1_length	Length of key_param1 stored in the certificate.
[in]	p_key_param2	Pointer to start address of the public key parameter in certificate. [ECC] Qy [RSA] e
[in]	key_param2_length	Length of key_param2 stored in the certificate.
[in,out]	p_wrapped_public_key	Pointer to destination of wrapped public key. The length depends on key type.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

• Enter argument p_cert of R_RSIP_PKI_InitialRootCertWrap() into this function without removing the padding.
• For arguments p_key_param1 and p_key_param2, specify an address inside the certificate. Addresses outside the certificate are invalid.

R_RSIP_KDF_TLS12PRFVerifyDataCompute()

fsp_err_t R_RSIP_KDF_TLS12PRFVerifyDataCompute	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_key,
		rsip_tls12_prf_label_t const	label,
		uint8_t const *const	p_hash,
		uint8_t *const	p_verify_data
	)

Computes plain verify_data of TLS1.2 from KDF output (TLS1.2 master secret).

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_key	Pointer to wrapped key derived by Derived Keying Material (DKM).
[in]	label	Label string. [Client] "client finished". [Server] "server finished".
[in]	p_hash	Hashed handshake message.
[out]	p_verify_data	Pointer to destination of plain verify_data.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

R_RSIP_TLS12_RSAPremasterSecretGenerate()

fsp_err_t R_RSIP_TLS12_RSAPremasterSecretGenerate	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t *const	p_wrapped_premaster_secret
	)

Generates TLS1.2 premaster secret for RSA key exchange.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[out]	p_wrapped_premaster_secret	Pointer to wrapped key of premaster secret.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

This function is used only on client side.

R_RSIP_TLS12_RSAPremasterSecretEncrypt()

fsp_err_t R_RSIP_TLS12_RSAPremasterSecretEncrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_public_key,
		rsip_wrapped_key_t const *const	p_wrapped_premaster_secret,
		uint8_t *const	p_encrypted_premaster_secret
	)

Encrypts TLS1.2 premaster secret for RSA key exchange with RSAES-PKCS1-v1_5.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_public_key	Pointer to wrapped public key imported by R_RSIP_PKI_CertKeyImport().
[in]	p_wrapped_premaster_secret	Pointer to wrapped key of premaster secret.
[out]	p_encrypted_premaster_secret	Pointer to encrypted premaster secret.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

This function used only on only client side.

R_RSIP_TLS12_RSAPremasterSecretDecrypt()

fsp_err_t R_RSIP_TLS12_RSAPremasterSecretDecrypt	(	rsip_ctrl_t *const	p_ctrl,
		rsip_wrapped_key_t const *const	p_wrapped_private_key,
		uint8_t const *const	p_encrypted_premaster_secret,
		rsip_wrapped_key_t *const	p_wrapped_premaster_secret
	)

Decrypts TLS1.2 premaster secret for RSA key exchange with RSAES-PKCS1-v1_5.

Conditions

Argument rsip_wrapped_key_t::type must be supported by both the function and the device, and must also be enabled in the configuration. For more details, please refer to Supported Algorithms and Configuration.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_wrapped_private_key	Pointer to wrapped private key.
[in]	p_encrypted_premaster_secret	Pointer to encrypted premaster secret.
[out]	p_wrapped_premaster_secret	Pointer to wrapped key of premaster secret.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_NOT_ENABLED	Input key type is disabled in this function by configuration.
FSP_ERR_CRYPTO_RSIP_KEY_SET_FAIL	Input key value is illegal.
FSP_ERR_CRYPTO_RSIP_FAIL	Input parameter is invalid.
FSP_ERR_CRYPTO_RSIP_RESOURCE_CONFLICT	A resource conflict occurred because a hardware resource required by the processing is in use by other processing.
FSP_ERR_CRYPTO_RSIP_FATAL	Software corruption is detected.

Note

This function is used only on server side.

R_RSIP_SB_ManifestVerify()

fsp_err_t R_RSIP_SB_ManifestVerify	(	rsip_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_key_cert,
		uint32_t const	key_cert_max_length,
		uint8_t const *const	p_code_cert,
		uint32_t const	code_cert_max_length
	)

Verifies a Manifest signature and decrypts program in the Manifest for secure boot.

State transition

This API can only be executed in STATE_MAIN, and does not cause any state transitions.

Note

If this API returns FSP_ERR_SB_CRYPTO_AUTH_FAIL or FSP_ERR_SB_CRYPTO_PARAM_ERR, RSIP stops working.

Parameters

[in,out]	p_ctrl	Pointer to control block.
[in]	p_key_cert	Pointer to key certificate.
[in]	key_cert_max_length	Maximum length of key certificate.
[in]	p_code_cert	Pointer to key code certificate.
[in]	code_cert_max_length	Maximum length of code certificate.

Return values

FSP_SUCCESS	Normal termination.
FSP_ERR_ASSERTION	A required parameter is NULL.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_STATE	Internal state is illegal.
FSP_ERR_SB_INTERNAL_FAIL	An internal failure.
FSP_ERR_SB_INVALID_ARG	An invalid argument was entered.
FSP_ERR_SB_UNSUPPORTED_FUNCTION	Unsupported function executed.
FSP_ERR_SB_INVALID_ALIGNMENT	Data entered with incorrect alignment.
FSP_ERR_SB_MANI_INVALID_MAGIC	An invalid magic number is set.
FSP_ERR_SB_MANI_UNSUPPORTED_VERSION	Unsupported version is set.
FSP_ERR_SB_MANI_OUT_OF_RANGE_LEN	Out of range TLV Length is set.
FSP_ERR_SB_MANI_TLV_FIELD_ERR	Missing required TLV field.
FSP_ERR_SB_MANI_TLV_INVALID_LEN	The length exceeding the end of the manifest is specified in length of the TLV field.
FSP_ERR_SB_MANI_INVALID_IMAGE_LEN	An invalid image length is set.
FSP_ERR_SB_MANI_MISMATCH_SIGN_ALGORITHM	There is a wrong combination of signature algorithms.
FSP_ERR_SB_MANI_UNSUPPORTED_ALGORITHM	An algorithm was specified that the manifest does not support.
FSP_ERR_SB_CRYPTO_FAIL	Cryptographic processing failure.
FSP_ERR_SB_CRYPTO_AUTH_FAIL	Verification failed.
FSP_ERR_SB_CRYPTO_UNSUPPORTED_ALGORITHM	Unsupported algorithm.
FSP_ERR_SB_CRYPTO_RESOURCE_CONFLICT	CryptoIP is in use.
FSP_ERR_SB_CRYPTO_PARAM_ERR	Parameter error.