1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2017-2019 NXP 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without modification, 8 * are permitted provided that the following conditions are met: 9 * 10 * o Redistributions of source code must retain the above copyright notice, this list 11 * of conditions and the following disclaimer. 12 * 13 * o Redistributions in binary form must reproduce the above copyright notice, this 14 * list of conditions and the following disclaimer in the documentation and/or 15 * other materials provided with the distribution. 16 * 17 * o Neither the name of the copyright holder nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 25 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 28 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*! 34 * Header file containing the public API for the System Controller (SC) 35 * Security (SECO) function. 36 * 37 * @addtogroup SECO_SVC SECO: Security Service 38 * 39 * Module for the Security (SECO) service. 40 * 41 * @anchor seco_err 42 * 43 * @includedoc seco/details.dox 44 * 45 * @{ 46 */ 47 48 #ifndef SC_SECO_API_H 49 #define SC_SECO_API_H 50 51 /* Includes */ 52 53 #include "main/types.h" 54 #include "svc/rm/rm_api.h" 55 56 /* Defines */ 57 58 /*! 59 * @name Defines for sc_seco_auth_cmd_t 60 */ 61 /*@{*/ 62 #define SC_SECO_AUTH_CONTAINER 0U /*!< Authenticate container */ 63 #define SC_SECO_VERIFY_IMAGE 1U /*!< Verify image */ 64 #define SC_SECO_REL_CONTAINER 2U /*!< Release container */ 65 #define SC_SECO_AUTH_SECO_FW 3U /*!< SECO Firmware */ 66 #define SC_SECO_AUTH_HDMI_TX_FW 4U /*!< HDMI TX Firmware */ 67 #define SC_SECO_AUTH_HDMI_RX_FW 5U /*!< HDMI RX Firmware */ 68 #define SC_SECO_EVERIFY_IMAGE 6U /*!< Enhanced verify image */ 69 /*@}*/ 70 71 /*! 72 * @name Defines for seco_rng_stat_t 73 */ 74 /*@{*/ 75 #define SC_SECO_RNG_STAT_UNAVAILABLE 0U /*!< Unable to initialize the RNG */ 76 #define SC_SECO_RNG_STAT_INPROGRESS 1U /*!< Initialization is on-going */ 77 #define SC_SECO_RNG_STAT_READY 2U /*!< Initialized */ 78 /*@}*/ 79 80 /* Types */ 81 82 /*! 83 * This type is used to issue SECO authenticate commands. 84 */ 85 typedef uint8_t sc_seco_auth_cmd_t; 86 87 /*! 88 * This type is used to return the RNG initialization status. 89 */ 90 typedef uint32_t sc_seco_rng_stat_t; 91 92 /* Functions */ 93 94 /*! 95 * @name Image Functions 96 * @{ 97 */ 98 99 /*! 100 * This function loads a SECO image. 101 * 102 * @param[in] ipc IPC handle 103 * @param[in] addr_src address of image source 104 * @param[in] addr_dst address of image destination 105 * @param[in] len length of image to load 106 * @param[in] fw SC_TRUE = firmware load 107 * 108 * @return Returns an error code (SC_ERR_NONE = success). 109 * 110 * Return errors codes: 111 * - SC_ERR_PARM if word fuse index param out of range or invalid, 112 * - SC_ERR_UNAVAILABLE if SECO not available, 113 * - SC_ERR_IPC if SECO response has bad header tag or size, 114 * - SC_ERR_VERSION if SECO response has bad version, 115 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 116 * 117 * This is used to load images via the SECO. Examples include SECO 118 * Firmware and IVT/CSF data used for authentication. These are usually 119 * loaded into SECO TCM. \a addr_src is in secure memory. 120 * 121 * See the <em>SECO API Reference Guide</em> for more info. 122 */ 123 sc_err_t sc_seco_image_load(sc_ipc_t ipc, sc_faddr_t addr_src, 124 sc_faddr_t addr_dst, uint32_t len, sc_bool_t fw); 125 126 /*! 127 * This function is used to authenticate a SECO image or command. 128 * 129 * @param[in] ipc IPC handle 130 * @param[in] cmd authenticate command 131 * @param[in] addr address of/or metadata 132 * 133 * @return Returns an error code (SC_ERR_NONE = success). 134 * 135 * Return errors codes: 136 * - SC_ERR_PARM if word fuse index param out of range or invalid, 137 * - SC_ERR_UNAVAILABLE if SECO not available, 138 * - SC_ERR_BUSY if SECO is busy with another authentication request, 139 * - SC_ERR_FAIL if SECO response is bad, 140 * - SC_ERR_IPC if SECO response has bad header tag or size, 141 * - SC_ERR_VERSION if SECO response has bad version, 142 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 143 * 144 * This is used to authenticate a SECO image or issue a security 145 * command. \a addr often points to an container. It is also 146 * just data (or even unused) for some commands. 147 * 148 * Implementation of this command depends on the underlying security 149 * architecture of the device. For example, on devices with SECO FW, 150 * the following options apply: 151 * 152 * - cmd=SC_SECO_AUTH_CONTAINER, addr=container address (sends AHAB_AUTH_CONTAINER_REQ to SECO) 153 * - cmd=SC_SECO_VERIFY_IMAGE, addr=image mask (sends AHAB_VERIFY_IMAGE_REQ to SECO) 154 * - cmd=SC_SECO_REL_CONTAINER, addr unused (sends AHAB_RELEASE_CONTAINER_REQ to SECO) 155 * - cmd=SC_SECO_AUTH_HDMI_TX_FW, addr unused (sends AHAB_ENABLE_HDMI_X_REQ with Subsystem=0 to SECO) 156 * - cmd=SC_SECO_AUTH_HDMI_RX_FW, addr unused (sends AHAB_ENABLE_HDMI_X_REQ with Subsystem=1 to SECO) 157 * 158 * See the <em>SECO API Reference Guide</em> for more info. 159 */ 160 sc_err_t sc_seco_authenticate(sc_ipc_t ipc, 161 sc_seco_auth_cmd_t cmd, sc_faddr_t addr); 162 163 /*! 164 * This function is used to authenticate a SECO image or command. This is an 165 * enhanced version that has additional mask arguments. 166 * 167 * @param[in] ipc IPC handle 168 * @param[in] cmd authenticate command 169 * @param[in] addr address of/or metadata 170 * @param[in] mask1 metadata 171 * @param[in] mask2 metadata 172 * 173 * Return errors codes: 174 * - SC_ERR_PARM if word fuse index param out of range or invalid, 175 * - SC_ERR_UNAVAILABLE if SECO not available, 176 * - SC_ERR_BUSY if SECO is busy with another authentication request, 177 * - SC_ERR_FAIL if SECO response is bad, 178 * - SC_ERR_IPC if SECO response has bad header tag or size, 179 * - SC_ERR_VERSION if SECO response has bad version, 180 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 181 * 182 * This supports all the commands found in sc_seco_authenticate(). Those 183 * commands should set both masks to 0 (except SC_SECO_VERIFY_IMAGE). 184 185 * New commands are as follows: 186 * 187 * - cmd=SC_SECO_VERIFY_IMAGE, addr unused, mask1=image mask, mask2 unused (sends AHAB_VERIFY_IMAGE_REQ to SECO) 188 * - cmd=SC_SECO_EVERIFY_IMAGE, addr=container address, mask1=image mask, mask2=move mask (sends AHAB_EVERIFY_IMAGE_REQ to SECO) 189 * 190 * See the <em>SECO API Reference Guide</em> for more info. 191 */ 192 sc_err_t sc_seco_enh_authenticate(sc_ipc_t ipc, 193 sc_seco_auth_cmd_t cmd, sc_faddr_t addr, 194 uint32_t mask1, uint32_t mask2); 195 196 /* @} */ 197 198 /*! 199 * @name Lifecycle Functions 200 * @{ 201 */ 202 203 /*! 204 * This function updates the lifecycle of the device. 205 * 206 * @param[in] ipc IPC handle 207 * @param[in] change desired lifecycle transition 208 * 209 * @return Returns and error code (SC_ERR_NONE = success). 210 * 211 * Return errors codes: 212 * - SC_ERR_UNAVAILABLE if SECO not available, 213 * - SC_ERR_IPC if SECO response has bad header tag or size, 214 * - SC_ERR_VERSION if SECO response has bad version, 215 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 216 * 217 * This function is used for going from Open to NXP Closed to OEM Closed. 218 * Note \a change is NOT the new desired lifecycle. It is a lifecycle 219 * transition as documented in the <em>SECO API Reference Guide</em>. 220 * 221 * If any SECO request fails or only succeeds because the part is in an 222 * "OEM open" lifecycle, then a request to transition from "NXP closed" 223 * to "OEM closed" will also fail. For example, booting a signed container 224 * when the OEM SRK is not fused will succeed, but as it is an abnormal 225 * situation, a subsequent request to transition the lifecycle will return 226 * an error. 227 */ 228 sc_err_t sc_seco_forward_lifecycle(sc_ipc_t ipc, uint32_t change); 229 230 /*! 231 * This function updates the lifecycle to one of the return lifecycles. 232 * 233 * @param[in] ipc IPC handle 234 * @param[in] addr address of message block 235 * 236 * @return Returns and error code (SC_ERR_NONE = success). 237 * 238 * Return errors codes: 239 * - SC_ERR_UNAVAILABLE if SECO not available, 240 * - SC_ERR_IPC if SECO response has bad header tag or size, 241 * - SC_ERR_VERSION if SECO response has bad version, 242 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 243 * 244 * Note \a addr must be a pointer to a signed message block. 245 * 246 * To switch back to NXP states (Full Field Return), message must be signed 247 * by NXP SRK. For OEM States (Partial Field Return), must be signed by OEM 248 * SRK. 249 * 250 * See the <em>SECO API Reference Guide</em> for more info. 251 */ 252 sc_err_t sc_seco_return_lifecycle(sc_ipc_t ipc, sc_faddr_t addr); 253 254 /*! 255 * This function is used to commit into the fuses any new SRK revocation 256 * and FW version information that have been found in the primary and 257 * secondary containers. 258 * 259 * @param[in] ipc IPC handle 260 * @param[in,out] info pointer to information type to be committed 261 * 262 * The return \a info will contain what was actually committed. 263 * 264 * @return Returns an error code (SC_ERR_NONE = success). 265 * 266 * Return errors codes: 267 * - SC_ERR_PARM if \a info is invalid, 268 * - SC_ERR_UNAVAILABLE if SECO not available, 269 * - SC_ERR_IPC if SECO response has bad header tag or size, 270 * - SC_ERR_VERSION if SECO response has bad version, 271 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 272 */ 273 sc_err_t sc_seco_commit(sc_ipc_t ipc, uint32_t *info); 274 275 /* @} */ 276 277 /*! 278 * @name Attestation Functions 279 * @{ 280 */ 281 282 /*! 283 * This function is used to set the attestation mode. Only the owner of 284 * the SC_R_ATTESTATION resource may make this call. 285 * 286 * @param[in] ipc IPC handle 287 * @param[in] mode mode 288 * 289 * @return Returns an error code (SC_ERR_NONE = success). 290 * 291 * Return errors codes: 292 * - SC_ERR_PARM if \a mode is invalid, 293 * - SC_ERR_NOACCESS if SC_R_ATTESTATON not owned by caller, 294 * - SC_ERR_UNAVAILABLE if SECO not available, 295 * - SC_ERR_IPC if SECO response has bad header tag or size, 296 * - SC_ERR_VERSION if SECO response has bad version, 297 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 298 * 299 * This is used to set the SECO attestation mode. This can be prover 300 * or verifier. See the <em>SECO API Reference Guide</em> for more on the 301 * supported modes, mode values, and mode behavior. 302 */ 303 sc_err_t sc_seco_attest_mode(sc_ipc_t ipc, uint32_t mode); 304 305 /*! 306 * This function is used to request attestation. Only the owner of 307 * the SC_R_ATTESTATION resource may make this call. 308 * 309 * @param[in] ipc IPC handle 310 * @param[in] nonce unique value 311 * 312 * @return Returns an error code (SC_ERR_NONE = success). 313 * 314 * Return errors codes: 315 * - SC_ERR_NOACCESS if SC_R_ATTESTATON not owned by caller, 316 * - SC_ERR_UNAVAILABLE if SECO not available, 317 * - SC_ERR_IPC if SECO response has bad header tag or size, 318 * - SC_ERR_VERSION if SECO response has bad version, 319 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 320 * 321 * This is used to ask SECO to perform an attestation. The result depends 322 * on the attestation mode. After this call, the signature can be 323 * requested or a verify can be requested. 324 * 325 * See the <em>SECO API Reference Guide</em> for more info. 326 */ 327 sc_err_t sc_seco_attest(sc_ipc_t ipc, uint64_t nonce); 328 329 /*! 330 * This function is used to retrieve the attestation public key. 331 * Mode must be verifier. Only the owner of the SC_R_ATTESTATION resource 332 * may make this call. 333 * 334 * @param[in] ipc IPC handle 335 * @param[in] addr address to write response 336 * 337 * Result will be written to \a addr. The \a addr parameter must point 338 * to an address SECO can access. It must be 64-bit aligned. There 339 * should be 96 bytes of space. 340 * 341 * @return Returns an error code (SC_ERR_NONE = success). 342 * 343 * Return errors codes: 344 * - SC_ERR_PARM if \a addr bad or attestation has not been requested, 345 * - SC_ERR_NOACCESS if SC_R_ATTESTATON not owned by caller, 346 * - SC_ERR_UNAVAILABLE if SECO not available, 347 * - SC_ERR_IPC if SECO response has bad header tag or size, 348 * - SC_ERR_VERSION if SECO response has bad version, 349 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 350 * 351 * See the <em>SECO API Reference Guide</em> for more info. 352 */ 353 sc_err_t sc_seco_get_attest_pkey(sc_ipc_t ipc, sc_faddr_t addr); 354 355 /*! 356 * This function is used to retrieve attestation signature and parameters. 357 * Mode must be provider. Only the owner of the SC_R_ATTESTATION resource 358 * may make this call. 359 * 360 * @param[in] ipc IPC handle 361 * @param[in] addr address to write response 362 * 363 * Result will be written to \a addr. The \a addr parameter must point 364 * to an address SECO can access. It must be 64-bit aligned. There 365 * should be 120 bytes of space. 366 * 367 * @return Returns an error code (SC_ERR_NONE = success). 368 * 369 * Return errors codes: 370 * - SC_ERR_PARM if \a addr bad or attestation has not been requested, 371 * - SC_ERR_NOACCESS if SC_R_ATTESTATON not owned by caller, 372 * - SC_ERR_UNAVAILABLE if SECO not available, 373 * - SC_ERR_IPC if SECO response has bad header tag or size, 374 * - SC_ERR_VERSION if SECO response has bad version, 375 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 376 * 377 * See the <em>SECO API Reference Guide</em> for more info. 378 */ 379 sc_err_t sc_seco_get_attest_sign(sc_ipc_t ipc, sc_faddr_t addr); 380 381 /*! 382 * This function is used to verify attestation. Mode must be verifier. 383 * Only the owner of the SC_R_ATTESTATION resource may make this call. 384 * 385 * @param[in] ipc IPC handle 386 * @param[in] addr address of signature 387 * 388 * The \a addr parameter must point to an address SECO can access. It must be 389 * 64-bit aligned. 390 * 391 * @return Returns an error code (SC_ERR_NONE = success). 392 * 393 * Return errors codes: 394 * - SC_ERR_PARM if \a addr bad or attestation has not been requested, 395 * - SC_ERR_NOACCESS if SC_R_ATTESTATON not owned by caller, 396 * - SC_ERR_UNAVAILABLE if SECO not available, 397 * - SC_ERR_FAIL if signature doesn't match, 398 * - SC_ERR_IPC if SECO response has bad header tag or size, 399 * - SC_ERR_VERSION if SECO response has bad version, 400 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 401 * 402 * See the <em>SECO API Reference Guide</em> for more info. 403 */ 404 sc_err_t sc_seco_attest_verify(sc_ipc_t ipc, sc_faddr_t addr); 405 406 /* @} */ 407 408 /*! 409 * @name Key Functions 410 * @{ 411 */ 412 413 /*! 414 * This function is used to generate a SECO key blob. 415 * 416 * @param[in] ipc IPC handle 417 * @param[in] id key identifier 418 * @param[in] load_addr load address 419 * @param[in] export_addr export address 420 * @param[in] max_size max export size 421 * 422 * @return Returns an error code (SC_ERR_NONE = success). 423 * 424 * Return errors codes: 425 * - SC_ERR_PARM if word fuse index param out of range or invalid, 426 * - SC_ERR_UNAVAILABLE if SECO not available, 427 * - SC_ERR_IPC if SECO response has bad header tag or size, 428 * - SC_ERR_VERSION if SECO response has bad version, 429 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 430 * 431 * This function is used to encapsulate sensitive keys in a specific structure 432 * called a blob, which provides both confidentiality and integrity protection. 433 * 434 * See the <em>SECO API Reference Guide</em> for more info. 435 */ 436 sc_err_t sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, 437 sc_faddr_t load_addr, sc_faddr_t export_addr, uint16_t max_size); 438 439 /*! 440 * This function is used to load a SECO key. 441 * 442 * @param[in] ipc IPC handle 443 * @param[in] id key identifier 444 * @param[in] addr key address 445 * 446 * @return Returns an error code (SC_ERR_NONE = success). 447 * 448 * Return errors codes: 449 * - SC_ERR_PARM if word fuse index param out of range or invalid, 450 * - SC_ERR_UNAVAILABLE if SECO not available, 451 * - SC_ERR_IPC if SECO response has bad header tag or size, 452 * - SC_ERR_VERSION if SECO response has bad version, 453 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 454 * 455 * This function is used to install private cryptographic keys encapsulated 456 * in a blob previously generated by SECO. The controller can be either the 457 * IEE or the VPU. The blob header carries the controller type and the key 458 * size, as provided by the user when generating the key blob. 459 * 460 * See the <em>SECO API Reference Guide</em> for more info. 461 */ 462 sc_err_t sc_seco_load_key(sc_ipc_t ipc, uint32_t id, 463 sc_faddr_t addr); 464 465 /* @} */ 466 467 /*! 468 * @name Manufacturing Protection Functions 469 * @{ 470 */ 471 472 /*! 473 * This function is used to get the manufacturing protection public key. 474 * 475 * @param[in] ipc IPC handle 476 * @param[in] dst_addr destination address 477 * @param[in] dst_size destination size 478 * 479 * @return Returns an error code (SC_ERR_NONE = success). 480 * 481 * Return errors codes: 482 * - SC_ERR_PARM if word fuse index param out of range or invalid, 483 * - SC_ERR_UNAVAILABLE if SECO not available, 484 * - SC_ERR_IPC if SECO response has bad header tag or size, 485 * - SC_ERR_VERSION if SECO response has bad version, 486 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 487 * 488 * This function is supported only in OEM-closed lifecycle. It generates 489 * the mfg public key and stores it in a specific location in the secure 490 * memory. 491 * 492 * See the <em>SECO API Reference Guide</em> for more info. 493 */ 494 sc_err_t sc_seco_get_mp_key(sc_ipc_t ipc, sc_faddr_t dst_addr, 495 uint16_t dst_size); 496 497 /*! 498 * This function is used to update the manufacturing protection message 499 * register. 500 * 501 * @param[in] ipc IPC handle 502 * @param[in] addr data address 503 * @param[in] size size 504 * @param[in] lock lock_reg 505 * 506 * @return Returns an error code (SC_ERR_NONE = success). 507 * 508 * Return errors codes: 509 * - SC_ERR_PARM if word fuse index param out of range or invalid, 510 * - SC_ERR_UNAVAILABLE if SECO not available, 511 * - SC_ERR_IPC if SECO response has bad header tag or size, 512 * - SC_ERR_VERSION if SECO response has bad version, 513 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 514 * 515 * This function is supported only in OEM-closed lifecycle. It updates the 516 * content of the MPMR (Manufacturing Protection Message register of 256 517 * bits). This register will be appended to the input-data message when 518 * generating the signature. Please refer to the CAAM block guide for details. 519 * 520 * See the <em>SECO API Reference Guide</em> for more info. 521 */ 522 sc_err_t sc_seco_update_mpmr(sc_ipc_t ipc, sc_faddr_t addr, 523 uint8_t size, uint8_t lock); 524 525 /*! 526 * This function is used to get the manufacturing protection signature. 527 * 528 * @param[in] ipc IPC handle 529 * @param[in] msg_addr message address 530 * @param[in] msg_size message size 531 * @param[in] dst_addr destination address 532 * @param[in] dst_size destination size 533 * 534 * @return Returns an error code (SC_ERR_NONE = success). 535 * 536 * Return errors codes: 537 * - SC_ERR_PARM if word fuse index param out of range or invalid, 538 * - SC_ERR_UNAVAILABLE if SECO not available, 539 * - SC_ERR_IPC if SECO response has bad header tag or size, 540 * - SC_ERR_VERSION if SECO response has bad version, 541 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 542 * 543 * This function is used to generate an ECDSA signature for an input-data 544 * message and to store it in a specific location in the secure memory. It 545 * is only supported in OEM-closed lifecycle. In order to get the ECDSA 546 * signature, the RNG must be initialized. In case it has not been started 547 * an error will be returned. 548 * 549 * See the <em>SECO API Reference Guide</em> for more info. 550 */ 551 sc_err_t sc_seco_get_mp_sign(sc_ipc_t ipc, sc_faddr_t msg_addr, 552 uint16_t msg_size, sc_faddr_t dst_addr, uint16_t dst_size); 553 554 /* @} */ 555 556 /*! 557 * @name Debug Functions 558 * @{ 559 */ 560 561 /*! 562 * This function is used to return the SECO FW build info. 563 * 564 * @param[in] ipc IPC handle 565 * @param[out] version pointer to return build number 566 * @param[out] commit pointer to return commit ID (git SHA-1) 567 */ 568 void sc_seco_build_info(sc_ipc_t ipc, uint32_t *version, 569 uint32_t *commit); 570 571 /*! 572 * This function is used to return SECO chip info. 573 * 574 * @param[in] ipc IPC handle 575 * @param[out] lc pointer to return lifecycle 576 * @param[out] monotonic pointer to return monotonic counter 577 * @param[out] uid_l pointer to return UID (lower 32 bits) 578 * @param[out] uid_h pointer to return UID (upper 32 bits) 579 * 580 * @return Returns and error code (SC_ERR_NONE = success). 581 * 582 * Return errors codes: 583 * - SC_ERR_UNAVAILABLE if SECO not available, 584 * - SC_ERR_IPC if SECO response has bad header tag or size, 585 * - SC_ERR_VERSION if SECO response has bad version, 586 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 587 */ 588 sc_err_t sc_seco_chip_info(sc_ipc_t ipc, uint16_t *lc, 589 uint16_t *monotonic, uint32_t *uid_l, uint32_t *uid_h); 590 591 /*! 592 * This function securely enables debug. 593 * 594 * @param[in] ipc IPC handle 595 * @param[in] addr address of message block 596 * 597 * @return Returns and error code (SC_ERR_NONE = success). 598 * 599 * Return errors codes: 600 * - SC_ERR_UNAVAILABLE if SECO not available, 601 * - SC_ERR_IPC if SECO response has bad header tag or size, 602 * - SC_ERR_VERSION if SECO response has bad version, 603 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 604 * 605 * Note \a addr must be a pointer to a signed message block. 606 * 607 * See the <em>SECO API Reference Guide</em> for more info. 608 */ 609 sc_err_t sc_seco_enable_debug(sc_ipc_t ipc, sc_faddr_t addr); 610 611 /*! 612 * This function is used to return an event from the SECO error log. 613 * 614 * @param[in] ipc IPC handle 615 * @param[out] idx index of event to return 616 * @param[out] event pointer to return event 617 * 618 * @return Returns an error code (SC_ERR_NONE = success). 619 * 620 * Return errors codes: 621 * - SC_ERR_UNAVAILABLE if SECO not available, 622 * - SC_ERR_IPC if SECO response has bad header tag or size, 623 * - SC_ERR_VERSION if SECO response has bad version, 624 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 625 * 626 * Read of \a idx 0 captures events from SECO. Loop starting 627 * with 0 until an error is returned to dump all events. 628 */ 629 sc_err_t sc_seco_get_event(sc_ipc_t ipc, uint8_t idx, 630 uint32_t *event); 631 632 /* @} */ 633 634 /*! 635 * @name Miscellaneous Functions 636 * @{ 637 */ 638 639 /*! 640 * This function securely writes a group of fuse words. 641 * 642 * @param[in] ipc IPC handle 643 * @param[in] addr address of message block 644 * 645 * @return Returns and error code (SC_ERR_NONE = success). 646 * 647 * Return errors codes: 648 * - SC_ERR_UNAVAILABLE if SECO not available, 649 * - SC_ERR_IPC if SECO response has bad header tag or size, 650 * - SC_ERR_VERSION if SECO response has bad version, 651 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 652 * 653 * Note \a addr must be a pointer to a signed message block. 654 * 655 * See the <em>SECO API Reference Guide</em> for more info. 656 */ 657 sc_err_t sc_seco_fuse_write(sc_ipc_t ipc, sc_faddr_t addr); 658 659 /*! 660 * This function applies a patch. 661 * 662 * @param[in] ipc IPC handle 663 * @param[in] addr address of message block 664 * 665 * @return Returns and error code (SC_ERR_NONE = success). 666 * 667 * Return errors codes: 668 * - SC_ERR_UNAVAILABLE if SECO not available, 669 * - SC_ERR_IPC if SECO response has bad header tag or size, 670 * - SC_ERR_VERSION if SECO response has bad version, 671 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 672 * 673 * Note \a addr must be a pointer to a signed message block. 674 * 675 * See the <em>SECO API Reference Guide</em> for more info. 676 */ 677 sc_err_t sc_seco_patch(sc_ipc_t ipc, sc_faddr_t addr); 678 679 /*! 680 * This function starts the random number generator. 681 * 682 * @param[in] ipc IPC handle 683 * @param[out] status pointer to return state of RNG 684 * 685 * @return Returns and error code (SC_ERR_NONE = success). 686 * 687 * Return errors codes: 688 * - SC_ERR_UNAVAILABLE if SECO not available, 689 * - SC_ERR_IPC if SECO response has bad header tag or size, 690 * - SC_ERR_VERSION if SECO response has bad version, 691 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 692 * 693 * The RNG is started automatically after all CPUs are booted. This 694 * function can be used to start earlier and to check the status. 695 * 696 * See the <em>SECO API Reference Guide</em> for more info. 697 */ 698 sc_err_t sc_seco_start_rng(sc_ipc_t ipc, sc_seco_rng_stat_t *status); 699 700 /*! 701 * This function sends a generic signed message to the 702 * SECO SHE/HSM components. 703 * 704 * @param[in] ipc IPC handle 705 * @param[in] addr address of message block 706 * 707 * @return Returns and error code (SC_ERR_NONE = success). 708 * 709 * Return errors codes: 710 * - SC_ERR_UNAVAILABLE if SECO not available, 711 * - SC_ERR_IPC if SECO response has bad header tag or size, 712 * - SC_ERR_VERSION if SECO response has bad version, 713 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 714 * 715 * Note \a addr must be a pointer to a signed message block. 716 * 717 * See the <em>SECO API Reference Guide</em> for more info. 718 */ 719 sc_err_t sc_seco_sab_msg(sc_ipc_t ipc, sc_faddr_t addr); 720 721 /*! 722 * This function is used to enable security violation and tamper interrupts. 723 * These are then reported using the IRQ service via the SC_IRQ_SECVIO 724 * interrupt. Note it is automatically enabled at boot. 725 * 726 * @param[in] ipc IPC handle 727 * 728 * @return Returns and error code (SC_ERR_NONE = success). 729 * 730 * Return errors codes: 731 * - SC_ERR_NOACCESS if caller does not own SC_R_SECVIO, 732 * - SC_ERR_UNAVAILABLE if SECO not available, 733 * - SC_ERR_IPC if SECO response has bad header tag or size, 734 * - SC_ERR_VERSION if SECO response has bad version, 735 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 736 * 737 * The security violation interrupt is self-masking. Once it is cleared in 738 * the SNVS it must be re-enabled using this function. 739 */ 740 sc_err_t sc_seco_secvio_enable(sc_ipc_t ipc); 741 742 /*! 743 * This function is used to read/write SNVS security violation 744 * and tamper registers. 745 * 746 * @param[in] ipc IPC handle 747 * @param[in] id register ID 748 * @param[in] access 0=read, 1=write 749 * @param[in] data0 pointer to data to read or write 750 * @param[in] data1 pointer to data to read or write 751 * @param[in] data2 pointer to data to read or write 752 * @param[in] data3 pointer to data to read or write 753 * @param[in] data4 pointer to data to read or write 754 * @param[in] size number of valid data words 755 * 756 * @return Returns and error code (SC_ERR_NONE = success). 757 * 758 * Return errors codes: 759 * - SC_ERR_NOACCESS if caller does not own SC_R_SECVIO, 760 * - SC_ERR_UNAVAILABLE if SECO not available, 761 * - SC_ERR_IPC if SECO response has bad header tag or size, 762 * - SC_ERR_VERSION if SECO response has bad version, 763 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 764 * 765 * Unused data words can be passed a NULL pointer. 766 * 767 * See AHAB_MANAGE_SNVS_REQ in the <em>SECO API Reference Guide</em> for 768 * more info. 769 */ 770 sc_err_t sc_seco_secvio_config(sc_ipc_t ipc, uint8_t id, uint8_t access, 771 uint32_t *data0, uint32_t *data1, uint32_t *data2, uint32_t *data3, 772 uint32_t *data4, uint8_t size); 773 774 /*! 775 * This function is used to read/write SNVS security violation 776 * and tamper DGO registers. 777 * 778 * @param[in] ipc IPC handle 779 * @param[in] id regsiter ID 780 * @param[in] access 0=read, 1=write 781 * @param[in] data pointer to data to read or write 782 * 783 * @return Returns and error code (SC_ERR_NONE = success). 784 * 785 * Return errors codes: 786 * - SC_ERR_NOACCESS if caller does not own SC_R_SECVIO, 787 * - SC_ERR_UNAVAILABLE if SECO not available, 788 * - SC_ERR_IPC if SECO response has bad header tag or size, 789 * - SC_ERR_VERSION if SECO response has bad version, 790 * - Others, see the [Security Service Detailed Description](\ref seco_err) section 791 * 792 * See AHAB_MANAGE_SNVS_DGO_REQ in the <em>SECO API Reference Guide</em> 793 * for more info. 794 */ 795 sc_err_t sc_seco_secvio_dgo_config(sc_ipc_t ipc, uint8_t id, 796 uint8_t access, uint32_t *data); 797 798 /* @} */ 799 800 #endif /* SC_SECO_API_H */ 801 802 /**@}*/ 803 804
