Skip to content

Commit

Permalink
certmap: Add documentation for some internal functions
Browse files Browse the repository at this point in the history 
Resolves: SSSD#6403

Reviewed-by: Alexey Tikhonov <atikhono@redhat.com>
Reviewed-by: Justin Stephenson <jstephen@redhat.com>
  • Loading branch information
@sumit-bose @alexey-tikhonov
sumit-bose authored and alexey-tikhonov committed Dec 2, 2022
1 parent 882f560 commit b0bdf71
Showing 1 changed file with 232 additions and 0 deletions.
232 changes: 232 additions & 0 deletions src/lib/certmap/sss_certmap_int.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -217,54 +217,286 @@ struct sss_cert_content {
const char *sid_ext;
};

/**
* @brief Extract various attributes from a binary X.509 certificate
*
* @param[in] mem_ctx Talloc memory context
* @param[in] der_blob Binary DER encoded X.509 certificate
* @param[in] der_size Length of the binary certificate
* @param[out] content Struct with parsed certificate data
*
* @return
* - 0: success
* - EINVAL: invalid input
* - ENOMEM: memory allocation error
*/
int sss_cert_get_content(TALLOC_CTX *mem_ctx,
const uint8_t *der_blob, size_t der_size,
struct sss_cert_content **content);

/**
* @brief Translate an RDN with NSS attribute names into AD names
*
* @param[in] mem_ctx Talloc memory context
* @param[in] rdn RDN input string
*
* @return
* - NULL in case of an error
* - RDN string with AD attribute name and the same value as the input
*/
char *check_ad_attr_name(TALLOC_CTX *mem_ctx, const char *rdn);

/**
* @brief Translate OpenSSL attribute name to NSS name
*
* @param[in] attr OpenSSL attribute name
*
* @return
* - NSS attribute name, most of the time it will be the same but there are
* some differences like e.g. 'GN' vs 'givenName'
*/
char *openssl_2_nss_attr_name(const char *attr);

/**
* @brief Parse matching rule
*
* @param[in] ctx Certmap context
* @param[in] rule_start Matching rule string
* @param[out] mapping_rule Parsed rule struct
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
* - EINVAL: invalid input
*/
int parse_krb5_match_rule(struct sss_certmap_ctx *ctx,
const char *rule_start,
struct krb5_match_rule **match_rule);

/**
* @brief Check hex conversion string
*
* @param[in] inp Conversion string
* @param[in] dec_allowed Flag to indicate if 'dec' for decimal output is
* allowed in the conversion string
* @param[out] _dec Flag to indicate decimal output
* @param[out] _upper Upper flag found in the conversion string
* @param[out] _colon Colon flag found in the conversion string
* @param[out] _reverse Reverse flag found in the conversion string
*
* @return
* - 0: success
* - EINVAL: invalid input
*/
int check_hex_conversion(const char *inp, bool dec_allowed, bool *_dec,
bool *_upper, bool *_colon, bool *_reverse);

/**
* @brief Check digest conversion string
*
* @param[in] inp Conversion string
* @param[in] digest_list List of know digest/hash functions
* @param[out] _dgst Name of digest found in the conversion string
* @param[out] _upper Upper flag found in the conversion string
* @param[out] _colon Colon flag found in the conversion string
* @param[out] _reverse Reverse flag found in the conversion string
*
* @return
* - 0: success
* - EINVAL: invalid input
*/
int check_digest_conversion(const char *inp, const char **digest_list,
const char **_dgst, bool *_upper, bool *_colon,
bool *_reverse);

/**
* @brief Parse mapping rule
*
* @param[in] ctx Certmap context
* @param[in] rule_start Mapping rule string
* @param[out] mapping_rule Parsed rule struct
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
* - EINVAL: invalid input
*/
int parse_ldap_mapping_rule(struct sss_certmap_ctx *ctx,
const char *rule_start,
struct ldap_mapping_rule **mapping_rule);

/**
* @brief Split attribute selector option
*
* @param[in] mem_ctx Talloc memory context
* @param[in] inp Attribute selector string in the format:
* - attr_name
* - [number]
* - attr_name[number]
* The number 0 is not allowed in the input
* @param[out] _attr_name Attribute name from the input if present, NULL if
* there is no name in the input
* @param[out] _number Number from the input if present, 0 if there is no
* number in the input
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
* - EINVAL: invalid input
*/
int check_attr_name_and_or_number(TALLOC_CTX *mem_ctx, const char *inp,
char **_attr_name, int32_t *_number);

