### Namespace

# Gcr – 3

GObject and GUI library for high level crypto handling

Version | 3
Authors | GCR contributors
License | LGPL-2.0-or-later
Website |
Source | https://gitlab.gnome.org/GNOME/gcr/

#### Build

C headers | `gcr/gcr-base.h`
pkg-config files | `gcr-base-3`

#### Dependencies

GObject—2.0 | The base type system library
| Browse documentation
Gio—2.0 | GObject interfaces and objects
| Browse documentation
Gck—1 | GObject bindings for PKCS#11
| Browse documentation

#### Additional documentation

- Non-pageable memory
- PKCS#11 configuration
- Trust store
- Classes Hierarchy

#### Classes

CertificateChain | Represents a chain of certificates, normally used to validate the trust in a certificate. An X.509 certificate chain has one endpoint certificate (the one for which trust is being verified) and then in turn the certificate that issued each previous certificate in the chain.
CertificateRequest | An object that allows creation of certificate requests. A certificate request is sent to a certificate authority to request an X.509 certificate.
FilterCollection | A collection which filters a `GcrCollection`.
Parser | A parser for parsing various types of files or data.
Pkcs11Certificate | A certificate loaded from a PKCS#11 storage. It is also a valid `GckObject` and can be used as such.
SecretExchange | Allows exchange of secrets between two processes on the same system without exposing those secrets to things like loggers, non-pageable memory etc.
SimpleCertificate | An implementation of `GcrCertificate` which loads a certificate from DER data already located in memory.
SimpleCollection | A simple implementation of `GcrCollection`, which you can add and remove objects from.
SshAskpass | When used as the setup function while spawning an ssh command like ssh-add or ssh, this allows callbacks for passwords on the provided interaction.
SystemPrompt | A `GcrPrompt` implementation which calls to the system prompter to display prompts in a system modal fashion.
SystemPrompter | A prompter used by implementations of system prompts.
UnionCollection | An implementation of `GcrCollection`, which combines the objects in other `GcrCollection`s. Use `gcr_union_collection_add()` to add and `gcr_union_collection_remove()` to remove them.

#### Interfaces

Certificate | An interface that represents an X.509 certificate.
Collection | A `GcrCollection` is used to group a set of objects.
Comparable | An interface for comparing objects.
Importer | An interface which allows importing of certificates and keys. Each importer is registered with a set of PKCS#11 attributes to match stuff that it can import.
ImportInteraction | This is an interface implemented by a caller performing an import. It allows the importer to ask the caller for further information about the import.
Prompt | A prompt displayed to the user. It is an interface with various implementations.

#### Structs

Column |
Parsed | A parsed item parsed by a `GcrParser`.

#### Enumerations

CertificateChainStatus | The status of a built certificate chain. Will be set to `GCR_CERTIFICATE_CHAIN_UNKNOWN` for certificate chains that have not been built.
CertificateRequestFormat | The format of a certificate request. Currently only PKCS#10 is supported.
DataError | Values responding to error codes for parsing and serializing data.
DataFormat | The various format identifiers.
PromptReply | Various replies returned by `gcr_prompt_confirm()` and friends.
SystemPrompterMode | The mode for the system prompter. Most system prompters can only show one prompt at a time and would use the `GCR_SYSTEM_PROMPTER_SINGLE` mode.
SystemPromptError | No error returned by the `GcrSystemPrompt` is suitable for display or to the user.

#### Bitfields

CertificateChainFlags | Flags to be used with the `gcr_certificate_chain_build()` operation.
ColumnFlags |

#### Callbacks

FilterCollectionFunc | A function which is called by `GcrFilterCollection` in order to determine whether an object should show through the filter or not.

#### Functions

