SharkSslCSR.h File Reference

#include "SharkSSL.h"

Go to the source code of this file.

Data Structures
struct	SharkSslCertSAN
	DNS/URI values are ASCII bytes; IP values are 4 or 16 network-order bytes. More...
struct	SharkSslCertProfile
	Required issuer policy for certificate signing. More...
struct	SharkSslCertDER
	One bounded DER certificate; a chain runs from operational CA to root. More...

Macros
#define	SHARKSSL_CERT_PROFILE_ROOT_CA   1
	Issuer-selected certificate profiles. More...
#define	SHARKSSL_CERT_PROFILE_INTERMEDIATE_CA   2
#define	SHARKSSL_CERT_PROFILE_TLS_SERVER   3
#define	SHARKSSL_CERT_PROFILE_TLS_CLIENT   4
#define	SHARKSSL_CERT_PROFILE_OPCUA_SERVER   5
#define	SHARKSSL_CERT_PROFILE_OPCUA_CLIENT   6
#define	SHARKSSL_CERT_PROFILE_TLS_SERVER_SELF_SIGNED   7
#define	SHARKSSL_CERT_SAN_DNS   2
#define	SHARKSSL_CERT_SAN_URI   6
#define	SHARKSSL_CERT_SAN_IP   7

Typedefs
typedef struct SharkSslCertSAN	SharkSslCertSAN
	DNS/URI values are ASCII bytes; IP values are 4 or 16 network-order bytes. More...
typedef struct SharkSslCertProfile	SharkSslCertProfile
typedef struct SharkSslCertDER	SharkSslCertDER
	One bounded DER certificate; a chain runs from operational CA to root. More...

Functions
SHARKSSL_API int	SharkSslCert_validateCAChain (const SharkSslCertDER *chain, const SharkSslCertDER *trustedRoot, const SharkSslKey expectedKey, const char *utcNow, U16 count)
	Validate an imported CA chain before enabling its issuing key. More...
SHARKSSL_API int	SharkSslCert_validateIssuedIdentity (const SharkSslCertDER *issued, const SharkSslCertDER *issuer, const SharkSslKey expectedKey, const SharkSslCertSAN *approvedSANs, const char *validFrom, const char *validTo, const char *utcNow, U16 sanCount)
	Check an issued leaf against the approved key, exact typed DNS/URI/IP SAN set, issuer, and validity timestamps. More...
SHARKSSL_API int	SharkSslCert_signCSR (SharkSslCert *signedCSR, const SharkSslCertProfile *profile, const U8 *csrData, const SharkSslCert caCert, const SharkSslKey privKey, const char *validFrom, const char *validTo, int csrDataLen, SharkCertSerialNumber serialNumber, U8 hashID)
	Sign a verified CSR under an explicit issuer policy. More...
SHARKSSL_API int	SharkSslCert_signCSRWithPSAKey (SharkSslCert *signedCSR, const SharkSslCertProfile *profile, const U8 *csrData, const SharkSslCert caCert, const char *validFrom, const char *validTo, int csrDataLen, SharkCertSerialNumber serialNumber, psa_key_id_t psaSignKey, U8 hashID)
	Sign a verified CSR with a PSA RSA or P-256/P-384/P-521 ECDSA private handle The public key of the handle must match caCert or the self-signed CSR The returned SharkSSL certificate contains no private key. More...
SHARKSSL_API int	SharkSslCert_signCSRWithPSAEdDSAKey (SharkSslCert *signedCSR, const SharkSslCertProfile *profile, const U8 *csrData, const SharkSslCert caCert, const char *validFrom, const char *validTo, int csrDataLen, SharkCertSerialNumber serialNumber, psa_key_id_t psaSignKey)
	Sign a verified CSR with a PSA Ed25519 or Ed448 PureEdDSA private handle The public key of the handle must match caCert or the self-signed CSR The returned SharkSSL certificate contains no private key. More...

Detailed Description

See Choose a SharkSSL API for build scope and the owning API layer.

Issuer policy for CSR signing.

Macro Definition Documentation

SHARKSSL_CERT_PROFILE_INTERMEDIATE_CA

#define SHARKSSL_CERT_PROFILE_INTERMEDIATE_CA   2

