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 
17 //! Set of types for supporting [CBOR Object Signing and Encryption (COSE)][COSE].
18 //!
19 //! Builds on the [`ciborium`](https://docs.rs/ciborium) crate for underlying [CBOR][CBOR] support.
20 //!
21 //! ## Usage
22 //!
23 //! ```
24 //! # #[derive(Copy, Clone)]
25 //! # struct FakeSigner {}
26 //! # impl FakeSigner {
27 //! #     fn sign(&self, data: &[u8]) -> Vec<u8> {
28 //! #         data.to_vec()
29 //! #     }
30 //! #     fn verify(&self, sig: &[u8], data: &[u8]) -> Result<(), String> {
31 //! #         if sig != self.sign(data) {
32 //! #             Err("failed to verify".to_owned())
33 //! #         } else {
34 //! #             Ok(())
35 //! #         }
36 //! #     }
37 //! # }
38 //! # let signer = FakeSigner {};
39 //! # let verifier = signer;
40 //! use coset::{iana, CborSerializable};
41 //!
42 //! // Inputs.
43 //! let pt = b"This is the content";
44 //! let aad = b"this is additional data";
45 //!
46 //! // Build a `CoseSign1` object.
47 //! let protected = coset::HeaderBuilder::new()
48 //!     .algorithm(iana::Algorithm::ES256)
49 //!     .key_id(b"11".to_vec())
50 //!     .build();
51 //! let sign1 = coset::CoseSign1Builder::new()
52 //!     .protected(protected)
53 //!     .payload(pt.to_vec())
54 //!     .create_signature(aad, |pt| signer.sign(pt)) // closure to do sign operation
55 //!     .build();
56 //!
57 //! // Serialize to bytes.
58 //! let sign1_data = sign1.to_vec().unwrap();
59 //! println!(
60 //!     "'{}' + '{}' => {}",
61 //!     String::from_utf8_lossy(pt),
62 //!     String::from_utf8_lossy(aad),
63 //!     hex::encode(&sign1_data)
64 //! );
65 //!
66 //! // At the receiving end, deserialize the bytes back to a `CoseSign1` object.
67 //! let mut sign1 = coset::CoseSign1::from_slice(&sign1_data).unwrap();
68 //!
69 //! // At this point, real code would validate the protected headers.
70 //!
71 //! // Check the signature, which needs to have the same `aad` provided, by
72 //! // providing a closure that can do the verify operation.
73 //! let result = sign1.verify_signature(aad, |sig, data| verifier.verify(sig, data));
74 //! println!("Signature verified: {:?}.", result);
75 //! assert!(result.is_ok());
76 //!
77 //! // Changing an unprotected header leaves the signature valid.
78 //! sign1.unprotected.content_type = Some(coset::ContentType::Text("text/plain".to_owned()));
79 //! assert!(sign1
80 //!     .verify_signature(aad, |sig, data| verifier.verify(sig, data))
81 //!     .is_ok());
82 //!
83 //! // Providing a different `aad` means the signature won't validate.
84 //! assert!(sign1
85 //!     .verify_signature(b"not aad", |sig, data| verifier.verify(sig, data))
86 //!     .is_err());
87 //!
88 //! // Changing a protected header invalidates the signature.
89 //! sign1.protected.original_data = None;
90 //! sign1.protected.header.content_type = Some(coset::ContentType::Text("text/plain".to_owned()));
91 //! assert!(sign1
92 //!     .verify_signature(aad, |sig, data| verifier.verify(sig, data))
93 //!     .is_err());
94 //! ```
95 //!
96 //! [COSE]: https://tools.ietf.org/html/rfc8152
97 //! [CBOR]: https://tools.ietf.org/html/rfc7049
98 
99 #![cfg_attr(not(feature = "std"), no_std)]
100 #![deny(rustdoc::broken_intra_doc_links)]
101 extern crate alloc;
102 
103 /// Use std to allow building as a dylib.
104 #[cfg(android_dylib)]
105 extern crate std;
106 
107 /// Re-export of the `ciborium` crate used for underlying CBOR encoding.
108 pub use ciborium as cbor;
109 
110 #[macro_use]
111 pub(crate) mod util;
112 
113 pub mod cwt;
114 #[macro_use]
115 pub mod iana;
116 
117 mod common;
118 pub use common::*;
119 mod context;
120 pub use context::*;
121 mod encrypt;
122 pub use encrypt::*;
123 mod header;
124 pub use header::*;
125 mod key;
126 pub use key::*;
127 mod mac;
128 pub use mac::*;
129 mod sign;
130 pub use sign::*;
131