Creates a new key of given type, description and payload and add it to the nominated keyring.
If a key of the same type and description as that proposed already exists in the keyring, this will try to update it with the given payload, or it will return error -EEXIST if that function is not supported by the key type. The process must also have permission to write to the key to be able to update it. The new key will have all user permissions granted and no group or third party permissions. Otherwise, this will attempt to create a new key of the specified type and description, and to instantiate it with the supplied payload and attach it to the keyring. In this case, an error will be generated if the process does not have permission to write to the keyring.
The payload is optional, and the pointer can be 0 if not required by the type.
A new keyring can be generated by setting type "keyring", the keyring name as the description (or 0) and setting the payload to 0.
User defined keys can be created by specifying type "user". It is recommended that a user defined key's description by prefixed with a type ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting ticket.
Any other type must have been registered with the kernel in advance by a kernel service such as a filesystem.
Arguments
eax |
286 |
ebx |
Pointer to a null-terminated string that specifies the type. |
ecx |
Pointer to a null-terminated string that specifies the description. |
edx |
Pointer to a null-terminated string that specifies the payload. |
esi |
Size of the payload. Should not exceed 32767 bytes. |
edi |
A positive non-zero 32-bit integer that specifies unique serial number for the key. It may be one of the predefined values:
KEY_SPEC_THREAD_KEYRING - Specifies the caller's thread-specific keyring.
KEY_SPEC_PROCESS_KEYRING - Specifies the caller's process-specific keyring.
KEY_SPEC_SESSION_KEYRING - Specifies the caller's session-specific keyring.
KEY_SPEC_USER_KEYRING - Specifies the caller's UID-specific keyring.
KEY_SPEC_USER_SESSION_KEYRING - Specifies the caller's UID-session keyring.
KEY_SPEC_GROUP_KEYRING - GID-specific keyring
KEY_SPEC_REQKEY_AUTH_KEY - assumed sys_request_key authorisation key |
|
Return values
If the system call succeeds the return value is the new key's ID.
If the system call fails the return value is one of the following errno values:
-ENOKEY |
The keyring doesn't exist. |
-EKEYEXPIRED |
The keyring has expired. |
-EKEYREVOKED |
The keyring has been revoked. |
-EINVAL |
The payload data was invalid. |
-ENOMEM |
Insufficient memory to create a key. |
-EDQUOT |
The key quota for this user would be exceeded by creating this key or linking it to the keyring. |
-EACCES |
The keyring wasn't available for modification by the user. |
|
Remarks
The keyring must be writable.
Compatibility
Available since 2.6.10
|