1 // Copyright 2021 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 ///////////////////////////////////////////////////////////////////////////////
16 #ifndef TINK_INTERNAL_EC_UTIL_H_
17 #define TINK_INTERNAL_EC_UTIL_H_
18
19 #include <stdint.h>
20
21 #include <memory>
22 #include <string>
23
24 #include "absl/strings/string_view.h"
25 #include "openssl/ec.h"
26 #include "tink/internal/ssl_unique_ptr.h"
27 #include "tink/subtle/common_enums.h"
28 #include "tink/util/secret_data.h"
29 #include "tink/util/statusor.h"
30
31 namespace crypto {
32 namespace tink {
33 namespace internal {
34
X25519KeyPubKeySize()35 constexpr int64_t X25519KeyPubKeySize() { return 32; }
X25519KeyPrivKeySize()36 constexpr int64_t X25519KeyPrivKeySize() { return 32; }
X25519KeySharedKeySize()37 constexpr int64_t X25519KeySharedKeySize() { return 32; }
38
Ed25519KeyPubKeySize()39 constexpr int64_t Ed25519KeyPubKeySize() { return 32; }
Ed25519KeyPrivKeySize()40 constexpr int64_t Ed25519KeyPrivKeySize() { return 32; }
41
42 struct EcKey {
43 subtle::EllipticCurveType curve;
44 // Affine coordinates in bigendian representation.
45 std::string pub_x;
46 std::string pub_y;
47 // Big integer in bigendian representation.
48 crypto::tink::util::SecretData priv;
49 };
50
51 struct X25519Key {
52 uint8_t public_value[X25519KeyPubKeySize()];
53 uint8_t private_key[X25519KeyPrivKeySize()];
54 };
55
56 struct Ed25519Key {
57 std::string public_key;
58 std::string private_key;
59 };
60
61 // EcKey.
62
63 // Returns a new EC key for the specified curve.
64 crypto::tink::util::StatusOr<EcKey> NewEcKey(
65 crypto::tink::subtle::EllipticCurveType curve_type);
66
67 // Returns a new EC key for the specified curve derived from a secret seed.
68 crypto::tink::util::StatusOr<EcKey> NewEcKey(
69 crypto::tink::subtle::EllipticCurveType curve_type,
70 const crypto::tink::util::SecretData &secret_seed);
71
72 // X25519Key Utils.
73
74 // Returns a new X25519Key key. It returns a kInternal error status if the
75 // OpenSSL/BoringSSL APIs fail.
76 crypto::tink::util::StatusOr<std::unique_ptr<X25519Key>> NewX25519Key();
77
78 // Returns a X25519Key matching the specified EcKey.
79 crypto::tink::util::StatusOr<std::unique_ptr<X25519Key>> X25519KeyFromEcKey(
80 const EcKey &ec_key);
81
82 // Returns an EcKey matching the specified X25519Key.
83 EcKey EcKeyFromX25519Key(const X25519Key *x25519_key);
84
85 // Generates a shared secret using `private_key` and `peer_public_key`; keys
86 // must be X25519 keys otherwise an error is returned.
87 crypto::tink::util::StatusOr<util::SecretData> ComputeX25519SharedSecret(
88 EVP_PKEY *private_key, EVP_PKEY *peer_public_key);
89
90 // Computes the corresponding public+private key for the supplied private key.
91 crypto::tink::util::StatusOr<std::unique_ptr<X25519Key>>
92 X25519KeyFromPrivateKey(const crypto::tink::util::SecretData &private_key);
93
94 // Ed25519Key Utils.
95
96 // Returns a new ED25519 key.
97 crypto::tink::util::StatusOr<std::unique_ptr<Ed25519Key>> NewEd25519Key();
98
99 // Returns a new ED25519 key generated from a 32-byte secret seed.
100 crypto::tink::util::StatusOr<std::unique_ptr<Ed25519Key>> NewEd25519Key(
101 const crypto::tink::util::SecretData &secret_seed);
102
103 // EC_POINT Encode/Decode.
104
105 // Given x, y as curve_size_in_bytes big-endian byte array, encoding is as
106 // follows:
107 // - The uncompressed point is encoded as 0x04 || x || y.
108 // - The compressed point is encoded as:
109 // - 0x03 || x if the least significant bit of y is 1;
110 // - 0x02 || x otherwise.
111
112 // Returns OpenSSL/BoringSSL's EC_POINT constructed from curve type
113 // `curve_type`, point `format` and encoded public key's point `encoded_point`.
114 crypto::tink::util::StatusOr<SslUniquePtr<EC_POINT>> EcPointDecode(
115 crypto::tink::subtle::EllipticCurveType curve_type,
116 crypto::tink::subtle::EcPointFormat format,
117 absl::string_view encoded_point);
118
119 // Returns the encoded public key based on curve type `curve_type`, point
120 // `format` and OpenSSL/BoringSSL's EC_POINT public key `point`.
121 crypto::tink::util::StatusOr<std::string> EcPointEncode(
122 crypto::tink::subtle::EllipticCurveType curve_type,
123 crypto::tink::subtle::EcPointFormat format, const EC_POINT *point);
124
125 // Returns the encoding size of a point on the specified elliptic curve
126 // `curve_type` when the given point `format` is used.
127 util::StatusOr<int32_t> EcPointEncodingSizeInBytes(
128 crypto::tink::subtle::EllipticCurveType curve_type,
129 crypto::tink::subtle::EcPointFormat format);
130
131 // Returns the size (in bytes) of an element of the field over which
132 // the curve `curve_type` is defined.
133 util::StatusOr<int32_t> EcFieldSizeInBytes(
134 crypto::tink::subtle::EllipticCurveType curve_type);
135
136 // EC_GROUP Utils.
137
138 // Returns OpenSSL/BoringSSL's EC_GROUP constructed from the given `curve_type`.
139 crypto::tink::util::StatusOr<SslUniquePtr<EC_GROUP>> EcGroupFromCurveType(
140 crypto::tink::subtle::EllipticCurveType curve_type);
141
142 // Returns the curve type associated with the given `group`.
143 crypto::tink::util::StatusOr<crypto::tink::subtle::EllipticCurveType>
144 CurveTypeFromEcGroup(const EC_GROUP *group);
145
146 // Returns OpenSSL/BoringSSL's EC_POINT constructed from the curve type,
147 // big-endian representation of public key's x-coordinate and y-coordinate.
148 crypto::tink::util::StatusOr<SslUniquePtr<EC_POINT>> GetEcPoint(
149 crypto::tink::subtle::EllipticCurveType curve, absl::string_view pubx,
150 absl::string_view puby);
151
152 // Transforms ECDSA IEEE_P1363 signature encoding to DER encoding.
153 //
154 // The IEEE_P1363 signature's format is r || s, where r and s are zero-padded
155 // and have the same size in bytes as the order of the curve. For example, for
156 // NIST P-256 curve, r and s are zero-padded to 32 bytes.
157 //
158 // The DER signature is encoded using ASN.1
159 // (https://tools.ietf.org/html/rfc5480#appendix-A):
160 // ECDSA-Sig-Value :: = SEQUENCE { r INTEGER, s INTEGER }.
161 // In particular, the encoding is:
162 // 0x30 || totalLength || 0x02 || r's length || r || 0x02 || s's length || s
163 util::StatusOr<std::string> EcSignatureIeeeToDer(const EC_GROUP *group,
164 absl::string_view ieee_sig);
165
166 // Returns the ECDH's shared secret between two peers A and B using A's private
167 // key `priv_key` and B's public key `pub_key`. Returns error if `pub_key`
168 // is not on `priv_key`'s curve `curve`.
169 util::StatusOr<util::SecretData> ComputeEcdhSharedSecret(
170 crypto::tink::subtle::EllipticCurveType curve, const BIGNUM *priv_key,
171 const EC_POINT *pub_key);
172
173 } // namespace internal
174 } // namespace tink
175 } // namespace crypto
176
177 #endif // TINK_INTERNAL_EC_UTIL_H_
178