SHARKSSL_CERT_PROFILE_OPCUA_CLIENT

#define SHARKSSL_CERT_PROFILE_OPCUA_CLIENT   6

SHARKSSL_CERT_PROFILE_OPCUA_SERVER

#define SHARKSSL_CERT_PROFILE_OPCUA_SERVER   5

SHARKSSL_CERT_PROFILE_ROOT_CA

#define SHARKSSL_CERT_PROFILE_ROOT_CA   1

Issuer-selected certificate profiles.

CSR extensions are validated but never copied to the certificate. CA profiles require an explicit pathLenConstraint. Use 0xFFFF for leaves.

SHARKSSL_CERT_PROFILE_TLS_CLIENT

#define SHARKSSL_CERT_PROFILE_TLS_CLIENT   4

SHARKSSL_CERT_PROFILE_TLS_SERVER

#define SHARKSSL_CERT_PROFILE_TLS_SERVER   3

SHARKSSL_CERT_PROFILE_TLS_SERVER_SELF_SIGNED

#define SHARKSSL_CERT_PROFILE_TLS_SERVER_SELF_SIGNED   7

SHARKSSL_CERT_SAN_DNS

#define SHARKSSL_CERT_SAN_DNS   2

SHARKSSL_CERT_SAN_IP

#define SHARKSSL_CERT_SAN_IP   7

SHARKSSL_CERT_SAN_URI

#define SHARKSSL_CERT_SAN_URI   6

Typedef Documentation

SharkSslCertDER

typedef struct SharkSslCertDER SharkSslCertDER

One bounded DER certificate; a chain runs from operational CA to root.

SharkSslCertProfile

typedef struct SharkSslCertProfile SharkSslCertProfile

SharkSslCertSAN

typedef struct SharkSslCertSAN SharkSslCertSAN

DNS/URI values are ASCII bytes; IP values are 4 or 16 network-order bytes.

Function Documentation

SharkSslCert_signCSR()

int SharkSslCert_signCSR	(	SharkSslCert *	signedCSR,
		const SharkSslCertProfile *	profile,
		const U8 *	csrData,
		const SharkSslCert	caCert,
		const SharkSslKey	privKey,
		const char *	validFrom,
		const char *	validTo,
		int	csrDataLen,
		SharkCertSerialNumber	serialNumber,
		U8	hashID
	)

Sign a verified CSR under an explicit issuer policy.

For leaf certificates, approveSANs must return zero only when all typed DNS/URI/IP names in the CSR match the authorized enrollment identity. The callback receives pointers into csrData that remain valid only during this call. No requested extension bytes are copied to the certificate. Root CA requires caCert to be NULL and privKey to match the CSR. OPC UA profiles also allow caCert=NULL with a matching privKey, producing a self-signed application leaf (cA=FALSE, keyCertSign present). TLS and intermediate profiles require caCert, except TLS_SERVER_SELF_SIGNED, which requires caCert=NULL, a matching signing key and at least one DNS/IP SAN. Its leaf has cA=FALSE, serverAuth EKU and no CA signing usage. When supplied, caCert must identify a CA permitted to sign and its attached signing key must match the certificate's public key. The caller must validate the issuer's trust chain and current validity separately. OPC UA profiles require exactly one absolute URI SAN, nonempty commonName and organization, and a DNS/IP SAN for servers. They select OPC UA Key Usage for the subject's RSA/ECC key; servers include both TLS EKU purposes. validFrom and validTo use UTC YYYYMMDDHHMMSS. On success, signedCSR receives an allocated SharkSSL certificate that the caller frees with baFree; the return value is its size. Require both a positive size and a non-NULL output. Failure leaves the output NULL and normally returns a negative value, but an ASN.1 encoding failure can propagate 1.

Parameters

