Botan: Botan::PKCS8 Namespace Reference

Botan 1.10.17

Functions
Botan::PKCS8 Namespace Reference

## Functions
SecureVector< byte > | BER_encode (const Private_Key &key)
SecureVector< byte > | BER_encode (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)
Private_Key * | copy_key (const Private_Key &key, RandomNumberGenerator &rng)
void | encode (const Private_Key &key, Pipe &pipe, X509_Encoding encoding=PEM)
void | encrypt_key (const Private_Key &key, Pipe &pipe, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo="", X509_Encoding encoding=PEM)
Private_Key * | load_key (DataSource &source, RandomNumberGenerator &rng, const User_Interface &ui)
Private_Key * | load_key (const std::string &fsname, RandomNumberGenerator &rng, const User_Interface &ui)
Private_Key * | load_key (DataSource &source, RandomNumberGenerator &rng, const std::string &pass)
Private_Key * | load_key (const std::string &fsname, RandomNumberGenerator &rng, const std::string &pass)
std::string | PEM_encode (const Private_Key &key)
std::string | PEM_encode (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)

## Detailed Description

This namespace contains functions for handling PKCS #8 private keys

## Function Documentation

## ◆ BER_encode() [1/2]

BOTAN_DLL SecureVector< byte > Botan::PKCS8::BER_encode | ( | const Private_Key & | key | ) |

BER encode a private key

Parameters

  key | the private key to encode

Returns
  BER encoded key

Definition at line 134 of file pkcs8.cpp.

References Botan::DER_Encoder::encode(), encode(), Botan::OCTET_STRING, Botan::Private_Key::pkcs8_algorithm_identifier(), Botan::Private_Key::pkcs8_private_key(), Botan::SEQUENCE, and Botan::DER_Encoder::start_cons().

Referenced by encode(), and PEM_encode().

135 {
136 const size_t PKCS8_VERSION = 0;
137
138 return DER_Encoder()
139 .start_cons(SEQUENCE)
140 .encode(PKCS8_VERSION)
141 .encode(key.pkcs8_algorithm_identifier())
142 .encode(key.pkcs8_private_key(), OCTET_STRING)
143 .end_cons()
144 .get_contents();
145 }
Botan::OCTET_STRING
Definition: asn1_int.h:31
Botan::SEQUENCE
Definition: asn1_int.h:35
Botan::PEM_Code::encode
std::string encode(const byte der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:19

## ◆ BER_encode() [2/2]

BOTAN_DLL SecureVector< byte > Botan::PKCS8::BER_encode | ( | const Private_Key & | key,
|  | RandomNumberGenerator & | rng,
|  | const std::string & | pass,
|  | const std::string & | pbe_algo = `""`
| ) |  |

Encrypt a key using PKCS #8 encryption

Parameters

  key | the key to encode
  rng | the rng to use
  pass | the password to use for encryption
  pbe_algo | the name of the desired password-based encryption algorithm; if empty ("") a reasonable (portable/secure) default will be chosen.

Returns
  encrypted key in binary BER form

Definition at line 158 of file pkcs8.cpp.

162 {
163 const std::string DEFAULT_PBE = "PBE-PKCS5v20(SHA-1,AES-256/CBC)";
164
165 std::auto_ptr<PBE> pbe(get_pbe(((pbe_algo != "") ? pbe_algo : DEFAULT_PBE)));
166
167 pbe->new_params(rng);
168 pbe->set_key(pass);
169
170 AlgorithmIdentifier pbe_algid(pbe->get_oid(), pbe->encode_params());
171
172 Pipe key_encrytor(pbe.release());
173 key_encrytor.process_msg(PKCS8::BER_encode(key));
174
175 return DER_Encoder()
176 .start_cons(SEQUENCE)
177 .encode(pbe_algid)
178 .encode(key_encrytor.read_all(), OCTET_STRING)
179 .end_cons()
180 .get_contents();
181 }
Botan::OCTET_STRING
Definition: asn1_int.h:31
Botan::PKCS8::BER_encode
SecureVector< byte > BER_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)
Definition: pkcs8.cpp:158
Botan::SEQUENCE
Definition: asn1_int.h:35
Botan::get_pbe
PBE * get_pbe(const std::string &algo_spec)
Definition: get_pbe.cpp:27

## ◆ copy_key()

