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 flagdecipherOnly
(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
-
mbedtls_x509_buf raw
-
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
-
mbedtls_pk_context *private_key