Mistake on this page?
Report an issue in GitHub or email us
attest_token.h
Go to the documentation of this file.
1 /*
2  * attest_token.h
3  *
4  * Copyright (c) 2018-2019, Laurence Lundblade. All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  *
8  * See BSD-3-Clause license in README.md
9  */
10 
11 #ifndef __ATTEST_TOKEN_H__
12 #define __ATTEST_TOKEN_H__
13 
14 #include <stdint.h>
15 #include "qcbor.h"
16 #include "t_cose_sign1_sign.h"
17 
18 
19 /**
20  * \file attest_token.h
21  *
22  * \brief Attestation Token Creation Interface
23  *
24  * The context and functions here are the way to create an attestation
25  * token. The steps are roughly:
26  *
27  * -# Creation and initialize an attest_token_ctx indicating the
28  * options, key and such using attest_token_start().
29  *
30  * -# Use various add methods to fill in the payload with claims. The
31  * encoding context can also be borrowed for more rich payloads.
32  *
33  * -# Call attest_token_finish() to create the signature and finish
34  * formatting the COSE signed output.
35  */
36 
37 
38 /**
39  Error codes returned from attestation token creation.
40  */
42  /** Success */
44  /** The buffer passed in to receive the output is too small. */
46  /** Something went wrong formatting the CBOR, most likely the
47  payload has maps or arrays that are not closed. */
49  /** A general, unspecific error when creating or decoding the
50  token. */
52  /** A hash function that is needed to make the token is not
53  available. */
55  /** CBOR Syntax not well-formed -- a CBOR syntax error. */
57  /** Bad CBOR structure, for example not a map when was is
58  required. */
60  /** Bad CBOR type, for example an not a text string, when a text
61  string is required. */
63  /** Integer too large, for example an \c int32_t is required, but
64  value only fits in \c int64_t */
66  /** Something is wrong with the COSE signing structure, missing
67  headers or such. */
69  /** COSE signature is invalid, data is corrupted. */
71  /** The signing algorithm is not supported. */
73  /** Out of memory. */
75  /** Tampering detected in cryptographic function. */
77  /** Verification key is not found or of wrong type. */
79 };
80 
81 
82 
83 /**
84  * Request that the claims internally generated not be added to the
85  * token. This is a test mode that results in a static token that
86  * never changes. Only the nonce is included. The nonce is under
87  * the callers control unlike the other claims.
88  */
89 #define TOKEN_OPT_OMIT_CLAIMS 0x40000000
90 
91 
92 /**
93  * A special test mode where a proper signature is not produced. In
94  * its place there is a concatenation of hashes of the payload to be
95  * the same size as the signature. This works and can be used to
96  * verify all of the SW stack except the public signature part. The
97  * token has no security value in this mode because anyone can
98  * replicate it. */
99 #define TOKEN_OPT_SHORT_CIRCUIT_SIGN 0x80000000
100 
101 
102 /**
103  * The context for creating an attestation token. The caller of
104  * attest_token must create one of these and pass it to the functions
105  * here. It is small enough that it can go on the stack. It is most of
106  * the memory needed to create a token except the output buffer and
107  * any memory requirements for the cryptographic operations.
108  *
109  * The structure is opaque for the caller.
110  *
111  * This is roughly 148 + 8 + 32 = 188 bytes
112  */
114  /* Private data structure */
115  QCBOREncodeContext cbor_enc_ctx;
116  uint32_t opt_flags;
117  int32_t key_select;
118  struct t_cose_sign1_ctx signer_ctx;
119 };
120 
121 
122 /**
123  * \brief Initialize a token creation context.
124  *
125  * \param[in] me The token creation context to be initialized.
126  * \param[in] opt_flags Flags to select different custom options,
127  for example \ref TOKEN_OPT_OMIT_CLAIMS.
128  * \param[in] key_select Selects which attestation key to sign with.
129  * \param[in] cose_alg_id The algorithm to sign with. The IDs are
130  * defined in [COSE (RFC 8152)]
131  * (https://tools.ietf.org/html/rfc8152) or
132  * in the [IANA COSE Registry]
133  * (https://www.iana.org/assignments/cose/cose.xhtml).
134  * \param[out] out_buffer The output buffer to write the encoded token into.
135  *
136  * \return one of the \ref attest_token_err_t errors.
137  *
138  * The size of the buffer in \c out_buffer->len
139  * determines the size of the token that can be created. It must be
140  * able to hold the final encoded and signed token. The data encoding
141  * overhead is just that of CBOR. The signing overhead depends on the
142  * signing key size. It is about 150 bytes for 256-bit ECDSA.
143  *
144  * If \c out_buffer->ptr is \c NULL and \c out_buffer_ptr->len is
145  * large like \c UINT32_MAX no token will be created but the length of
146  * the token that would be created will be in \c completed_token as
147  * returned by attest_token_finish(). None of the cryptographic
148  * functions run during this, but the sizes of what they would output
149  * is taken into account.
150  */
153  uint32_t opt_flags,
154  int32_t key_select,
155  int32_t cose_alg_id,
156  const struct useful_buf *out_buffer);
157 
158 
159 
160 /**
161  * \brief Get a copy of the CBOR encoding context
162  *
163  * \param[in] me Token creation context.
164  *
165  * \return The CBOR encoding context
166  *
167  * Allows the caller to encode CBOR right into the output buffer using
168  * any of the \c QCBOREncode_AddXXXX() methods. Anything added here
169  * will be part of the payload that gets hashed. This can be used to
170  * make complex CBOR structures. All open arrays and maps must be
171  * close before calling any other \c attest_token methods. \c
172  * QCBOREncode_Finish() should not be closed on this context.
173  */
175 
176 /**
177  * \brief Add a 64-bit signed integer claim
178  *
179  * \param[in] me Token creation context.
180  * \param[in] label Integer label for claim.
181  * \param[in] value The integer claim data.
182  */
184  int32_t label,
185  int64_t value);
186 
187 /**
188  * \brief Add a binary string claim
189  *
190  * \param[in] me Token creation context.
191  * \param[in] label Integer label for claim.
192  * \param[in] value The binary claim data.
193  */
195  int32_t label,
196  const struct useful_buf_c *value);
197 
198 /**
199  * \brief Add a text string claim
200  *
201  * \param[in] me Token creation context.
202  * \param[in] label Integer label for claim.
203  * \param[in] value The text claim data.
204  */
206  int32_t label,
207  const struct useful_buf_c *value);
208 
209 /**
210  * \brief Add some already-encoded CBOR to payload
211  *
212  * \param[in] me Token creation context.
213  * \param[in] label Integer label for claim.
214  * \param[in] encoded The already-encoded CBOR.
215  *
216  * Encoded CBOR must be a full map or full array or a non-aggregate
217  * type. It cannot be a partial map or array. It can be nested maps
218  * and arrays, but they must all be complete.
219  */
221  int32_t label,
222  const struct useful_buf_c *encoded);
223 
224 
225 /**
226  * \brief Finish the token, complete the signing and get the result
227  *
228  * \param[in] me Token Creation Context.
229  * \param[out] completed_token Pointer and length to completed token.
230  *
231  * \return one of the \ref attest_token_err_t errors.
232  *
233  * This completes the token after the payload has been added. When
234  * this is called the signing algorithm is run and the final
235  * formatting of the token is completed.
236  */
239  struct useful_buf_c *completed_token);
240 
241 #endif /* __ATTEST_TOKEN_H__ */
Bad CBOR type, for example an not a text string, when a text string is required.
Definition: attest_token.h:62
enum attest_token_err_t attest_token_finish(struct attest_token_ctx *me, struct useful_buf_c *completed_token)
Finish the token, complete the signing and get the result.
void attest_token_add_tstr(struct attest_token_ctx *me, int32_t label, const struct useful_buf_c *value)
Add a text string claim.
QCBOREncodeContext * attest_token_borrow_cbor_cntxt(struct attest_token_ctx *me)
Get a copy of the CBOR encoding context.
Tampering detected in cryptographic function.
Definition: attest_token.h:76
Bad CBOR structure, for example not a map when was is required.
Definition: attest_token.h:59
void attest_token_add_encoded(struct attest_token_ctx *me, int32_t label, const struct useful_buf_c *encoded)
Add some already-encoded CBOR to payload.
Integer too large, for example an int32_t is required, but value only fits in int64_t.
Definition: attest_token.h:65
Q C B O R E n c o d e / D e c o d e.
attest_token_err_t
Error codes returned from attestation token creation.
Definition: attest_token.h:41
The non-const UsefulBuf typically used for some allocated memory that is to be filled in...
Definition: UsefulBuf.h:160
CBOR Syntax not well-formed – a CBOR syntax error.
Definition: attest_token.h:56
Verification key is not found or of wrong type.
Definition: attest_token.h:78
UsefulBufC and UsefulBuf are simple data structures to hold a pointer and length for a binary data...
Definition: UsefulBuf.h:149
Create a COSE_Sign1, usually for EAT or CWT Token.
A general, unspecific error when creating or decoding the token.
Definition: attest_token.h:51
Something went wrong formatting the CBOR, most likely the payload has maps or arrays that are not clo...
Definition: attest_token.h:48
The signing algorithm is not supported.
Definition: attest_token.h:72
The buffer passed in to receive the output is too small.
Definition: attest_token.h:45
void attest_token_add_integer(struct attest_token_ctx *me, int32_t label, int64_t value)
Add a 64-bit signed integer claim.
This is the context for creating a COSE_Sign1 structure.
Something is wrong with the COSE signing structure, missing headers or such.
Definition: attest_token.h:68
void attest_token_add_bstr(struct attest_token_ctx *me, int32_t label, const struct useful_buf_c *value)
Add a binary string claim.
COSE signature is invalid, data is corrupted.
Definition: attest_token.h:70
A hash function that is needed to make the token is not available.
Definition: attest_token.h:54
The context for creating an attestation token.
Definition: attest_token.h:113
enum attest_token_err_t attest_token_start(struct attest_token_ctx *me, uint32_t opt_flags, int32_t key_select, int32_t cose_alg_id, const struct useful_buf *out_buffer)
Initialize a token creation context.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.