Skip to content
This repository has been archived by the owner on May 9, 2023. It is now read-only.

Home

Jump to bottom
Artem Yushev edited this page Aug 22, 2018 · 5 revisions

Available functions

begin

  • Prototype 
    int32_t begin(void);
int32_t begin(TwoWire& CustomWire);
  • Description: This function initializes the Infineon OPTIGA Trust X command library and sends the 'open application' command to the device. This opens the communicatino channel to the Optiga Trust X, so that you can carry out different operations
  • Arguments:
    • CustomWire: Reference to a custom TwoWire object used with the Optiga
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.

reset

  • Prototype 
    int32_t reset(void);
  • Description: This function resets the Infineon OPTIGA Trust X. This helps to recover the connection to the optiga once it got lost. (Indicator: 1 is returned by any other function)
  • Arguments: No arguments
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.

checkChip

  • Prototype 
    int32_t checkChip(void);
  • Description: This function performs one-way authentication of the security chip
  • Arguments: No arguments
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See: examples/selfTest

getCertificate

  • Prototype 
    int32_t getCertificate(uint8_t certificate[], uint16_t& certificateLength);
  • Description: The function retrieves the public X.509 certificate stored in the Infineon OPTIGA Trust X device. This certificate and the contained public key can be used to verify a signature from the device. In addition, the receiver of the certificate can verify the chain of trust by validating the issuer of the certificate and the issuer's signature on it.
  • Arguments:
    • certificate Pointer to the buffer that will contain the output.
    • certificateLength Pointer to the variable that will contain the length.
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See: examples/getCertificate 
      uint8_t  cert[CERT_MAXLENGTH];
  uint16_t certLen = 0;
  trustX.getCertificate(cert, certLen);

getPublicKey

  • Prototype 
    int32_t getPublicKey(uint8_t publickey[68]);
  • Description: The function retrieves the public X.509 certificate stored in the Infineon OPTIGA Trust X device and extracts the public key from it. Work for Certificates based on NIST P256 curve.
  • Arguments:
    • publickey Pointer to the buffer where the public key will be stored. Should 68 bytes long. 64 bytes for the key and 4 bytes for the encoding BitString Format (0x03, 0x42, 0x00) + Compression format (0x04) + Public Key (64 bytes)
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See: examples/calculateSignVerifySign 
      uint8_t  ifxPublicKey[68];
  trustX.getPublicKey(ifxPublicKey);

getUniqueID

  • Prototype 
    int32_t getUniqueID(uint8_t uniqueID[], uint16_t& uidLength);
  • Description: This function returns the Coprocessor UID value. Length is 27, where the first 25 bytes is the unique hardware identifier Last 2 bytes is the Embedded Software Build Number BCD Coded
  • Arguments:
    • uniqueID Pointer where the value will be stored
    • ulen Pointer where the length of the value is stored
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: 
      uint8_t  uid[UID_LENGTH];
  uint16_t uidLength = UID_LENGTH;
  trustX.getUniqueID(uid, uidLength);

getRandom

  • Prototype 
    int32_t getRandom(uint16_t length, uint8_t random[]);
  • Description: The function retrieves a cryptographic-quality random number from the OPTIGA device. This function can be used as entropy source for various security schemes.
  • Arguments:
    • length Length of the random number (range 8 to 256).
    • random Buffer to store the data.
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See examples/getRandom 
      uint8_t rnd[RND_MAXLENGTH];
  trustX.getRandom(RND_MAXLENGTH, rnd);

getCurrentLimit

  • Prototype 
    int32_t getCurrentLimit(uint8_t& currentLim);
  • Description: This function returns the current limitation, which holds the maximum value of current allowed to be consumed by the OPTIGA™ Trust X across all operating conditions. Default value 6 (6 mA). Maximum value 15 (15 mA)
  • Arguments:
    • currentLim Reference where the value will be stored
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See examples/testFullAPI 
      uint8_t current_lim;
  trustX.getCurrentLimit(current_lim);

