1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef CRYPTO_SYMMETRIC_KEY_H_
6 #define CRYPTO_SYMMETRIC_KEY_H_
11 #include "base/basictypes.h"
12 #include "crypto/crypto_export.h"
15 #include "crypto/scoped_nss_types.h"
16 #elif defined(OS_MACOSX)
17 #include <Security/cssmtype.h>
19 #include "crypto/scoped_capi_types.h"
24 // Wraps a platform-specific symmetric key and allows it to be held in a
26 class CRYPTO_EXPORT SymmetricKey
{
28 // Defines the algorithm that a key will be used with. See also
35 virtual ~SymmetricKey();
37 // Generates a random key suitable to be used with |algorithm| and of
38 // |key_size_in_bits| bits.
39 // The caller is responsible for deleting the returned SymmetricKey.
40 static SymmetricKey
* GenerateRandomKey(Algorithm algorithm
,
41 size_t key_size_in_bits
);
43 // Derives a key from the supplied password and salt using PBKDF2, suitable
44 // for use with specified |algorithm|. Note |algorithm| is not the algorithm
45 // used to derive the key from the password. The caller is responsible for
46 // deleting the returned SymmetricKey.
47 static SymmetricKey
* DeriveKeyFromPassword(Algorithm algorithm
,
48 const std::string
& password
,
49 const std::string
& salt
,
51 size_t key_size_in_bits
);
53 // Imports an array of key bytes in |raw_key|. This key may have been
54 // generated by GenerateRandomKey or DeriveKeyFromPassword and exported with
55 // GetRawKey, or via another compatible method. The key must be of suitable
56 // size for use with |algorithm|. The caller owns the returned SymmetricKey.
57 static SymmetricKey
* Import(Algorithm algorithm
, const std::string
& raw_key
);
59 #if defined(USE_OPENSSL)
60 const std::string
& key() { return key_
; }
61 #elif defined(USE_NSS)
62 PK11SymKey
* key() const { return key_
.get(); }
63 #elif defined(OS_MACOSX)
64 CSSM_DATA
cssm_data() const;
66 HCRYPTKEY
key() const { return key_
.get(); }
69 // Extracts the raw key from the platform specific data.
70 // Warning: |raw_key| holds the raw key as bytes and thus must be handled
72 bool GetRawKey(std::string
* raw_key
);
75 #if defined(USE_OPENSSL)
78 #elif defined(USE_NSS)
79 explicit SymmetricKey(PK11SymKey
* key
);
80 ScopedPK11SymKey key_
;
81 #elif defined(OS_MACOSX)
82 SymmetricKey(const void* key_data
, size_t key_size_in_bits
);
85 SymmetricKey(HCRYPTPROV provider
, HCRYPTKEY key
,
86 const void* key_data
, size_t key_size_in_bytes
);
88 ScopedHCRYPTPROV provider_
;
91 // Contains the raw key, if it is known during initialization and when it
92 // is likely that the associated |provider_| will be unable to export the
93 // |key_|. This is the case of HMAC keys when the key size exceeds 16 bytes
94 // when using the default RSA provider.
95 // TODO(rsleevi): See if KP_EFFECTIVE_KEYLEN is the reason why CryptExportKey
96 // fails with NTE_BAD_KEY/NTE_BAD_LEN
100 DISALLOW_COPY_AND_ASSIGN(SymmetricKey
);
103 } // namespace crypto
105 #endif // CRYPTO_SYMMETRIC_KEY_H_