File x509_csr.h

X.509 certificate signing request parsing and writing.

Structures and functions for X.509 Certificate Signing Requests (CSR)

typedef struct mbedtls_x509_csr mbedtls_x509_csr

Certificate Signing Request (CSR) structure.

Some fields of this structure are publicly readable. Do not modify them except via Mbed TLS library functions: the effect of modifying those fields or the data that those fields point to is unspecified.

typedef struct mbedtls_x509write_csr mbedtls_x509write_csr

Container for writing a CSR

int mbedtls_x509_csr_parse_der(mbedtls_x509_csr *csr, const unsigned char *buf, size_t buflen)

Load a Certificate Signing Request (CSR) in DER format.

Note

CSR attributes (if any) are currently silently ignored.

Note

If MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.

Parameters

  • csr – CSR context to fill

  • buf – buffer holding the CRL data

  • buflen – size of the buffer

Returns

0 if successful, or a specific X509 error code

int mbedtls_x509_csr_parse(mbedtls_x509_csr *csr, const unsigned char *buf, size_t buflen)

Load a Certificate Signing Request (CSR), DER or PEM format.

Note

See notes for mbedtls_x509_csr_parse_der()

Note

If MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto subsystem must have been initialized by calling psa_crypto_init() before calling this function.

Parameters

  • csr – CSR context to fill

  • buf – buffer holding the CRL data

  • buflen – size of the buffer (including the terminating null byte for PEM data)

Returns

0 if successful, or a specific X509 or PEM error code

int mbedtls_x509_csr_parse_file(mbedtls_x509_csr *csr, const char *path)

Load a Certificate Signing Request (CSR)

Note

See notes for mbedtls_x509_csr_parse()

Parameters

  • csr – CSR context to fill

  • path – filename to read the CSR from

Returns

0 if successful, or a specific X509 or PEM error code

void mbedtls_x509_csr_init(mbedtls_x509_csr *csr)

Initialize a CSR.

Parameters

csr – CSR to initialize

void mbedtls_x509_csr_free(mbedtls_x509_csr *csr)

Unallocate all CSR data.

Parameters

csr – CSR to free

Functions

void mbedtls_x509write_csr_init(mbedtls_x509write_csr *ctx)

Initialize a CSR context.

Parameters

ctx – CSR context to initialize

int mbedtls_x509write_csr_set_subject_name(mbedtls_x509write_csr *ctx, const char *subject_name)

Set the subject name for a CSR Subject names should contain a comma-separated list of OID types and values: e.g. “C=UK,O=ARM,CN=Mbed TLS Server 1”.

Parameters

  • ctx – CSR context to use

  • subject_name – subject name to set

Returns

0 if subject name was parsed successfully, or a specific error code

void mbedtls_x509write_csr_set_key(mbedtls_x509write_csr *ctx, mbedtls_pk_context *key)

Set the key for a CSR (public key will be included, private key used to sign the CSR when writing it)

Parameters

  • ctx – CSR context to use

  • key – Asymmetric key to include

void mbedtls_x509write_csr_set_md_alg(mbedtls_x509write_csr *ctx, mbedtls_md_type_t md_alg)

Set the MD algorithm to use for the signature (e.g. MBEDTLS_MD_SHA1)

Parameters

  • ctx – CSR context to use

  • md_alg – MD algorithm to use

int mbedtls_x509write_csr_set_key_usage(mbedtls_x509write_csr *ctx, unsigned char key_usage)

Set the Key Usage Extension flags (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)

Note

The decipherOnly flag from the Key Usage extension is represented by bit 8 (i.e. 0x8000), which cannot typically be represented in an unsigned char. Therefore, the flag decipherOnly (i.e. MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this function.

Parameters

  • ctx – CSR context to use

  • key_usage – key usage flags to set

Returns

0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED

int mbedtls_x509write_csr_set_subject_alternative_name(mbedtls_x509write_csr *ctx, const mbedtls_x509_san_list *san_list)

Set Subject Alternative Name.

Note

Only “dnsName”, “uniformResourceIdentifier” and “otherName”, as defined in RFC 5280, are supported.

Parameters

  • ctx – CSR context to use

  • san_list – List of SAN values

Returns

0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED

int mbedtls_x509write_csr_set_ns_cert_type(mbedtls_x509write_csr *ctx, unsigned char ns_cert_type)

Set the Netscape Cert Type flags (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)

Parameters

  • ctx – CSR context to use

  • ns_cert_type – Netscape Cert Type flags to set

Returns

0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED

int mbedtls_x509write_csr_set_extension(mbedtls_x509write_csr *ctx, const char *oid, size_t oid_len, int critical, const unsigned char *val, size_t val_len)

Generic function to add to or replace an extension in the CSR.

Parameters

  • ctx – CSR context to use

  • oid – OID of the extension

  • oid_len – length of the OID

  • critical – Set to 1 to mark the extension as critical, 0 otherwise.

  • val – value of the extension OCTET STRING

  • val_len – length of the value data

Returns

0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED

void mbedtls_x509write_csr_free(mbedtls_x509write_csr *ctx)

Free the contents of a CSR context.

Parameters

ctx – CSR context to free

int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Write a CSR (Certificate Signing Request) to a DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer.

Note

f_rng is used for the signature operation.

Parameters

  • ctx – CSR to write away

  • buf – buffer to write to

  • size – size of the buffer

  • f_rng – RNG function. This must not be NULL.

  • p_rng – RNG parameter

Returns

length of data written if successful, or a specific error code

int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)

Write a CSR (Certificate Signing Request) to a PEM string.

Note

f_rng is used for the signature operation.

Parameters

  • ctx – CSR to write away

  • buf – buffer to write to

  • size – size of the buffer

  • f_rng – RNG function. This must not be NULL.

  • p_rng – RNG parameter

Returns

0 if successful, or a specific error code

struct mbedtls_x509_csr
#include <x509_csr.h>

Certificate Signing Request (CSR) structure.

Some fields of this structure are publicly readable. Do not modify them except via Mbed TLS library functions: the effect of modifying those fields or the data that those fields point to is unspecified.

Public Members

mbedtls_x509_buf raw

The raw CSR data (DER).

mbedtls_x509_buf cri

The raw CertificateRequestInfo body (DER).

int version

CSR version (1=v1).

mbedtls_x509_buf subject_raw

The raw subject data (DER).

mbedtls_x509_name subject

The parsed subject data (named information object).

mbedtls_pk_context pk

Container for the public key context.

unsigned int key_usage

Optional key usage extension value: See the values in x509.h

unsigned char ns_cert_type

Optional Netscape certificate type extension value: See the values in x509.h

mbedtls_x509_sequence subject_alt_names

Optional list of raw entries of Subject Alternative Names extension. These can be later parsed by mbedtls_x509_parse_subject_alt_name.

int private_ext_types

Bit string containing detected and parsed extensions

mbedtls_x509_buf sig_oid
mbedtls_x509_buf private_sig
mbedtls_md_type_t private_sig_md

Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256

mbedtls_pk_type_t private_sig_pk

Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA

void *private_sig_opts

Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS

struct mbedtls_x509write_csr
#include <x509_csr.h>

Container for writing a CSR

Public Members

mbedtls_pk_context *private_key
mbedtls_asn1_named_data *private_subject
mbedtls_md_type_t private_md_alg
mbedtls_asn1_named_data *private_extensions