setCurrentLimit

  • Prototype 
    int32_t setCurrentLimit(uint8_t currentLim);
  • Description: Oposite to the getCurrentLimit function. Default value 6 (6 mA). Maximum value 15 (15 mA)
  • Arguments:
    • currentLim The value that is going to be set
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See examples/testFullAPI 
      trustX.setCurrentLimit(15);

sha256

  • Prototype 
    int32_t sha256(uint8_t dataToHash[], uint16_t dlen, uint8_t hash[32]);
  • Description: This function calculates SHA256 hash of the given data.
  • Arguments:
    • dataToHash Pointer to the data
    • dlen Length of the input data
    • hash Pointer to the data array where the final result should be stored. Must be defined.
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See examples/testFullAPI 
      uint8_t  data[] = "Data to be hashed";
  uint8_t  hash[32];
  trustX.sha256(data, sizeof(data), hash);

calculateSignature

  • Prototype 
    int32_t calculateSignature(uint8_t dataToSign[], uint16_t dlen, uint16_t privateKey_oid, uint8_t result[], uint16_t& rlen);
int32_t calculateSignature(uint8_t dataToSign[], uint16_t dlen, uint8_t result[], uint16_t& rlen);
  • Description: This function generates an ECDSA FIPS 186-3 w/o hash signature.
  • Arguments:
    • dataToSign Pointer to the data
    • dlen Length of the input data
    • privateKey_oid [Optional] Object ID defines which private key slot will be used to generate the signature. Default is the first slot. Use one of:
      • eFIRST_DEVICE_PRIKEY_1 (Default)
      • eFIRST_DEVICE_PRIKEY_2
      • eFIRST_DEVICE_PRIKEY_3
      • eFIRST_DEVICE_PRIKEY_4
      • eSESSION_ID_1
      • eSESSION_ID_2
      • eSESSION_ID_3
      • eSESSION_ID_4
    • result Pointer to the data array where the final result should be stored.
    • rlen Length of the output data. Will be modified in case of success.
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See examples/calculateSignVerifySign 
      uint8_t hash[32];
  uint16_t hashLen = 32;
  uint8_t formSign[80];
  uint16_t signLen;
  trustX.calculateSignature(hash, hashLen, formSign, signLen);

formatSignature

  • Prototype 
     int32_t formatSignature(uint8_t signature[], uint16_t slen, uint8_t result[], uint16_t& rlen);
  • Description: This function encodes generated signature in ASN.1 format
  • Arguments:
    • signature Pointer to raw signature
    • slen Length of the input data
    • result Pointer to the data array where the final result should be stored.
    • rlen Length of the output data. Will be modified in case of success.
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.

verifySignature

  • Prototype 
    int32_t verifySignature(uint8_t hash[], uint16_t hlen, uint8_t signature[], uint16_t slen, uint16_t publicKey_oid);
int32_t verifySignature(uint8_t hash[], uint16_t hlen, uint8_t signature[], uint16_t slen );
int32_t verifySignature(uint8_t hash[], uint16_t hlen, uint8_t signature[], uint16_t slen, uint8_t pubKey[], uint16_t plen);
  • Description: This function verifies an ECDSA FIPS 186-3 w/o hash signature. This functions works in two modes, either use internal OID where a public key is stored or you can give your own public key as an input.
  • Arguments:
    • hash Pointer to the hash
    • hlen Length of the input data
    • publicKey_oid [Optional] Object ID defines which private key slot will be used to generate the signature. Default is the first slot. Use one of:
      • eDEVICE_PUBKEY_CERT_IFX (Default)
      • eDEVICE_PUBKEY_CERT_PRJSPC_1
      • eDEVICE_PUBKEY_CERT_PRJSPC_2
      • eDEVICE_PUBKEY_CERT_PRJSPC_3
    • signature Pointer to the data array where the final result should be stored.
    • slen Length of the output data. Will be modified in case of success.
    • pubKey A pointer to the public key to be used for the verification
    • plen Length of the public key to be used for the verification
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See examples/calculateSignVerifySign