signedCSR	SharkSslCert *; required output pointer, initialized to NULL. On success receives an allocation owned by the caller; free it with baFree.
profile	const SharkSslCertProfile *; required issuer-selected profile; borrowed, including callback context, for this call.
csrData	const U8 *; required DER request bytes, borrowed for the call.
caCert	SharkSslCert; issuer certificate in SharkSSL format, or NULL only for a profile permitting self-signing. Validate issuer trust and time separately.
privKey	SharkSslKey; optional native key attached to the issued subject certificate. When supplied it must match the CSR subject key. For CA signing, the issuer certificate supplies its own attached signing key. NULL creates a certificate without a subject private key.
validFrom	const char *; required NUL-terminated UTC start timestamp, YYYYMMDDHHMMSS.
validTo	const char *; required NUL-terminated UTC end timestamp, YYYYMMDDHHMMSS, later than validFrom.
csrDataLen	int; DER request length from 1 to 32767 bytes.
serialNumber	SharkCertSerialNumber; caller-selected certificate serial number in host byte order.
hashID	U8; enabled SHARKSSL_HASHID_SHA256, SHARKSSL_HASHID_SHA384, or SHARKSSL_HASHID_SHA512, compatible with the issuer key and profile.

Returns

int: positive allocated certificate byte count on success, with *signedCSR non-NULL. Failure leaves *signedCSR NULL and normally returns a negative error; an ASN.1 encoding failure can propagate 1. Check the output pointer as well as the return value.

SharkSslCert_signCSRWithPSAEdDSAKey()

int SharkSslCert_signCSRWithPSAEdDSAKey	(	SharkSslCert *	signedCSR,
		const SharkSslCertProfile *	profile,
		const U8 *	csrData,
		const SharkSslCert	caCert,
		const char *	validFrom,
		const char *	validTo,
		int	csrDataLen,
		SharkCertSerialNumber	serialNumber,
		psa_key_id_t	psaSignKey
	)

Sign a verified CSR with a PSA Ed25519 or Ed448 PureEdDSA private handle The public key of the handle must match caCert or the self-signed CSR The returned SharkSSL certificate contains no private key.

The output contains no private key.

Requires a PureEdDSA Ed25519 or Ed448 key.

Parameters

signedCSR	SharkSslCert *; required output pointer, initialized to NULL. On success receives an allocation owned by the caller; free it with baFree.
profile	const SharkSslCertProfile *; required issuer-selected profile; borrowed, including callback context, for this call.
csrData	const U8 *; required DER request bytes, borrowed for the call.
caCert	SharkSslCert; issuer certificate in SharkSSL format, or NULL only for a profile permitting self-signing. Validate issuer trust and time separately.
validFrom	const char *; required NUL-terminated UTC start timestamp, YYYYMMDDHHMMSS.
validTo	const char *; required NUL-terminated UTC end timestamp, YYYYMMDDHHMMSS, later than validFrom.
csrDataLen	int; DER request length from 1 to 32767 bytes.
serialNumber	SharkCertSerialNumber; caller-selected certificate serial number in host byte order.
psaSignKey	psa_key_id_t; required borrowed private signing handle matching the issuer certificate or self-signed CSR. The caller retains ownership.

Returns

int: positive allocated certificate byte count on success, with *signedCSR non-NULL. Failure leaves *signedCSR NULL and normally returns a negative error; an ASN.1 encoding failure can propagate 1. Check the output pointer as well as the return value.

SharkSslCert_signCSRWithPSAKey()

int SharkSslCert_signCSRWithPSAKey	(	SharkSslCert *	signedCSR,
		const SharkSslCertProfile *	profile,
		const U8 *	csrData,
		const SharkSslCert	caCert,
		const char *	validFrom,
		const char *	validTo,
		int	csrDataLen,
		SharkCertSerialNumber	serialNumber,
		psa_key_id_t	psaSignKey,
		U8	hashID
	)

Sign a verified CSR with a PSA RSA or P-256/P-384/P-521 ECDSA private handle The public key of the handle must match caCert or the self-signed CSR The returned SharkSSL certificate contains no private key.

The output contains no private key.

Requires a supported RSA or NIST P-256/P-384/P-521 ECDSA signing key.

Parameters

