1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef COMPONENTS_GCM_DRIVER_CRYPTO_GCM_MESSAGE_CRYPTOGRAPHER_H_
#define COMPONENTS_GCM_DRIVER_CRYPTO_GCM_MESSAGE_CRYPTOGRAPHER_H_
#include <stddef.h>
#include <stdint.h>
#include <memory>
#include <string>
#include "base/gtest_prod_util.h"
#include "base/strings/string_piece.h"
namespace gcm {
// Messages delivered through GCM may be encrypted according to the IETF Web
// Push protocol. We support two versions of ietf-webpush-encryption. The user
// of this class must pass in the version to use when constructing an instance.
//
// https://tools.ietf.org/html/draft-ietf-webpush-encryption-03
// https://tools.ietf.org/html/draft-ietf-webpush-encryption-08 (WGLC)
//
// This class implements the ability to encrypt or decrypt such messages using
// AEAD_AES_128_GCM with a 16-octet authentication tag. The encrypted payload
// will be stored in a single record.
//
// Note that while this class is not responsible for creating or storing the
// actual keys, it uses a key derivation function for the actual message
// encryption/decryption, thus allowing for the safe re-use of keys in multiple
// messages provided that a cryptographically-strong random salt is used.
class GCMMessageCryptographer {
public:
// Size, in bytes, of the authentication tag included in the messages.
static const size_t kAuthenticationTagBytes;
// Salt size, in bytes, that will be used together with the key to create a
// unique content encryption key for a given message.
static const size_t kSaltSize;
// Version of the encryption scheme desired by the consumer.
enum class Version {
// https://tools.ietf.org/html/draft-ietf-webpush-encryption-03
DRAFT_03,
// https://tools.ietf.org/html/draft-ietf-webpush-encryption-08 (WGLC)
DRAFT_08
};
// Interface that different versions of the encryption scheme must implement.
class EncryptionScheme {
public:
virtual ~EncryptionScheme() {}
// Type of encoding to produce in GenerateInfoForContentEncoding().
enum class EncodingType { CONTENT_ENCRYPTION_KEY, NONCE };
// Derives the pseudo random key (PRK) to use for deriving the content
// encryption key and the nonce.
virtual std::string DerivePseudoRandomKey(
const base::StringPiece& recipient_public_key,
const base::StringPiece& sender_public_key,
const base::StringPiece& ecdh_shared_secret,
const base::StringPiece& auth_secret) = 0;
// Generates the info string used for generating the content encryption key
// and the nonce used for the cryptographic transformation.
virtual std::string GenerateInfoForContentEncoding(
EncodingType type,
const base::StringPiece& recipient_public_key,
const base::StringPiece& sender_public_key) = 0;
// Creates an encryption record to contain the given |plaintext|.
virtual std::string CreateRecord(const base::StringPiece& plaintext) = 0;
// Validates that the |ciphertext_size| is valid following the scheme.
virtual bool ValidateCiphertextSize(size_t ciphertext_size,
size_t record_size) = 0;
// Verifies that the padding included in |record| is valid and removes it
// from the StringPiece. Returns whether the padding was valid.
virtual bool ValidateAndRemovePadding(base::StringPiece& record) = 0;
};
// Creates a new cryptographer for |version| of the encryption scheme.
explicit GCMMessageCryptographer(Version version);
~GCMMessageCryptographer();
// Encrypts the |plaintext| in accordance with the Web Push Encryption scheme
// this cryptographer represents, storing the result in |*record_size| and
// |*ciphertext|. Returns whether encryption was successful.
//
// |recipient_public_key|: Recipient's key as an uncompressed P-256 EC point.
// |sender_public_key|: Sender's key as an uncompressed P-256 EC point.
// |ecdh_shared_secret|: 32-byte shared secret between the key pairs.
// |auth_secret|: 16-byte prearranged secret between recipient and sender.
// |salt|: 16-byte cryptographically secure salt unique to the message.
// |plaintext|: The plaintext that is to be encrypted.
// |*record_size|: Out parameter in which the record size will be written.
// |*ciphertext|: Out parameter in which the ciphertext will be written.
[[nodiscard]] bool Encrypt(const base::StringPiece& recipient_public_key,
const base::StringPiece& sender_public_key,
const base::StringPiece& ecdh_shared_secret,
const base::StringPiece& auth_secret,
const base::StringPiece& salt,
const base::StringPiece& plaintext,
size_t* record_size,
std::string* ciphertext) const;
// Decrypts the |ciphertext| in accordance with the Web Push Encryption scheme
// this cryptographer represents, storing the result in |*plaintext|. Returns
// whether decryption was successful.
//
// |recipient_public_key|: Recipient's key as an uncompressed P-256 EC point.
// |sender_public_key|: Sender's key as an uncompressed P-256 EC point.
// |ecdh_shared_secret|: 32-byte shared secret between the key pairs.
// |auth_secret|: 16-byte prearranged secret between recipient and sender.
// |salt|: 16-byte cryptographically secure salt unique to the message.
// |ciphertext|: The ciphertext that is to be decrypted.
// |record_size|: Size of a single record. Must be larger than or equal to
// len(plaintext) plus the ciphertext's overhead (18 bytes).
// |*plaintext|: Out parameter in which the plaintext will be written.
[[nodiscard]] bool Decrypt(const base::StringPiece& recipient_public_key,
const base::StringPiece& sender_public_key,
const base::StringPiece& ecdh_shared_secret,
const base::StringPiece& auth_secret,
const base::StringPiece& salt,
const base::StringPiece& ciphertext,
size_t record_size,
std::string* plaintext) const;
private:
FRIEND_TEST_ALL_PREFIXES(GCMMessageCryptographerTest, AuthSecretAffectsPRK);
FRIEND_TEST_ALL_PREFIXES(GCMMessageCryptographerTest, InvalidRecordPadding);
enum class Direction { ENCRYPT, DECRYPT };
// Derives the content encryption key from |ecdh_shared_secret| and |salt|.
std::string DeriveContentEncryptionKey(
const base::StringPiece& recipient_public_key,
const base::StringPiece& sender_public_key,
const base::StringPiece& ecdh_shared_secret,
const base::StringPiece& salt) const;
// Derives the nonce from |ecdh_shared_secret| and |salt|.
std::string DeriveNonce(const base::StringPiece& recipient_public_key,
const base::StringPiece& sender_public_key,
const base::StringPiece& ecdh_shared_secret,
const base::StringPiece& salt) const;
// Private implementation of the encryption and decryption routines.
bool TransformRecord(Direction direction,
const base::StringPiece& input,
const base::StringPiece& key,
const base::StringPiece& nonce,
std::string* output) const;
// Implementation of the encryption scheme. Set in the constructor depending
// on the version requested by the consumer.
std::unique_ptr<EncryptionScheme> encryption_scheme_;
};
} // namespace gcm
#endif // COMPONENTS_GCM_DRIVER_CRYPTO_GCM_MESSAGE_CRYPTOGRAPHER_H_
|
