mbed TLS v2.23.0: asn1write.h File Reference

mbed TLS v2.23.0

Macros | Functions
asn1write.h File Reference

ASN.1 buffer writing functionality. More...

`#include "mbedtls/config.h"`
`#include "mbedtls/asn1.h"`
Include dependency graph for asn1write.h:

Go to the source code of this file.

## Macros
#define | MBEDTLS_ASN1_CHK_ADD(g, f)

## Functions
int | mbedtls_asn1_write_len (unsigned char **p, unsigned char *start, size_t len)
| Write a length field in ASN.1 format. More...
int | mbedtls_asn1_write_tag (unsigned char **p, unsigned char *start, unsigned char tag)
| Write an ASN.1 tag in ASN.1 format. More...
int | mbedtls_asn1_write_raw_buffer (unsigned char **p, unsigned char *start, const unsigned char *buf, size_t size)
| Write raw buffer data. More...
int | mbedtls_asn1_write_mpi (unsigned char **p, unsigned char *start, const mbedtls_mpi *X)
| Write a arbitrary-precision number (MBEDTLS_ASN1_INTEGER) in ASN.1 format. More...
int | mbedtls_asn1_write_null (unsigned char **p, unsigned char *start)
| Write a NULL tag (MBEDTLS_ASN1_NULL) with zero data in ASN.1 format. More...
int | mbedtls_asn1_write_oid (unsigned char **p, unsigned char *start, const char *oid, size_t oid_len)
| Write an OID tag (MBEDTLS_ASN1_OID) and data in ASN.1 format. More...
int | mbedtls_asn1_write_algorithm_identifier (unsigned char **p, unsigned char *start, const char *oid, size_t oid_len, size_t par_len)
| Write an AlgorithmIdentifier sequence in ASN.1 format. More...
int | mbedtls_asn1_write_bool (unsigned char **p, unsigned char *start, int boolean)
| Write a boolean tag (MBEDTLS_ASN1_BOOLEAN) and value in ASN.1 format. More...
int | mbedtls_asn1_write_int (unsigned char **p, unsigned char *start, int val)
| Write an int tag (MBEDTLS_ASN1_INTEGER) and value in ASN.1 format. More...
int | mbedtls_asn1_write_enum (unsigned char **p, unsigned char *start, int val)
| Write an enum tag (MBEDTLS_ASN1_ENUMERATED) and value in ASN.1 format. More...
int | mbedtls_asn1_write_tagged_string (unsigned char **p, unsigned char *start, int tag, const char *text, size_t text_len)
| Write a string in ASN.1 format using a specific string encoding tag. More...
int | mbedtls_asn1_write_printable_string (unsigned char **p, unsigned char *start, const char *text, size_t text_len)
| Write a string in ASN.1 format using the PrintableString string encoding tag (MBEDTLS_ASN1_PRINTABLE_STRING). More...
int | mbedtls_asn1_write_utf8_string (unsigned char **p, unsigned char *start, const char *text, size_t text_len)
| Write a UTF8 string in ASN.1 format using the UTF8String string encoding tag (MBEDTLS_ASN1_UTF8_STRING). More...
int | mbedtls_asn1_write_ia5_string (unsigned char **p, unsigned char *start, const char *text, size_t text_len)
| Write a string in ASN.1 format using the IA5String string encoding tag (MBEDTLS_ASN1_IA5_STRING). More...
int | mbedtls_asn1_write_bitstring (unsigned char **p, unsigned char *start, const unsigned char *buf, size_t bits)
| Write a bitstring tag (MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format. More...
int | mbedtls_asn1_write_named_bitstring (unsigned char **p, unsigned char *start, const unsigned char *buf, size_t bits)
| This function writes a named bitstring tag (MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format. More...
int | mbedtls_asn1_write_octet_string (unsigned char **p, unsigned char *start, const unsigned char *buf, size_t size)
| Write an octet string tag (MBEDTLS_ASN1_OCTET_STRING) and value in ASN.1 format. More...
mbedtls_asn1_named_data * | mbedtls_asn1_store_named_data (mbedtls_asn1_named_data **list, const char *oid, size_t oid_len, const unsigned char *val, size_t val_len)
| Create or find a specific named_data entry for writing in a sequence or list based on the OID. If not already in there, a new entry is added to the head of the list. Warning: Destructive behaviour for the val data! More...

## Detailed Description

ASN.1 buffer writing functionality.

Definition in file asn1write.h.

## Macro Definition Documentation

## ◆ MBEDTLS_ASN1_CHK_ADD

#define MBEDTLS_ASN1_CHK_ADD | ( |  | g,
|  |  | f
| ) |  |

Value:
do \
{ \
if( ( ret = (f) ) < 0 ) \
return( ret ); \
else \
(g) += ret; \
} while( 0 )

Definition at line 36 of file asn1write.h.

## Function Documentation

## ◆ mbedtls_asn1_store_named_data()

mbedtls_asn1_named_data* mbedtls_asn1_store_named_data | ( | mbedtls_asn1_named_data ** | list,
|  | const char * | oid,
|  | size_t | oid_len,
|  | const unsigned char * | val,
|  | size_t | val_len
| ) |  |

Create or find a specific named_data entry for writing in a sequence or list based on the OID. If not already in there, a new entry is added to the head of the list. Warning: Destructive behaviour for the val data!

Parameters

  list | The pointer to the location of the head of the list to seek through (will be updated in case of a new entry).
  oid | The OID to look for.
  oid_len | The size of the OID.
  val | The associated data to store. If this is `NULL`, no data is copied to the new or existing buffer.
  val_len | The minimum length of the data buffer needed. If this is 0, do not allocate a buffer for the associated data. If the OID was already present, enlarge, shrink or free the existing buffer to fit `val_len`.

Returns
  A pointer to the new / existing entry on success.
  `NULL` if if there was a memory allocation error.

## ◆ mbedtls_asn1_write_algorithm_identifier()

int mbedtls_asn1_write_algorithm_identifier | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const char * | oid,
|  | size_t | oid_len,
|  | size_t | par_len
| ) |  |