signedCSR	SharkSslCert *; required output pointer, initialized to NULL. On success receives an allocation owned by the caller; free it with baFree.
profile	const SharkSslCertProfile *; required issuer-selected profile; borrowed, including callback context, for this call.
csrData	const U8 *; required DER request bytes, borrowed for the call.
caCert	SharkSslCert; issuer certificate in SharkSSL format, or NULL only for a profile permitting self-signing. Validate issuer trust and time separately.
validFrom	const char *; required NUL-terminated UTC start timestamp, YYYYMMDDHHMMSS.
validTo	const char *; required NUL-terminated UTC end timestamp, YYYYMMDDHHMMSS, later than validFrom.
csrDataLen	int; DER request length from 1 to 32767 bytes.
serialNumber	SharkCertSerialNumber; caller-selected certificate serial number in host byte order.
hashID	U8; enabled SHARKSSL_HASHID_SHA256, SHARKSSL_HASHID_SHA384, or SHARKSSL_HASHID_SHA512, compatible with the issuer key and profile.
psaSignKey	psa_key_id_t; required borrowed private signing handle matching the issuer certificate or self-signed CSR. The caller retains ownership.

Returns

int: positive allocated certificate byte count on success, with *signedCSR non-NULL. Failure leaves *signedCSR NULL and normally returns a negative error; an ASN.1 encoding failure can propagate 1. Check the output pointer as well as the return value.

SharkSslCert_validateCAChain()

int SharkSslCert_validateCAChain	(	const SharkSslCertDER *	chain,
		const SharkSslCertDER *	trustedRoot,
		const SharkSslKey	expectedKey,
		const char *	utcNow,
		U16	count
	)

Validate an imported CA chain before enabling its issuing key.

chain[0] is the operational CA and chain[count - 1] must be byte-for-byte equal to trustedRoot. expectedKey is the operational CA's SharkSSL public key. utcNow is a NUL-terminated YYYYMMDDHHMMSS UTC timestamp. Rejects weak signatures, unsupported constraints, and chains over eight certificates or with DER entries over 32767 bytes. Issuer/subject names must have the same DER encoding; self-issued CAs count toward path length. Returns zero only when all checks pass. The caller selects the trusted root from its configured trust store and revalidates when the time or chain changes.

Parameters

chain	const SharkSslCertDER *; required array from operational CA at index 0 to root at count-1. All DER is borrowed for this call.
trustedRoot	const SharkSslCertDER *; required caller-selected trust anchor; the last chain entry must match its bytes exactly.
expectedKey	SharkSslKey; required expected public key of chain[0], in SharkSSL key encoding.
utcNow	const char *; required NUL-terminated current UTC timestamp, YYYYMMDDHHMMSS.
count	U16; number of chain entries, from 1 to 8; each DER length must be 1..32767 bytes.

Returns

int: 0 only when every chain, key, time, constraint, and signature check succeeds; nonzero on failure.

SharkSslCert_validateIssuedIdentity()

int SharkSslCert_validateIssuedIdentity	(	const SharkSslCertDER *	issued,
		const SharkSslCertDER *	issuer,
		const SharkSslKey	expectedKey,
		const SharkSslCertSAN *	approvedSANs,
		const char *	validFrom,
		const char *	validTo,
		const char *	utcNow,
		U16	sanCount
	)

Check an issued leaf against the approved key, exact typed DNS/URI/IP SAN set, issuer, and validity timestamps.

The issuer certificate must already belong to a validated CA chain. The function verifies the leaf signature with that issuer's public key and rejects cA=TRUE or keyCertSign. Profile purposes and revocation remain the caller's policy checks. DER inputs are bounded to 32767 bytes and the SAN set to 16 entries. Timestamps are NUL-terminated YYYYMMDDHHMMSS UTC strings. Returns zero only on success.

Parameters

issued	const SharkSslCertDER *; required bounded leaf certificate, borrowed for this call.
issuer	const SharkSslCertDER *; required direct issuer already accepted through a trusted CA chain; borrowed.
expectedKey	SharkSslKey; required expected leaf public key in SharkSSL encoding.
approvedSANs	const SharkSslCertSAN *; approved exact typed SAN set, required when sanCount is nonzero.
validFrom	const char *; required expected start timestamp, NUL-terminated UTC YYYYMMDDHHMMSS.
validTo	const char *; required expected end timestamp in the same format.
utcNow	const char *; required current UTC timestamp in the same format.
sanCount	U16; approved SAN count, at most 16. DER inputs must each fit 32767 bytes.

Returns

int: 0 on successful key, SAN, issuer/signature, timestamp, and leaf-constraint checks; nonzero on failure. Application purpose and revocation policy remain separate.