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

typedef int (*mbedtls_x509_csr_ext_cb_t)(void *p_ctx, mbedtls_x509_csr const *csr, mbedtls_x509_buf const *oid, int critical, const unsigned char *p, const unsigned char *end)

The type of certificate extension callbacks. 

            Callbacks of this type are passed to and used by the
            mbedtls_x509_csr_parse_der_with_ext_cb() routine when
            it encounters either an unsupported extension.
            Future versions of the library may invoke the callback
            in other cases, if and when the need arises.

Note

The callback must fail and return a negative error code if it can not parse or does not support the extension. When the callback fails to parse a critical extension mbedtls_x509_csr_parse_der_with_ext_cb() also fails. When the callback fails to parse a non critical extension mbedtls_x509_csr_parse_der_with_ext_cb() simply skips the extension and continues parsing.

Param p_ctx

An opaque context passed to the callback.

Param csr

The CSR being parsed.

Param oid

The OID of the extension.

Param critical

Whether the extension is critical.

Param p

Pointer to the start of the extension value (the content of the OCTET STRING).

Param end

End of extension value.

Return

0 on success.

Return

A negative error code on failure.

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

Any unsupported requested extensions are silently ignored, unless the critical flag is set, in which case the CSR is rejected.

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_der_with_ext_cb(mbedtls_x509_csr *csr, const unsigned char *buf, size_t buflen, mbedtls_x509_csr_ext_cb_t cb, void *p_ctx)

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

Note

Any unsupported requested extensions are silently ignored, unless the critical flag is set, in which case the result of the callback function decides whether CSR is rejected.

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

  • cb – A callback invoked for every unsupported certificate extension.

  • p_ctx – An opaque context passed to the callback.

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