Write an AlgorithmIdentifier sequence in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  oid | The OID of the algorithm to write.
  oid_len | The length of the algorithm's OID.
  par_len | The length of the parameters, which must be already written. If 0, NULL parameters are added

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_bitstring()

int mbedtls_asn1_write_bitstring | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const unsigned char * | buf,
|  | size_t | bits
| ) |  |

Write a bitstring tag (MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  buf | The bitstring to write.
  bits | The total number of bits in the bitstring.

Returns
  The number of bytes written to `p` on success.
  A negative error code on failure.

## ◆ mbedtls_asn1_write_bool()

int mbedtls_asn1_write_bool | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | int | boolean
| ) |  |

Write a boolean tag (MBEDTLS_ASN1_BOOLEAN) and value in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  boolean | The boolean value to write, either `0` or `1`.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_enum()

int mbedtls_asn1_write_enum | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | int | val
| ) |  |

Write an enum tag (MBEDTLS_ASN1_ENUMERATED) and value in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  val | The integer value to write.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_ia5_string()

int mbedtls_asn1_write_ia5_string | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const char * | text,
|  | size_t | text_len
| ) |  |

Write a string in ASN.1 format using the IA5String string encoding tag (MBEDTLS_ASN1_IA5_STRING).

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  text | The string to write.
  text_len | The length of `text` in bytes (which might be strictly larger than the number of characters).

Returns
  The number of bytes written to `p` on success.
  A negative error code on failure.

## ◆ mbedtls_asn1_write_int()

int mbedtls_asn1_write_int | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | int | val
| ) |  |

Write an int tag (MBEDTLS_ASN1_INTEGER) and value in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  val | The integer value to write. It must be non-negative.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_len()

int mbedtls_asn1_write_len | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | size_t | len
| ) |  |

Write a length field in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  len | The length value to write.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_mpi()