/**
* @brief Get the short name from a fully-qulified name
*
* @param[in] mem_ctx Talloc memory context
* @param[in] full_name Fully-qulified name in the format
* "short-name""delimiter""suffix"
* @param[in] delim Delimiter character
* @param[out] short_name Resulting short name
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
* - EINVAL: invalid input
*/
int get_short_name(TALLOC_CTX *mem_ctx, const char *full_name,
char delim, char **short_name);

/**
* @brief Add generic data to a new san_list item
*
* @param[in] mem_ctx Talloc memory context
* @param[in] is_bin Binary data not a string
* @param[in] san_opt Type of Subject alternative name (SAN)
* @param[in] data Data
* @param[in] len Length of data
* @param[out] san_list New san_list item
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
* - EINVAL: invalid input
*/
int add_to_san_list(TALLOC_CTX *mem_ctx, bool is_bin,
enum san_opt san_opt, const uint8_t *data, size_t len,
struct san_list **item);

/**
* @brief Add a principal and the related short name to a new san_list item
*
* @param[in] mem_ctx Talloc memory context
* @param[in] san_opt Type of Subject alternative name (SAN)
* @param[in] princ String representation of the principal
* @param[out] item New san_list item
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
*/
int add_principal_to_san_list(TALLOC_CTX *mem_ctx, enum san_opt san_opt,
const char *princ, struct san_list **item);

/**
* @brief Get DN specified by 'conversion' from 'rdn_list'
*
* @param[in] mem_ctx Talloc memory context
* @param[in] conversion Specifies how the DN should be formatted:
* - (ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap)
* where 'x500' means most specific RDN comes last and
* 'ldap' most specific RDN comes first. 'ad' and
* 'nss' specify if the attributes names should be
* translated in the way Active Directory or the NSS
* library is using them.
* @param[in] rdn_list String array with the the individual RDNs of a DN
* starting with the most specific component
* @param[out] result The resulting DN
*
* @return
* - 0: success
* - EINVAL: unsupported 'conversion'
* - ENOMEM: memory allocation failure
*/
int rdn_list_2_dn_str(TALLOC_CTX *mem_ctx, const char *conversion,
const char **rdn_list, char **result);

/**
* @brief Get attribute value specified by 'conversion' from 'rdn_list'
*
* @param[in] mem_ctx Talloc memory context
* @param[in] conversion Selection by position and/or name, format:
* - name
* - [pos]
* - name[pos]
* where 'name' is an attribute name and pos to
* position of the attribute in the DN starting with
* 1, negative numbers will start at the least
* specific component of the DN
* @param[in] rdn_list String array with the the individual RDNs of a DN
* starting with the most specific component
* @param[out] result The selected attribute value
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
* - EINVAL: unsupported 'conversion' or 'rdn_list'
* - EIO: no value could be returned
*/
int rdn_list_2_component(TALLOC_CTX *mem_ctx, const char *conversion,
const char **rdn_list, char **result);

/**
* @brief Get list of supported has/digest types
*
* @param[in] mem_ctx Talloc memory context
* @param[out] digest_list Resulting list of hash type names
*
* @return
* - 0: success
* - ENOMEM: memory allocation failure
*/
int get_digest_list(TALLOC_CTX *mem_ctx, const char ***digest_list);

/**
* @brief Calculate the digest/hash of some binary data and return it as hex
* string
*
* @param[in] mem_ctx Talloc memory context
* @param[in] blob Binary data to calculate the hash of
* @param[in] blob_size Length of binary data
* @param[in] digest Type of hash/digest
* @param[in] upper_case Use upper-case letters in hex string
* @param[in] colon_sep Seperate each byte in the hex string with a ':'
* @param[in] reverse Start at the end of the binary blob
* @param[out] out Resulting hex string
*
* @return
* - 0: success
* - EINVAL: invalid hash type
* - EIO: error while calculating the hash
* - ENOMEM: memory allocation failure
*/
int get_hash(TALLOC_CTX *mem_ctx, const uint8_t *blob, size_t blob_size,
const char *digest, bool upper, bool colon, bool reverse,
char **out);

/**
* @brief Convert a binary blob into a hex string
*
* @param[in] mem_ctx Talloc memory context
* @param[in] upper_case Use upper-case letters in hex string
* @param[in] colon_sep Seperate each byte in the hex string with a ':'
* @param[in] reverse Start at the end of the binary blob
* @param[in] buf Start of the binary blob
* @param[in] len Length of the binary blob
* @param[out] out Resulting hex string
*
* @return
* - 0: success
* - EINVAL: invalid buffer or length
* - ENOMEM: memory allocation failure
*/
int bin_to_hex(TALLOC_CTX *mem_ctx, bool upper_case, bool colon_sep,
bool reverse, uint8_t *buf, size_t len, char **out);
#endif /* __SSS_CERTMAP_INT_H__ */

0 comments on commit b0bdf71

Please sign in to comment.