BOTAN_DLL Private_Key * Botan::PKCS8::copy_key | ( | const Private_Key & | key,
|  | RandomNumberGenerator & | rng
| ) |  |

Copy an existing encoded key object.

Parameters

  key | the key to copy
  rng | the rng to use

Returns
  new copy of the key

Definition at line 250 of file pkcs8.cpp.

252 {
253 DataSource_Memory source(PEM_encode(key));
254 return PKCS8::load_key(source, rng);
255 }
Botan::PKCS8::load_key
Private_Key * load_key(const std::string &fsname, RandomNumberGenerator &rng, const std::string &pass)
Definition: pkcs8.cpp:240
Botan::PKCS8::PEM_encode
std::string PEM_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)
Definition: pkcs8.cpp:186

## ◆ encode()

void Botan::PKCS8::encode | ( | const Private_Key & | key,
|  | Pipe & | pipe,
|  | X509_Encoding | encoding = `PEM`
| ) |  |
| inline

Encode a private key into a pipe.

Deprecated:
  Use PEM_encode or BER_encode instead

Parameters

  key | the private key to encode
  pipe | the pipe to feed the encoded key into
  encoding | the encoding type to use

Definition at line 85 of file pkcs8.h.

References BER_encode(), Botan::PEM, and PEM_encode().

Referenced by BER_encode().

88 {
89 if(encoding == PEM)
90 pipe.write(PKCS8::PEM_encode(key));
91 else
92 pipe.write(PKCS8::BER_encode(key));
93 }
Botan::PKCS8::BER_encode
SecureVector< byte > BER_encode(const Private_Key &key)
Definition: pkcs8.cpp:134
Botan::PKCS8::PEM_encode
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:150
Botan::PEM
Definition: pubkey_enums.h:67

## ◆ encrypt_key()

void Botan::PKCS8::encrypt_key | ( | const Private_Key & | key,
|  | Pipe & | pipe,
|  | RandomNumberGenerator & | rng,
|  | const std::string & | pass,
|  | const std::string & | pbe_algo = `""`,
|  | X509_Encoding | encoding = `PEM`
| ) |  |
| inline

Encode and encrypt a private key into a pipe.

Deprecated:
  Use PEM_encode or BER_encode instead

Parameters

  key | the private key to encode
  pipe | the pipe to feed the encoded key into
  pass | the password to use for encryption
  rng | the rng to use
  pbe_algo | the name of the desired password-based encryption algorithm; if empty ("") a reasonable (portable/secure) default will be chosen.
  encoding | the encoding type to use

Definition at line 109 of file pkcs8.h.

115 {
116 if(encoding == PEM)
117 pipe.write(PKCS8::PEM_encode(key, rng, pass, pbe_algo));
118 else
119 pipe.write(PKCS8::BER_encode(key, rng, pass, pbe_algo));
120 }
Botan::PKCS8::BER_encode
SecureVector< byte > BER_encode(const Private_Key &key)
Definition: pkcs8.cpp:134
Botan::PKCS8::PEM_encode
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:150
Botan::PEM
Definition: pubkey_enums.h:67

## ◆ load_key() [1/4]

BOTAN_DLL Private_Key * Botan::PKCS8::load_key | ( | DataSource & | source,
|  | RandomNumberGenerator & | rng,
|  | const User_Interface & | ui
| ) |  |

Load a key from a data source.

Parameters

  source | the data source providing the encoded key
  rng | the rng to use
  ui | the user interface to be used for passphrase dialog

Returns
  loaded private key object

Definition at line 201 of file pkcs8.cpp.

204 {
205 AlgorithmIdentifier alg_id;
206 SecureVector<byte> pkcs8_key = PKCS8_decode(source, ui, alg_id);
207
208 const std::string alg_name = OIDS::lookup(alg_id.oid);
209 if(alg_name == "" || alg_name == alg_id.oid.as_string())
210 throw PKCS8_Exception("Unknown algorithm OID: " +
211 alg_id.oid.as_string());
212
213 return make_private_key(alg_id, pkcs8_key, rng);
214 }
Botan::make_private_key
Private_Key * make_private_key(const AlgorithmIdentifier &alg_id, const MemoryRegion< byte > &key_bits, RandomNumberGenerator &rng)
Definition: pk_algs.cpp:104
Botan::OIDS::lookup
std::string lookup(const OID &oid)
Definition: oids.cpp:31

