| Hasini Gunasinghe | 985cf04 | 2022-09-10 01:26:49 +0000 | [diff] [blame] | 1 | # [RustCrypto]: PKCS#8 (Private Keys) |
| 2 | |
| 3 | [![crate][crate-image]][crate-link] |
| 4 | [![Docs][docs-image]][docs-link] |
| 5 | [![Build Status][build-image]][build-link] |
| 6 | ![Apache2/MIT licensed][license-image] |
| 7 | ![Rust Version][rustc-image] |
| 8 | [![Project Chat][chat-image]][chat-link] |
| 9 | |
| 10 | Pure Rust implementation of Public-Key Cryptography Standards (PKCS) #8: |
| 11 | Private-Key Information Syntax Specification ([RFC 5208]). |
| 12 | |
| 13 | [Documentation][docs-link] |
| 14 | |
| 15 | ## About PKCS#8 |
| 16 | |
| 17 | PKCS#8 is a format for cryptographic private keys, often containing pairs |
| 18 | of private and public keys. |
| 19 | |
| 20 | You can identify a PKCS#8 private key encoded as PEM (i.e. text) by the |
| 21 | following: |
| 22 | |
| 23 | ```text |
| 24 | -----BEGIN PRIVATE KEY----- |
| 25 | ``` |
| 26 | |
| 27 | PKCS#8 private keys can optionally be encrypted under a password using |
| 28 | key derivation algorithms like PBKDF2 and [scrypt], and encrypted with |
| 29 | ciphers like AES-CBC. When a PKCS#8 private key has been encrypted, |
| 30 | it starts with the following: |
| 31 | |
| 32 | ```text |
| 33 | -----BEGIN ENCRYPTED PRIVATE KEY----- |
| 34 | ``` |
| 35 | |
| 36 | PKCS#8 private keys can also be serialized in an ASN.1-based binary format. |
| 37 | The PEM text encoding is a Base64 representation of this format. |
| 38 | |
| 39 | ## Supported Algorithms |
| 40 | |
| 41 | This crate is implemented in an algorithm-agnostic manner with the goal of |
| 42 | enabling PKCS#8 support for any algorithm. |
| 43 | |
| 44 | That said, it has been tested for interoperability against keys generated by |
| 45 | OpenSSL for the following algorithms: |
| 46 | |
| 47 | - ECC (`id-ecPublicKey`) |
| 48 | - Ed25519 (`id-Ed25519`) |
| 49 | - RSA (`id-rsaEncryption`) |
| 50 | - X25519 (`id-X25519`) |
| 51 | |
| 52 | Please open an issue if you encounter trouble using it with a particular |
| 53 | algorithm, including the ones listed above or other algorithms. |
| 54 | |
| 55 | ## Minimum Supported Rust Version |
| 56 | |
| 57 | This crate requires **Rust 1.57** at a minimum. |
| 58 | |
| 59 | We may change the MSRV in the future, but it will be accompanied by a minor |
| 60 | version bump. |
| 61 | |
| 62 | ## License |
| 63 | |
| 64 | Licensed under either of: |
| 65 | |
| 66 | * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) |
| 67 | * [MIT license](http://opensource.org/licenses/MIT) |
| 68 | |
| 69 | at your option. |
| 70 | |
| 71 | ### Contribution |
| 72 | |
| 73 | Unless you explicitly state otherwise, any contribution intentionally submitted |
| 74 | for inclusion in the work by you, as defined in the Apache-2.0 license, shall be |
| 75 | dual licensed as above, without any additional terms or conditions. |
| 76 | |
| 77 | [//]: # (badges) |
| 78 | |
| 79 | [crate-image]: https://buildstats.info/crate/pkcs8 |
| 80 | [crate-link]: https://crates.io/crates/pkcs8 |
| 81 | [docs-image]: https://docs.rs/pkcs8/badge.svg |
| 82 | [docs-link]: https://docs.rs/pkcs8/ |
| 83 | [license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg |
| 84 | [rustc-image]: https://img.shields.io/badge/rustc-1.57+-blue.svg |
| 85 | [chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg |
| 86 | [chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/300570-formats |
| 87 | [build-image]: https://github.com/RustCrypto/formats/workflows/pkcs8/badge.svg?branch=master&event=push |
| 88 | [build-link]: https://github.com/RustCrypto/formats/actions |
| 89 | |
| 90 | [//]: # (links) |
| 91 | |
| 92 | [RustCrypto]: https://github.com/rustcrypto |
| 93 | [RFC 5208]: https://tools.ietf.org/html/rfc5208 |
| 94 | [scrypt]: https://en.wikipedia.org/wiki/Scrypt |