data_error_get_domain |
fingerprint_from_attributes | Create a key fingerprint for a certificate, public key or private key. Note that this is not a fingerprint of certificate data, which you would use `gcr_certificate_get_fingerprint()` for.
fingerprint_from_subject_public_key_info | Create a key fingerprint for a DER encoded subjectPublicKeyInfo. The fingerprint is created so that it will be identical for a key and its corresponding certificate.
icon_for_token | Get an appropriate icon for the token.
mock_prompter_disconnect | Disconnect the mock prompter.
mock_prompter_expect_close | Queue an expected response on the mock prompter.
mock_prompter_expect_confirm_cancel | Queue an expected response on the mock prompter.
mock_prompter_expect_confirm_ok | Queue an expected response on the mock prompter.
mock_prompter_expect_password_cancel | Queue an expected response on the mock prompter.
mock_prompter_expect_password_ok | Queue an expected response on the mock prompter.
mock_prompter_get_delay_msec | Get the delay in milliseconds before the mock prompter completes an expected prompt.
mock_prompter_is_expecting | Check if the mock prompter is expecting a response. This will be `TRUE` when one of the <literal>gcr_mock_prompter_expect_xxx()</literal> functions have been used to queue an expected prompt, but that prompt response has not be ‘used’ yet.
mock_prompter_is_prompting | Check if the mock prompter is showing any prompts.
mock_prompter_set_delay_msec | Set the delay in milliseconds before the mock prompter completes an expected prompt.
mock_prompter_start | Start the mock prompter. This is often used from the <literal>setup()</literal> function of tests.
mock_prompter_stop | Stop the mock prompter. This is often used from the <literal>teardown()</literal> function of tests.
pkcs11_add_module | Add a `GckModule` to the list of PKCS#11 modules that are used by the GCR library.
pkcs11_add_module_from_file | Initialize a PKCS#11 module and add it to the modules that are used by the GCR library. Note that is an error to initialize the same PKCS#11 module twice.
pkcs11_get_modules | List all the PKCS#11 modules that are used by the GCR library. Each module is a `GckModule` object.
pkcs11_get_trust_lookup_slots | List all the PKCS#11 slots that are used by the GCR library for lookup of trust assertions. Each slot is a `GckSlot` object.
pkcs11_get_trust_lookup_uris | Get the PKCS#11 URIs that are used to identify which slots to use for lookup trust assertions.
pkcs11_get_trust_store_slot | Selects an appropriate PKCS#11 slot to store trust assertions. The slot to use is normally configured automatically by the system.
pkcs11_get_trust_store_uri | Get the PKCS#11 URI that is used to identify which slot to use for storing trust storage.
pkcs11_initialize | Asynchronously initialize the registered PKCS#11 modules.
pkcs11_initialize_async | Asynchronously initialize the registered PKCS#11 modules.
pkcs11_initialize_finish | Complete the asynchronous operation to initialize the registered PKCS#11 modules.
pkcs11_set_modules | Set the list of PKCS#11 modules that are used by the GCR library. Each module in the list is a `GckModule` object.
pkcs11_set_trust_lookup_uris | Set the PKCS#11 URIs that are used to identify which slots to use for lookup of trust assertions.
pkcs11_set_trust_store_uri | Set the PKCS#11 URI that is used to identify which slot to use for storing trust assertions.
secure_memory_alloc | Allocate a block of non-pageable memory.
secure_memory_free | Free a block of non-pageable memory.
secure_memory_is_secure | Check if a pointer is in non-pageable memory allocated by.
secure_memory_realloc | Reallocate a block of non-pageable memory.
secure_memory_strdup | Copy a string into non-pageable memory. If the input string is `NULL`, then `NULL` will be returned.
secure_memory_strfree | Free a string, whether securely allocated using these functions or not. This will also clear out the contents of the string so they do not remain in memory.
secure_memory_try_alloc | Allocate a block of non-pageable memory.
secure_memory_try_realloc | Reallocate a block of non-pageable memory.
trust_add_pinned_certificate | Add a pinned `certificate` for connections to `peer` for `purpose`. A pinned certificate overrides all other certificate verification and should be used with care.
trust_add_pinned_certificate_async | Add a pinned certificate for communication with `peer` for `purpose`. A pinned certificate overrides all other certificate verification and should be used with care.
trust_add_pinned_certificate_finish | Finishes an asynchronous operation started by gcr_trust_add_pinned_certificate_async().
trust_is_certificate_anchored | Check if the `certificate` is a trust anchor for the given `purpose`. A trust anchor is used to verify the signatures on other certificates when verifying a certificate chain. Also known as a trusted certificate authority.
trust_is_certificate_anchored_async | Check if the `certificate` is a trust anchor for the given `purpose`. A trust anchor is used to verify the signatures on other certificates when verifying a certificate chain. Also known as a trusted certificate authority.
trust_is_certificate_anchored_finish | Finishes an asynchronous operation started by gcr_trust_is_certificate_anchored_async().
trust_is_certificate_pinned | Check if `certificate` is pinned for `purpose` to communicate with `peer`. A pinned certificate overrides all other certificate verification.
trust_is_certificate_pinned_async | Check if `certificate` is pinned for `purpose` to communicate with `peer`. A pinned certificate overrides all other certificate verification.
trust_is_certificate_pinned_finish | Finishes an asynchronous operation started by gcr_trust_is_certificate_pinned_async().
trust_remove_pinned_certificate | Remove a pinned certificate for communication with `peer` for `purpose`.
trust_remove_pinned_certificate_async | Remove a pinned certificate for communication with `peer` for `purpose`.
trust_remove_pinned_certificate_finish | Finishes an asynchronous operation started by gcr_trust_remove_pinned_certificate_async().

#### Function Macros

CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE | Implement the GcrComparable interface. Use this macro like this:
CHECK_VERSION | Checks the version of the Gcr library that is being compiled against.
secure_memory_new | Allocate objects in non-pageable memory.

#### Constants

ICON_CERTIFICATE |
ICON_GNUPG |
ICON_HOME_DIRECTORY |
ICON_KEY |
ICON_KEY_PAIR |
ICON_PASSWORD |
ICON_SMART_CARD |
MAJOR_VERSION | The major version number of the Gcr library.
MICRO_VERSION | The micro version number of the Gcr library.
MINOR_VERSION | The minor version number of the Gcr library.
PURPOSE_CLIENT_AUTH | The purpose used to verify the client certificate in a TLS connection.
PURPOSE_CODE_SIGNING | The purpose used to verify certificate used for the signature on signed code.
PURPOSE_EMAIL | The purpose used to verify certificates that are used in email communication such as S/MIME.
PURPOSE_SERVER_AUTH | The purpose used to verify the server certificate in a TLS connection. This is the most common purpose in use.
SECRET_EXCHANGE_PROTOCOL_1 | The current secret exchange protocol. Key agreement is done using DH with the 1536 bit IKE parameter group. Keys are derived using SHA256 with HKDF. The transport encryption is done with 128 bit AES.
UNLOCK_OPTION_ALWAYS |
UNLOCK_OPTION_IDLE |
UNLOCK_OPTION_SESSION |
UNLOCK_OPTION_TIMEOUT |