## ◆ load_key() [2/4]

BOTAN_DLL Private_Key * Botan::PKCS8::load_key | ( | const std::string & | filename,
|  | RandomNumberGenerator & | rng,
|  | const User_Interface & | ui
| ) |  |

Load a key from a file.

Parameters

  filename | the path to the file containing the encoded key
  rng | the rng to use
  ui | the user interface to be used for passphrase dialog

Returns
  loaded private key object

Definition at line 219 of file pkcs8.cpp.

222 {
223 DataSource_Stream source(fsname, true);
224 return PKCS8::load_key(source, rng, ui);
225 }
Botan::PKCS8::load_key
Private_Key * load_key(const std::string &fsname, RandomNumberGenerator &rng, const std::string &pass)
Definition: pkcs8.cpp:240

## ◆ load_key() [3/4]

BOTAN_DLL Private_Key * Botan::PKCS8::load_key | ( | DataSource & | source,
|  | RandomNumberGenerator & | rng,
|  | const std::string & | pass = `""`
| ) |  |

Load a key from a data source.

Parameters

  source | the data source providing the encoded key
  rng | the rng to use
  pass | the passphrase to decrypt the key. Provide an empty string if the key is not encoded.

Returns
  loaded private key object

Definition at line 230 of file pkcs8.cpp.

233 {
234 return PKCS8::load_key(source, rng, User_Interface(pass));
235 }
Botan::PKCS8::load_key
Private_Key * load_key(const std::string &fsname, RandomNumberGenerator &rng, const std::string &pass)
Definition: pkcs8.cpp:240

## ◆ load_key() [4/4]

BOTAN_DLL Private_Key * Botan::PKCS8::load_key | ( | const std::string & | filename,
|  | RandomNumberGenerator & | rng,
|  | const std::string & | pass = `""`
| ) |  |

Load a key from a file.

Parameters

  filename | the path to the file containing the encoded key
  rng | the rng to use
  pass | the passphrase to decrypt the key. Provide an empty string if the key is not encoded.

Returns
  loaded private key object

Definition at line 240 of file pkcs8.cpp.

243 {
244 return PKCS8::load_key(fsname, rng, User_Interface(pass));
245 }
Botan::PKCS8::load_key
Private_Key * load_key(const std::string &fsname, RandomNumberGenerator &rng, const std::string &pass)
Definition: pkcs8.cpp:240

## ◆ PEM_encode() [1/2]

BOTAN_DLL std::string Botan::PKCS8::PEM_encode | ( | const Private_Key & | key | ) |

Get a string containing a PEM encoded private key.

Parameters

  key | the key to encode

Returns
  encoded key

Definition at line 150 of file pkcs8.cpp.

References BER_encode(), and Botan::PEM_Code::encode().

Referenced by encode().

151 {
152 return PEM_Code::encode(PKCS8::BER_encode(key), "PRIVATE KEY");
153 }
Botan::PKCS8::BER_encode
SecureVector< byte > BER_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)
Definition: pkcs8.cpp:158
Botan::PEM_Code::encode
std::string encode(const byte der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:19

## ◆ PEM_encode() [2/2]

BOTAN_DLL std::string Botan::PKCS8::PEM_encode | ( | const Private_Key & | key,
|  | RandomNumberGenerator & | rng,
|  | const std::string & | pass,
|  | const std::string & | pbe_algo = `""`
| ) |  |

Get a string containing a PEM encoded private key, encrypting it with a password.

Parameters

  key | the key to encode
  rng | the rng to use
  pass | the password to use for encryption
  pbe_algo | the name of the desired password-based encryption algorithm; if empty ("") a reasonable (portable/secure) default will be chosen.

Returns
  encrypted key in PEM form

Definition at line 186 of file pkcs8.cpp.

190 {
191 if(pass == "")
192 return PEM_encode(key);
193
194 return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, pbe_algo),
195 "ENCRYPTED PRIVATE KEY");
196 }
Botan::PKCS8::PEM_encode
std::string PEM_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)
Definition: pkcs8.cpp:186
Botan::PKCS8::BER_encode
SecureVector< byte > BER_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)
Definition: pkcs8.cpp:158
Botan::PEM_Code::encode
std::string encode(const byte der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:19