int mbedtls_asn1_write_mpi | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const mbedtls_mpi * | X
| ) |  |

Write a arbitrary-precision number (MBEDTLS_ASN1_INTEGER) in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  X | The MPI to write. It must be non-negative.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_named_bitstring()

int mbedtls_asn1_write_named_bitstring | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const unsigned char * | buf,
|  | size_t | bits
| ) |  |

This function writes a named bitstring tag (MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format.

As stated in RFC 5280 Appendix B, trailing zeroes are omitted when encoding named bitstrings in DER.

Note
  This function works backwards within the data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer which is used for bounds-checking.
  buf | The bitstring to write.
  bits | The total number of bits in the bitstring.

Returns
  The number of bytes written to `p` on success.
  A negative error code on failure.

## ◆ mbedtls_asn1_write_null()

int mbedtls_asn1_write_null | ( | unsigned char ** | p,
|  | unsigned char * | start
| ) |  |

Write a NULL tag (MBEDTLS_ASN1_NULL) with zero data in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_octet_string()

int mbedtls_asn1_write_octet_string | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const unsigned char * | buf,
|  | size_t | size
| ) |  |

Write an octet string tag (MBEDTLS_ASN1_OCTET_STRING) and value in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  buf | The buffer holding the data to write.
  size | The length of the data buffer `buf`.

Returns
  The number of bytes written to `p` on success.
  A negative error code on failure.

## ◆ mbedtls_asn1_write_oid()

int mbedtls_asn1_write_oid | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const char * | oid,
|  | size_t | oid_len
| ) |  |

Write an OID tag (MBEDTLS_ASN1_OID) and data in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  oid | The OID to write.
  oid_len | The length of the OID.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_printable_string()

int mbedtls_asn1_write_printable_string | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const char * | text,
|  | size_t | text_len
| ) |  |

Write a string in ASN.1 format using the PrintableString string encoding tag (MBEDTLS_ASN1_PRINTABLE_STRING).

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  text | The string to write.
  text_len | The length of `text` in bytes (which might be strictly larger than the number of characters).

Returns
  The number of bytes written to `p` on success.
  A negative error code on failure.

## ◆ mbedtls_asn1_write_raw_buffer()

int mbedtls_asn1_write_raw_buffer | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const unsigned char * | buf,
|  | size_t | size
| ) |  |

Write raw buffer data.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  buf | The data buffer to write.
  size | The length of the data buffer.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_tag()

int mbedtls_asn1_write_tag | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | unsigned char | tag
| ) |  |

Write an ASN.1 tag in ASN.1 format.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  tag | The tag to write.

Returns
  The number of bytes written to `p` on success.
  A negative `MBEDTLS_ERR_ASN1_XXX` error code on failure.

## ◆ mbedtls_asn1_write_tagged_string()

int mbedtls_asn1_write_tagged_string | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | int | tag,
|  | const char * | text,
|  | size_t | text_len
| ) |  |

Write a string in ASN.1 format using a specific string encoding tag.

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  tag | The string encoding tag to write, e.g. MBEDTLS_ASN1_UTF8_STRING.
  text | The string to write.
  text_len | The length of `text` in bytes (which might be strictly larger than the number of characters).

Returns
  The number of bytes written to `p` on success.
  A negative error code on failure.

## ◆ mbedtls_asn1_write_utf8_string()

int mbedtls_asn1_write_utf8_string | ( | unsigned char ** | p,
|  | unsigned char * | start,
|  | const char * | text,
|  | size_t | text_len
| ) |  |

Write a UTF8 string in ASN.1 format using the UTF8String string encoding tag (MBEDTLS_ASN1_UTF8_STRING).

Note
  This function works backwards in data buffer.

Parameters

  p | The reference to the current position pointer.
  start | The start of the buffer, for bounds-checking.
  text | The string to write.
  text_len | The length of `text` in bytes (which might be strictly larger than the number of characters).

Returns
  The number of bytes written to `p` on success.
  A negative error code on failure.