Function caprock_grant_create

Function Documentation

caprock_error_t caprock_grant_create(void *buffer, size_t *bufsize, caprock_key_pair const *issuer, uint64_t sequence_no, char const *from, char const *to, char const *expiry_policy, caprock_claim const *claims, size_t claims_size, caprock_identifier_hash_length issuer_hash_length, caprock_signature_algorithm sigalg)

Use this function to create and serialize a capability that grants some privileges. The caprock_token_create macro is provided for backwards compatibility, but takes the same parameters.

See caprock_revocation_create for a function with the same parameters that creates revocation capabilities.

Parameters

  • buffer – [out] The output buffer to write the serialized data into.

  • bufsize – [inout] A pointer to the output buffer size. Initialize this to the maximum size of the output buffer before calling. Upon return, this should typically contain the amount of buffer space used.

  • issuer – [in] A key pair for the issuer. Since the capability needs to be signed, a public and private key are both required.

  • sequence_no – [in] A sequence number for the capability, so that grants and revocations may be ordered. It is only required that each issuer increments this by some value for each capability generated.

  • from – [in] NULL-terminated time stamp in ISO-8601 format that specifies the start of the capability’s validity.

  • to – [in] Same format as from, but for the end of the validity period.

  • expiry_policy – [in] One of CAPROCK_EXPIRY_POLICY_ISSUER or CAPROCK_EXPIRY_POLICY_LOCAL.

  • claims – [in] A pointer to one or more caprock_claim structures.

  • claims_size – [in] The number of claims pointed to by claims.

  • issuer_hash_length – [in] The hash length for the issuer identifier that is encoded into the capability. See caprock_identifier_hash_length for possible values.

  • sigalg – [in] The signature algorithm which should be used to sign the capability. Possible values are provided by caprock_signature_algorithm.

Return values

  • CAPROCK_ERR_SUCCESS – All good, the capability was created and signed. The bufsize parameter should now contain the amount of buffer used.

  • CAPROCK_ERR_INVALID_VALUE – Some parameter had an invalid value. Most often, this means NULL values have been passed to pointers. But it could als mean that the parameters do not make sense in combination with each other. Refer to the log output for details.

  • CAPROCK_ERR_CODEC – Creating the capability was successful, but the result could not be encoded into the buffer. Often, this means the buffer was too small.