include/psa/crypto_extra.h

9  * This file is reserved for vendor-specific definitions.
27 /* UID for secure storage seed */
30 /* See mbedtls_config.h for definition */
38  * See mbedtls_config.h for the definition. */
49 /** \brief Declare the enrollment algorithm for a key.
56  *                              for, in addition to the algorithm set with
64  *          if it is necessary to support a protocol for which it has been
91  * A slot number is only defined for keys that are stored in a secure
120  * A slot number is only meaningful for keys that are stored in a secure
124  * \note Setting a slot number in key attributes for a key creation can
131  *         valid in general or not valid for this specific key.
171  *                                range for persistent keys.
185  *         The secure element driver for the specified lifetime does not
232     /** Number of slots containing key material for a volatile key. */
234     /** Number of slots containing key material for a key which is in
245     /** Number of slots that are not used for anything. */
265  * \brief Inject an initial entropy seed for the random generator into
268  * This function injects data to be used as a seed for the random generator
285  * You can call this function again after correcting the reason for the
322  *         of the PSA Crypto implementation is now ready for use.
360  * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
361  * or the order of the curve's base point for ECC).
445  * this function replaces Mbed TLS's entropy and DRBG modules for all
451  *       is responsible for ensuring that the random generator is seeded
473  *         this function is responsible for obtaining as much entropy as
492 /** The minimum value for a key identifier that is built into the
505 /** The maximum value for a key identifier that is built into the
508  * See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.
548  * \param key_id                The key ID for which to retrieve the
604  *       set) for now this function only checks the state of the driver
653  * For more information on how to set a specific curve or field, refer to the
676  * The key exchange flow for J-PAKE is as follows:
681  *    // Get the ZKP public key for x1
683  *    // Get the ZKP proof for x1
687  *    // Get the ZKP public key for x2
689  *    // Get the ZKP proof for x2
697  *    // Set the ZKP public key for x3
699  *    // Set the ZKP proof for x3
703  *    // Set the ZKP public key for x4
705  *    // Set the ZKP proof for x4
712  *    // Get ZKP public key for x2*s
714  *    // Get ZKP proof for x2*s
722  *    // Set ZKP public key for x4*s
724  *    // Set ZKP proof for x4*s
733  * For more information consult the documentation of the individual
742  * for example accessing restricted files).
745  * of RFC 8236 for two examples.
754  * This is a proposed PAKE interface for the PSA Crypto API. It is not part of
759  *       Same holds for the corresponding macros #PSA_ALG_CATEGORY_PAKE and
766  * Encodes the application's role in the algorithm is being executed. For more
772 /** Encoding of input and output indicators for PAKE.
775  * This type is for encoding additional input and output data for such
785  * For more information see the documentation of individual
792  * For more information see the documentation of individual
799  * For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
804  * This value can be used in a call to psa_pake_set_role() for symmetric PAKE
812  * ordering of peers for the transcript calculations. If the algorithm does not
821  * ordering of peers for the transcript calculations. If the algorithm does not
842  * specific elliptic curve, using the same mapping that is used for ECC
850  * -# The format for group elements is the same as for public keys on the
851  *  specific curve would be. For more information, consult the documentation of
853  * -# The format for scalars is the same as for private keys on the specific
854  *  curve would be. For more information, consult the documentation of
862  * a specific Diffie-Hellman group, using the same mapping that is used for
870  * -# The format for group elements is the same as for public keys on the
871  *  specific group would be. For more information, consult the documentation of
873  * -# The format for scalars is the same as for private keys on the specific
874  *  group would be. For more information, consult the documentation of
885  *                      on \p pake_type, for more information consult the
890  *                      of this parameter depends on \p pake_family, for more
905  * The format for both input and output at this step is the same as for public
909  * For more information on the format, consult the documentation of
912  * For information regarding how the group is determined, consult the
922  * The format for both input and output at this step is the same as for public
926  * For more information on the format, consult the documentation of
929  * For information regarding how the group is determined, consult the
939  * Both for input and output, the value at this step is an integer less than
943  * - For Montgomery curves, the encoding is little endian.
944  * - For everything else the encoding is big endian (see Section 2.3.8 of
950  * For information regarding how the group is determined, consult the
957 /** A sufficient output buffer size for psa_pake_output().
969  * \param output_step   A value of type ::psa_pake_step_t that is valid for the
971  * \return              A sufficient output buffer size for the specified
988 /** A sufficient input buffer size for psa_pake_input().
990  * The value returned by this macro is guaranteed to be large enough for any
1000  * \param input_step    A value of type ::psa_pake_step_t that is valid for the
1002  * \return              A sufficient input buffer size for the specified
1018 /** Output buffer size for psa_pake_output() for any of the supported PAKE
1030 /** Input buffer size for psa_pake_input() for any of the supported PAKE
1042 /** Returns a suitable initializer for a PAKE cipher suite object of type
1047 /** Returns a suitable initializer for a PAKE operation object of type
1078 …PSA_JPAKE_X1_STEP_KEY_SHARE   = 1,  /* Round 1: input/output key share (for ephemeral private key …
1079 …PSA_JPAKE_X1_STEP_ZK_PUBLIC   = 2,  /* Round 1: input/output Schnorr NIZKP public key for the X1 k…
1080 … PSA_JPAKE_X1_STEP_ZK_PROOF    = 3,  /* Round 1: input/output Schnorr NIZKP proof for the X1 key */
1081 …PSA_JPAKE_X2_STEP_KEY_SHARE   = 4,  /* Round 1: input/output key share (for ephemeral private key …
1082 …PSA_JPAKE_X2_STEP_ZK_PUBLIC   = 5,  /* Round 1: input/output Schnorr NIZKP public key for the X2 k…
1083 … PSA_JPAKE_X2_STEP_ZK_PROOF    = 6,  /* Round 1: input/output Schnorr NIZKP proof for the X2 key */
1085 …PSA_JPAKE_X2S_STEP_ZK_PUBLIC  = 8,  /* Round 2: output Schnorr NIZKP public key for the X2S key (o…
1086 …PSA_JPAKE_X2S_STEP_ZK_PROOF   = 9,  /* Round 2: output Schnorr NIZKP proof for the X2S key (our ke…
1088 …PSA_JPAKE_X4S_STEP_ZK_PUBLIC  = 11, /* Round 2: input Schnorr NIZKP public key for the X4S key (fr…
1089 …PSA_JPAKE_X4S_STEP_ZK_PROOF   = 12  /* Round 2: input Schnorr NIZKP proof for the X4S key (from pe…
1136     /* Stage of the PAKE operation: waiting for the setup, collecting inputs
1157 /** The type of the data structure for PAKE cipher suites.
1165 /** Return an initial value for a PAKE cipher suite object.
1178 /** Declare the PAKE algorithm for the cipher suite.
1202 /** Declare the primitive for a PAKE cipher suite.
1243 /** Declare the hash algorithm for a PAKE cipher suite.
1250  * for more information.
1262 /** The type of the state data structure for PAKE operations.
1266  * - Set the structure to all-bits-zero, for example:
1271  * - Initialize the structure to logical zero values, for example:
1276  *   for example:
1281  *   to the structure, for example:
1292 /** The type of input values for PAKE operations. */
1295 /** The type of computation stage for J-PAKE operations. */
1298 /** Return an initial value for a PAKE operation object.
1319  * \param[out] buffer           Return buffer for password.
1399  * \param[out] cipher_suite     Return buffer for role.
1410 /** Set the session information for a password-authenticated key exchange.
1417  *    documentation for #psa_pake_operation_t, e.g.
1426  * for more information.
1436  * -# Call psa_pake_get_implicit_key() for accessing the shared secret.
1440  * for more information.
1483 /** Set the password for a password-authenticated key exchange from key ID.
1488  * \param[in,out] operation     The operation object to set the password for. It
1492  *                              be on operation for which the password hasn't
1511  *         The key type for \p password is not #PSA_KEY_TYPE_PASSWORD or
1531 /** Set the user ID for a password-authenticated key exchange.
1533  * Call this function to set the user ID. For PAKE algorithms that associate a
1535  * psa_pake_set_peer() as well. For PAKE algorithms that associate a single
1540  * for more information.
1542  * \param[in,out] operation     The operation object to set the user ID for. It
1546  *                              be on operation for which the user ID hasn't
1555  *         \p user_id is not valid for the \p operation's algorithm and cipher
1572 /** Set the peer ID for a password-authenticated key exchange.
1574  * Call this function in addition to psa_pake_set_user() for PAKE algorithms
1575  * that associate a user identifier with each side of the session. For PAKE
1581  * for more information.
1583  * \param[in,out] operation     The operation object to set the peer ID for. It
1587  *                              be on operation for which the peer ID hasn't
1596  *         \p peer_id is not valid for the \p operation's algorithm and cipher
1614 /** Set the application role for a password-authenticated key exchange.
1617  * It is optional to call this function for PAKEs that don't require a role
1618  * to be specified. For such PAKEs the application role parameter is ignored,
1623  * for more information.
1626  *                              application's role for. It must have been set up
1629  *                              called yet). It must be on operation for which
1634  *                              that is being set up. For more information see
1643  *         The \p role for this algorithm is not supported or is not valid.
1655 /** Get output for a step of a password-authenticated key exchange.
1663  * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1670  * \param step                 The step of the algorithm for which the output is
1673  *                             format appropriate for this \p step. Refer to
1675  *                             \c PSA_PAKE_STEP_XXX constants for more
1705  *         for ordering of input and output steps), or
1716 /** Provide input for a step of a password-authenticated key exchange.
1724  * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1731  * \param step                 The step for which the input is provided.
1733  *                             appropriate for this \p step. Refer to the
1735  *                             \c PSA_PAKE_STEP_XXX constants for more
1742  *         The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step.
1745  *         or the \p input is not valid for the \p operation's algorithm,
1749  *         \p input is not supported for the \p operation's algorithm, cipher
1760  *         for ordering of input and output steps), or
1778  * is who it claims to be. For example, do not access restricted files on the
1790  * ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
1800  *                             for an input step of type
1821  *         or the state of \p output is not valid for
1833  * Aborting an operation frees all associated resources except for the \c
1835  * for another operation by calling psa_pake_setup() again.