EXTERNAL_HEADERS/corecrypto/cczp.h

   1 /* Copyright (c) (2010,2011,2012,2013,2014,2015,2016,2017,2018,2019) Apple Inc. All rights reserved.
   2  *
   3  * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which
   4  * is contained in the License.txt file distributed with corecrypto) and only to
   5  * people who accept that license. IMPORTANT:  Any license rights granted to you by
   6  * Apple Inc. (if any) are limited to internal use within your organization only on
   7  * devices and computers you own or control, for the sole purpose of verifying the
   8  * security characteristics and correct functioning of the Apple Software.  You may
   9  * not, directly or indirectly, redistribute the Apple Software or any portions thereof.
  10  */
  11
  12 #ifndef _CORECRYPTO_CCZP_H_
  13 #define _CORECRYPTO_CCZP_H_
  14
  15 #include <corecrypto/ccn.h>
  16 #include <corecrypto/ccrng.h>
  17
  18 /*
  19  Don't use cczp_hd struct directly, except in static tables such as eliptic curve parameter
  20  definitions.
  21
  22  Declare cczp objects using cczp_decl_n(). It allocates cc_unit arrays of the length returned by
  23  cczp_nof_n().
  24 */
  25
  26 struct cczp;
  27
  28 typedef struct cczp *cczp_t;
  29 typedef const struct cczp *cczp_const_t;
  30
  31 struct cczp_funcs;
  32 typedef const struct cczp_funcs *cczp_funcs_t;
  33
  34 // keep cczp_hd and cczp structures consistent
  35 // cczp_hd is typecasted to cczp to read EC curve params
  36 // make sure n is the first element see ccrsa_ctx_n macro
  37 #define __CCZP_HEADER_ELEMENTS_DEFINITIONS(pre) \
  38     cc_size pre##n;                             \
  39     cc_unit pre##bitlen;                        \
  40     cczp_funcs_t pre##funcs;
  41
  42 #define __CCZP_ELEMENTS_DEFINITIONS(pre)    \
  43     __CCZP_HEADER_ELEMENTS_DEFINITIONS(pre) \
  44     cc_unit pre##ccn[];
  45
  46 // cczp_hd must be defined separetly without variable length array ccn[], because it is used in
  47 // sructures such as ccdh_gp_decl_n
  48 struct cczp_hd {
  49     __CCZP_HEADER_ELEMENTS_DEFINITIONS()
  50 } CC_ALIGNED(CCN_UNIT_SIZE);
  51
  52 struct cczp {
  53     __CCZP_ELEMENTS_DEFINITIONS()
  54 } CC_ALIGNED(CCN_UNIT_SIZE);
  55
  56 /* Return the size of an cczp where each ccn is _size_ bytes. */
  57 #define cczp_size(_size_) (sizeof(struct cczp) + ccn_sizeof_n(1) + 2 * (_size_))
  58
  59 /* Return number of units that a struct cczp needs to be in units for a prime
  60    size of N units.  This is large enough for all operations.  */
  61 #define cczp_nof_n(_n_) (ccn_nof_size(sizeof(struct cczp)) + 1 + 2 * (_n_))
  62
  63 /* Return number of units that a struct cczp needs to be in units for a prime
  64    size of _n_ units. */
  65 #define cczp_decl_n(_n_, _name_) cc_ctx_decl(struct cczp, ccn_sizeof_n(cczp_nof_n(_n_)), _name_)
  66 #define cczp_clear_n(_n_, _name_) cc_clear(ccn_sizeof_n(cczp_nof_n(_n_)), _name_)
  67
  68 #define CCZP_N(ZP) ((ZP)->n)
  69 #define CCZP_PRIME(ZP) ((ZP)->ccn)
  70 #define CCZP_BITLEN(ZP) ((ZP)->bitlen)
  71 #define CCZP_RECIP(ZP) ((ZP)->ccn + CCZP_N(ZP))
  72 CC_NONNULL((1)) CC_INLINE cc_size cczp_n(cczp_const_t zp)
  73 {
  74     return zp->n;
  75 }
  76
  77 CC_NONNULL((1)) CC_INLINE const cc_unit *cczp_prime(cczp_const_t zp)
  78 {
  79     return zp->ccn;
  80 }
  81
  82 CC_NONNULL((1)) CC_INLINE size_t cczp_bitlen(cczp_const_t zp)
  83 {
  84     cc_assert(ccn_bitlen(cczp_n(zp), cczp_prime(zp)) == CCZP_BITLEN(zp));
  85     return (size_t)CCZP_BITLEN(zp);
  86 }
  87
  88 /* Return a pointer to the Reciprocal or Montgomery constant of zp, which is
  89  allocated cczp_n(zp) + 1 units long. */
  90 CC_NONNULL((1)) CC_INLINE const cc_unit *cczp_recip(cczp_const_t zp)
  91 {
  92     return zp->ccn + zp->n;
  93 }
  94
  95 /* Ensure both cczp_mod_prime(zp) and cczp_recip(zp) are valid. cczp_n and
  96    cczp_prime must have been previously initialized. The reciprocal will
  97    be computed and set. */
  98 CC_NONNULL((1))
  99 int cczp_init(cczp_t zp);
 100
 101 /*! @function cczp_init_with_recip
 102  @abstract Initializes a cczp struct with a given reciprocal.
 103
 104  @param zp    Pointer to a cczp struct.
 105  @param recip Reciprocal for zp's prime.
 106  */
 107 CC_NONNULL((1, 2))
 108 void cczp_init_with_recip(cczp_t zp, const cc_unit *recip);
 109
 110 /* Compute r = m ^ e mod cczp_prime(zp), using Montgomery ladder.
 111    - writes cczp_n(zp) units to r
 112    - reads  cczp_n(zp) units units from m and e
 113    - if r and m are not identical they must not overlap.
 114    - r and e must not overlap nor be identical.
 115    - before calling this function either cczp_init(zp) must have been called
 116    or both CCZP_MOD_PRIME((cc_unit *)zp) and CCZP_RECIP((cc_unit *)zp) must
 117    be initialized some other way.
 118  */
 119 CC_NONNULL((1, 2, 3, 4))
 120 int cczp_power(cczp_const_t zp, cc_unit *r, const cc_unit *m, const cc_unit *e);
 121
 122 /*!
 123  @brief cczp_inv(zp, r, x) computes r = x^-1 (mod p) , where p=cczp_prime(zp).
 124  @discussion It is a general function and works for any p. It validates the inputs. r and x can
 125  overlap. It writes n =cczp_n(zp) units to r, and read n units units from x and p. The output r is
 126  overwriten only if the inverse is correctly computed. This function is not constant time in
 127  absolute sense, but it does not have data dependent 'if' statements in the code.
 128  @param zp  The input zp. cczp_n(zp) and cczp_prime(zp) need to be valid. cczp_init(zp) need not to
 129  be called before invoking cczp_inv().
 130  @param x input big integer
 131  @param r output big integer
 132  @return  0 if inverse exists and correctly computed.
 133  */
 134 CC_NONNULL((1, 2, 3))
 135 int cczp_inv(cczp_const_t zp, cc_unit *r, const cc_unit *x);
 136
 137 #endif /* _CORECRYPTO_CCZP_H_ */