sharedSecret

  • Prototype 
    int32_t sharedSecret(uint8_t publicKey[], uint16_t plen);
int32_t sharedSecret(uint16_t oid, uint8_t publicKey[], uint16_t plen);
int32_t sharedSecret(String curveName, uint8_t publicKey[], uint16_t plen);
int32_t sharedSecret(String curveName, uint16_t oid, uint8_t publicKey[], uint16_t plen);
int32_t sharedSecretWithExport(uint8_t publicKey[], uint16_t plen, uint8_t sharedSecret[], uint16_t shlen);
int32_t sharedSecretWithExport(String curveName, uint8_t publicKey[], uint16_t plen, uint8_t sharedSecret[], uint16_t shlen);
  • Description: This function generates a shared secret based on Elliptic Curve Diffie-Hellman Key Exchange Algorithm This functions works in several modes. In general for such functions you need to specify followng: elliptic curve type, private key, public key, result shared secret Different functions listed below:
    1. sharedSecret(p_pubkey) - Private Key is taken from the first private keys slot. NISTP256 Curve is used
    2. sharedSecret(priv_oid, p_pubkey) - Works like 1, but you can specifiy which slot to use.
    3. sharedSecret(curve_type, p_pubkey) - Works like 1, but you can define a curve type: "secp256r1" or "secp384r1"
    4. sharedSecret(curve_type, priv_oid, p_pubkey) - Works like 2, but you can define a curve type: "secp256r1" or "secp384r1"
    5. sharedSecretWithExport(p_pubkey, p_out) - Works like 1, but exports the result in p_out
    6. sharedSecretWithExport(curve_type, p_pubkey, p_out) - Works like 5, but additionally you can define curve type of the publick key This Shared secret can be used until the Session Context will be flashed, either after an application restart or a reset FW versions >= 1.40.1118, please refer to getUniqueID support sharedSecret generation from arbitrary OIDs 0xF1D0-0xF1DF. For more information refere to the Solutions Reference Manual
  • Arguments:
    • curveName Curve name. The following are supported:
      • secp256r1 (Default)
      • secp384r1
    • oid Object ID defines which slot will be used as input and output. Use one of the following slots:
      • eSESSION_ID_1
      • eSESSION_ID_2 (Default)
      • eSESSION_ID_3
      • eSESSION_ID_4
    • publicKey A pointer to a public key .
    • plen Length of a public key
    • sharedSecret Pointer to the data array where the final result should be stored.
    • shlen Length of the output data. Will be modified in case of success.
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.

generateKeypair

  • Prototype 
    	int32_t generateKeypair(uint8_t publicKey[], uint16_t& plen );
	int32_t generateKeypair(uint8_t publicKey[], uint16_t& plen, uint16_t privateKey_oid);
	int32_t generateKeypair(uint8_t publicKey[], uint16_t& plen, uint8_t privateKey[], uint16_t& prlen);
  • Description: This function generates a public private keypair. You can store the private key internally or export it for your usage
  • Arguments:
    • publicKey Pointer to the data array where the result public key should be stored.
    • plen Length of the public key
    • privateKey_oid an Object ID of a slot, where the newly generated key should be stored. Use one of the following slots:
      • eSESSION_ID_1
      • eSESSION_ID_2 (Default)
      • eSESSION_ID_3
      • eSESSION_ID_4
      • eFIRST_DEVICE_PRIKEY_1
      • eFIRST_DEVICE_PRIKEY_2
      • eFIRST_DEVICE_PRIKEY_3
      • eFIRST_DEVICE_PRIKEY_4
    • privateKey [Optional] Pointer to the data array where the result private key should be stored.
    • prlen [Optional] Length of the private key.
  • Returns:
    • 0 If the function was successful
    • 1 If the operation failed.
  • Example: See examples/generateKeypair
Clone this wiki locally