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.

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

int mbedtls_x509_csr_info(char *buf, size_t size, const char *prefix, const mbedtls_x509_csr *csr)

Returns an informational string about the CSR.

Parameters:

buf – Buffer to write to
size – Maximum size of buffer
prefix – A line prefix
csr – The X509 CSR to represent

Returns:

The length of the string written (not including the terminated nul byte), or a negative 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_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, 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
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 may be NULL if RSA is used for signature and the signature is made offline (otherwise f_rng is desirable for countermeasures against timing attacks). ECDSA signatures always require a non-NULL f_rng.

Parameters:

ctx – CSR to write away
buf – buffer to write to
size – size of the buffer
f_rng – RNG function (for signature, see note)
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 may be NULL if RSA is used for signature and the signature is made offline (otherwise f_rng is desirable for countermeasures against timing attacks). ECDSA signatures always require a non-NULL f_rng.

Parameters:

ctx – CSR to write away
buf – buffer to write to
size – size of the buffer
f_rng – RNG function (for signature, see note)
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.

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.

mbedtls_x509_buf sig_oid

mbedtls_x509_buf sig

mbedtls_md_type_t sig_md: Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256

mbedtls_pk_type_t sig_pk: Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA

void *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 *key

mbedtls_asn1_named_data *subject

mbedtls_md_type_t md_alg

mbedtls_asn1_named_data *extensions